Design Token 实战：先定义角色，再决定颜色

Reference Token 描述原始色阶和空间尺度；Semantic Token 描述成功、警告、表面、正文等角色；Component Token 才描述按钮、输入框和卡片。

如果组件直接引用品牌绿或灰色 300，主题切换与状态校正最终都会变成全局搜替换。

主色用于可操作信号，不应用来铺满页面。成功、警告、错误必须同时有文字和图标等非色彩线索。

浮萍绿适合作为本站的生长与完成信号，但它不能替代所有 CTA，也不能被当成信息背景。

为每个 Token 写清使用边界：谁可以用、什么场景禁用、对比度要求是什么。设计稿、组件库和代码使用同一套命名，Token 才会成为协作语言。

版本升级时记录废弃项与替代项，避免旧页面长期持有过期视觉债务。

已有产品通常已经存在大量直接色值。迁移时不要先全局搜 hex 并替换变量，而要抽样按钮、输入框、表格、浮层和状态组件，判断每个值在承担背景、文本、边界、交互还是反馈角色。

同一个灰色可能同时被用于禁用文本、分割线和 hover 背景，这并不意味着它们应该共享 Semantic Token。角色不同就要拆开，否则未来调整对比度时会牵一发动全身。

先完成高频组件的角色映射，再把重复决策上提为 Token。Token 是稳定语义的结果，不是给每个现有色值换一个更长的名字。

Light 与 Dark 不是两张互相取反的色卡。Surface 层级、文字强调、边界可见度、状态背景和交互反馈在两个主题里都要保持相同关系。

验证时按组件状态生成矩阵：default、hover、active、focus、disabled、loading、success 和 error。每个状态同时检查对比度与辨识方式，确保颜色变化之外还有文本、图标或形状线索。

主题 Token 应通过 alias 控制组件，不要在组件内部写 dark 条件分支。否则新增高对比主题或品牌主题时，逻辑会散落在整个代码库。

Token 一旦被多个应用消费，就具有 API 属性。修改值可能改变视觉，改名则会破坏构建，因此需要 owner、版本、changelog、deprecated 标记和迁移期限。

新增 Token 前先回答现有语义为何不能覆盖；删除前统计使用范围并给出替代项。对 Component Token，最好由组件包和 Token 包同步发布，避免消费者拿到新组件却仍使用旧主题。

持续检查可以进入 CI：禁止新增未登记色值、验证引用不存在断链、生成主题预览和对比度报告。Design Token 只有进入工程治理，才不只是设计文件中的一张表。