UI 视觉设计 / 系统课时
用 $value 和 $type 定义设计值
用 $value 和 $type 定义设计值
把颜色、间距和行高写进 Token JSON 时,必须让数据类型与值结构匹配。这里依据 DTCG 2025.10 编写一个完整文件,说明 $value、$type、$description 的职责,并实际检查三种常用类型。
学习目标
- 能辨认 Token、分组,以及三个以
$开头的属性。 - 能正确编写
color、dimension和number的$value。 - 能执行基础检查,发现缺失类型、错误单位和字符串数值。
看懂一个 Token 的三个属性
DTCG 以含有 $value 的对象表示 Token;没有 $value 的对象通常是用于组织子项的分组。$value 保存实际设计值,是 Token 的必需属性。$type 规定如何解释和校验这个值,$description 是可选的人类可读用途说明,不参与数值计算。
例如,将主按钮背景称为 color.brand.primary,其值是蓝色,类型是 color,描述写“主要操作按钮背景”。不要只写“蓝色”作为描述,使用位置比重复颜色本身更能帮助维护者判断改动影响。
$type 可以写在 Token 上,也可以继承最近的上层分组;引用别的 Token 时还可以取得被引用项的类型。但如果既没有可继承的类型,也没有能解析出类型的引用,该 Token 无效;工具不应凭 $value 的外形猜类型。属性名区分大小写,$Value 不能替代 $value。
写出可以复用的三种值
新建 ui.tokens.json 并填入以下完整文件。示例使用已发布的 DTCG 2025.10 格式,$schema 指向对应的 JSON Schema,便于支持该功能的编辑器提示和校验。
{
"$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
"color": {
"brand": {
"$type": "color",
"primary": {
"$value": {
"colorSpace": "srgb",
"components": [0, 0.4, 0.8],
"hex": "#0066cc"
},
"$description": "主要操作按钮背景"
}
}
},
"spacing": {
"md": {
"$type": "dimension",
"$value": { "value": 16, "unit": "px" },
"$description": "卡片标准内边距"
}
},
"typography": {
"bodyLineHeight": {
"$type": "number",
"$value": 1.5,
"$description": "正文行高相对字号的倍率"
}
}
}这里 color.brand.primary 从 brand 分组继承 color 类型。srgb 的三个分量顺序是红、绿、蓝,范围各为 0~1;可选的 hex 与分量对应,便于部分工具转换。spacing.md 是 16px 的长度,typography.bodyLineHeight 则是没有单位的 1.5 倍行高。
识别看起来合理却无效的写法
$type |
合法 $value |
错误示例 | 为什么错 |
|---|---|---|---|
color |
{"colorSpace":"srgb","components":[0,0.4,0.8]} |
"#0066cc" |
2025.10 颜色需要颜色空间和分量对象,不能只用十六进制字符串 |
dimension |
{"value":16,"unit":"px"} |
"16px" |
必须是数值加单位对象;只支持 px、rem |
number |
1.5 |
"1.5" |
必须是 JSON 数字,而非字符串 |
将 dimension 的单位改成 dp 或 % 也不符合该类型的 2025.10 规定;跨平台换算应在导出阶段处理。即使数值是零,dimension 仍要写 {"value":0,"unit":"px"},不能省掉单位。反过来,number 不需要额外套一层 {"value":...}。
运行基础检查并确认结果
在同一个目录另存为 check_tokens.py,用 Python 3 执行 python check_tokens.py。下面的断言只检查本例的三个 Token,不是覆盖所有类型与引用规则的完整 DTCG 校验器。
import json
from pathlib import Path
data = json.loads(Path("ui.tokens.json").read_text(encoding="utf-8"))
# 颜色类型由上级分组给出,子 Token 不必重复声明。
color_group = data["color"]["brand"]
color_value = color_group["primary"]["$value"]
assert color_group["$type"] == "color"
assert color_value["colorSpace"] == "srgb"
assert color_value["components"] == [0, 0.4, 0.8]
# 尺寸有单位,数字类型直接使用 JSON 数值。
spacing = data["spacing"]["md"]
line_height = data["typography"]["bodyLineHeight"]
assert spacing["$type"] == "dimension"
assert spacing["$value"] == {"value": 16, "unit": "px"}
assert line_height["$type"] == "number"
assert type(line_height["$value"]) in (int, float)
print("3 tokens checked")预期输出:
3 tokens checked试着把 spacing.md 的 unit 改成 rem 而不改数值:这仍是合法的 dimension 结构,但本脚本因断言预期 16px 而报错,提醒你当前示例值已改变。若要检查任意 Token 的完整合法性,需要让校验器按 DTCG 2025.10 格式规范和颜色模块执行类型与引用校验,不能仅靠 JSON 语法检查。