设计系统搭建与设计 Token 管理体系：发布前检查失败路径与回滚

1. 交付前检查：深色主题最容易漏什么

产品新版本准备在周五下午四点正式提测并发布。就在交付前最后一小时，qa 在测试黑暗模式（Dark Mode）切流时，突然发现新建项目的主弹窗里，原本应该清晰可见的说明文字全变成了“黑底黑字”的隐形文本。用户根本看不清按钮上写了什么，整个主流程被卡死。

团队紧急召集 UI 设计师和前端排查，大家互找原因：UI 确定 Figma 里的设计规范全都有，前端也声称自己 100% 引用了 CSS 变量。

# 扫描产物 CSS 中未建立语义映射的硬编码颜色与冲突 Token grep -E -r "var\(--color-text-main\)" dist/css/ | grep "background-color: #000" # 使用 stylelint 扫描非标准 Design Token 变量命名 npx stylelint "src/**/*.css" --custom-syntax stylelint-config-design-system

深入代码细节后才暴露问题根因：前端在组件开发时，把原本应该映射到sys.color.on-surface（随主题切流变化的语义 Token）错写成了primitive.color.gray-900（写死不变的基础原始色值 Token）。交付前如果不做自动化深度检查，仅凭人工在几十个页面里肉眼走查，很难不漏掉隐蔽的主题色失误。

flowchart TD A[Design Token JSON 定义导出] --> B[Style Dictionary 编译管道] B --> C[生成 CSS / TailWind / TS 配置文件] C --> D{交付前自动化检查卡点} D -- 检查 1 --> E[WCAG 2.1 AA 级对比度断言 ≥ 4.5:1] D -- 检查 2 --> F[未使用的孤立 Token 标记清理] D -- 检查 3 --> G[暗黑/亮色 双主题语义 Token 对齐] E & F & G -- 校验全通过 --> H[生成最终编译产物并准许发布] E & F & G -- 存在违规 --> I[中断 CI 构建并输出错误 Token 映射路径]

2. 追查 Token 映射链路：在语义层 Alias Token 上被写死了硬编码

在成熟的设计系统体系中，Token 绝不能只是一堆乱糟糟的 CSS 变量。它必须严格划分为四级分层架构：

1. Primitive Tokens（原始层）：如color.blue.500 = #3B82F6（只描述物理属性，不包含业务语义）。
2. Semantic Tokens（语义层）：如color.interactive.primary = {color.blue.500}（根据场景映射）。
3. Component Tokens（组件层）：如button.primary.background = {color.interactive.primary}。
4. Theme Overrides（主题覆写层）：在 Dark Mode 下把color.interactive.primary动态重新绑定至color.blue.400。

当时出问题的代码片段如下：

/* ❌ 错误示范：组件直接绑定了 Primitive 原始 Token，丧失了主题响应能力 */ .modal-body-text { background-color: var(--color-surface-dark); /* 暗色背景 */ color: var(--color-gray-900); /* 错误绑定了浅色主题下的深灰原始色值，切换暗色后直接黑底黑字！ */ }

要从根本上避免这种情况，就必须在交付前挂载自动编译与断言检查脚本，强行阻断任何组件对 Primitive 原始 Token 的直接越级引用。

3. Style Dictionary 管道改造：构建强校验的四级 Token 架构

我们使用 Style Dictionary 重构了整个 Design Token 的编译管道。所有 Token 在 JSON 源文件里定义，编译阶段自动推导生成 TypeScript 类型声明、CSS 自定义属性以及 Tailwind 配置文件。

同时，在转换器（Transform）层注入了严格的映射层级校验器：

