UI 视觉设计 / 系统课时
表示字体和阴影等复合类型
表示字体和阴影等复合类型
字体样式同时包含字号、字重与行高,阴影也需要颜色、偏移和模糊参数。把它们压成字符串会让引用与校验失效。本课按 DTCG 2025.10 编写一份可复用的 Token JSON,并验证复合字段的类型与引用位置。
学习目标
- 区分简单 Token、复合 Token 与字段级引用。
- 正确填写
typography和shadow的必需子字段。 - 使用整项引用与 JSON Pointer 复用值,并检查常见错误。
判定简单值与复合值
一个字体族名称是 fontFamily 简单 Token,颜色是 color 简单 Token;一套文字样式使用 typography,一个阴影样式使用 shadow。在 DTCG 2025.10 中,Token 用 $type 声明类型,用 $value 存放值。复合值的子字段不是独立 Token,不应在其中随意嵌套 $type、$value。
| 复合类型 | $value 必需字段 |
值的格式 |
|---|---|---|
typography |
fontFamily、fontSize、fontWeight、letterSpacing、lineHeight |
字体族字符串/数组;字号与字距为维度对象;字重为数值或规范别名;行高为无单位数字 |
shadow |
color、offsetX、offsetY、blur、spread |
颜色对象或颜色 Token 引用;其余四项为维度对象;可选 inset 布尔值 |
维度必须写成 {"value": 16, "unit": "px"} 这类对象;2025.10 允许 px 或 rem,即使是零也不能省略单位。lineHeight: 1.5 表示建议按字号的 1.5 倍计算,不能把它写成 "24px"。
编写字体与阴影数据文件
将以下内容保存为 tokens.json。示例同时包含基础字体和颜色 Token、两套文字样式及单层/双层阴影。颜色用 DTCG 的 sRGB 结构表示,不能直接用 "#00000026" 冒充 2025.10 的 color 值。
{
"$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
"font": {
"familyBody": {
"$type": "fontFamily",
"$value": [
"Inter",
"Arial",
"sans-serif"
]
}
},
"color": {
"shadow": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [
0,
0,
0
],
"alpha": 0.16
}
}
},
"typography": {
"body": {
"$type": "typography",
"$value": {
"fontFamily": "{font.familyBody}",
"fontSize": {
"value": 16,
"unit": "px"
},
"fontWeight": 400,
"letterSpacing": {
"value": 0,
"unit": "px"
},
"lineHeight": 1.5
}
},
"heading": {
"$type": "typography",
"$value": {
"fontFamily": "{font.familyBody}",
"fontSize": {
"value": 24,
"unit": "px"
},
"fontWeight": 700,
"letterSpacing": {
"value": 0,
"unit": "px"
},
"lineHeight": {
"$ref": "#/typography/body/$value/lineHeight"
}
}
}
},
"shadow": {
"card": {
"$type": "shadow",
"$value": {
"color": "{color.shadow}",
"offsetX": {
"value": 0,
"unit": "px"
},
"offsetY": {
"value": 4,
"unit": "px"
},
"blur": {
"value": 12,
"unit": "px"
},
"spread": {
"value": 0,
"unit": "px"
}
}
},
"popover": {
"$type": "shadow",
"$value": [
"{shadow.card}",
{
"color": "{color.shadow}",
"offsetX": {
"value": 0,
"unit": "px"
},
"offsetY": {
"value": 12,
"unit": "px"
},
"blur": {
"value": 24,
"unit": "px"
},
"spread": {
"value": 0,
"unit": "px"
}
}
]
}
}
}typography.body 对应 16px、400 字重和 1.5 倍行高,按 16 × 1.5 得到约 24px 行盒高度;typography.heading 是 24px、700 字重,引用相同行高倍率后约为 36px。shadow.card 的垂直偏移是 4px、模糊半径是 12px;shadow.popover 用数组表示两层阴影,第一层引用 shadow.card,第二层向下偏移 12px。
区分整项引用与字段引用
花括号引用如 {font.familyBody}、{color.shadow} 取目标 Token 的完整 $value,适合在复合值中复用已有字体或颜色。{shadow.card} 在阴影数组里复用完整的单层阴影对象。
如果只想复用行高,应使用 { "$ref": "#/typography/body/$value/lineHeight" }。这里 #/ 从当前 JSON 文档根部开始,$value/lineHeight 精确定位子字段;写成 {typography.body.lineHeight} 不合法,因为花括号不能直接指向复合值的内部属性。字段引用必须解析为目标字段所需的类型,且不能形成循环。

验证文件与修正常见错误
安装 Node.js 后,在 tokens.json 所在目录运行以下命令,先只检查 JSON 语法:
node -e "JSON.parse(require('node:fs').readFileSync('tokens.json','utf8')); console.log('JSON syntax OK')"预期输出:
JSON syntax OK这一步不会检查 DTCG 结构和引用。还需使用支持 DTCG 2025.10 的校验工具或导入器,对照文件的 $schema 校验,并确认:typography 的五个必需字段齐全;shadow 每层包含五项;所有维度都具备 value、unit;$ref 指向存在的字段且无循环。
常见错误是把阴影写成 "0 4px 12px #0003"、把整套字体写成 "700 24px/1.5 Inter",或把 fontSize 简写成 "16px"。这些是 CSS 风格的字符串,不是这里要求的 DTCG 复合值。需要生成 CSS 时,应先解析 Token 和引用,再由转换器输出对应属性。规范依据:DTCG Format Module 2025.10。