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。

json
{
  "$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、沿完整令牌路径解析花括号别名,并拦截当前引用链中的环。

python
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']}")

预期输出:

text
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 再执行脚本:断言应当失败,直到明确审核并更新期望值;这可以防止设计令牌变化悄悄进入组件包。

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

目录与阅读设置

阅读设置

17

记录一个想法

按 DTCG 定义令牌字段与类型

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

登录哪都通