code-to-figma

Code to Figma

生成适用于特定项目的 Figma 导出流水线：一个读取编译后的 HTML 和 CSS、解析类名 → 令牌绑定关系，并将结构化 JSON 工件推送到 GitHub Gist 的遍历器，tokens-sync-to-figma Figma 插件会使用该工件。

该流水线有意采用单向流程，并以 CI 为锚点。在 setup 期间评估一次项目、生成脚本并接入 CI。之后，每次推送只要涉及配置的令牌或模板路径，都会自动更新 Gist，无需 Figma API 密钥。随附的插件会使用现有 Figma 变量重建页面结构；令牌值发生变化时，必须单独更新集合并读取回验，才能确认与 Figma 保持一致。

命令

命令	适用场景	结果
/code-to-figma setup	首次使用；尚无脚本	生成遍历器和令牌脚本，创建 Gist，接入 CI，保存配置
/code-to-figma sync	脚本已存在；将当前状态推送到 Gist	构建 figma-export.json 并更新 Gist
/code-to-figma update	技术栈或令牌命名发生重大变化	重新生成脚本，更新 CI 和配置
/code-to-figma status	检查流水线健康状况	Gist 时效、CI 状态、脚本是否存在、配置是否有效

对于未明确指定的 setup/sync 请求，如果未找到 figma-sync.config.json 或遍历器脚本，则默认执行 /code-to-figma setup。保留明确的只读 status 请求：报告流水线缺失，而不是创建流水线。

---

/code-to-figma setup

1 — 评估项目

生成任何内容之前，按以下顺序读取：

1. 包清单 — package.json、pyproject.toml 等。识别框架（Next.js、Eleventy、SolidJS、纯 HTML）和包管理器。
2. CSS / 令牌文件 — 查找编译后的输出，而非源文件。常见路径：
   • Tailwind v4：out/assets/css/tailwind.css 或同类构建输出
   • 自定义 CSS：查找包含 --token-name: value; 自定义属性声明的文件
   • Style Dictionary：tokens.json、variables.css 或 dist/ 中的生成输出
3. 组件 CSS — 查找与主 CSS 文件同目录下的 components.css 或 utilities.css
4. 构建后的 HTML — 编译后的输出页面，而非源模板。常见路径：out/index.html、dist/index.html、_site/index.html。Next.js：默认构建不会输出单个 HTML 文件；继续操作前需要设置 output: 'export'（生成 out/index.html）——请参阅 references/walker-patterns.md 中的 Next.js 说明。如果无法生成静态 HTML 工件，请停止并告知用户，而不要猜测路径。
5. 令牌命名约定 — 读取 CSS 自定义属性名称，提取前缀到分组的映射（例如 beige-* → palette/beige/、fs-* → typography/scale/）
6. 区块结构 — 扫描 HTML，了解区块如何划分：<section id="...">、[data-section]、<article>、页眉/页脚标记等。

如果存在两种确实不同的遍历器结构（例如按 ID 还是按类名识别区块），请提出一个有针对性的问题。否则，推断并说明所选方案。

2 — 生成并验证脚手架

创建或更新项目专用 walker、DTCG 2025.10 令牌转换器、通用 Gist 推送脚本、figma-sync.config.json、package 脚本、GitHub Actions 工作流、Gist、密钥、首次同步以及 Figma 插件连接。加载 references/setup-scaffold.md 以查看文件规范，并加载 references/ci-and-gist-setup.md 以查看规范的 Gist、密钥、CI 和插件设置命令。

依赖 CI 前必须完成的本地检查：

