墨刀双十一 会员低至3.7折 限时加赠 15000 AI积分 立即前往 arrow

Design Token是什么?分层命名、代码映射与主题更新

文章目录
免费使用墨刀
更新时间: 2026年10月21日

Design Token(设计令牌)是给可复用的设计决策加上名称、类型和取值,例如正文颜色、标题字号、按钮内边距。团队用同一名称讨论和传递这些决定,再把它们映射到设计变量、组件样式与代码。命名本身不会让设计稿和代码自动同步,更新还需要经过明确的数据来源、转换和发布流程。

在墨刀设计中,可以先把颜色、文字等重复选择整理成变量与组件规则。本文在此基础上,用一个预约按钮从常规16px水平内边距改为紧凑12px的例子,说明token如何分层、怎样生成CSS,以及更新后应检查什么。

Design Token把颜色、圆角和间距命名后映射到按钮组件

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:当纵向间距、圆角或颜色也需要跨组件统一或按模式变化时,再纳入同一套规则。

墨刀设计画布中预约按钮的16px与12px内边距,以及Design Token到CSS变量的映射

第四步:从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和维护职责。实际收益来自规则被持续复用和正确更新,而不仅是把一批色值换成了英文名字。

免费在线原型设计工具

内容丰富组件拖拽即用

多人在线编辑实时协作

海量模板素材快速复用

一键分享交付在线评论互动