figma-setup-design-tokens

figma-setup-design-tokens — 原子化令牌系统初始化

在一次 use_figma 调用中创建变量集合、模式和所有变量。这是快速搭建新令牌系统（或在现有系统中创建新集合）的最快方式。由于它作为一个原子脚本运行，因此要么全部创建成功，要么什么都不创建（脚本失败不会应用任何更改）。

技能边界

• use_figma 规则——先加载官方 figma-use 技能；其中包含完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用带顶层 await 和 return 的纯 JS（不使用 IIFE 或 figma.closePlugin()；console.log 不会作为返回值返回），在每个脚本顶部以内联 const 的方式填写输入值，颜色值范围为 0–1，在任何文本操作前加载字体，使用 await figma.getNodeByIdAsync(...)，以及原子化错误处理（脚本失败不会应用任何更改——读取错误、修复后重试）。
• 对现有系统进行增量 CRUD／批量编辑 → figma-manage-variables。
• 从代码令牌文件同步 → figma-import-tokens。

工作流

1. 确定 v1 范围。 列出集合名称、模式（第一个为默认模式）以及包含各模式值的完整令牌集。编写前先敲定范围——这比之后再编辑省时得多。
2. 填写 scripts/setup-tokens.js 中的常量：COLLECTION_NAME、MODES、TOKENS（按模式名称设定值），以及可选的每变量 SCOPES。
3. 通过 use_figma 运行（skillNames: "figma-setup-design-tokens"）。它会返回 { collectionId, modes, created, errors }。
4. 使用 get_variable_defs 或 figma-export-tokens 读取脚本进行验证，如果还创建了色板，则截屏检查。

注意

• 双层系统：使用此技能创建原始令牌（原始值），再使用 figma-import-tokens（包含别名处理阶段）或 figma-manage-variables 创建指向它们的语义令牌。原始令牌应保持为单模式，并将主题设置放在语义层。
• 设置作用范围：默认的 ALL_SCOPES 会使每个属性选择器变得杂乱。请为每个令牌所属的界面元素传入 SCOPES（背景使用 FRAME_FILL／SHAPE_FILL，文本使用 TEXT_FILL，间距使用 GAP，圆角使用 CORNER_RADIUS，尺寸使用 WIDTH_HEIGHT）。
• 每个集合只初始化一次。多个集合需要多次运行。