node scripts/tokens-to-figma/convert-to-dtcg.mjs
git status --short -- scripts/tokens-to-figma/*.w3c.json
node scripts/figma-export/walk-<site>.mjs | jq -e '.sections | type == "array"'

明确核心边界：CI 生成 figma-export.json，并检查已提交的 <project>-tokens.w3c.json；tokens-sync-to-figma 插件只使用 figma-export.json。应单独使用 DTCG 文件来维护 Figma variables。不要要求在 CI 中提供 Figma API 密钥。

生成的脚本能够运行、Gist 包含已验证的导出内容、CI 已接通，并且用户已通过集合协调验证插件连接和变量值，即表示设置完成。如果 Figma 访问权限或手动步骤尚未完成，请将流水线设置与 Figma 验证情况分开报告。

---

/code-to-figma sync

1. 确认 figma-sync.config.json 存在，且 walker 路径有效。
2. 使用项目的构建命令构建当前网站，重新生成 node scripts/tokens-to-figma/convert-to-dtcg.mjs，并检查 .w3c.json 差异，包括现有值和别名的变更。然后运行 node <walker> > figma-export.tmp.json。
3. 验证：jq -e '.sections | type == "array"' figma-export.tmp.json 必须以 0 退出；失败时停止。
4. 确认已按照 references/ci-and-gist-setup.md 从密钥管理器导出 GIST_TOKEN；切勿在命令行中输入 PAT。
5. 推送：node scripts/tokens-to-figma/push-to-figma.mjs < figma-export.tmp.json
6. 使用协调流程，将令牌变更与 Figma 集合协调。Gist 授权并不等于获准在 Figma 内写入。分别报告已上传导出内容和Figma 令牌一致性已验证／未验证两种状态；如果没有经授权的 Figma 访问权限或手动回读，一致性就属于未验证，并应列出待处理的差异。
7. 完成后删除 figma-export.tmp.json，然后报告导出的区段和节点数量、Gist URL，以及单独的 Figma 验证状态。只有在验证集合值和插件结果后，才能声称 Figma 令牌一致。

---

/code-to-figma update

当框架输出、令牌命名约定、区段选择器或 CSS 构建路径发生足以导致现有 walker 过时的变更时，请使用此命令。

1. 根据当前编译后的 HTML/CSS 和令牌文件，重新进行设置评估。
2. 同步更新 walk-<site>.mjs、convert-to-dtcg.mjs、figma-sync.config.json 和 CI 路径，确保 tokenPath()、显式令牌类型和文件路径保持一致。
3. 重新生成 DTCG 令牌文件：node scripts/tokens-to-figma/convert-to-dtcg.mjs。
4. 验证 walker 输出：node <walker> > figma-export.tmp.json && jq -e '.sections | type == "array"' figma-export.tmp.json。
5. 检查脚本和 .w3c.json 差异后，通过 /code-to-figma sync 或 CI 推送；随后协调集合变更，并分别报告导出情况和 Figma 令牌一致性。

---

/code-to-figma status

报告：

检查项	方法
Walker 脚本	figma-sync.config.json 是否存在？Walker 文件是否存在？
Gist 新鲜度	gh api gists/<id> --jq '.updated_at' — 报告 Gist 的更新时间距今多久
CI 接线	figma-sync.yml 是否存在？是否包含 workflow_dispatch？
密钥	gh secret list --repo <org>/<repo> — 确认 GIST_TOKEN 和 FIGMA_EXPORT_GIST_ID 是否存在
上次运行	gh run list --workflow=figma-sync.yml --limit=1
Figma 令牌一致性	将当前 .w3c.json 与可用的集合读取结果进行比较；如果无法访问 Figma 或读取数据，则报告为未验证。仅凭 Gist 新鲜度不足以完成验证。

---

技能边界

用户意图	使用
将代码令牌和页面结构导出到 Figma	本技能
将 Figma 设计导入代码	figma-to-code 技能
在 Agent 会话期间，由 Agent 驱动一次性写入 Figma：在文件中创建或编辑变量、集合、节点或组件	官方 figma-use 技能和 use_figma MCP 工具（用于可复用变量／令牌集合时，还可使用 figma-generate-library）——不使用本技能
从代码、HTML 或实时页面在 Figma 中生成一次性屏幕或设计	官方 figma-generate-design 技能或 Figma MCP 写入工具（generate_figma_design、html_to_figma、send_code_to_figma）（Figma MCP 工具，检查日期：2026-10-21）——不使用本技能
手动同步现有 Gist	/code-to-figma sync

本技能不会编辑 Figma 文件。插件（tokens-sync-to-figma）是 Figma 侧的使用方——本技能负责生成它读取的产物。该插件绑定到现有的 Design Tokens 集合；因此，必须先创建一次该集合。其可选的 Agent 路径会交接给 figma-use（参见 references/ci-and-gist-setup.md）。

行为评测

**仅限作者／审阅者：**仅在明确评测本技能时使用场景目录；正常执行任务时请跳过。该目录包含仅描述路由提示的内容，以及隔离的同步／读取结果测试夹具；请勿向执行任务的 Agent 提供标签和断言。该目录不能证明运行通过，合成读取结果也无法验证与实时 Figma 的集成。转换器行为由 tests/walker-patterns-snippets.test.mjs 通过测试夹具进行测试。

参考文件

文件	何时加载
references/walker-patterns.md	生成或更新 walker、DTCG 转换器或通用 Gist 推送器；调整 tokenPath()、显式令牌分类、区块检测或 Next.js 静态导出限制时
references/setup-scaffold.md	生成设置文件、包脚本、Gist 命令、GitHub 密钥、首次同步或插件侧契约细节时
references/figma-export-contract.md	验证 walker JSON 输出结构（meta、sections、节点、令牌引用）时
references/ci-and-gist-setup.md	配置 figma-sync.yml、GitHub 密钥、首次推送 Gist 或设置 tokens-sync-to-figma 插件时
references/benchmarks.md	在 skills.sh 上比较同类技能，或对比本流水线与其他方案时

运行原则

• 读取编译后的输出，而非源文件。 只有在构建后的 HTML+CSS 中，令牌绑定才可解析。源模板可能使用尚未替换的变量。
• tokenPath() 和显式的 $type 映射是约定。 遍历器和 DTCG 转换器必须使用相同的路径函数，并且每个导出的令牌都必须有明确指定的 DTCG 类型。切勿根据原始 CSS 值推断 $type；遇到未知分类或不符合规范的值时，必须报错。
• 遍历器针对特定项目；推送器通用。 遍历器了解项目的 HTML 结构；推送器只了解 Gist API。两者应保持分离。
• 提交 DTCG JSON。 .w3c.json 文件是查看令牌变更的可读差异界面。它应保存在仓库中，而非 .gitignore 中。
• CI 中使用 node，而非 pnpm。 运行生命周期脚本时，pnpm 会向标准输出写入脚本头，导致 > file.json 重定向内容出错。在 CI 步骤中，始终直接使用 node 调用遍历器。