Design Token(设计令牌)是给可复用的设计决策加上名称、类型和取值,例如正文颜色、标题字号、按钮内边距。团队用同一名称讨论和传递这些决定,再把它们映射到设计变量、组件样式与代码。命名本身不会让设计稿和代码自动同步,更新还需要经过明确的数据来源、转换和发布流程。
在墨刀设计中,可以先把颜色、文字等重复选择整理成变量与组件规则。本文在此基础上,用一个预约按钮从常规16px水平内边距改为紧凑12px的例子,说明token如何分层、怎样生成CSS,以及更新后应检查什么。

Design Token、设计变量与组件属性怎样区分
| 概念 | 解决的问题 | 预约按钮中的例子 |
|---|---|---|
| Design Token | 用什么稳定名称描述设计决定,并跨工具传递 | control.padding.x表示控件水平内边距 |
| 设计变量 | 在设计工具内如何保存、绑定和切换值 | 把需要复用的数值或颜色绑定到图层属性 |
| 组件属性 | 这个组件允许使用者选择哪些表现或状态 | 常规/紧凑、主按钮/次按钮、是否加载 |
| CSS自定义属性 | 网页代码如何引用可复用的值 | 用var(--control-padding-x)设置按钮间距 |
设计变量可以承载token,但两者并非天然一一对应:一个随手命名的局部变量未必已经有跨团队约定,某些工具变量还承载文本或开关逻辑。组件属性则负责选择哪种样式,内部可以再引用token。需要先了解工具操作时,可阅读设计变量的含义与用途。
基础、语义、组件三层,按需要使用
常见的分层是“基础值→语义用途→特定组件”。它帮助分开一个值是什么、用在哪里,以及某个组件有什么例外。但小团队不必先把三层全部建齐;只有少量页面时,基础值和语义用途两层就能开始,甚至一组清楚的语义名称也有价值。
| 层次 | 示例 | 什么时候值得保留这一层 |
|---|---|---|
| 基础值 | space.4=16px | 多个用途共用同一套间距刻度,需要集中调整 |
| 语义用途 | control.padding.x引用space.4 | 希望组件表达“控件水平内边距”,不直接依赖某个数字 |
| 组件专用 | booking-button.padding.x | 预约按钮有独立规则,需要与普通控件分开演进 |
本例采用前两层。若预约按钮与其他控件一致,就直接引用control.padding.x;只有它需要独立调整时,再增加组件专用项。层数越多并不必然越好,重复转发而没有独立含义的名称会增加维护成本。
基础值也可能因密度、品牌或平台适配发生变化,不能预设它“几乎不改”;页面和组件是否可直接使用某一层,则由团队规则决定。分层的判断依据是能否理解改动影响,而不是所有文件是否长成同一棵树。
先给一个小范围写清命名与维护规则
从已经重复出现、又确实需要统一调整的选择开始,例如正文颜色、主要操作色、标题字号、字段间距和按钮圆角。不必为了达到10个或100个名额造新token,也不必立即把所有固定数值都抽出来。
- 语义名称描述用途:text.primary比dark-gray更适合长期表达正文角色;基础色板使用gray.600等刻度名称则合理。
- 同一层保持命名顺序:例如类别、对象、方向依次组成control.padding.x。点号表示本文的路径分隔,JSON中会用嵌套对象表达。
- 刻度不是像素承诺:本例space.4表示第4档间距,不表示4px。不要命名为space.16px后又把它改成12px。
- 区分共享规则与例外:某个图标需要1px视觉修正,可以说明局部原因;一批按钮都重复使用的间距则更适合统一维护。
再明确一份能执行的小规范,避免设计和开发各自维护一套同名值:
| 约定项 | 本练习的决定 |
|---|---|
| 范围 | 只管理预约按钮水平内边距,其他样式暂不扩展 |
| 主要来源 | 项目中的tokens.json;设计画布按已批准版本对照更新 |
| 维护与确认 | 设计提出间距变更,组件维护者确认影响,再更新源文件 |
| 版本 | v1常规16px;v2紧凑候选12px,保留各自修改记录 |
| 生成与使用 | 运行转换脚本生成tokens.css,页面加载它,组件引用CSS变量 |
| 完成条件 | 源值、生成文件、设计样张与页面表现对上同一版本 |
这是一种以代码仓库文件为来源的组织方式。团队也可以选择设计工具或专门的token仓库为主要来源,只要写清方向、负责人和同步时机。早期用人工表格记录同样可以工作,关键是保留版本并核对差异;不能把“手工记录”直接等同于“必然失效”。

