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 所在位置解析。

json
{
  "$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}。输入对象的键排列顺序不会影响求值。

Resolver 的品牌与模式选择以及覆盖顺序

对于 {"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 的解析测试。

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

预期输出:

text
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。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Resolver 定义主题解析路径

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

登录哪都通