import-tokens-figma

import-tokens-figma — 设计令牌 → Figma variables

根据令牌源（DTCG tokens.json、Tailwind/SCSS 导出文件或普通令牌对象）创建和更新 Figma variables。支持别名和多模式值。重复运行是安全的：variables 会按已保存的 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 → 代码）→ export-tokens-figma。

工作流

1. 将源解析为规范令牌列表——确保结果确定。 对于 DTCG 输入（包括任何由 export-tokens-figma 生成的内容），请运行捆绑的解析器，不要手动展平：

   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 中独有的 variables。确认目标 collection 名称和模式列表（第一个为默认模式）。
3. 应用。 将解析后的数据放入 scripts/apply-tokens.js 顶部的常量中，并通过 use_figma 运行（skillNames: "import-tokens-figma"）。脚本分两轮执行——先处理字面值，再处理别名——并返回 { created, updated, errors, variableIds }。
4. 报告并验证。 告知创建和更新的数量，以及任何 errors。执行回读（使用 export-tokens-figma 读取脚本或 get_variable_defs），确认值已写入。

说明与注意事项

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