用途:保持设计系统只有一个真正生效的令牌来源。它先定位所有定义令牌的位置(tokens.json 或 .tokens.json 的 W3C 格式、Figma 变量导出、tailwind.config. 主题、CSS 自定义属性、TS 主题对象、SCSS 变量文件),若存在多个声称权威的来源,会先询问以哪个为准再动手,同步方向由人决定。
主要能力:构建令牌图谱,记录每个令牌的规范值、所有下游定义和消费点;检查代码中的原始值(hex、px、rem、ms、cubic-bezier)是否已有对应令牌。输出 token-drift-report.md,分四类:STALE COPIES(不再匹配规范值的下游定义,附两个值)、HARDCODED(组件中存在匹配令牌的原始值,先精确匹配,再按颜色感知距离近似匹配)、ORPHANS(已定义但无人消费)、UNTOKENIZED(出现 3 次以上且无令牌的原始值)。
使用方式:可执行“Audit my tokens”只做第 1-3 步并出报告;“Sync from [source]”以指定规范源做完整对账;“What's hardcoded?”只看 HARDCODED 类;“Add the CI guard”单独加守卫。同步需经确认:过期副本从规范源重新生成;硬编码精确匹配自动替换,近似匹配逐例确认;未令牌化值按现有命名约定建议名称并加入规范源;孤立令牌仅列出待删,绝不自动删除。可添加 npm run tokens:check 脚本,在 CI 中对新的过期副本或硬编码近似匹配报错。
限制与规则:一次只做单向同步,规范源优先,反向流动须先显式编辑规范源;近似匹配替换逐例进行,不批量(如 #0B1121 与 #0b1220 可能是漂移也可能是决策);保留语义分层,在正确层级修复引用而非全部压平到原始值;重命名要么全传播要么不传播;生成文件(如由 tokens.json 构建的 theme.css)应改源后重建,不手改输出。报告用令牌覆盖率衡量健康度。官方文本与具体安装命令暂未提供。