UI 视觉设计 / 系统课时
把设计变量映射成CSS Token
把设计变量映射成CSS Token
把设计稿中的颜色、文字、间距和圆角转换为 CSS 自定义属性,并让组件通过语义变量取值。本篇用一个可切换明暗主题的工单卡片完成映射、实现和验收,避免组件散落硬编码颜色。
学习目标
- 区分基础 Token 与语义 Token,并建立可追溯的命名映射。
- 使用 CSS 自定义属性统一控制颜色、文字、间距和圆角。
- 验证主题切换时语义引用和组件计算样式是否同步变化。
建立设计变量到 CSS 的对照
先从 Figma 的 Variables 面板整理变量名称、模式和值。以下是一套示例约定;实际项目可采用不同路径,但导出名称必须固定,不能一处写 blue-600、另一处写 primaryBlue。
| Figma 设计变量(示例) | CSS 基础 Token | 值 |
|---|---|---|
| Color/Blue/600 | --palette-blue-600 |
#2563eb |
| Color/Blue/300 | --palette-blue-300 |
#93c5fd |
| Color/Neutral/0 | --palette-white |
#ffffff |
| Color/Neutral/900 | --palette-ink-900 |
#0f172a |
| Typography/Body/Size | --font-size-body |
16px |
| Typography/Body/Weight | --font-weight-body |
400 |
| Spacing/2、Spacing/3 | --space-2、--space-3 |
8px、12px |
| Radius/Medium | --radius-md |
8px |
基础变量保存色板或尺寸标尺;语义变量描述用途,例如 --color-primary(主操作)和 --color-surface(页面底色)。设计稿里的语义变量应逐项对应到 CSS 语义变量,而不是让按钮直接引用 --palette-blue-600。
理清明暗主题的引用链
浅色模式下,--color-primary 指向 --palette-blue-600;深色模式改为 --palette-blue-300。按钮始终只写 background: var(--color-primary),因此切换模式时不必改按钮类名。文字和页面底色同理;间距 12px 与圆角 8px 在本例中跨主题保持一致。
| Figma 语义变量(示例) | CSS 语义 Token | Light 引用 | Dark 引用 |
|---|---|---|---|
| Semantic/Action/Primary | --color-primary |
--palette-blue-600 |
--palette-blue-300 |
| Semantic/Surface/Default | --color-surface |
--palette-white |
--palette-ink-900 |
| Semantic/Text/Primary | --color-text |
--palette-ink-900 |
--palette-muted-100 |

实现可切换主题的最小页面
将下面内容保存为 tokens.html,用浏览器直接打开。:root 中声明基础值和默认语义映射,:root[data-theme='dark'] 只覆盖需要变动的语义值。页面与按钮使用相同的语义入口,JS 仅切换根元素的 data-theme。
<!doctype html>
<html lang='zh-CN' data-theme='light'>
<head>
<meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<title>CSS Token 演示</title>
<style>
:root {
/* 基础层:与设计变量的实际取值对应 */
--palette-blue-600: #2563eb;
--palette-blue-300: #93c5fd;
--palette-white: #ffffff;
--palette-ink-900: #0f172a;
--palette-ink-800: #1e293b;
--palette-muted-100: #f1f5f9;
--palette-border-200: #cbd5e1;
--font-size-body: 16px;
--font-weight-body: 400;
--space-2: 8px;
--space-3: 12px;
--radius-md: 8px;
/* 语义层:组件不直接依赖色板编号 */
--color-surface: var(--palette-white);
--color-text: var(--palette-ink-900);
--color-border: var(--palette-border-200);
--color-primary: var(--palette-blue-600);
--color-on-primary: var(--palette-white);
}
:root[data-theme='dark'] {
--color-surface: var(--palette-ink-900);
--color-text: var(--palette-muted-100);
--color-border: var(--palette-ink-800);
--color-primary: var(--palette-blue-300);
--color-on-primary: var(--palette-ink-900);
}
body {
margin: 0;
padding: var(--space-3);
background: var(--color-surface);
color: var(--color-text);
font: var(--font-weight-body) var(--font-size-body) system-ui, sans-serif;
}
.panel {
padding: var(--space-3);
border: 1px solid var(--color-border);
border-radius: var(--radius-md);
}
button {
padding: var(--space-2) var(--space-3);
border: 0;
border-radius: var(--radius-md);
background: var(--color-primary);
color: var(--color-on-primary);
cursor: pointer;
}
</style>
</head>
<body>
<section class='panel'>
<p>工单概览</p>
<button id='theme-toggle' type='button'>切换主题</button>
</section>
<script>
const root = document.documentElement;
const toggle = document.querySelector('#theme-toggle');
function reportTheme() {
const style = getComputedStyle(document.body);
console.log(`${root.dataset.theme}: ${style.backgroundColor} / ${style.color}`);
}
// 只切换主题标记,保留各组件的 Token 引用。
toggle.addEventListener('click', () => {
root.dataset.theme = root.dataset.theme === 'light' ? 'dark' : 'light';
reportTheme();
});
reportTheme();
</script>
</body>
</html>预期输出(以 Chrome 的 Console 为例,首次加载后点击一次按钮):
light: rgb(255, 255, 255) / rgb(15, 23, 42)
dark: rgb(15, 23, 42) / rgb(241, 245, 249)可见效果是页面从白底深字变为深底浅字,按钮从深蓝底白字变为浅蓝底深字;卡片内边距仍是 12px,圆角仍是 8px。控制台打印的是实际计算后的颜色,不是尚未展开的 var(...) 引用。
检查覆盖层级和交付一致性
- 在 Chrome 按
F12打开开发者工具,进入 Elements → Styles,选中按钮,确认background来自var(--color-primary),而不是写死的十六进制色值。 - 进入 Computed,检查按钮的最终
background-color:浅色为rgb(37, 99, 235),深色为rgb(147, 197, 253);页面background-color同步切换。 - 检查根元素
html的data-theme:点击前是light,点击后是dark。若深色不生效,先看属性是否错误地加在body上,因为本例选择器匹配的是:root。 - 回到设计变量表逐项核对单位和取值:
16px正文字号、8px/12px间距、8px圆角在两个主题下均不应改变。
若某项样式突然消失,先检查 var() 中的名称是否拼错;无回退值的无效变量引用会让该属性声明失效,不要靠随意添加回退色掩盖错误。
交付给开发时,至少同时提供设计变量名、基础 Token、语义 Token、明暗模式对应值这四列映射;验收以浏览器实际计算样式为准,不能只核对 CSS 中是否出现了变量名。