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 变量。
交付前按以下顺序检查映射:
- 在 Figma 选中 Card 实例,检查填充、描边关联的是语义变量还是直接色值。
- 在变量集合中分别查看 Light、Dark 模式,核对语义变量的引用目标与最终色值。
- 选中正文文本,确认文字样式的字体族、字号、行高及字重。
- 在映射表中记录 Figma 名称、CSS 名称、默认值、主题差异和使用组件。
如果设计稿使用 16px 间距,而前端自行改成 14px,即使视觉差异很小,也属于令牌映射不一致,应先确认是否存在正式的紧凑规格,而不是直接修改基础令牌。
让主题在语义层切换
CSS 双连字符自定义属性默认参与层叠并可以从祖先元素继承。将默认语义颜色定义在 :root,再通过根节点的 data-theme 属性覆盖对应颜色,组件就能通过 var() 获取当前主题值。
对于本例,推荐按以下边界处理:
- 主题级覆盖:表面色、正文色和边框色在 Light、Dark 之间重新映射,Card 不保存自己的固定主题色。
- 全局共享:正文的 14px 字号、21px 行高和 8px 圆角在两个主题下使用同一数值,除非设计规范明确要求不同。
- 组件局部覆盖:Card 默认内边距为 16px,紧凑规格可以单独调整为 12px,但不应顺带覆盖全局正文色。
- 实例级例外:只有产品语义确实不同,例如危险操作卡片,才考虑引入
--color-bg-danger-subtle等新的语义令牌,不应把例外色值硬编码在普通 Card 内。

这张图中的继承指的是自定义属性的取值继承,并不意味着 background-color 本身会自动继承。Card 仍需要显式声明 background-color: var(--color-bg-surface),才能将当前语义颜色应用到背景。
编写可运行的 Card 样式
下面使用原生 HTML、CSS 和 JavaScript 制作一个最小示例,无需安装框架或构建工具。新建 index.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 |
如果深色主题下卡片仍显示浅色文字以外的错误值,应优先检查三个位置:
- 根节点是否实际具有
data-theme="dark"。 - 目标元素的语义属性是否被更近作用域或更高优先级的声明覆盖。
- 组件是否绕过语义令牌,直接写入
color: #0f172a或background-color: #ffffff等固定值。
尤其需要避免在 .card 中再次声明 --color-text-primary: #0f172a。这样会让组件使用自己的局部值,而不是从根节点继承主题语义值。修复方法是删除多余覆盖,让主题语义变量在统一位置生效。
若只有紧凑卡片需要变化,应优先增加 --card-padding 这样的组件别名,而不是修改全局间距。若 Light、Dark 的正文色或背景色都需要不同的表达,则应回到语义令牌层更新对应映射。
最后再将 Figma 中的 Card 分别设置为 Light、Dark,核对两种模式下的填充、文字、边框和圆角;再与浏览器的普通、紧凑卡片交叉比较。验收标准是颜色随主题正确变化、尺寸随组件规格正确变化,且任一局部规格都不会意外改变其他组件的主题表现。