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,便于支持该功能的编辑器提示和校验。

json
{
  "$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 校验器。

python
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")

预期输出:

text
3 tokens checked

试着把 spacing.md 的 unit 改成 rem 而不改数值:这仍是合法的 dimension 结构,但本脚本因断言预期 16px 而报错,提醒你当前示例值已改变。若要检查任意 Token 的完整合法性,需要让校验器按 DTCG 2025.10 格式规范和颜色模块执行类型与引用校验,不能仅靠 JSON 语法检查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 $value 和 $type 定义设计值

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通