UI 视觉设计 / 系统课时

将语义令牌映射到组件样式

将语义令牌映射到组件样式

将 Figma 中的语义颜色直接写成固定色值,容易让组件在切换主题时出现局部漏改。本课以 Card 组件为例,把语义色、字体、间距和圆角映射到 CSS 自定义属性,建立可以追踪的设计与代码对应关系,并验证主题继承和组件局部覆盖的实际效果。

学习目标

  • 建立 Figma 语义令牌、CSS 自定义属性与组件样式之间的映射关系。
  • 区分应随主题变化的语义颜色,以及保持不变或允许局部覆盖的排版和尺寸令牌。
  • 实现支持浅色、深色及紧凑规格的 Card 组件,并检查浏览器计算样式。

建立可追踪的变量映射

设计稿中的原始色值不应直接成为组件的长期依赖。例如,Card 背景在浅色主题中是白色,在深色主题中是深灰色,但组件实际需要表达的是“表面背景”,而不是指定某个固定颜色。

在 Figma 中,可以为 color/bg/surface 建立 Light 和 Dark 两个变量模式,分别引用基础色板中的 palette/white 和 palette/slate/800。前端组件始终引用同一个语义名称,主题负责决定该名称最终对应哪个值。

以下是一套演示用令牌。它们是项目自定义名称,并非 Figma 内置变量;实际交付时应以团队令牌库为准。

Figma 来源 Light Dark 前端 CSS 变量
color/bg/surface #ffffff #1e293b --color-bg-surface
color/text/primary #0f172a #f8fafc --color-text-primary
color/border/default #cbd5e1 #475569 --color-border-default
文字样式 Body/Regular Arial、14px、21px、400 同左 --font-family-body 等
space/4 16px 16px --space-4
space/3 12px 12px --space-3
radius/md 8px 8px --radius-md

文字样式 Body/Regular 在前端拆成字体族、字号、行高和字重四项。颜色适合使用 Figma 变量模式,文字排版则需要同时核对 Figma Text Style 中的实际属性,不应假设一个样式名称就是一个完整的 CSS 变量。

交付前按以下顺序检查映射:

  1. 在 Figma 选中 Card 实例,检查填充、描边关联的是语义变量还是直接色值。
  2. 在变量集合中分别查看 Light、Dark 模式,核对语义变量的引用目标与最终色值。
  3. 选中正文文本,确认文字样式的字体族、字号、行高及字重。
  4. 在映射表中记录 Figma 名称、CSS 名称、默认值、主题差异和使用组件。

如果设计稿使用 16px 间距,而前端自行改成 14px,即使视觉差异很小,也属于令牌映射不一致,应先确认是否存在正式的紧凑规格,而不是直接修改基础令牌。

让主题在语义层切换

CSS 双连字符自定义属性默认参与层叠并可以从祖先元素继承。将默认语义颜色定义在 :root,再通过根节点的 data-theme 属性覆盖对应颜色,组件就能通过 var() 获取当前主题值。

对于本例,推荐按以下边界处理:

  • 主题级覆盖:表面色、正文色和边框色在 Light、Dark 之间重新映射,Card 不保存自己的固定主题色。
  • 全局共享:正文的 14px 字号、21px 行高和 8px 圆角在两个主题下使用同一数值,除非设计规范明确要求不同。
  • 组件局部覆盖:Card 默认内边距为 16px,紧凑规格可以单独调整为 12px,但不应顺带覆盖全局正文色。
  • 实例级例外:只有产品语义确实不同,例如危险操作卡片,才考虑引入 --color-bg-danger-subtle 等新的语义令牌,不应把例外色值硬编码在普通 Card 内。

Figma 语义令牌、主题模式与 Card 组件样式的映射继承关系

这张图中的继承指的是自定义属性的取值继承,并不意味着 background-color 本身会自动继承。Card 仍需要显式声明 background-color: var(--color-bg-surface),才能将当前语义颜色应用到背景。

编写可运行的 Card 样式

下面使用原生 HTML、CSS 和 JavaScript 制作一个最小示例,无需安装框架或构建工具。新建 index.html,保存以下完整内容,再用现代浏览器打开。

