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 从硬编码到两级 Token 的样式依赖关系

这条引用路径还有一个实际用途:主题容器可以覆盖语义变量,容器内的 Button 在不修改组件 CSS 的情况下取得新颜色。由于 CSS 自定义属性参与层叠和继承,组件变量在按钮元素上引用语义变量时,会根据按钮所在的作用域解析取值。

使用完整页面替换 Button 样式

将下面的完整示例保存为 button-token-demo.html,使用 Chrome、Edge 或 Firefox 的现代版本直接打开,无需安装构建工具。页面保留一枚硬编码按钮作为基线,再展示 Token 按钮和主题覆盖后的按钮。

html
<!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 声明都包装成变量。

用计算样式验证迁移结果

肉眼观察只能发现较明显的差异。对于高度、圆角和颜色是否完全一致,应检查浏览器最终计算出的样式,而不只是查看源码中的变量引用。

  1. 打开页面,按 F12 进入开发者工具,在 Elements 面板分别选中 .button-legacy 和默认的 .button。
  2. 切换到 Computed,逐项核对 background-color、color、height、padding-left、padding-right、border-top-left-radius 与 font-size。
  3. 在 Styles 面板使用 :hov 强制开启 :hover,对比旧按钮与新按钮的悬停背景。
  4. 选中 .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 等状态,并保留键盘焦点可见性与文字对比度检查。

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

目录与阅读设置

阅读设置

17

记录一个想法

将 Button 视觉属性替换为 Token

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

登录哪都通