Design Token（设计令牌）是把设计决策抽成“有名字、可复用、能跨工具传递”的最小单元。颜色、字号、间距、圆角、阴影这些反复出现的选择，一旦被命名成 token，同一套决定就能同时作用在设计稿、组件库和前端代码上；改一次，三处一起变，而不是靠人去逐个替换。
它和站内常说的“设计变量”是同一件事的两个视角：设计变量偏工具里的功能与操作，token 偏工程侧的规范与传递。先在工具里把变量建起来，是理解 token 最直观的入口，可参考什么是设计变量；本文重点讲 token 怎么分层、怎么命名、怎么落地到组件与代码。
先分清三个容易混的概念
| 概念 | 回答的问题 | 典型形态 |
|---|---|---|
| 设计变量 | 这个值在工具里叫什么、怎么改 | 颜色变量、文本变量、数值变量 |
| Design Token | 这个决定怎么跨设计稿与代码统一传递 | 分层的命名集合 + 可导出的值 |
| 组件属性 | 这个组件在不同场景怎么表现 | 尺寸、状态、是否带图标 |
简单说：变量是“值”，token 是“有约定含义的值”，组件属性是“组件允许你改什么”。三者经常一起出现，但职责不能混：把组件属性当 token 用，会让 token 表迅速膨胀。
三层结构：基础值、语义、组件
token 的价值来自分层。同一份颜色只维护一次，越往上越贴近业务，越往下越稳定。
| 层级 | 例子 | 改动频率 |
|---|---|---|
| 基础值 | blue-600、gray-100、size-16 | 几乎不改，只在品牌规范调整时变 |
| 语义 | text-primary、bg-surface、border-subtle | 较低，语义含义稳定 |
| 组件 | button-bg-primary、input-border-error | 随组件调整，但不直接写色值 |
判断分层是否合理，用一个问题就能测：换主题时，需要改动的 token 是不是集中在语义层？如果需要挨个改组件 token，说明层级还没拆开。
命名规则：能读、能搜、能换主题
- 用含义不用外观：用 text-primary 而不是 dark-gray，否则换主题时名字会骗人。
- 按“类别-用途-程度”排列：bg-surface、bg-surface-hover、text-danger-strong，顺序固定才搜得到。
- 不在名字里写具体值：不要出现 blue-按钮 这类混写，值放右边，名字只描述用途。
- 组件层带组件前缀：button-、input-、table-，让归属一目了然。
token 在工具里长什么样
落到工具里，token 通常以一个集中管理的列表存在：名称、类型、当前值，加上按类型分组的入口。集中管理的意义是让“改值”和“用值”分离，避免每个页面各自定义。
如果团队已经在用变量管理颜色、字号，下一步不是新建一套 token 表，而是把命名和分层补齐；颜色变量的实操路径可参考颜色变量实战教程。
从设计到代码：token 怎么传下去
token 从设计侧到代码通常走四步：设计侧定值并命名 → 导出成结构化数据 → 前端映射为变量或主题配置 → 组件只引用变量。任何一步用“手抄值”补上，都会在下次改主题时失效。
验收方式是看改动成本：换一次品牌色，理想状态只改基础值或语义层，页面、组件和代码同步生效；如果还要逐个页面调整，说明中间某一步仍然写死了具体值。
多主题为什么靠 token 才成立
深浅模式、多品牌、多端密度，本质都是同一套语义在不同取值下的组合。做法是给语义 token 增加“模式”维度，让同一个名字在不同模式下取不同值，页面与组件不需要知道自己处在哪个主题里。
这也是 token 与普通样式表最大的区别：样式表描述“现在长什么样”，token 描述“在什么条件下取什么值”。多主题切换的完整做法，可参考深浅主题切换怎么设计。
四种常见失效场景
| 场景 | 表现 | 修正方向 |
|---|---|---|
| 值被写死 | 组件里直接填色值，换主题后不变 | 绑定到语义 token，禁止直接填值 |
| 命名失控 | 同色出现 5 种叫法，搜不到 | 固定命名顺序，集中评审 |
| 层级颠倒 | 组件 token 被页面直接引用 | 页面只引用语义层，组件内部再向下取用 |
| 缺少单一来源 | 设计和代码各维护一份值 | 指定唯一来源，导出而不是手抄 |
落地顺序：从 10 个语义 token 开始
- 第一步：统计现有页面里重复出现的颜色、字号、间距，选出最高频的 10 个。
- 第二步：为它们建立基础值与语义两层，先在一条真实业务链路上替换。
- 第三步：把替换结论写进组件规范，禁止组件内部出现具体数值，做法可参考组件库治理。
- 第四步：补上导出与代码映射，让设计与前端共用一份来源。
整条路径和设计系统本身的搭建顺序是一致的，模块、变量与评审机制的完整关系可参考设计系统怎么搭建。
Design Token 落地检查清单
| 维度 | 检查项 |
|---|---|
| 分层 | 基础值、语义、组件三层齐全，页面只引用语义层 |
| 命名 | 按固定顺序命名，名字描述用途而非外观 |
| 绑定 | 组件与页面元素均绑定 token，无写死具体值 |
| 模式 | 深浅主题通过模式取值，而非复制一整套组件 |
| 来源 | 设计与代码共用一份来源，通过导出同步 |
| 维护 | 新增 token 有评审与命名规则，废弃 token 有替代方案 |
常见问题
Design Token 和 CSS 变量是一回事吗？
不是。token 是设计与工程共用的命名约定，CSS 变量只是它在网页端的一种落地形式；同一个 token 在小程序、原生端或主题配置里可以有不同实现。
小团队需要一开始就做完整 token 体系吗？
不需要。先做 10 个左右高频语义 token，覆盖颜色和字号即可；规模扩大后再补基础值与组件层，避免一开始就陷入命名讨论。
已经有了组件库，还需要单独管 token 吗？
需要。组件库解决结构复用，token 解决取值统一：两者分开管理，换主题时才不会挨个改组件。
总结
Design Token 的本质是把设计决策变成可复用、可传递、可切换的命名值：基础值保证稳定，语义层承载含义，组件层承接具体场景，再通过导出让设计与代码共用一份来源。先做 10 个高频语义 token、替换一条真实链路，比一次性设计完整体系更容易落地。
