UI 视觉设计 / 系统课时
将 Button 视觉属性替换为 Token
将 Button 视觉属性替换为 Token
现有 Button 常把背景色、文字色、尺寸和圆角写死在选择器里,视觉改版时难以追踪影响范围。这里以一个高度为 40px 的主按钮为例,把视觉值迁移到语义与组件级 Token,并用浏览器计算样式确认改造前后外观一致、主题覆盖能够生效。
学习目标
- 识别 Button 中应当迁移的硬编码视觉值,建立改造前的验收基线。
- 使用语义 Token 和组件 Token 两级引用,替换按钮的颜色、尺寸、间距和圆角。
- 通过计算样式、交互状态和主题覆盖验证 Token 接入结果。
固定改造前的视觉基线
假设项目中已有一个主按钮,默认背景为 #155eef,白色文字,高度 40px,水平内边距 16px,圆角 8px。不要在迁移时顺便修改这些数值,否则很难判断视觉差异来自 Token 接入还是样式调整。
先整理需要迁移的属性及目标映射:
| 视觉属性 | 原硬编码值 | 共享 Token | 组件 Token |
|---|---|---|---|
| 默认背景 | #155eef |
--color-action-primary |
--button-bg |
| 悬停背景 | #004eeb |
--color-action-primary-hover |
--button-bg-hover |
| 文字颜色 | #ffffff |
--color-on-action-primary |
--button-fg |
| 按钮高度 | 40px |
--size-control-md |
--button-height |
| 水平内边距 | 16px |
--space-control-inline-md |
--button-padding-inline |
| 圆角 | 8px |
--radius-control-md |
--button-radius |
| 字号 | 14px |
--font-size-control |
--button-font-size |
其中,--color-action-primary 描述颜色的使用意图,--button-bg 描述 Button 组件内部的属性职责。两者不是重复定义,而是分别处理跨组件语义和组件实现。
迁移验收至少包括默认态和 Hover 态。按钮文字、字体、边框规则也应保持一致;本例沿用浏览器正常的键盘焦点指示,不把焦点样式调整混入此次迁移。
建立语义变量到组件变量的引用路径
直接将 background-color: #155eef 改成 background-color: var(--color-action-primary) 虽然消除了色值硬编码,但 Button 仍然直接依赖全局变量名。进一步设置 --button-bg: var(--color-action-primary),可以让组件样式只消费自身的变量接口。
例如,按钮实际使用 background-color: var(--button-bg),而 --button-bg 默认引用 --color-action-primary。以后如果某一种按钮需要特殊背景,只需在相应变体中覆盖 --button-bg,不必修改 Button 的背景属性声明。
尺寸和圆角采用相同方法:组件变量分别引用 --size-control-md 和 --radius-control-md。--button-height、--button-radius 是组件的使用接口;共享变量则负责统一数值刻度。

