设计系统搭建与设计 Token 管理体系：选型别只看功能清单

2026/8/10 1:06:18

设计系统搭建与设计 Token 管理体系：选型别只看功能清单

范围说明：本文给出 Token 治理示例；编译、注入和兼容策略应在目标构建链路中验证。

1. 商业化上线前夕：暗黑模式 CSS 产物突然暴增 4MB

一次主题方案接入后，全局样式从 120KB 增长到 4.2MB，网络加载也多了约 1.8 秒。先查构建产物，往往比继续调网络参数更有效。

构建产物显示，新增的 Token 编译配置展开了过多主题组合。

工具支持的导出格式和主题层级并不等于适合当前工程。若编译阶段把每个 Theme、Brand 和 Level 都展开成静态 CSS 类名，产物会随着组合数快速变大。

选型看功能清单 ➔ 引入复杂 Token 工具 ➔ 暴力展开全量 Theme ➔ CSS 体积暴增 4MB ❌ 选型看工程契约 ➔ W3C Token 标准 + Tree-shaking ➔ CSS Custom Properties 按需注入 ➔ 体积稳定在 45KB ✅

2. 分析 Style Dictionary 构建树节点展开膨胀

为了找出 Token 编译展开的内存与体积膨胀瓶颈，我们在 Node.js 构建脚本中注入诊断标记：

npx style-dictionary build --config ./tokens.config.json --verbose

控制台输出的日志揭露了膨胀细节：

[Style Dictionary] Processing tokens for brand: brand-a, mode: dark... [Style Dictionary] Generated 14,200 CSS variable declarations. [Style Dictionary] Duplicated node paths detected across 12 nested theme groups.

这里的症结不是某个工具“功能不够”，而是 Web 端产物选择了静态展开。CSS 变量能够在运行时覆写主题，没必要为每种组合复制整套选择器。

flowchart TD A[W3C 标准 Token JSON 源码] --> B[Token 编译转换引擎] B -->|错误范式: 全量静态展开| C[生成 14000+ 冗余 CSS 类名 4.2MB] B -->|正确范式: 语义分层 + Tree-shaking| D[提取 Semantic Tokens 集合] D --> E[生成全局根 CSS 变量 Root Var] E --> F[按需注入动态 Theme Override 45KB]

3. 生产级 Token 编译与按需注入源码实现

真正高效的设计 Token 体系，应当严格区分Global Tokens（原始标量）、Semantic Tokens（语义标记）与Component Tokens（组件绑定）。

下面是经过重构后的轻量化 Token 转换引擎核心代码：

// build-tokens.ts import fs from 'fs'; import path from 'path'; interface TokenNode { $value: string; $type: string; $description?: string; } type TokenGroup = Record<string, TokenNode | Record<string, any>>; export class LightweightTokenCompiler { private semanticCssBuffer: string[] = []; // 仅编译和注入语义层 Token，避免全量展开 Global Tokens public compileToCssVariables(tokens: TokenGroup, prefix = 'ds'): string { this.semanticCssBuffer = []; this.semanticCssBuffer.push(':root {'); this.walkTokenTree(tokens, prefix); this.semanticCssBuffer.push('}'); return this.semanticCssBuffer.join('\n'); } private walkTokenTree(obj: Record<string, any>, currentPath: string): void { for (const key of Object.keys(obj)) { if (key.startsWith('$')) continue; // 过滤元数据 const val = obj[key]; const newPath = `${currentPath}-${key}`; if (val && typeof val === 'object' && '$value' in val) { // 解析引用值，如 {color.primitive.blue.500} 转换为 var(--ds-color-primitive-blue-500) const cssValue = this.resolveTokenReference(val.$value); this.semanticCssBuffer.push(` --${newPath}: ${cssValue};`); } else if (typeof val === 'object') { this.walkTokenTree(val, newPath); } } } private resolveTokenReference(value: string): string { if (value.startsWith('{') && value.endsWith('}')) { const pathKeys = value.slice(1, -1).split('.'); return `var(--ds-${pathKeys.join('-')})`; } return value; } } // 运行编译器 const compiler = new LightweightTokenCompiler(); const rawTokens = JSON.parse(fs.readFileSync('./tokens/semantic.json', 'utf8')); const cssOutput = compiler.compileToCssVariables(rawTokens); fs.writeFileSync('./dist/tokens.css', cssOutput);

配合前端框架的增量主题切换机制，无需加载多余样式：

// theme-loader.ts export function applyDynamicTheme(themeName: 'light' | 'dark'): void { // 仅通过修改 html 根节点属性，触发 CSS 变量替换，无任何 CSS 文件体积增加 document.documentElement.setAttribute('data-theme', themeName); }

/* tokens.css - 极度精简的增量覆写 */ :root { --ds-color-bg-primary: #FFFFFF; --ds-color-text-main: #0F172A; } [data-theme="dark"] { --ds-color-bg-primary: #0F172A; --ds-color-text-main: #F8FAFC; }