已经使用颜色变量的团队,可以保留现有集合,逐步补齐用途和命名,不必重建另一份平行台账。具体绑定方法可继续参考颜色变量教程。
可运行例子:源值→CSS变量→预约按钮
下面使用本地Node.js与浏览器完成一个小练习。三个文件放在同一目录,不需要额外安装依赖。它演示的是工程侧转换,不代表墨刀已经提供这段脚本对应的自动导出或双向同步功能。
第一步:把有类型的值写进tokens.json
DTCG 2025.10格式文档用$type声明类型、$value保存值。dimension的值包含数字value与单位unit;本例使用px。语义token通过花括号路径引用基础token。这是社区组发布的格式规范,不应称为W3C正式标准。
{
"space": {
"4": {
"$type": "dimension",
"$value": { "value": 16, "unit": "px" }
}
},
"control": {
"padding": {
"x": {
"$type": "dimension",
"$value": "{space.4}"
}
}
}
}
space.4拥有实际值16px,control.padding.x引用它。这里的引用保留了用途与数值之间的关系;以后修改基础值时,可以重新解析所有使用它的语义项。
第二步:生成页面能加载的CSS
保存下面的build-tokens.mjs。为了便于阅读,它只处理本例明确声明为dimension的两个token及其花括号引用,不是实现完整DTCG规范的通用转换器。
import fs from 'node:fs/promises';
const tokens = JSON.parse(await fs.readFile('tokens.json', 'utf8'));
const names = ['space.4', 'control.padding.x'];
function dimension(name, trail = []) {
if (trail.includes(name)) {
throw new Error('循环引用: ' + [...trail, name].join(' -> '));
}
const token = name.split('.').reduce((node, key) => node?.[key], tokens);
if (!token || token.$type !== 'dimension') {
throw new Error('缺少 dimension token: ' + name);
}
const value = token.$value;
const ref = typeof value === 'string' && value.match(/^\{([^{}]+)\}$/);
if (ref) return dimension(ref[1], [...trail, name]);
if (!value || !Number.isFinite(value.value) ||
!['px', 'rem'].includes(value.unit)) {
throw new Error('无效 dimension 值: ' + name);
}
return String(value.value) + value.unit;
}
const lines = names.map(name =>
' --' + name.replaceAll('.', '-') + ': ' + dimension(name) + ';'
);
await fs.writeFile('tokens.css', ':root {\n' + lines.join('\n') + '\n}\n');
console.log('已生成 tokens.css');
在这三个文件所在目录执行:
node build-tokens.mjs
生成的tokens.css应为:
:root {
--space-4: 16px;
--control-padding-x: 16px;
}
本脚本在生成时把引用解析成最终值,引用关系继续保存在tokens.json中。修改JSON后必须重新运行脚本;直接手改tokens.css,下次生成就会被覆盖。若团队选择保留CSS变量之间的引用,也需要考虑变量作用范围与主题覆盖方式,不能把两种策略混用而不检查。
第三步:让组件引用生成的值
将以下内容保存为demo.html,浏览器打开后会显示一个“确认预约”按钮。代码中的水平内边距来自CSS变量,文字、圆角等其余样式只是本练习的固定设置。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>预约按钮 Token 练习</title>
<link rel="stylesheet" href="tokens.css">
<style>
.booking-button {
padding: 8px var(--control-padding-x);
border: 1px solid #3454d1;
border-radius: 8px;
background: #3454d1;
color: white;
font: 16px/1.5 sans-serif;
}
</style>
<button class="booking-button" type="button">确认预约</button>
</html>
本例纵向内边距保持8px,水平为16px。不是所有固定值都必须立刻抽成token:当纵向间距、圆角或颜色也需要跨组件统一或按模式变化时,再纳入同一套规则。

