UI 视觉设计 / 系统课时
测试主题兜底和引用优先级
测试主题兜底和引用优先级
多品牌、多模式主题容易在缺省值、覆盖顺序和别名解析时出现隐蔽错误。本课把默认策略写成可执行断言,模拟品牌与主题缺项,再验证高对比和紧凑密度的组合,最终形成可以接入持续集成的主题回归检查。
学习目标
- 区分未传主题参数、某层缺少 Token 与非法主题值的处理方式。
- 验证品牌、明暗、高对比和密度覆盖的先后顺序,以及跨层别名的最终取值。
- 编写可运行的组合测试,识别静默兜底和错误的跨维度覆盖。
固定覆盖顺序和缺失规则
本例约定 brand=core、mode=light、contrast=normal、density=comfortable 为缺省输入。这是项目的明确策略,不表示任意工具都自动采用相同默认值。DTCG Resolver 按 resolutionOrder 的先后合并,同路径冲突由后出现者覆盖,别名在合并后解析。
| 合并顺序 | 层 | 本例覆盖的路径 |
|---|---|---|
| 1 | Foundation | 全部基础令牌 |
| 2 | Brand | palette.primary |
| 3 | Mode | color.canvas、color.text |
| 4 | Contrast | 高对比时重新覆盖画布与文本色 |
| 5 | Density | space.control |
缺省要分开处理:没有传入维度时使用该维度默认值;选中层未定义某个 Token时沿用前面层已经合并的值。例如深色层没有 color.border,就保留 Foundation 的 #CBD5E1。但输入 mode=sepia 不属于允许的上下文,应报错,不能悄悄切回浅色。
在覆盖完成后追踪跨层 Alias
component.button.bg 引用 semantic.action,后者再引用 palette.primary。当 acme 品牌把基础蓝 #2563EB 覆盖为橙色 #C2410C 时,按钮背景也必须得到橙色。如果在合并品牌层之前就把 Alias 提前解析成蓝色,品牌切换不会传播到按钮。

