export-tokens-figma

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

读取 Figma 文件中的所有本地变量，并生成设计令牌文件。规范输出格式为 DTCG（W3C Design Tokens Community Group JSON）；CSS、Tailwind、SCSS、TS 和 JSON 均由此派生。

为什么它优于原始 REST 导出： Figma 的 Variables REST API 仅限 Enterprise 套餐（Starter/Pro/Org 会返回 403）。此技能通过 use_figma 使用 Plugin API 读取变量，因此所有套餐均可使用，并能解析别名和多模式值，而 get_variable_defs（仅默认模式）会遗漏这些值。

技能边界

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

工作流

1. 确认范围和格式。 询问（或推断）目标格式（安全默认值为 dtcg）、是否按模式/集合拆分，以及输出路径。从当前打开的 Figma 文件或用户提供的 URL 获取文件 key。
2. 读取变量。 通过 use_figma 运行 scripts/read-variables.js （skillNames: "export-tokens-figma"）。脚本会返回标准化的集合/模式/变量树，其中包含十六进制颜色、已解析的别名引用、作用域和代码语法。
3. 保存读取结果到文件，例如 variables.json。
4. 确定性转换。 运行内置转换器（Node 18+，零依赖）。不要手动编写转换逻辑 — 此脚本是事实依据，每次运行都会生成相同的输出：

   node scripts/convert-tokens.mjs variables.json --format dtcg --out tokens/
   # --format: dtcg (default) | css-vars | tailwind-v4 | tailwind-v3 | scss | ts-module
   #           | json-flat | json-nested | style-dictionary-v3 | tokens-studio
   #           (aliases: css, tailwind, ts)
   # --out <dir>  write file(s) — tokens-studio writes several; omit to print to stdout
   # --prefix <p>            prefix CSS/SCSS var names
   # --modes Light,Dark      include only these modes (default: all)
   # --collection <substr>   include only collections whose name contains <substr>
   

   这与 Console 的 figma_export_tokens 格式化器一致。它会处理手动转换常出错的情况：按类型设置单位（opacity/line-height 无单位，spacing/radius 使用 px）；多模式输出（CSS 和 Tailwind v4 生成 :root + .dark/[data-theme]；TS/JSON 生成 {mode: value}；SCSS 为模式添加后缀；DTCG 将模式保存在 $extensions 中）；别名 → var()/{ref}；字体粗细名称 → 数字；DTCG 往返转换元数据；并且会对 slug 冲突和非数字字体粗细发出警告。（style-dictionary-v3 和 tailwind-v3 使用主模式，与 Console 行为一致 — 这些格式没有原生的多模式编码方式。）
5. 报告结果。 列出已写入的路径，并指出转换器打印的任何警告（冲突/字体粗细问题反映了 Figma 文件中的实际情况，值得提醒用户）。

说明

• 转换器具有确定性且权威。 references/token-formats.md 介绍了它生成的格式；该文档仅供参考，不应据此手动重新实现转换器。
• 运行环境： read-variables.js 可通过 use_figma 在任何地方运行。convert-tokens.mjs 需要 Node，因此需要支持终端的 Agent（Claude Code、Claude Desktop 中的 Code 标签页、Cursor、Codex、Gemini CLI）。在纯 Desktop/网页聊天环境中（没有 shell），可在自己的机器上使用保存的 variables.json 运行转换器，或仅针对 DTCG 接受尽力而为的内联转换。
• 大型系统： 如果读取结果过大，请在保存前限定特定的集合名称。
• 跨集合别名会转换为 var(--…) / {ref} — 请一并导出所有集合，以便解析这些引用。