当设计稿的变量遇上代码的变量：从 Figma 到 CSS Variable 的管道为何总是断流-平芜编程栈

当设计稿的变量遇上代码的变量：从 Figma 到 CSS Variable 的管道为何总是断流

一、深度引言与场景痛点

设计 Token 是设计系统的心跳——每一组颜色、间距、字号都是一个脉搏信号，从设计工具传向代码仓库，驱动整个产品界面的统一节奏。Figma 里的变量定义得再漂亮，如果传不到 CSS 代码里，那脉搏就断了。

断流的痛点不是"能不能传"，而是"怎么传才不漏、不乱、不慢"。手动导出 JSON 再手动写 CSS Variable？设计师改一次颜色，开发者就得手动改一次代码，中间有无数个"忘了更新"的时刻。自动导出工具能解决速度问题，但映射规则、命名对齐、多主题同步这些结构性问题，才是管道真正容易堵塞的地方。

这篇文章要搭建的管道：从 Figma Variables API 自动提取设计 Token，经过语义映射层转换命名格式，输出为 CSS 自定义属性文件，并自动提交到组件库仓库。管道全程自动化，设计师在 Figma 中修改 Token，代码仓库在几分钟内同步更新。

二、底层机制与原理深度剖析

Figma 到 CSS Variable 的管道由三个核心阶段组成：提取、映射、输出。每个阶段处理一类特定问题，逐层把设计意图转化为可执行的代码声明。

flowchart LR A[Figma Variables API] --> B[提取层] B --> B1[遍历 Variable Collections] B --> B2[读取每个 Variable 的值与类型] B --> B3[提取模式 Mode 映射关系] B1 & B2 & B3 --> C[映射层] C --> C1[命名格式转换：figma-name → kebab-case] C --> C2[语义层级重构：primitive → semantic] C --> C3[别名关系解析：Variable 引用链展开] C1 & C2 & C3 --> D[输出层] D --> D1[生成 tokens.css：CSS 自定义属性] D --> D2[生成 tokens.json：跨平台共享源] D --> D3[Git 提交触发 CI 同步] D1 --> E[组件库样式入口] D2 --> F[iOS / Android 转换管道]

提取层通过 Figma REST API 访问 Variables 数据。每个 Collection 是一个 Token 分组（比如Global Colors、Spacing），每个 Variable 有name、value、variableType三个核心字段。Figma 支持 Mode（模式）机制——一个 Variable 可以在不同 Mode 下有不同值，这正是暗色模式的天然容器：同一个background-primaryVariable，在LightMode 下是白色，在DarkMode 下是深灰。

映射层解决命名对齐问题。Figma 的变量命名使用/作为层级分隔符（如Colors/Primary/Blue500），而 CSS Variable 使用-连接（如--colors-primary-blue-500）。映射层还负责语义层级重构——Figma 中设计师可能定义的是原始色值（primitive），但 CSS 中需要语义引用（semantic），比如--color-background-primary应该引用--color-blue-500而不是直接写值。这层映射确保了设计意图的语义传递。

输出层将映射后的 Token 写入两种格式：CSS 自定义属性文件供 Web 端直接使用，JSON 文件供 iOS/Android 端的转换管道消费。输出后通过 Git 自动提交触发 CI，确保代码仓库始终与 Figma 同步。

三、生产级代码实现与最佳实践

Figma Token 提取脚本：

// scripts/figma-token-extract.ts import { FigmaClient } from './figma-client'; interface FigmaVariable { id: string; name: string; variableType: 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN'; resolvedType: string; valuesByMode: Record<string, string | number | { r: number; g: number; b: number; a: number }>; aliasesByMode?: Record<string, string>; // 引用其他 Variable 的 ID } interface TokenOutput { name: string; // 语义化 CSS 命名 value: string; // 最终值或 CSS 引用表达式 type: 'color' | 'spacing' | 'font-size' | 'font-weight' | 'opacity' | 'border-radius'; figmaName: string; // 原始 Figma 命名（用于溯源） mode: string; // 所属模式（Light / Dark） } // Figma 文件 key 和项目 Token Collection ID const FIGMA_FILE_KEY = process.env.FIGMA_FILE_KEY!; const FIGMA_TOKEN_COLLECTIONS = ['Global Colors', 'Spacing', 'Typography']; async function extractTokens(): Promise<TokenOutput[]> { const client = new FigmaClient(process.env.FIGMA_ACCESS_TOKEN!); const tokens: TokenOutput[] = []; // 获取文件中所有 Variable Collections const collections = await client.getVariableCollections(FIGMA_FILE_KEY); for (const collectionName of FIGMA_TOKEN_COLLECTIONS) { const collection = collections.find(c => c.name === collectionName); if (!collection) continue; // 获取 Collection 下的所有 Variables const variables = await client.getVariablesByCollection( FIGMA_FILE_KEY, collection.id ); // 遍历每个 Mode（通常是 Light 和 Dark） for (const [modeId, modeName] of Object.entries(collection.modes)) { for (const variable of variables) { const modeValue = variable.valuesByMode[modeId]; // 如果值是引用（alias），先解析引用链 const resolvedValue = resolveAlias(variable, modeId, variables); tokens.push({ // Figma 的 / 分隔符转为 CSS 的 - 连接符 name: figmaNameToCssName(variable.name), value: formatValue(resolvedValue, variable.variableType), type: figmaTypeToTokenType(variable.variableType), figmaName: variable.name, mode: modeName }); } } } return tokens; } // Figma 命名转 CSS Variable 命名 function figmaNameToCssName(figmaName: string): string { // Colors/Primary/Blue500 → --colors-primary-blue-500 const segments = figmaName .split('/') .map(s => s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()); return `--${segments.join('-')}`; } // 格式化 Token 值为 CSS 合法格式 function formatValue(value: any, type: string): string { if (type === 'COLOR' && typeof value === 'object') { // Figma 颜色值为 {r, g, b, a}，转为 rgba() const { r, g, b, a } = value; return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`; } if (type === 'FLOAT') { // 间距等数值 Token，带单位 return `${value}px`; } return String(value); } // 解析 Variable 引用链：确保语义 Token 引用原始 Token function resolveAlias( variable: FigmaVariable, modeId: string, allVariables: FigmaVariable[] ): any { const aliasId = variable.aliasesByMode?.[modeId]; if (!aliasId) return variable.valuesByMode[modeId]; // 递归解析引用，直到找到最终值 const referenced = allVariables.find(v => v.id === aliasId); if (!referenced) return variable.valuesByMode[modeId]; return resolveAlias(referenced, modeId, allVariables); } function figmaTypeToTokenType(type: string): TokenOutput['type'] { const map: Record<string, TokenOutput['type']> = { 'COLOR': 'color', 'FLOAT': 'spacing', 'STRING': 'font-size', }; return map[type] || 'spacing'; }

