设计 Token 审计：颜色统一不等于语义统一

一、Token 不是颜色表

很多团队把设计 Token 理解成颜色变量：blue-500、gray-100、radius-8。这能减少硬编码，但还不等于设计系统成熟。真正可维护的 Token 要表达语义：主按钮背景、危险操作文本、弱提示边框、焦点轮廓。

颜色统一只是第一层，语义统一才决定界面能不能随业务演进。

二、审计 Token 使用方式

flowchart TD A[界面样式] --> B[原始值] A --> C[基础 Token] A --> D[语义 Token] D --> E[组件 Token]

审计时要找三类问题：直接写颜色值、只用基础 Token 但没有语义、同一语义在不同组件里使用不同 Token。第三类最隐蔽，视觉上可能差不多，但主题切换时会散掉。

token_audit: forbid_raw_value: true prefer_semantic_token: true detect_duplicate_meaning: true track_component_override: true

审计报告要指向具体文件和组件，否则修复成本会很高。

三、语义命名要稳定

语义 Token 不应该描述颜色本身，而要描述用途。color-danger-text比red-600更适合业务代码，因为未来危险色可能从红色变成橙色，调用方不需要改。

:root { --color-action-primary-bg: #2563eb; --color-action-primary-text: #ffffff; --color-feedback-danger-text: #dc2626; }

命名稳定后，主题切换、暗色模式、品牌换肤都会更顺。

四、审计要覆盖状态和层级

Token 审计不能只扫默认状态。hover、active、disabled、focus、selected、error 都可能出现临时色值。尤其是焦点轮廓和错误提示，常被业务页面自己补样式。

state_token_check: hover: required focus_visible: required disabled: required error: required selected: required

还要检查视觉层级。标题、正文、弱提示、占位符、辅助说明如果都使用相近灰度，界面会失去信息秩序。Token 审计应该输出对比度和层级关系，而不是只看变量是否存在。

最后，审计要接入 CI。新增原始颜色值、新增未登记 Token、语义 Token 被错误复用，都应触发提醒。Token 体系一旦靠人工记忆维护，很快会长出新的旁路。

Token 审计还要关注跨端映射。Web、iOS、Android、Flutter 可能使用不同单位、命名和主题机制。如果只审计 Web 代码，移动端仍可能出现另一套颜色和圆角。统一源数据，再生成各端产物，会比人工同步稳定。

token_pipeline: source: tokens.json targets: - css_variables - flutter_theme - ios_assets - android_resources

设计侧也需要审计。组件库代码已经语义化，但设计稿里仍然直接使用局部色值，工程就会被迫迁就。可以定期扫描设计文件，找出未绑定 Token 的颜色、字号和间距。

最后，Token 变更要有影响面报告。比如修改color-feedback-danger-text，应列出受影响组件、页面截图和对比度变化。这样评审看到的不只是变量改动，而是界面后果。

五、总结

设计 Token 审计要检查原始值、语义命名、状态覆盖、层级关系和 CI 约束。

颜色统一不等于语义统一。Token 的目标不是变量更多，而是界面决策更可控。