设计令牌Design Token

设计令牌实验台：改一处，引用处一起换

任务是为「项目申请卡」定 token。换品牌主色、调 --space-md 与 --radius-card，顶条、徽章、输入、按钮和留白同步响应；再点「打破徽章」，看偷写的死值如何脱钩。顶条色、徽章、留白和审计计数都长在卡片物件上。

面板里测到的结论

刚才顶条、徽章和留白随 token 整体联动、偷写值却原地不动，对应的就是命名、单一来源、改一处全局更新、脱钩与审计这几条主线。

• 命名即意图：--brand / --space-md / --radius-card 说用途，而不是 #3d4a7a / 16px / 8px。
• 单一来源：一个 token 被顶条、徽章、按钮、链接同时引用；token 是这些组件的共同上游。
• 改一处全局更新：调 --space-md 或换 --brand，所有引用处一起换，组件代码零改动。
• 偷写魔法数就脱钩：组件写死 hex/px 不再引用 token，换 token 时它不变，和引用处对不上。
• 审计可数：把每个组件的实际值对照 token，数出差值，得到「不一致 X/N」。

什么时候专门搭令牌

出现同一视觉决策反复出现、要做品牌换色或深色模式、多端或多组件库复用时搭；只一两处装饰色、一次性静态页不必上整套。

从重复决策到可审计的 token

不要从 hex 开始。先列重复决策，再分层命名，让组件只引用，最后用审计数出脱钩项。

1. 列重复决策：扫一遍界面，把反复出现的颜色、间距、圆角、字号、阴影列出来，作为候选 token。
2. 分层命名：基础值（scale.500）→ 语义 token（color.brand / space-md / radius-card）→ 组件级（button.bg），命名说用途和状态。
3. 组件只引用：代码里写 var(--brand) / space-md，禁止裸 hex/px；新决策先加 token 再使用。
4. 改 token 验证全局：换一个 token，检查所有引用处是否一起更新；没跟上的就是偷写值，记下来。
5. 加审计：用 lint 或脚本数出裸 hex/px 和不一致项，把「不一致 X/N」纳入评审，防止魔法数回潮。

同一张申请卡：正例与反例

目标都是让徽章跟着品牌主色一起换。差异只在徽章是引用 token 还是写死 hex。