design-tokens-sync

设计令牌同步

确保唯一真实来源始终名副其实。每个设计系统都会以相同方式逐渐失控：有人匆忙硬编码一个十六进制值，在 Figma 中重命名了令牌，却没改 Tailwind；某个一次性 CSS 文件里又出现了一份调色板的副本。本技能会找出偏差，与用户确定方向，然后协调一致。

工作流

1. 定位真实来源。 找出令牌定义的所有位置：tokens.json/*.tokens.json（W3C 格式）、Figma 变量导出文件、tailwind.config.* 主题、CSS 自定义属性、TS 主题对象、SCSS 变量文件。如果有多个来源都声称自己是权威来源，在进行任何修改之前询问以哪个为准——同步方向由人决定。
2. 构建关系图。 对于每个令牌，记录其权威值、所有下游定义和所有使用位置。对于代码中的每个原始值（十六进制、px、rem、ms、cubic-bezier），判断是否存在对应令牌。
3. 偏差报告。 输出 token-drift-report.md，分为以下四类：
   • STALE COPIES —— 与权威来源不再一致的下游定义（同时列出两个值）
   • HARDCODED —— 组件中存在原始值，且有匹配令牌（先精确匹配，再为颜色查找感知距离较近的匹配）
   • ORPHANS —— 已定义但从未使用的令牌
   • UNTOKENIZED —— 出现 3 次或以上但没有对应令牌的原始值；这些值正等待被命名为令牌
4. 经批准后协调一致。 过时副本：根据权威来源重新生成下游内容。硬编码值：替换为令牌引用——精确匹配自动替换，近似匹配则逐项确认（略有偏差的蓝色可能是有意为之）。尚未令牌化的值：遵循现有命名规范提出名称，并添加到权威来源。孤立令牌：列出以供删除；绝不自动删除。
5. 设防。 提议添加一个成本低廉的预警机制：编写脚本（npm run tokens:check），重新运行偏差检测，并在出现新的过时副本或硬编码近似匹配时使 CI 失败，这样你离开后系统也能保持同步。

规则

• 一次运行中绝不双向同步。以权威来源为准；任何反向流动的修改（例如设计师希望采用代码中的较新值），都必须先显式修改权威来源。
• 近似匹配的替换必须逐项确认，绝不批量处理。#0B1121 与 #0b1220 之间的差异可能是偏差，也可能是有意决定。
• 保留语义层级：如果系统有 color.blue.500 -> color.accent -> button.bg，就在正确的层级修复引用，而不是把所有内容都扁平化为基础值。
• 重命名必须传播到所有位置，或完全不传播——只重命名一部分的令牌比旧名称更糟。
• 尊重生成文件：如果 theme.css 由 tokens.json 构建，就修改源文件并重新构建；绝不手动编辑输出文件。
• 报告要量化健康状况：令牌覆盖率（组件中已令牌化的值占原始值总数的比例）是每次发布都应提升的指标。

快捷命令

• “审计我的令牌”——执行第 1 至 3 步，仅生成报告
• “从 [source] 同步”——使用指定的权威来源进行完整协调
• “哪些值是硬编码的？”——仅查看 HARDCODED 类别
• “添加 CI 预警机制”——单独执行第 5 步