figma-import-tokens

figma-import-tokens — 设计令牌 → Figma 变量

从令牌源（DTCG tokens.json、Tailwind/SCSS 导出文件或纯令牌对象）创建并更新 Figma 变量。支持别名和多模式值。重复运行是安全的：变量按已保存的 Figma id → key → 完全匹配的名称进行匹配，因此更新会原位修改变量，而不会重复创建。

技能边界

• use_figma 规则 — 首先加载官方 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用带顶层 await 和 return 的纯 JS（不要使用 IIFE 或 figma.closePlugin()；console.log 不会作为返回值返回）；在每个脚本顶部以内联 const 定义输入；颜色值范围为 0–1；任何文本操作前先加载字体；使用 await figma.getNodeByIdAsync(...)；以及原子错误（脚本失败时不会应用任何更改——读取错误、修复后重试）。
• 反向转换（Figma → 代码）→ figma-export-tokens。

工作流

1. 确定性地将源数据解析为规范令牌列表。 对于 DTCG 输入（包括 figma-export-tokens 生成的内容），请运行内置解析器，而不要手动展平：

   node scripts/parse-tokens.mjs tokens.tokens.json --default-mode Light --collection Brand
   # --strip-prefix "ds-"   drops a leading name prefix on import (e.g. ds-color/x → color/x)
   

   它会输出可粘贴到应用脚本中的确切 COLLECTION_NAME / MODES / TOKENS 常量，并处理 $type→Figma 类型、{ref} 别名、多模式（$extensions…modes）、dimension 单位剥离和 variableId 往返。对于非 DTCG 来源（如 Tailwind/SCSS 导出文件），请先导出为 DTCG，或手动构建 TOKENS 数组： { name: "Color/Brand/Primary", type: "COLOR"|"FLOAT"|"STRING"|"BOOLEAN", values: { <mode>: literal | { reference: "{Color.Brand.500}" } }, figmaVariableId? }。
2. 确定冲突策略。 默认情况下，以代码中的值为准，但未经询问绝不删除 Figma 中独有的变量。确认目标集合名称和模式列表（第一个模式为默认模式）。
3. 应用。 将解析后的数据放入 scripts/apply-tokens.js 顶部的常量中，并通过 use_figma 运行（skillNames: "figma-import-tokens"）。脚本分两轮运行——先处理字面值，再处理别名——并返回 { created, updated, errors, variableIds }。
4. 报告并验证。 告知创建数、更新数和任何 errors。执行回读（使用 figma-export-tokens 读取脚本或 get_variable_defs），确认值已写入。

注意事项与易错点

• 必须分两轮处理——创建 createVariableAlias 前，别名目标必须已存在。脚本会处理此步骤；不要合并为一轮。
• 颜色接受十六进制字符串（3/6/8 位），并会自动转换为范围为 0–1 的 {r,g,b,a}。
• 作用域：新变量默认使用 ALL_SCOPES，这会让变量出现在所有选择器中。导入后，可考虑设置 variable.scopes（参见 figma-manage-variables），以限定到正确的界面区域。
• 往返转换：导入先前由 figma-export-tokens 生成的文件是最理想的情况——暂存的 variableId 可实现精确匹配。