设计令牌多源同步对齐

设计系统为什么会漂移

当 tokens.json、Figma 变量、tailwind.config.*、CSS 自定义属性和 SCSS 变量各自演化时，设计系统会以同一种方式衰败：某个 hex 被匆忙硬编码进组件；令牌在 Figma 里改了名但 Tailwind 没跟上；一份一次性 CSS 里又长出第二份调色板。多个来源都声称自己才是唯一真相，漂移就此产生。

技能如何工作

这个技能先找到所有定义令牌的位置：W3C 格式的 tokens.json/*.tokens.json、Figma variables 导出、tailwind.config.* 的 theme、CSS 自定义属性、TS theme 对象和 SCSS 变量文件。如果不止一个来源声称 canonical，它不会擅自动手，而是先问清同步方向。随后为每个令牌构建映射图：canonical 值、所有下游定义和每个消费点；同时检查组件里的原始值（hex、px、rem、ms、cubic-bezier）是否已有对应令牌。

报告写入 token-drift-report.md，分四类：STALE COPIES（下游定义与 canonical 不一致，并列出两个值）、HARDCODED（组件里存在完全或近似匹配的硬编码值）、ORPHANS（定义了但无人消费）、UNTOKENIZED（原始值出现 3 次以上且无令牌）。经用户批准后执行修复：stale copies 从 canonical 重新生成下游；hardcoded 替换为令牌引用，精确匹配自动处理，近匹配逐例确认；untokenized 按现有约定提议命名并加入 canonical；orphans 只列清单供删除，绝不自动删除。最后可以加一道 CI 防护：用 npm run tokens:check 重新跑漂移检测，在新 stale copies 或硬编码近匹配出现时让 CI 失败。

适用边界与注意点

• 单次运行永远不做双向同步。Canonical 赢；任何反向流动都必须先明确编辑 canonical。
• 近匹配替换逐例进行，绝不批量。#0B1121 与 #0b1220 可能是漂移，也可能是有意为之。
• 保持语义分层：如果系统有 color.blue.500 → color.accent → button.bg，就在正确层级修复引用，而不是全部扁平化成 primitives。
• 重命名要么全链路传播，要么完全不动；半截改名比旧名字更糟。
• 尊重生成文件：theme.css 若由 tokens.json 构建，就修源文件再 rebuild，不手改输出。
• 报告用 token coverage percentage（组件中令牌化值与原始值的比例）量化健康度，这是逐版本改进的指标。
• 安全上不自动安装依赖、修改系统权限、创建持久化任务或执行下载内容；涉及发送、发布、删除、付款、部署等外部写入时，先展示目标与影响并取得明确确认。凭据只用于用户指定的官方服务，不回显、不记录、不转发。命令和代码默认仅供参考，只有在用户明确要求且目标范围清楚时才执行。