// style-dictionary.config.js const StyleDictionary = require('style-dictionary'); // 注册自定义校验转换器：禁止在组件层直接引用原始色值 StyleDictionary.registerTransform({ name: 'attribute/enforce-semantic-alias', type: 'value', matcher: (prop) => prop.path[0] === 'component', transformer: (prop, options) => { // 如果组件级 Token 的 original 属性直接使用了 hex/rgb 色值，直接抛错 if (/^#|^rgb|^hsl/.test(prop.original.value)) { throw new Error( `❌ [Token 架构违规] 组件 Token [${prop.name}] 不允许直接赋值原始色值 [${prop.original.value}]，必须引用语义层 Semantic Token！` ); } return prop.value; }, }); module.exports = { source: ['tokens/**/*.json'], platforms: { css: { transforms: ['attribute/cti', 'color/css', 'attribute/enforce-semantic-alias'], buildPath: 'build/css/', files: [{ destination: 'variables.css', format: 'css/variables' }] } } };

引入编译管道拦截后，任何开发者尝试在设计系统代码库里手写#HEX色值或直接跨层引用的行為，都会在保存的瞬间被编译器直接拦截报红。

4. 自动化检查脚本：基于 WCAG 4.5:1 色彩对比度的无头校验器

为了确保亮色模式与暗色模式下的文本可读性，交付前的最后检查必须包含 WCAG 2.1 AA 级无障碍（Accessibility）色彩对比度计算。

我们编写了一个 Node.js 脚本，自动提取编译好的 Token JSON 树，计算所有textToken 与对应的backgroundToken 之间的相对亮度比（Relative Luminance Ratio）。如果对比度低于 4.5:1（大文本低于 3.0:1），强制判定检查失败。

// validate-contrast.ts import chroma from 'chroma-js'; import * as fs from 'fs'; interface TokenPair { textToken: string; bgToken: string; textColor: string; bgColor: string; } export function validateAccessibilityTokens(tokensJsonPath: string): void { const rawData = fs.readFileSync(tokensJsonPath, 'utf8'); const tokens = JSON.parse(rawData); const failures: Array<{ pair: string; ratio: number }> = []; // 1. 遍历所有明暗主题配置 const themes = ['light', 'dark']; for (const theme of themes) { const themeTokens = tokens.theme[theme]; // 检查核心语义对: surface 与 on-surface const bgHex = themeTokens.color.surface.value; const textHex = themeTokens.color['on-surface'].value; // 2. 计算 chroma 对比度 const contrastRatio = chroma.contrast(bgHex, textHex); console.log(`[${theme.toUpperCase()}] 模式对比度校验: surface(${bgHex}) vs on-surface(${textHex}) = ${contrastRatio.toFixed(2)}:1`); // 3. WCAG 2.1 AA 标准卡点断言 (普通文本要求 >= 4.5:1) if (contrastRatio < 4.5) { failures.push({ pair: `${theme} - surface vs on-surface`, ratio: contrastRatio, }); } } if (failures.length > 0) { console.error('❌ [Accessibility Failed] 色彩对比度未达标交付标准:'); failures.forEach((f) => console.error(` - ${f.pair}: 当前对比度仅 ${f.ratio.toFixed(2)}:1 (要求 >= 4.5:1)`)); process.exit(1); // 拒绝交付 } else { console.log('✅ WCAG 2.1 AA 双主题无障碍对比度检查全量通过！'); } }

这套检查逻辑彻底消除了“暗黑模式隐形字”的可能。在脚本运行的短短 2 秒内，系统会自动穷举所有主题下背景与字体的组合，只要有任何不达标的暗坑，立刻在日志中高亮输出。

5. 提测防线卡卡点：不通过 Token Diff 与无障碍对比度检测不许发布

设计系统搭建的终局，是用确定性的 CI/CD 流水线把守住交付前的最后检查关口。我们把检查流程封装到了 Git Pre-push Hook 和 CI Pipeline 步骤里：

# 交付前检查 Task 组合命令 npm run build:tokens && npx ts-node validate-contrast.ts && npm run test:token-diff

检查项至少要覆盖：深浅主题的语义 Token 是否成对存在、文本与背景的对比度是否达到目标，以及组件是否绕过了 Token。对于图表、插画和品牌色，另行记录允许的例外和原因。

自动检查能在交付前发现常见遗漏，但不能代替真实页面走查。把检查命令、阈值和例外写清楚，下一次修改才有据可循。