用 Codex 同步 Figma 设计 Token：7 步让变量、CSS 与组件不再漂移

admin 设计创意 1小时前

7 0

Figma 变量、代码里的 CSS 自定义属性、Tailwind 配置和组件样式经常各自演进，最后形成“设计稿改了、页面没改”或“代码修了、下一次导出又被覆盖”的漂移。下面用 Codex 建立一条可审计的同步链：先确定唯一事实源，再把 token 变换、组件迁移和视觉回归连起来。本文以 Figma 官方变量指南、Design Tokens Community Group 稳定格式、Style Dictionary、OpenAI 官方 Figma-to-code 用例和 Playwright 文档为依据，示例可直接按项目调整。

Codex 与 Figma 设计 Token 的单向可重复同步链 — 先确定唯一事实源，再将变量转换成代码资产，并用组件与视觉证据验证。

适合哪些场景

Figma 已使用 variables / modes，前端也有 CSS variables、Tailwind 或主题文件；
需要用 Codex 批量迁移硬编码颜色、间距、圆角和排版；
同一产品有 light / dark 或品牌主题，设计与代码经常不同步；
希望把设计稿到代码的交付，从“人工对眼”升级为可重复检查。

第一步：只读审计，先决定谁是唯一事实源

先不要让 Codex 修改文件。请它读取项目的 AGENTS.md、包管理脚本、现有 token 文件、主题配置和组件目录；同时从 Figma 获取变量集合、mode、alias 和一张基准截图。OpenAI 官方 Figma-to-code 用例建议先取得设计上下文、元数据和截图，并优先复用仓库已有组件与 token。若团队还没有稳定的 Figma 导出或 API 权限，也可以暂时让代码仓库的中立 JSON 成为事实源，再由设计和工程共同审阅。

先做只读审计，不修改任何文件：
1. 读取 AGENTS.md、package.json、tokens、styles、Tailwind 和组件目录。
2. 列出 Figma Variables 与代码 token 的对应关系。
3. 标记重复值、硬编码值、缺失 alias、未覆盖 mode。
4. 输出 source-of-truth 建议、风险和最小迁移范围。
不要输出或记录任何 token、cookie、API key。

设计 Token 的 primitive、semantic 与 component 三层结构 — 用 alias 保留替换关系，让组件消费语义而不是直接消费原始值。

第二步：把 token 分成原始、语义和组件三层

Figma 官方文档把变量定义为可复用值，并用 collection 与 mode 管理主题；alias 则能表达变量之间的关系。实践中可分为三层：primitive 保存原始色值和尺寸，semantic 表达 action、surface、text 等用途，component 只在确有必要时定义按钮或输入框的专属角色。组件不应直接读取 #2563EB，而应读取 color.action.primary；light / dark 改的是语义映射，不是每个组件的实现。

第三步：用 DTCG JSON 建立中立合同

Design Tokens Community Group 在 2025.10 发布首个稳定格式，可用 $type、$value 和 alias 表达工具间交换。需要准确说明：它是 Community Group Report，并非 W3C Recommendation。下面示例把原始色与语义色分开；不同 mode 可以拆成独立集合或由转换配置注入。

{
  "color": {
    "blue": {
      "600": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922], "alpha": 1 } }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.600}", "$description": "主要操作与焦点" }
    }
  }
}

第四步：让转换可重复，不手改生成文件

Style Dictionary 官方文档支持 DTCG 的 $value、$type 和 $description，适合把同一份 JSON 变成 CSS 与 TypeScript。先复用项目已有构建工具；如果项目没有 Style Dictionary，不要为了教程盲目引入。生成文件写明来源并由脚本覆盖，人工修改只发生在源 token。

/* generated/tokens.css — do not edit */
:root {
  --color-action-primary: #2563eb;
  --space-control-gap: 1rem;
  --radius-control: 0.5rem;
}
[data-theme="dark"] {
  --color-action-primary: #60a5fa;
}

Codex 设计 Token 任务的输入边界与交付证据 — 明确输入、禁止事项和验收证据，避免范围扩张或只交付视觉近似。

第五步：用任务合同让 Codex 迁移组件

一次只迁移一个组件族，例如 Button、Input、Card。提示词必须同时给出输入、边界和证据：禁止新 UI 库、禁止新增硬编码值、禁止无关重构；要求列出每个旧值映射到哪个语义 token，并运行现有检查。下面可直接使用。

读取 AGENTS.md、token 源文件、生成脚本和 Button 组件。

目标：把 Button 的颜色、间距、圆角迁移到现有语义 token，并覆盖 default、hover、focus-visible、disabled、loading。

边界：
- 不引入新 UI 库，不修改无关页面；
- 不硬编码新的颜色或尺寸；
- generated 文件只通过现有脚本生成；
- 若设计变量与代码冲突，先报告，不自行选择覆盖方向。

交付：
- 修改文件清单和旧值 → 新 token 映射；
- 未覆盖状态与原因；
- lint、typecheck、build、组件测试结果；
- 390 / 768 / 1440px 的固定环境截图。

第六步：逐一检查 mode 与交互状态

变量同步最容易漏掉的不是默认态，而是 hover、focus-visible、disabled、error、selected 和 loading。对每个支持的 mode 建立小矩阵，确认文本与背景对比度、焦点轮廓和禁用状态仍清楚。不要因为 Figma 有 high-contrast mode 就假设代码已经支持；只有设计、实现和测试都存在时才把它列为已完成。

Token 值代码检查与 Playwright 视觉回归闭环 — 差异报告、构建检查、固定环境截图和人工语义复核缺一不可。

第七步：用 Playwright 固定视觉证据

Playwright 的 toHaveScreenshot() 可比较页面或组件截图，但官方明确提醒：操作系统、浏览器、字体与硬件不同都可能改变像素。基线和 CI 必须使用同一环境、固定 viewport 与设备像素比。截图通过后仍需人工核对 Figma：自动化能发现像素变化，却不能判断一个 token 的语义是否用错。

await expect(page.getByTestId("button-states"))
  .toHaveScreenshot("button-states-light.png");

await page.locator("html").setAttribute("data-theme", "dark");
await expect(page.getByTestId("button-states"))
  .toHaveScreenshot("button-states-dark.png");