设计 Token 语义化：不要把颜色命名成 blue-500 就结束

设计 Token 语义化：不要把颜色命名成 blue-500 就结束

一、Token 命名决定协作成本

设计 Token 常从颜色和字号开始。很多团队会用blue-500、gray-100这类命名，短期很直观。但业务组件真正需要的是语义：主按钮背景、危险文本、边框弱化、页面背景。只靠色值命名，后续主题和暗色模式会很痛苦。

语义化 Token 的目标，是让设计和代码共享同一套意图。颜色可以变，但语义不变。这样设计系统才能支持主题、品牌和状态演进。

二、Token 要分层

flowchart TD A[基础 Token] --> B[语义 Token] B --> C[组件 Token] C --> D[组件实现]

基础 Token 描述色板，如 blue-500。语义 Token 描述用途，如 color-primary-bg。组件 Token 描述具体组件插槽，如 button-primary-bg。三层职责不同。

如果组件直接使用基础 Token，主题切换时会很难控制。语义层提供了中间抽象，让“主色”在不同主题下映射到不同基础色。

三、代码生成要读取语义

{ "color": { "primary": { "bg": "{palette.blue.500}", "text": "{palette.white}" }, "danger": { "text": "{palette.red.600}" } } }

AI 生成组件时，应读取语义 Token，而不是猜色值。提示词里也要明确：禁止硬编码 hex，禁止使用未登记颜色，组件状态必须引用语义 Token。

.dangerText { color: var(--color-danger-text); }

这样生成结果更容易进入设计系统，也更容易被自动检查。硬编码颜色可以直接作为阻塞项。

四、语义层要定期清理

语义 Token 不是越多越好。若每个页面都新增一个专用语义，系统会变成另一种混乱。新增 Token 前要确认是否已有语义可复用，是否代表稳定意图。

Token 变更要有影响分析。修改color-primary-bg可能影响所有主按钮、导航、链接和强调区域。设计系统需要能列出受影响组件，而不是靠人工猜。

语义 Token 还要覆盖状态。默认、hover、active、focus、disabled、selected、error 都应有明确语义。很多系统只有默认色，状态色靠组件自己推导，最后不同组件的反馈会不一致。

命名也要保持稳定。Token 名称应表达用途，不要夹带当前视觉结果。比如color-action-primary-bg比color-blue-button更适合长期演进。主题变化后，主按钮可能不再是蓝色，但它仍然是主操作。

设计工具和代码仓库之间要有同步机制。Token 从设计工具导出后，需要经过校验、版本化和 changelog，再进入前端包。直接复制 JSON，缺少审计和影响分析，出错后很难追溯。

最后，废弃 Token 要有迁移路径。不能简单删除旧变量，否则历史组件会突然失效。可以先标记 deprecated，给出替代项，再在大版本清理。

Token 校验也应进入 CI。新增样式如果使用未登记变量、硬编码颜色或跳过语义层，应直接失败。这样语义化不是靠自觉，而是成为代码合并的一部分。

五、总结

设计 Token 要从基础色板走向语义 Token 和组件 Token。AI 生成 UI 时应引用语义 Token，避免硬编码色值。

blue-500描述的是颜色，不是设计意图。语义化 Token 才能支撑主题、状态和长期协作。