这条引用路径还有一个实际用途:主题容器可以覆盖语义变量,容器内的 Button 在不修改组件 CSS 的情况下取得新颜色。由于 CSS 自定义属性参与层叠和继承,组件变量在按钮元素上引用语义变量时,会根据按钮所在的作用域解析取值。
使用完整页面替换 Button 样式
将下面的完整示例保存为 button-token-demo.html,使用 Chrome、Edge 或 Firefox 的现代版本直接打开,无需安装构建工具。页面保留一枚硬编码按钮作为基线,再展示 Token 按钮和主题覆盖后的按钮。
<!doctype html>
<html lang='zh-CN'>
<head>
<meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<title>Button Token 对照</title>
<style>
:root {
/* 跨组件共享的语义色和尺寸刻度 */
--color-action-primary: #155eef;
--color-action-primary-hover: #004eeb;
--color-on-action-primary: #ffffff;
--size-control-md: 40px;
--space-control-inline-md: 16px;
--radius-control-md: 8px;
--font-size-control: 14px;
}
body {
font-family: system-ui, sans-serif;
padding: 24px;
}
.demo {
display: flex;
flex-wrap: wrap;
gap: 24px;
}
/* 两种实现共用结构样式,避免无关差异 */
.button-legacy,
.button {
box-sizing: border-box;
border: 0;
font-family: inherit;
font-weight: 600;
cursor: pointer;
}
/* 旧实现:视觉值写死在组件选择器中 */
.button-legacy {
background-color: #155eef;
color: #ffffff;
height: 40px;
padding-inline: 16px;
border-radius: 8px;
font-size: 14px;
}
.button-legacy:hover {
background-color: #004eeb;
}
/* 新实现:先建立组件Token,再消费组件Token */
.button {
--button-bg: var(--color-action-primary);
--button-bg-hover: var(--color-action-primary-hover);
--button-fg: var(--color-on-action-primary);
--button-height: var(--size-control-md);
--button-padding-inline: var(--space-control-inline-md);
--button-radius: var(--radius-control-md);
--button-font-size: var(--font-size-control);
background-color: var(--button-bg);
color: var(--button-fg);
height: var(--button-height);
padding-inline: var(--button-padding-inline);
border-radius: var(--button-radius);
font-size: var(--button-font-size);
}
.button:hover {
background-color: var(--button-bg-hover);
}
/* 主题覆盖仅修改语义颜色,不复制组件规则 */
.theme-alt {
--color-action-primary: #067647;
--color-action-primary-hover: #05603a;
}
</style>
</head>
<body>
<main class='demo'>
<section>
<p>旧版硬编码</p>
<button type='button' class='button-legacy'>保存更改</button>
</section>
<section>
<p>Token 默认</p>
<button type='button' class='button'>保存更改</button>
</section>
<section class='theme-alt'>
<p>Token 主题覆盖</p>
<button type='button' class='button'>保存更改</button>
</section>
</main>
</body>
</html>预期结果: 页面显示三枚文案均为“保存更改”的按钮。前两枚默认视觉一致,背景均为 #155eef,文字为白色;第三枚因为父容器覆盖了语义颜色,背景显示为 #067647。三枚按钮的高度均为 40px,圆角均为 8px,水平内边距均为 16px。
将鼠标分别移到前两枚按钮上,两者背景都应变为 #004eeb;第三枚的 Hover 背景应变为 #05603a。第三枚按钮只覆盖语义颜色,没有重新定义 --button-bg,说明原有组件映射已经正确消费当前作用域中的变量。
这里没有把 box-sizing、cursor 或按钮的结构性边框规则全部改成 Token。Token 应当优先承载需要跨组件共享、主题切换或设计系统统一管理的值;不必把每一条 CSS 声明都包装成变量。
用计算样式验证迁移结果
肉眼观察只能发现较明显的差异。对于高度、圆角和颜色是否完全一致,应检查浏览器最终计算出的样式,而不只是查看源码中的变量引用。
- 打开页面,按
F12进入开发者工具,在Elements面板分别选中.button-legacy和默认的.button。 - 切换到
Computed,逐项核对background-color、color、height、padding-left、padding-right、border-top-left-radius与font-size。 - 在
Styles面板使用:hov强制开启:hover,对比旧按钮与新按钮的悬停背景。 - 选中
.theme-alt内的按钮,再次检查背景色与尺寸,确认主题只影响预期属性。
正常状态下应得到以下关键计算值:
| 计算属性 | 旧版按钮 | Token 默认按钮 | 主题覆盖按钮 |
|---|---|---|---|
background-color |
rgb(21, 94, 239) |
rgb(21, 94, 239) |
rgb(6, 118, 71) |
color |
rgb(255, 255, 255) |
rgb(255, 255, 255) |
rgb(255, 255, 255) |
height |
40px |
40px |
40px |
padding-left |
16px |
16px |
16px |
border-top-left-radius |
8px |
8px |
8px |
font-size |
14px |
14px |
14px |
在强制 Hover 状态下,前两枚按钮的 background-color 应为 rgb(0, 78, 235),主题覆盖按钮则为 rgb(5, 96, 58)。
还可以执行一次变量传播检查:在开发者工具中临时修改 :root 的 --color-action-primary,例如改为 #7f56d9。预期只有默认 Token 按钮跟随改变,旧版硬编码按钮保持蓝色,.theme-alt 内的按钮仍使用自身覆盖的绿色。完成后撤销临时修改。
如果 Token 按钮背景透明,优先检查 var() 引用的变量名是否拼写错误、语义变量是否存在,以及变量是否在当前作用域可见。若主题覆盖没有生效,应检查 .theme-alt 是否确实包住按钮,以及按钮自身是否定义了更高优先级的同名语义变量。
如果高度不一致,先检查 box-sizing、边框和外部样式覆盖;如果只有 Hover 不一致,检查状态选择器以及 --button-bg-hover 的引用值。不要为了让页面看起来正常,就给每一个缺失变量增加硬编码兜底色,这可能掩盖真正的 Token 接入错误。
本例的验收标准是:默认态与 Hover 态的新旧计算样式一致,修改共享 Token 能传播到对应组件,主题覆盖只改变指定视觉属性。实际接入已有组件库时,还应将该方法分别应用于 Disabled、Focus Visible、Loading 等状态,并保留键盘焦点可见性与文字对比度检查。