figma-export-tokens

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

读取 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 variables）→ 使用 figma-import-tokens 技能。

工作流

1. 确认范围和格式。 询问（或推断）目标格式（安全默认值为 dtcg）、是否按模式/集合拆分，以及输出路径。从当前打开的 Figma 文件或用户提供的 URL 获取文件 key。
2. 读取变量。 通过 use_figma 运行 scripts/read-variables.js （skillNames: "figma-export-tokens"）。它会返回规范化的集合/模式/变量树，其中包含十六进制颜色、已解析的别名引用、作用域和代码语法。
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 格式化器一致。它会准确处理手动转换容易出错的内容：按类型使用单位（不透明度/行高不带单位，间距/圆角使用 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} — 请一并导出所有集合，以确保这些引用能够解析。