UI 视觉设计 / 系统课时
按 DTCG 定义令牌字段与类型
按 DTCG 定义令牌字段与类型
把 Figma 中的颜色、间距和组件样式整理成可交换的令牌文件,首先要约定字段、类型与引用规则。本篇以 DTCG 2025.10 为基准,写出一份包含基础值、语义别名和复合边框的 JSON,并用本地脚本检查引用结果。
学习目标
- 区分
$value、$type、$description的约束和用途。 - 正确表示
color、dimension与border令牌。 - 解析令牌别名,并识别循环引用和类型不匹配等问题。
确定令牌字段与命名规则
DTCG 用对象的键作为令牌名;带有 $value 的对象是令牌,不带 $value 的容器通常是分组。下面的约束依据 DTCG Format Module 2025.10。
| 字段 | 规则 | 实际作用 |
|---|---|---|
$value |
令牌必填 | 保存数值、颜色对象、引用或复合值 |
$type |
可显式指定,也可从父组或被引用令牌解析 | 决定值是否合法、如何转换 |
$description |
可选,值为纯文本字符串 | 解释使用意图,供设计与开发审核 |
每个令牌最终必须能确定类型,不能仅凭值猜测。常用类型包括 color、dimension、number、fontFamily、typography、border 和 shadow。例如 dimension 的值是包含数字 value 与单位 unit 的对象,单位限 px 或 rem;color 在该版本中使用包含 colorSpace、components 等字段的颜色对象,而非单独的十六进制字符串。
分组名和令牌名不能以 $ 开头,也不能含有 .、{ 或 }。因此用多层对象表达 color.blue.600,不要把它直接写成一个带句点的键。
建立基础值、别名和复合令牌
新建 tokens.json,保存下面的完整示例。根节点的 $schema 指向 2025.10 格式约束;size 组统一声明 dimension,组内令牌因此不必逐个重复 $type。
{
"$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
"color": {
"blue": {
"600": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0, 0.4, 0.8],
"hex": "#0066CC"
},
"$description": "品牌基础蓝"
}
},
"action": {
"primary": {
"$type": "color",
"$value": "{color.blue.600}",
"$description": "主要操作使用的语义色"
}
}
},
"size": {
"$type": "dimension",
"border": {
"$value": { "value": 1, "unit": "px" }
},
"controlHeight": {
"$value": { "value": 40, "unit": "px" }
}
},
"component": {
"button": {
"outline": {
"$type": "border",
"$description": "按钮描边的颜色、宽度和线型",
"$value": {
"color": "{color.action.primary}",
"width": "{size.border}",
"style": "solid"
}
}
}
}
}这里 color.blue.600 是原始颜色,color.action.primary 是语义别名;前者改变后,后者仍保留同一引用路径。size.controlHeight 规定控件高度为 40px,size.border 规定描边宽度为 1px。它们都是独立的尺寸令牌,不会因为同属一个组就自动关联。
看懂整令牌引用与复合值
{color.blue.600} 是花括号别名,引用的是整个令牌的值。border 则是一个复合类型:$value 内必须提供 color、width、style 三个子值,分别对应颜色、尺寸和描边样式;子值可以直接写值,也可以引用匹配类型的令牌。

注意:复合值里的 color 不是新令牌名,而是 border 类型规定的子字段。若需要只引用另一复合令牌的某个内部属性,须采用规范中的 JSON Pointer $ref 机制,不能用花括号语法直接拼内部属性路径。
在本地验证引用结果
将以下内容保存为与 tokens.json 同目录的 check_tokens.py,执行 python check_tokens.py。脚本读取 JSON、沿完整令牌路径解析花括号别名,并拦截当前引用链中的环。
import json
from pathlib import Path
tokens = json.loads(Path("tokens.json").read_text(encoding="utf-8"))
def token_at(path):
node = tokens
for segment in path.split("."):
node = node[segment]
return node
def resolve(value, visited=frozenset()):
# 别名解析时保留访问记录,避免循环引用导致无限递归
if isinstance(value, str) and value.startswith("{") and value.endswith("}"):
path = value[1:-1]
if path in visited:
raise ValueError(f"循环引用:{path}")
return resolve(token_at(path)["$value"], visited | {path})
return value
border = tokens["component"]["button"]["outline"]["$value"]
color = resolve(border["color"])
width = resolve(border["width"])
# 守住这个按钮描边的设计契约
assert color["hex"] == "#0066CC"
assert width == {"value": 1, "unit": "px"}
assert border["style"] == "solid"
print(f"border: {width['value']}{width['unit']} {border['style']} {color['hex']}")预期输出:
border: 1px solid #0066CC这个脚本是针对示例的冒烟检查,并非完整的 DTCG 格式校验器。生产流水线还应根据 2025.10 规范检查引用存在性、类型兼容性、复合字段完整性以及整个令牌图的循环依赖。
修正容易混淆的边界
最常见的错误是把 color 的 $value 直接写成 "#0066CC",或把 dimension 写成 "40px":这些写法虽然常见于 CSS 或旧导出格式,却不符合这里采用的 DTCG 2025.10 类型结构。导出到 Web、Android、iOS 前应先按声明类型解析,再由平台转换层生成目标格式。
另一个问题是把 border.width 指向颜色令牌,或者让 A 引用 B、B 再引用 A。前者是类型错误,后者是循环依赖,都不能靠“JSON 能解析”认定正确。可把示例中的 size.border 从 1 改成 2 再执行脚本:断言应当失败,直到明确审核并更新期望值;这可以防止设计令牌变化悄悄进入组件包。