示例保留基础色板、语义令牌和组件局部别名三个层次。基础色板只负责存储数值;语义令牌负责主题映射;组件通过语义属性和尺寸令牌生成最终样式。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Card 语义令牌演示</title>
  <style>
    :root {
      /* 基础色板不直接作为组件的颜色依赖。 */
      --palette-white: #ffffff;
      --palette-slate-50: #f8fafc;
      --palette-slate-200: #cbd5e1;
      --palette-slate-600: #475569;
      --palette-slate-800: #1e293b;
      --palette-slate-900: #0f172a;

      --color-bg-surface: var(--palette-white);
      --color-text-primary: var(--palette-slate-900);
      --color-border-default: var(--palette-slate-200);

      --font-family-body: Arial, sans-serif;
      --font-size-body: 14px;
      --line-height-body: 21px;
      --font-weight-body: 400;
      --space-3: 12px;
      --space-4: 16px;
      --radius-md: 8px;
    }

    /* 切换主题时只重映射有变化的语义颜色。 */
    :root[data-theme="dark"] {
      --color-bg-surface: var(--palette-slate-800);
      --color-text-primary: var(--palette-slate-50);
      --color-border-default: var(--palette-slate-600);
    }

    body {
      padding: var(--space-4);
    }

    .card {
      --card-padding: var(--space-4);
      margin-top: var(--space-3);
      padding: var(--card-padding);
      background-color: var(--color-bg-surface);
      color: var(--color-text-primary);
      border: 1px solid var(--color-border-default);
      border-radius: var(--radius-md);
      font-family: var(--font-family-body);
      font-size: var(--font-size-body);
      line-height: var(--line-height-body);
      font-weight: var(--font-weight-body);
    }

    /* 紧凑规格只覆盖本组件的尺寸别名。 */
    .card--compact {
      --card-padding: var(--space-3);
    }
  </style>
</head>
<body>
  <button type="button" id="toggleTheme">切换为深色主题</button>
  <article class="card">默认卡片:项目 A,待办 3 项</article>
  <article class="card card--compact">紧凑卡片:项目 B,待办 1 项</article>

  <script>
    const button = document.getElementById("toggleTheme");
    button.addEventListener("click", () => {
      // 只改变根节点的主题标识,不逐个修改组件。
      const isDark = document.documentElement.dataset.theme === "dark";
      document.documentElement.dataset.theme = isDark ? "light" : "dark";
      button.textContent = isDark ? "切换为深色主题" : "切换为浅色主题";
    });
  </script>
</body>
</html>

预期结果:首次打开时,两张 Card 均为白色背景、深色正文、浅灰边框和 8px 圆角。普通 Card 内边距为 16px,紧凑 Card 为 12px。点击按钮后,两张 Card 同时变为深色背景、浅色正文及深灰边框,而字体、圆角与各自的内边距均保持不变。再次点击即可恢复浅色主题。

这里的 --card-padding 是组件局部别名,目的是让尺寸变体覆盖一个明确的入口。如果直接在 .card--compact 中重新定义 --space-4,该值还可能影响紧凑卡片内部其他引用同一间距令牌的元素,导致无关样式一起变化。

校验计算样式与覆盖边界

运行成功并不代表设计映射正确。需要同时比较 Figma 的令牌值、浏览器计算样式和组件变体行为。

在 Chrome 或其他 Chromium 浏览器中,按 F12 打开开发者工具,进入 Elements(元素),选中 Card 节点,在 Computed(计算样式)中逐项检查。此处使用前述示例的固定设计值,结果应满足以下条件。

检查项 浅色预期 深色预期
background-color rgb(255, 255, 255) rgb(30, 41, 59)
color rgb(15, 23, 42) rgb(248, 250, 252)
border-color rgb(203, 213, 225) rgb(71, 85, 105)
默认 Card 的 padding 16px 16px
紧凑 Card 的 padding 12px 12px
border-radius 8px 8px

如果深色主题下卡片仍显示浅色文字以外的错误值,应优先检查三个位置:

  1. 根节点是否实际具有 data-theme="dark"。
  2. 目标元素的语义属性是否被更近作用域或更高优先级的声明覆盖。
  3. 组件是否绕过语义令牌,直接写入 color: #0f172a 或 background-color: #ffffff 等固定值。

尤其需要避免在 .card 中再次声明 --color-text-primary: #0f172a。这样会让组件使用自己的局部值,而不是从根节点继承主题语义值。修复方法是删除多余覆盖,让主题语义变量在统一位置生效。

若只有紧凑卡片需要变化,应优先增加 --card-padding 这样的组件别名,而不是修改全局间距。若 Light、Dark 的正文色或背景色都需要不同的表达,则应回到语义令牌层更新对应映射。

最后再将 Figma 中的 Card 分别设置为 Light、Dark,核对两种模式下的填充、文字、边框和圆角;再与浏览器的普通、紧凑卡片交叉比较。验收标准是颜色随主题正确变化、尺寸随组件规格正确变化,且任一局部规格都不会意外改变其他组件的主题表现。

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

目录与阅读设置

阅读设置

17

记录一个想法

将语义令牌映射到组件样式

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

登录哪都通