UI 视觉设计 / 系统课时
在组件样式中消费语义变量
在组件样式中消费语义变量
把 Design Token 编译成 CSS 自定义属性后,组件应通过表示用途的语义变量取色,而不是直接依赖基础色阶。本篇用一个可在浏览器打开的双主题按钮示例,说明全局变量、组件局部变量、var() 回退值如何协作,并验证最终样式来自哪里。
学习目标
- 在组件 CSS 中消费语义 Token,避免直接绑定基础色阶。
- 区分根级默认值、主题容器覆盖与组件局部覆盖。
- 使用
var()的回退参数,并在浏览器中验证计算后的颜色。
为什么组件不应引用基础色阶
基础变量如 --palette-blue-600 描述具体色阶,语义变量如 --color-action-primary 描述“主要操作背景”的用途。如果按钮直接使用 var(--palette-blue-600),品牌改成绿色时,业务组件就要改引用;使用 var(--color-action-primary),只需在主题层重新映射语义值。
建议把消费边界定为:Token 源文件或编译器负责基础值到语义值的映射;业务组件只认识语义变量;少数组件特有的差异再由 --button-bg 等局部变量承接。示例中的 CSS 变量名是一套约定,实际接入时必须与编译产物保持一致。
全局变量、主题覆盖与局部变量
默认语义值定义在 :root;暗色主题容器 .theme-dark 覆盖同名语义变量。普通、未通过 @property 特殊注册的 CSS 自定义属性会继承,因此容器内的按钮可以自动读取所在主题的值。
组件再提供自己的变量入口:主按钮未声明 --button-bg,便回退到全局语义变量;次按钮声明 --button-bg,优先使用自己的组件值。变体不必重复整套 background-color、color 等属性。

运行双主题按钮示例
把下面的完整内容保存为 index.html,双击用现代浏览器打开即可。为保证示例独立运行,语义变量直接写在 style 内;实际项目通常由构建产物 tokens.css 提供这些根级与主题变量,组件文件只保留消费规则。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>语义 Token 按钮示例</title>
<style>
:root {
--color-action-primary: #155eef;
--color-text-on-action: #ffffff;
--color-surface-default: #ffffff;
--color-text-primary: #1e293b;
--color-border-default: #cbd5e1;
}
/* 主题只覆盖语义变量,组件规则保持不变 */
.theme-dark {
--color-action-primary: #9bbcff;
--color-text-on-action: #0b1b36;
--color-surface-default: #1e293b;
--color-text-primary: #f8fafc;
--color-border-default: #94a3b8;
}
.demo {
display: flex;
gap: 12px;
padding: 16px;
background-color: var(--color-surface-default, #fff);
}
/* 先取组件局部变量;没有时读取语义变量 */
.button {
padding: 10px 16px;
border: 1px solid transparent;
border-radius: 8px;
background-color: var(--button-bg, var(--color-action-primary, #155eef));
color: var(--button-fg, var(--color-text-on-action, #fff));
cursor: pointer;
}
/* 变体只重映射局部变量,不复制主按钮样式 */
.button--secondary {
--button-bg: var(--color-surface-default, #fff);
--button-fg: var(--color-text-primary, #1e293b);
border-color: var(--color-border-default, #cbd5e1);
}
</style>
</head>
<body>
<div class="demo">
<button class="button" type="button">主操作</button>
<button class="button button--secondary" type="button">次操作</button>
</div>
<div class="demo theme-dark">
<button class="button" type="button">主操作</button>
<button class="button button--secondary" type="button">次操作</button>
</div>
</body>
</html>预期结果:页面出现上下两组按钮。上组为浅色主题,主按钮背景是 #155eef,次按钮为白底深字;下组为深色主题,主按钮背景是 #9bbcff,次按钮为深色底浅字。两组使用相同的 .button 规则,没有按品牌或模式复制组件样式。
回退值能处理什么,不能处理什么
var(--button-bg, var(--color-action-primary, #155eef)) 按顺序取值:先看按钮元素是否有可用的 --button-bg,缺失时查找所在作用域的 --color-action-primary,两者都不可用才使用 #155eef。回退参数适用于可选的组件覆盖值,以及防止样式因变量缺失而失效。
回退值不能修复类型错误。例如将 --color-action-primary 定义为 12px,变量虽然存在,但 12px 不是合法的 background-color;浏览器不会因此采用 #155eef,背景声明会在计算值阶段无效。也不要让回退值长期掩盖漏发的 Token 文件:发布构建应校验所需语义变量是否存在、类型是否正确。细节参见 MDN:CSS var()。
在浏览器中验收覆盖顺序
- 在 Chrome 或 Edge 按
F12,进入 Elements → Computed,选中上组主按钮;background-color应为rgb(21, 94, 239),即#155eef。 - 选中下组主按钮,背景应为
rgb(155, 188, 255),即#9bbcff。在 Styles 面板向上检查.theme-dark的--color-action-primary,确认它覆盖了根级定义。 - 选中下组次按钮,在 Styles 中查找
.button--secondary的--button-bg;它应引用--color-surface-default,最终背景为#1e293b,而不是主操作蓝色。 - 把
:root中--color-action-primary改为#0f766e并刷新。只有上组主按钮改变;下组主按钮仍使用暗色主题覆盖值,两组次按钮不受影响。
如果颜色未变化,先查组件是否写死了 background-color,再核对 CSS 变量名拼写和主题类是否挂在组件祖先节点上。组件长期只依赖语义名称,后续更换品牌或模式就可以留在 Token 层完成。