Design Token 單一真源從 Figma 變量到代碼的工程化同步一、設(shè)計(jì)稿與代碼的漂移Token 治理的工程痛點(diǎn)在多人協(xié)作的前端工程中設(shè)計(jì)稿與代碼不一致是高頻出現(xiàn)的協(xié)作債務(wù)。設(shè)計(jì)師在 Figma 中定義了一組顏色變量如color/brand/primary-500開發(fā)者在代碼中以硬編碼方式如#3B82F6使用。當(dāng)品牌升級(jí)需要調(diào)整主色時(shí)設(shè)計(jì)師在 Figma 中改一次開發(fā)者卻需要在代碼庫中全局搜索替換遺漏與不一致幾乎不可避免。這種漂移的根因是設(shè)計(jì)源與代碼源分離。設(shè)計(jì)稿與代碼各自維護(hù)一份顏色、間距、字體的真理兩者之間沒有機(jī)器可校驗(yàn)的同步鏈路。Design Token 的提出正是為了消除這一分裂——它定義了一種與平臺(tái)無關(guān)的中間表示使設(shè)計(jì)決策可以從 Figma 單向流向前端、iOS、Android 等多端代碼產(chǎn)物。但 Design Token 落地的工程復(fù)雜度遠(yuǎn)超把顏色寫成變量。它涉及 Token 的分層策略、命名規(guī)范、跨平臺(tái)轉(zhuǎn)譯、版本管理與 CI 校驗(yàn)。本文聚焦 Figma 到前端代碼的同步鏈路討論生產(chǎn)級(jí) Token 體系的工程實(shí)現(xiàn)與權(quán)衡。二、Token 分層與同步鏈路從 Figma 變量到多平臺(tái)產(chǎn)物要理解 Design Token 的同步鏈路需要先看 Token 的分層模型。W3C Design Tokens Format Module 定義了 Token 的標(biāo)準(zhǔn)結(jié)構(gòu)但實(shí)際工程中需要在標(biāo)準(zhǔn)之上做分層治理。2.1 Token 的三層分層模型生產(chǎn)級(jí) Token 體系通常分為三層原始 Token、語義 Token、組件 Token。原始 Token 是無意義的原子值如color-blue-500: #3B82F6。它只描述是什么不描述用于哪里。語義 Token 描述用途如color-background-primary它的值引用原始 Token。組件 Token 描述具體組件的某個(gè)屬性如button-primary-bg它的值引用語義 Token。三層之間的引用關(guān)系如下圖所示。[Figma Variables] [代碼產(chǎn)物] ------------------ ------------------- | 原始 Token | Style | CSS 變量 | | color-blue-500 | Dictionary | --color-blue-500 | | space-4 | -------------- | --space-4 | ------------------ 轉(zhuǎn)譯 ------------------- | | v v ------------------ ------------------- | 語義 Token | | CSS 變量語義 | | color-bg-primary | 引用關(guān)系保留 | --color-bg-primary| | color-blue-500| | var(--color-blue-500) | ------------------ ------------------- | | v v ------------------ ------------------- | 組件 Token | | 組件級(jí)樣式 | | button-bg | | .button { | | color-bg-... | | background: | ------------------ | var(--color-bg-primary)| | } | -------------------2.2 同步鏈路的關(guān)鍵節(jié)點(diǎn)從 Figma 到代碼的同步鏈路包含五個(gè)關(guān)鍵節(jié)點(diǎn)每個(gè)節(jié)點(diǎn)都有明確的輸入輸出與校驗(yàn)職責(zé)。節(jié)點(diǎn)輸入輸出校驗(yàn)職責(zé)Figma Variables設(shè)計(jì)師定義.tokens.jsonW3C 格式命名規(guī)范、引用完整性Token 倉庫.tokens.jsonStyle Dictionary 配置分層結(jié)構(gòu)、循環(huán)引用Style DictionaryToken 加配置CSS、SCSS、TS、iOS、Android轉(zhuǎn)譯正確性前端代碼庫轉(zhuǎn)譯產(chǎn)物組件樣式Token 使用率 lintCI 校驗(yàn)PR diff通過或阻斷禁止硬編碼顏色2.3 引用關(guān)系與循環(huán)檢測語義 Token 引用原始 Token組件 Token 引用語義 Token形成有向無環(huán)圖DAG。Style Dictionary 在轉(zhuǎn)譯時(shí)會(huì)展開引用將button-bg: {color-bg-primary}解析為最終的 CSS 值。但如果 Token 之間存在循環(huán)引用如 A 引用 BB 又引用 A轉(zhuǎn)譯會(huì)陷入死循環(huán)。工程上需要在 Token 入庫階段做拓?fù)渑判蛐ｒ?yàn)發(fā)現(xiàn)環(huán)則拒絕入庫。三、Style Dictionary 流水線生產(chǎn)級(jí) Token 轉(zhuǎn)譯與校驗(yàn)實(shí)現(xiàn)以下實(shí)現(xiàn)基于 Style Dictionary v4它支持 W3C Design Tokens Format Module并可通過插件擴(kuò)展多平臺(tái)輸出。3.1 Token 文件結(jié)構(gòu)與命名規(guī)范// tokens/primitive/color.json // 原始 Token 層只包含無語義的原子值 // 命名規(guī)范{category}-{item}-{variant} // 嚴(yán)禁在此層引入業(yè)務(wù)語義否則會(huì)破壞分層治理 { color: { blue: { 500: { value: #3B82F6, type: color }, 600: { value: #2563EB, type: color } }, gray: { 100: { value: #F3F4F6, type: color }, 900: { value: #111827, type: color } } }, space: { 4: { value: 16px, type: dimension }, 8: { value: 32px, type: dimension } } }// tokens/semantic/color.json // 語義 Token 層使用引用而非硬編碼 // 引用語法 {path.to.token} 是 W3C 標(biāo)準(zhǔn)的一部分 // 關(guān)鍵約束語義 Token 只能引用原始 Token禁止跨語義層引用 { color: { background: { primary: { value: {color.gray.100}, type: color }, inverse: { value: {color.gray.900}, type: color } }, brand: { primary: { value: {color.blue.500}, type: color }, primary-hover:{ value: {color.blue.600}, type: color } } } }3.2 Style Dictionary 配置與多平臺(tái)轉(zhuǎn)譯// style-dictionary.config.mjs // Style Dictionary v4 配置 // 關(guān)鍵設(shè)計(jì) // 1. 按原始、語義、組件三層分別 include確保引用順序 // 2. 每個(gè)平臺(tái)web/css、web/ts獨(dú)立配置避免產(chǎn)物耦合 // 3. 轉(zhuǎn)譯時(shí)保留引用關(guān)系CSS 變量版便于運(yùn)行時(shí)主題切換 import StyleDictionary from style-dictionary; import { promises as fs } from node:fs; import path from node:path; // 自定義格式輸出帶 CSS 變量引用的產(chǎn)物 // 選擇保留引用而非展開最終值是為了支持運(yùn)行時(shí)主題切換 // 展開值會(huì)導(dǎo)致主題切換時(shí)需要重新加載所有 CSS StyleDictionary.registerFormat({ name: css/variables-with-references, format: async ({ dictionary, file }) { const lines [ /* Generated by Style Dictionary - do not edit */, :root {, ]; for (const token of dictionary.allTokens) { // 原始 Token 輸出值語義 Token 輸出 var() 引用 const value token.original.value.startsWith({) ? var(--${token.path.join(-)}) : token.value; lines.push( --${token.path.join(-)}: ${value};); } lines.push(}); return lines.join(\n); }, }); const sd new StyleDictionary({ // include 順序決定引用解析原始 Token 必須先于語義 Token include: [ tokens/primitive/**/*.json, tokens/semantic/**/*.json, tokens/component/**/*.json, ], platforms: { css: { transformGroup: css, buildPath: dist/css/, files: [ { destination: tokens.css, format: css/variables-with-references, }, ], }, ts: { transformGroup: ts, buildPath: dist/ts/, files: [ { destination: tokens.ts, format: javascript/es6, // TS 產(chǎn)物用于組件庫的類型校驗(yàn)確保代碼中使用合法 Token options: { type: module }, }, ], }, }, }); // 構(gòu)建前的循環(huán)引用檢測 // 通過拓?fù)渑判蚺袛?Token 引用圖是否存在環(huán) // 環(huán)的存在會(huì)導(dǎo)致 Style Dictionary 轉(zhuǎn)譯時(shí)無限遞歸 async function detectCircularReferences(tokens) { const graph new Map(); for (const token of tokens) { const refs extractReferences(token.original.value); graph.set(token.path.join(.), refs); } // 深度優(yōu)先遍歷檢測環(huán) const visited new Set(); const stack new Set(); for (const [node] of graph) { if (hasCycle(node, graph, visited, stack)) { throw new Error(檢測到循環(huán)引用起始節(jié)點(diǎn)${node}); } } } function extractReferences(value) { if (typeof value ! string) return []; const matches value.matchAll(/\{([^}])\}/g); return [...matches].map((m) m[1]); } function hasCycle(node, graph, visited, stack) { if (stack.has(node)) return true; if (visited.has(node)) return false; visited.add(node); stack.add(node); for (const dep of graph.get(node) ?? []) { if (hasCycle(dep, graph, visited, stack)) return true; } stack.delete(node); return false; } try { // 先做循環(huán)檢測避免 Style Dictionary 進(jìn)入死循環(huán)導(dǎo)致 CI 卡死 await detectCircularReferences(sd.tokens); await sd.cleanAllPlatforms(); await sd.buildAllPlatforms(); console.log([tokens] 轉(zhuǎn)譯完成); } catch (err) { console.error([tokens] 轉(zhuǎn)譯失敗${err.message}); process.exit(1); }3.3 CI 校驗(yàn)與硬編碼阻斷// scripts/lint-tokens-usage.js // 校驗(yàn)代碼庫中是否出現(xiàn)硬編碼顏色或間距 // 阻斷策略 // - 顏色十六進(jìn)制值如 #3B82F6直接阻斷 // - px 間距值如 16px記錄警告允許但不推薦 // - 例外tailwind 配置、構(gòu)建腳本本身可豁免 const { execSync } require(node:child_process); const IGNORE_PATTERNS [ tailwind.config.js, scripts/lint-tokens-usage.js, style-dictionary.config.mjs, ]; // 獲取本次 PR 修改的樣式相關(guān)文件 const changedFiles execSync( git diff --name-only --diff-filterACM origin/main...HEAD, { encoding: utf8 } ).split(\n).filter(Boolean); const violations []; for (const file of changedFiles) { if (IGNORE_PATTERNS.some((p) file.includes(p))) continue; if (!/\.(css|scss|vue|tsx|jsx)$/.test(file)) continue; const content execSync(git show HEAD:${file}, { encoding: utf8 }); // 匹配十六進(jìn)制顏色但不匹配注釋中的說明 const hexColorMatches content.matchAll(/(?!\/\/.*)#([0-9a-fA-F]{3,8})\b/g); for (const match of hexColorMatches) { violations.push({ file, line: content.slice(0, match.index).split(\n).length, value: match[0], }); } } if (violations.length 0) { console.error([lint] 發(fā)現(xiàn)硬編碼顏色應(yīng)使用 Design Token); for (const v of violations) { console.error( - ${v.file}:${v.line} 使用了 ${v.value}); } process.exit(1); } console.log([lint] 通過未發(fā)現(xiàn)硬編碼顏色);四、Token 體系的代價(jià)治理成本與平臺(tái)差異邊界Design Token 體系引入的治理成本與平臺(tái)差異需要在落地前充分評(píng)估。4.1 治理成本與組織協(xié)作Token 體系的引入會(huì)改變設(shè)計(jì)師與開發(fā)者的協(xié)作模式。設(shè)計(jì)師需要在 Figma 中嚴(yán)格使用 Variables 而非自由填色這要求 Figma 協(xié)作規(guī)范的培訓(xùn)成本。開發(fā)者需要從隨手寫顏色切換到查 Token 字典初期開發(fā)效率會(huì)有所下降。根據(jù)生產(chǎn)項(xiàng)目的觀測數(shù)據(jù)接入 Token 體系后的前兩周組件開發(fā)耗時(shí)平均增加 15% 至 20%但在第三周后回落到原有水平長期看因減少返工而凈收益為正。治理手段是引入 IDE 插件如 VSCode 的 Design Token 自動(dòng)補(bǔ)全將 Token 查詢的摩擦降到最低。4.2 平臺(tái)差異與轉(zhuǎn)譯損耗不同平臺(tái)的樣式系統(tǒng)存在原生差異。CSS 變量是運(yùn)行時(shí)可改的而 iOS 的 UIColor 在編譯期確定Android 的資源系統(tǒng)對(duì)命名有約束小寫下劃線。Style Dictionary 的 transformGroup 會(huì)做平臺(tái)適配但某些復(fù)雜 Token如帶透明度的顏色、響應(yīng)式間距在轉(zhuǎn)譯到 iOS 時(shí)會(huì)丟失語義。生產(chǎn)實(shí)踐中對(duì)復(fù)雜 Token 需要為每個(gè)平臺(tái)單獨(dú)定義 transform代價(jià)是配置文件膨脹可維護(hù)性下降。4.3 版本管理與兼容性Token 體系作為獨(dú)立 npm 包發(fā)布后下游代碼庫依賴特定版本。Token 重命名或刪除會(huì)構(gòu)成破壞性變更需要 Semver 主版本號(hào)升級(jí)。治理手段是引入deprecated標(biāo)記與別名機(jī)制在 Token 倉庫中保留舊名稱一段時(shí)間給予下游遷移窗口。代價(jià)是 Token 倉庫會(huì)累積歷史別名需要定期做廢棄清理否則命名空間會(huì)逐漸污染。4.4 適用邊界與禁用場景Token 體系不適用于以下場景。第一營銷活動(dòng)頁面生命周期短通常 1 至 2 周引入 Token 治理的收益低于成本。第二數(shù)據(jù)可視化場景如圖表顏色由數(shù)據(jù)驅(qū)動(dòng)而非設(shè)計(jì)系統(tǒng)定義Token 化反而限制靈活性。第三原型與 demo 代碼迭代頻繁Token 查詢的摩擦?xí)下?yàn)證速度。第四第三方主題完全由用戶控制的應(yīng)用應(yīng)在運(yùn)行時(shí)切換 CSS 變量而非通過 Token 體系構(gòu)建多套產(chǎn)物。結(jié)論Design Token 單一真源的工程化落地核心是建立原始、語義、組件三層分層模型并通過 Style Dictionary 實(shí)現(xiàn) Figma 到多端代碼的自動(dòng)轉(zhuǎn)譯。分層模型的價(jià)值在于隔離變化——品牌色調(diào)整只需改原始 Token組件級(jí)樣式自動(dòng)跟隨語義層調(diào)整只需改語義 Token原始層不受影響。落地建議分四步推進(jìn)。第一步在 Figma 中固化 Variables 命名規(guī)范導(dǎo)出 W3C 格式的 Token 文件作為唯一源。第二步建立獨(dú)立的 Token 倉庫配置 Style Dictionary 轉(zhuǎn)譯流水線輸出 CSS 變量與 TS 類型。第三步在前端代碼庫接入硬編碼 lint阻斷未經(jīng) Token 的顏色與間距使用。第四步建立 Token 版本管理與廢棄流程確保破壞性變更有 Semver 信號(hào)與遷移窗口。Token 體系不是一次性工程而是持續(xù)的治理過程。工具鏈?zhǔn)枪羌苊?guī)范與 lint 約束才是確保設(shè)計(jì)稿與代碼長期一致的真正機(jī)制。