用 Node.js 跑通十六种组合
把下面的完整脚本保存为 theme-check.cjs,使用 Node.js 20 或更新版本执行 node theme-check.cjs,无需安装依赖。为便于独立测试,示例用扁平路径键保存具有 DTCG $type、$value 结构的令牌,手工模拟合并与别名解析;它不是完整的 DTCG Resolver 文件解析器。
const assert = require('node:assert/strict');
// 使用 DTCG 颜色与尺寸值结构,测试同一路径令牌的覆盖。
const color = hex => ({
$type: 'color',
$value: {
colorSpace: 'srgb',
components: [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16) / 255),
hex
}
});
const dimension = n => ({ $type: 'dimension', $value: { value: n, unit: 'px' } });
const alias = path => ({ $type: 'color', $value: `{${path}}` });
const base = {
'palette.primary': color('#2563EB'),
'color.canvas': color('#FFFFFF'),
'color.text': color('#111827'),
'color.border': color('#CBD5E1'),
'semantic.action': alias('palette.primary'),
'component.button.bg': alias('semantic.action'),
'space.control': dimension(10)
};
const brands = { core: {}, acme: { 'palette.primary': color('#C2410C') } };
const modes = {
light: {},
dark: { 'color.canvas': color('#101820'), 'color.text': color('#F8FAFC') }
};
const highContrast = {
light: { 'color.canvas': color('#FFFFFF'), 'color.text': color('#000000') },
dark: { 'color.canvas': color('#000000'), 'color.text': color('#FFFFFF') }
};
const densities = { comfortable: {}, compact: { 'space.control': dimension(6) } };
function resolve(input = {}) {
const { brand = 'core', mode = 'light', contrast = 'normal', density = 'comfortable' } = input;
const choices = { brand: Object.keys(brands), mode: Object.keys(modes), contrast: ['normal', 'high'], density: Object.keys(densities) };
for (const [key, value] of Object.entries({ brand, mode, contrast, density })) {
if (!choices[key].includes(value)) throw new Error(`invalid ${key}: ${value}`);
}
// 先按既定优先级合并,再解析跨层 Alias。
const tokens = { ...base, ...brands[brand], ...modes[mode],
...(contrast === 'high' ? highContrast[mode] : {}), ...densities[density] };
function read(path, visited = []) {
if (visited.includes(path)) throw new Error(`alias cycle: ${[...visited, path].join(' -> ')}`);
const token = tokens[path];
if (!token) throw new Error(`missing token: ${path}`);
const raw = token.$value;
if (typeof raw === 'string' && raw.startsWith('{') && raw.endsWith('}')) {
const target = read(raw.slice(1, -1), [...visited, path]);
assert.equal(token.$type, target.$type, `type mismatch: ${path}`);
return target;
}
return token;
}
return path => read(path).$value;
}
assert.equal(resolve()('component.button.bg').hex, '#2563EB');
assert.equal(resolve()('space.control').value, 10);
console.log('PASS 默认输入使用 core/light/normal/comfortable');
const darkAcme = resolve({ brand: 'acme', mode: 'dark' });
assert.equal(darkAcme('component.button.bg').hex, '#C2410C');
assert.equal(darkAcme('color.border').hex, '#CBD5E1');
console.log('PASS 品牌覆盖、跨层 Alias 与主题缺项继承');
for (const brand of Object.keys(brands)) {
for (const mode of Object.keys(modes)) {
for (const contrast of ['normal', 'high']) {
for (const density of Object.keys(densities)) {
const get = resolve({ brand, mode, contrast, density });
const regular = resolve({ brand, mode, contrast, density: 'comfortable' });
assert.equal(get('component.button.bg').hex, brand === 'acme' ? '#C2410C' : '#2563EB');
assert.equal(get('color.text').hex, regular('color.text').hex);
assert.equal(get('space.control').value, density === 'compact' ? 6 : 10);
if (contrast === 'high') {
assert.equal(get('color.text').hex, mode === 'light' ? '#000000' : '#FFFFFF');
assert.equal(get('color.canvas').hex, mode === 'light' ? '#FFFFFF' : '#000000');
}
}
}
}
}
console.log('PASS 16 种品牌、明暗、高对比、密度组合');
assert.throws(() => resolve({ mode: 'sepia' }), /invalid mode/);
assert.throws(() => resolve({ brand: 'unknown' }), /invalid brand/);
console.log('PASS 非法上下文被拒绝');预期输出:
PASS 默认输入使用 core/light/normal/comfortable
PASS 品牌覆盖、跨层 Alias 与主题缺项继承
PASS 16 种品牌、明暗、高对比、密度组合
PASS 非法上下文被拒绝测试采用 Node.js 内置 node:assert/strict。任一断言不成立时会抛错并以非零退出码结束,因此执行命令可直接作为 CI 的发布门禁,而不仅是人工目测页面的替代品。
核对高对比与密度的组合边界
本例矩阵覆盖 2 个品牌、2 种明暗、2 种对比度与 2 种密度,合计 16 种。以下是需要核对的代表性结果:
| 模式 | 对比度 | 密度 | 画布 / 文本 | 控件间距 |
|---|---|---|---|---|
| light | normal | comfortable | #FFFFFF / #111827 |
10px |
| dark | normal | comfortable | #101820 / #F8FAFC |
10px |
| light | high | compact | #FFFFFF / #000000 |
6px |
| dark | high | compact | #000000 / #FFFFFF |
6px |
高对比两种模式的黑白画布与文字对比度都是 21:1,但这不代表按钮、边框和提示色已经合格;这些语义令牌还需分别测试。密度变更只应影响尺寸,例如 space.control 从 10px 到 6px,不应改变 color.text。
实际项目可以把 resolve() 换成生产 Resolver 的输出读取接口,保留这些断言和十六种输入。若某个品牌确实不支持高对比模式,应将该组合显式标为不支持并在应用入口拒绝选择,而不是让普通主题冒充高对比结果。