UI 视觉设计 / 系统课时
用 Resolver 定义主题解析路径
用 Resolver 定义主题解析路径
一个组件库同时支持 Atlas、Grove 两个品牌和浅色、深色模式时,逐份复制 Token 容易让按钮色与页面底色互相覆盖。这里用 DTCG Resolver 2025.10 分开声明条件、按固定顺序合并来源,并算出四种主题的实际结果。
学习目标
- 区分固定
set与按条件选择的modifier,识别品牌和模式两条维度。 - 配置
resolutionOrder,说明冲突覆盖与 Alias 的解析时机。 - 用四组输入核对 Token 结果,并定位错误上下文与意外覆盖。
将品牌和模式定义成独立维度
set 负责所有主题都会使用的基础 Token;modifier 的 contexts 则为每种条件提供来源数组。本例让 brand 决定 color.brand.primary,mode 决定 color.surface.page,两者尽量不写同一 Token 路径。
品牌上下文为 atlas、grove,模式上下文为 light、dark,因此有 2 × 2 = 4 种组合。两条维度分别设 default,未传值时分别选 atlas 与 light;显式选择时,例如 {"brand":"grove","mode":"dark"},只合入对应两条分支。
编写可独立解析的 Resolver 文件
将下列标准 JSON 保存为 tokens.resolver.json。为使示例无需依赖外部文件,sources 与 contexts 直接内嵌 DTCG Token。真实仓库可将这些对象拆到文件,再用 {"$ref":"brand/atlas.json"} 等引用对象替换;文件引用相对 Resolver 所在位置解析。
{
"$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
"version": "2025.10",
"sets": {
"foundation": {
"sources": [{
"color": {"button": {"background": {
"$type": "color",
"$value": "{color.brand.primary}"
}}}
}]
}
},
"modifiers": {
"brand": {
"default": "atlas",
"contexts": {
"atlas": [{
"color": {"brand": {"primary": {
"$type": "color",
"$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"}
}}}
}],
"grove": [{
"color": {"brand": {"primary": {
"$type": "color",
"$value": {"colorSpace": "srgb", "components": [0, 0.6, 0.4], "hex": "#009966"}
}}}
}]
}
},
"mode": {
"default": "light",
"contexts": {
"light": [{
"color": {"surface": {"page": {
"$type": "color",
"$value": {"colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff"}
}}}
}],
"dark": [{
"color": {"surface": {"page": {
"$type": "color",
"$value": {"colorSpace": "srgb", "components": [0, 0, 0], "hex": "#000000"}
}}}
}]
}
}
},
"resolutionOrder": [
{"$ref": "#/sets/foundation"},
{"$ref": "#/modifiers/brand"},
{"$ref": "#/modifiers/mode"}
]
}$schema 用于编辑器提示与校验,version 声明 Resolver 规范版本。foundation 定义按钮背景的别名引用;合并期间暂不求值,等品牌和模式覆盖完成后才解析。contexts 里的每个选项都是来源数组,不能写成单个文件名字符串。
沿解析顺序合成最终 Token
resolutionOrder 严格按数组顺序处理:先合入 foundation,再选择 brand,最后选择 mode。同一路径多次出现时后者覆盖前者;合并完成后才解析 {color.brand.primary}。输入对象的键排列顺序不会影响求值。

对于 {"brand":"grove","mode":"dark"},基础层先留下 color.button.background 的别名;品牌层定义 color.brand.primary=#009966;模式层定义 color.surface.page=#000000。最后解开按钮背景别名,结果为 #009966。
| brand | mode | button.background | surface.page |
|---|---|---|---|
| atlas | light | #0066cc |
#ffffff |
| atlas | dark | #0066cc |
#000000 |
| grove | light | #009966 |
#ffffff |
| grove | dark | #009966 |
#000000 |
检查组合并排查覆盖冲突
在安装了 Python 3 的环境中进入文件目录,运行下列命令检查 JSON 语法、解析顺序与组合数量。它不是完整的 Resolver 校验器,不能替代最终 Token 的解析测试。
python -c "import json; d=json.load(open('tokens.resolver.json', encoding='utf-8')); assert [x['$ref'] for x in d['resolutionOrder']] == ['#/sets/foundation', '#/modifiers/brand', '#/modifiers/mode']; print('permutations:', len(d['modifiers']['brand']['contexts']) * len(d['modifiers']['mode']['contexts']))"预期输出:
permutations: 4再使用支持 DTCG Resolver 2025.10 的实现分别传入上表四组输入,并核对最终 Token。规范定义解析行为,但不规定所有工具通用的命令行接口,具体参数应按所用实现的文档设置。
若误把 color.brand.primary=#663399 也写入 mode.dark,所有暗色组合都会以该值覆盖品牌色,按钮背景也随 Alias 变紫;这称为非正交覆盖。优先让品牌负责品牌色、模式负责明暗语义;确需交叉覆盖时,必须在变更评审中写明优先级,并覆盖全部四种组合的测试。
传入 {"brand":"unknown","mode":"dark"} 必须拒绝,因为 unknown 不在品牌上下文中;缺少输入且未声明 default 的维度也必须报错。$ref 失效、Alias 指向不存在的 Token 或形成引用循环同样需要阻断发布。详细规则见 DTCG Resolver 2025.10。