设计令牌（Design Tokens）简明入门
如果你曾经更新过品牌色，然后花了一个小时在样式表里到处搜寻那些硬编码的 #3B82F6，那么你已经理解了设计令牌所要解决的问题。本文将介绍什么是设计令牌、它们与普通 CSS 变量有何区别，以及如何在前端样式工作流中开始使用它们。
关键要点
- 设计令牌是具名的、可复用的值，以平台无关的格式承载设计决策，使同一套定义能够从单一可信源驱动 Web、iOS 和 Android 的样式。
- 基础令牌（Primitive Tokens）保存原始值，而语义令牌（Semantic Tokens）引用基础令牌并附加使用意图，形成一个灵活的双层体系，可以干净地扩展。
- 设计令牌和 CSS 变量相关但有所不同：令牌是源（通常是 JSON），而 CSS 变量是通过 Style Dictionary 等工具生成的众多可能输出之一。
- 你可以从简单的颜色和间距基础令牌起步，随着设计体系的成熟，再逐步加入语义令牌并构建工具链。
什么是设计令牌？
设计令牌是具名的、可复用的值，用于表示你的设计决策——例如颜色、间距、排版、边框圆角和阴影。你不再直接在组件中写 padding: 16px，而是引用一个像 space-4 这样持有该值的令牌。
从本质上看，每个设计令牌只是一个名称与一个值的配对。但作为一种方法论，它的意义远不止于此。设计令牌社区组（DTCG） 是致力于推动统一规范的 W3C 社区组，他们将其描述为一种以平台无关的格式来表达设计决策的方式，使其能够在不同的学科、工具和技术之间共享。
“平台无关”这一点很关键。同一组令牌定义可以转换为 Web 端的 CSS 自定义属性、iOS 端的 Swift 常量，或 Android 端的 XML 值——全部来自单一可信源。
常见的设计令牌类别
大多数设计系统将令牌组织为以下几个类别：
- 颜色（Color） —— 品牌色板、文字颜色、背景、边框
- 间距（Spacing） —— padding、margin、gap 值
- 排版（Typography） —— 字体族、字号、字重、行高
- 边框圆角（Border radius） —— 组件的圆角处理
- 阴影（Shadow） —— 层级与深度效果
基础令牌 vs. 语义令牌
这种区分是使用设计系统令牌时最有用的概念之一。
基础令牌（也称为 base 或 global 令牌）是不带使用语义的原始值：
{
"color-blue-500": { "$value": "#3B82F6", "$type": "color" },
"space-4": { "$value": "16px", "$type": "dimension" }
}语义令牌 引用基础令牌并附加意图。它告诉你某个值应该用在哪里，而不仅仅是它是什么：
{
"color-action-primary": { "$value": "{color-blue-500}", "$type": "color" },
"spacing-component-padding": { "$value": "{space-4}", "$type": "dimension" }
}当你更改 color-blue-500 时，所有指向它的语义令牌都会自动更新。这才是这个体系的真正威力所在。
Discover how at OpenReplay.com.
设计令牌 vs. CSS 变量
CSS 变量和设计令牌相关，但并非同一回事。
| 方面 | 设计令牌 | CSS 变量 |
|---|---|---|
| 作用范围 | 平台无关 | 仅限 CSS |
| 格式 | JSON（或类似格式） | 原生 CSS |
| 工具链 | 需要构建步骤 | 浏览器原生支持 |
| 最适用于 | 多平台设计系统 | 仅 Web 的主题化 |
设计令牌是源。CSS 变量通常是输出。像 Style Dictionary 这样的工具会把你的令牌定义转换为各平台所需的格式。
一个简单的实用示例
以下是使用 DTCG 风格语法定义的一组小型令牌：
{
"color-blue-500": { "$value": "#3B82F6", "$type": "color" },
"color-text-primary": { "$value": "{color-blue-500}", "$type": "color" },
"space-4": { "$value": "16px", "$type": "dimension" }
}通过 Style Dictionary 处理后，CSS 输出如下：
:root {
--color-blue-500: #3B82F6;
--color-text-primary: var(--color-blue-500);
--space-4: 16px;
}现在，你的组件使用 var(--color-text-primary) 而不是硬编码的十六进制值。只需修改一次令牌，所有地方就会同步更新。
在设计端，Figma 变量 遵循同样的”基础到语义”模式，使设计和代码更易于保持一致。
起步要小，扩展要有意识
你不需要在第一天就建立完整的令牌体系。先从颜色和间距的基础令牌开始，当模式逐渐显现时再加入语义层，等手工流程成为瓶颈时再引入工具链。
结语
设计令牌不仅仅是组织 CSS 的一种方式——它们是设计师与开发者之间的共同语言。一旦这门语言确立起来，产品中的一致性就不再是你需要手动去强制执行的事情，而是变成了系统自动为你处理的事情。
常见问题
不需要。即便没有正式的设计系统，你也可以从单个 JSON 文件或样式表中一组扁平的基础令牌（颜色和间距）起步。令牌往往会成为后续设计系统赖以生长的基础，因此尽早引入它们实际上会让日后构建更大的体系变得更容易。
大多数工具类框架允许你从共享的令牌源生成其主题值。在 Tailwind CSS v4 中，设计令牌通常通过 @theme 变量暴露，进而自动生成对应的工具类。像 Style Dictionary 这样的工具可以帮助这些值在 Web 和其他平台之间保持同步。
当你发现某个基础令牌在许多组件中被反复用于特定用途时——比如某种蓝色被一致地用于操作按钮——就该加入语义令牌了。当你需要主题化（例如暗黑模式）时，语义令牌就变得必不可少，因为它们让你能够切换语义，而无需在整个代码库中重命名每一处基础令牌引用。
可以。主题通常通过将语义令牌重新映射到不同的基础令牌来工作。在浅色主题下，color-text-primary 可能指向深灰色；而在深色主题下则指向浅灰色。组件只引用语义令牌，因此切换主题不需要修改任何组件，只需切换一套不同的令牌映射即可。
Truly understand users experience
See every user interaction, feel every frustration and track all hesitations with OpenReplay — the open-source digital experience platform. It can be self-hosted in minutes, giving you complete control over your customer data. . Check our GitHub repo and join the thousands of developers in our community..