第四步:从v1常规16px改为v2紧凑12px
先保存v1的源文件版本或提交记录,再将tokens.json中的space.4.$value.value改为12;control.padding.x仍保持对space.4的引用。重新执行生成命令并刷新页面,tokens.css中的两个变量都应变为12px,按钮左右留白各减少4px。
在浏览器样式检查中查看padding-left与padding-right,二者应为12px。再把按钮文案换成长文本,确认紧凑版仍能阅读,页面不会因为按钮变窄而产生不合理换行。这次调整只演示水平密度,不能据此判断触控区域、字号和所有无障碍条件都已合格。
这里的v1、v2是两个候选版本的对比。若产品需要常规与紧凑同时存在,应分别维护模式取值,并由组件属性或页面模式选择;不要直接修改共享基础值,让所有引用它的页面一起意外变紧。
多主题不一定要用token,但需要清楚的取值关系
深浅色、不同品牌和不同密度可以通过普通CSS类、主题对象等方式实现。Token的帮助在于让团队用稳定名称管理这些取值,减少分散维护;它不是支持多主题的唯一前提。
颜色主题可以让text.primary在浅色与深色分别取合适的值;密度模式可以让control.padding.x在常规与紧凑分别取16px与12px。两者是不同维度,不应因为切深色就顺便缩小按钮。组合使用时,需要检查浅色常规、浅色紧凑、深色常规和深色紧凑各自的实际页面。

主题失败常常不在命名本身:文字换成白色,按钮底色却仍使用旧的浅色;一个局部组件覆盖了主题变量;图片、Logo或错误状态没有对应处理。应把默认、禁用、聚焦与错误状态放在两套主题下分别比较,而不是只看首屏换色。设计侧操作可参考深浅主题切换教程。
更新没有生效,按这几类问题排查
| 现象 | 先查什么 | 修正方向 |
|---|---|---|
| 源文件变12,按钮仍16 | 是否重新生成、加载最新CSS,组件是否仍写padding:8px 16px | 确认版本与加载路径;把要跟随规则的水平值改成变量引用 |
| 只有部分按钮变化 | 局部覆盖、不同组件版本、未更新的设计图层绑定 | 定位具体实例;区分有意例外与遗留硬编码,不盲目全局替换 |
| 找不到引用值 | 路径拼写、重命名后是否保留旧引用、引用目标是否为token | 修正路径或提供迁移映射,再生成 |
| 引用循环 | 例如space.4引用control.padding.x,后者又引用space.4 | 让其中一个回到明确基础值,解除循环,不能随便取0掩盖问题 |
| 切主题后文字难读 | 前景与背景是否一起更新、状态色是否被局部覆盖 | 检查实际成对颜色与各状态,不能仅以模式名判断通过 |
| 设计与代码数值不同 | 双方依据的版本和同步方向 | 确认批准版本,更新落后的一端并记录,避免两边各自改成新值 |
删除或重命名token前,先查受影响的组件和页面,给出替代名称与迁移时间。已经被多个项目引用的值,不宜在不通知维护者的情况下直接移除。具体的发布与废弃安排可以与组件库治理放在同一流程。
从一条已经跑通的规则继续扩展
预约按钮练习完成后,团队应能指出值从哪里来、谁批准了12px、哪份CSS由哪版源文件生成,以及哪些页面已经应用。做到这些,再把颜色、字号、圆角和其他组件逐步加入;不需要先建齐所有层级,也不应把尚未接通的同步流程写成自动能力。
如果接下来要建立更完整的规范,可以结合设计系统搭建方法组织组件、token和维护职责。实际收益来自规则被持续复用和正确更新,而不仅是把一批色值换成了英文名字。