CSS Variable 输出生成：

// scripts/generate-css-tokens.ts import { extractTokens } from './figma-token-extract'; import fs from 'fs'; async function generateCssTokens() { const tokens = await extractTokens(); // 按 Mode 分组：Light 和 Dark 分别输出 const lightTokens = tokens.filter(t => t.mode === 'Light'); const darkTokens = tokens.filter(t => t.mode === 'Dark'); // Light 模式：默认值声明 const lightCss = lightTokens.map(t => ` ${t.name}: ${t.value}; /* 源: ${t.figmaName} */` ).join('\n'); // Dark 模式：覆盖声明 const darkCss = darkTokens.map(t => ` ${t.name}: ${t.value}; /* 源: ${t.figmaName} */` ).join('\n'); const output = `/* 设计 Token — 自动生成，勿手动编辑 */ /* 生成时间: ${new Date().toISOString()} */ /* Figma 源文件: ${process.env.FIGMA_FILE_KEY} */ :root { ${lightCss} } [data-theme="dark"] { ${darkCss} } `; fs.writeFileSync('src/styles/tokens.css', output); console.log(`✅ 已生成 ${tokens.length} 个 Token 至 tokens.css`); } generateCssTokens();

CI 自动同步 Git 提交：

# .github/workflows/token-sync.yml name: Design Token Sync on: schedule: - cron: '0 */4 * * *' # 每4小时自动同步 workflow_dispatch: # 手动触发同步 jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci # 从 Figma 提取并生成 Token 文件 - run: node scripts/generate-css-tokens.ts env: FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }} FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }} # 检测是否有变更 - id: changes run: | if git diff --quiet src/styles/tokens.css; then echo "has_changes=false" >> $GITHUB_OUTPUT else echo "has_changes=true" >> $GITHUB_OUTPUT fi # 有变更时自动提交 - if: steps.changes.outputs.has_changes == 'true' run: | git config user.name "Design Token Bot" git config user.email "token-bot@design-system.dev" git add src/styles/tokens.css git commit -m "sync: 更新设计 Token from Figma" git push

四、边界分析与架构权衡

Figma API 的速率限制。REST API 每分钟最多 60 次请求，大型项目的 Token 提取可能需要多次分页请求。CI 定时同步间隔设为 4 小时是合理的平衡点，更频繁的同步会撞上速率墙。如果需要即时同步，可以在 Figma 端设置 Webhook 插件，在 Variable 修改时主动推送变更信号。

命名映射的语义断层。Figma 中设计师的命名习惯是视觉导向的（Blue500），而 CSS Variable 需要语义导向的命名（--color-background-primary）。自动转换脚本只能做格式转换（/→-），语义重构需要额外的映射配置文件。这个映射文件本身需要人工维护——哪个原始色值对应哪个语义用途，这是设计决策而非技术决策。

引用链的深度问题。Figma 变量支持多层引用：语义 Token 引用中间 Token，中间 Token 引用原始 Token。深度引用链在提取时需要递归解析，而递归可能产生循环引用（如果设计师在 Figma 中不小心把 A 引用了 B，B 又引用了 A）。提取脚本必须加入循环检测逻辑，避免无限递归。

多平台输出的复杂性。CSS Variable 只解决了 Web 端的问题，iOS 和 Android 各有自己的 Token 体系。JSON 中间格式是跨平台同步的基础，但 iOS 的 Swift Color 需要不同的数值格式，Android 的 XML Resource 有自己的命名规则。管道需要额外的转换层适配每个平台的语法习惯，这些转换层的维护成本随平台数量线性增长。