20
26
2026
從 Figma 到 npm，設計 Token 的完整工作流程
一套 Design Token，讓 Figma Make、Claude Code、Cursor、工程師同時從同一個來源取色。 這份指南說明如何建置 npm token 套件、三種取用方式的比較，以及在 Claude Code 中半自動化同步更新的完整工作流程。
想像一個場景：設計系統決定把品牌主色調整一個色值。設計師更新了 Figma， 但 Figma Make 生成的 prototype、Claude Code 建置的 HTML 稿、Cursor 的補全建議、 工程師的 production code——這四個地方各自有一份顏色定義，要一個一個通知、一個一個更新。
這是大多數設計系統面臨的現實問題：設計決策存在多份，維護成本隨工具數量線性增長。 npm token 套件試圖解決的，正是這個問題。
「npm token 的核心價值不是讓 AI 更聰明，而是讓設計決策只存在一份，讓所有工具都從同一個來源執行。」
SHP Design System 2026 採用的方案是：將 Figma 裡的 Design Token 打包成 npm 套件
@tofuydesign/shp-react，
發布到 registry 後，所有工具安裝同一個套件、用同一份 CSS 自訂屬性（var(--shp-*)）取色。
Figma 改了顏色，npm 發布後，所有地方只需要升版本號就完成更新。
SHP Design System 的 Token 分三層，由抽象到具體。理解這三層的分工， 是理解「為什麼 npm 套件只打包 Tier 2」的關鍵。
Primitive（基礎值層）— 只存在 Figma 內部
儲存原始色值，是整個系統的調色盤。這一層不會輸出到 npm 套件，只用於 Figma 內部讓 Tier 2 引用。
例如 SHP 系統的 Tier 2 token --shp-surface-element-brand 的 light 值 #7759FF，
就是指向 Tier 1 裡的某個「品牌紫」原始色。
設計師在 Figma 修改 Primitive 層，所有引用它的 Tier 2 token 會跟著更新。
Semantic（語意層）— npm 套件的核心，已上線可用
給原始值賦予意義，定義每個顏色的用途。這就是目前 @tofuydesign/shp-react 輸出的 129 個 token。
每個 token 都包含 light / dark 兩個值，例如：
text--icon/basic/primary
→ Light：--shp-text-icon-basic-primary: #232A31（深灰近黑）
→ Dark：--shp-text-icon-basic-primary: #F0F3F5（近白，自動切換）
工程師或 AI 工具只需要寫 color: var(--shp-text-icon-basic-primary)，
light / dark 切換完全自動，不需要任何額外邏輯。
Component（元件層）— 只存在 Figma 元件庫
針對特定元件定義的 token，例如 Figma 元件庫裡的按鈕元件會有自己的 token 指向 Tier 2。 這一層不會輸出到 npm，也不需要——工程師直接使用 Tier 2 的語意 token 即可。 SHP 系統目前的 Component 層有 71 個 token，全部只用於 Figma 內部的元件連結。
Token 命名規則 — 以下均為 npm 套件中的真實 token
Figma 裡的 token 路徑轉換成 CSS 自訂屬性時，雙連字號合併為單一連字號，斜線和空格轉為連字號：
text--icon/basic/primary
→ --shp-text-icon-basic-primary
surface/element/brand
→ --shp-surface-element-brand
divider--border/basic/subtle
→ --shp-divider-border-basic-subtle
mask/dark-overlay40
→ --shp-mask-dark-overlay40
Dark Mode 的處理方式
Semantic Color 層的 token 在 Figma 裡就定義了 light 和 dark 兩組值。 npm 套件把這些差異輸出成三個 CSS 區塊，讓 dark mode 完全自動切換，不需要工程師另外寫任何邏輯：
TOKENS.CSS · Dark Mode 三區塊結構
只有值在 dark mode 不同的 token 才會出現在 override 區塊，相同值的 token 不重複輸出。
例如 --shp-theme-purple: #7759FF light / dark 相同，所以 dark 區塊裡沒有這個 token。
TOKENS.CSS · 真實的 Light → Dark 對應值（已在 npm v0.3.2 上線）
/* ── :root（Light 模式預設值） ── */ --shp-text-icon-basic-primary: #232A31; /* 主文字：深灰近黑 */ --shp-surface-basic-level1: #FFFFFF; /* 頁面底色：純白 */ --shp-surface-element-brand: #7759FF; /* 品牌色：SHP 紫 */ --shp-text-icon-basic-price: #EB0F29; /* 價格文字：紅 */ --shp-mask-dark-overlay40: #00000066; /* 遮罩：黑色 40% 透明 */ /* ── Dark mode override（只有值不同的才出現）── */ --shp-text-icon-basic-primary: #F0F3F5; /* 反轉為近白 */ --shp-surface-basic-level1: #101518; /* 深色背景 */ --shp-surface-element-brand: #907CFF; /* 品牌紫略亮，在深色背景下可讀性更好 */ --shp-text-icon-basic-price: #FF5257; /* 價格紅略亮 */ --shp-mask-dark-overlay40: #FFFFFF66; /* 遮罩從黑色反轉為白色 40% 透明 */
設計師視角：這對你的工作流程意味著什麼
你在 Figma 裡把主文字標記為 text--icon/basic/primary，這個決定就已經包含了 light 和 dark 兩個版本的顏色。
工程師實作時只需要寫 color: var(--shp-text-icon-basic-primary)，
不需要另外寫 dark mode 的覆蓋邏輯，也不需要你再提供一份「dark mode 版的顏色規格」。
遮罩 token 是最直觀的例子：mask/dark-overlay40 在 light mode 是黑色半透明遮罩（#000066，40% 不透明），
在 dark mode 自動反轉為白色半透明遮罩（#FFFFFF66）——
這個設計決策你在定義 token 時就做了，工程師零設定地拿到正確結果。
唯一例外：部分 token 的 light / dark 值相同，例如 --shp-theme-purple: #7759FF
在兩個模式都是同一個紫色，代表這個顏色不需要跟隨模式切換。dark override 區塊裡不會有這個 token。
HTML · Dark Mode 啟用方式
<!-- 跟隨系統（@media prefers-color-scheme 自動處理）--> <html> <!-- 強制 Dark：用 [data-theme="dark"] 覆蓋 --> <html data-theme="dark"> <!-- 強制 Light：即使系統在 dark mode，:not([data-theme="light"]) 保護 light 值 --> <html data-theme="light">
同一套 Design Token，有三種方式可以讓 AI 工具和工程師取用。 它們不是互相排除的，而是設計系統在不同成熟階段的自然演進選擇。
方案 A：npm 套件
系統穩定後的標準方案
打包成可安裝的軟體套件，發布到 registry。任何工具安裝後，
直接用 var(--shp-*) 取色。
這是唯一能讓設計 + AI + 工程師共用同一份規則並有版本記錄的方案。
方案 B：Figma MCP 直讀
探索期 / 零建置成本
AI 工具每次生成時直接連線 Figma，讀最新 token 值。 不需要打包，但 Figma 需要開著，且 AI 自行詮釋格式，兩次生成結果可能略有差異。 適合設計系統還在探索、token 尚未定案時。
方案 C：直接提供 Token 給 AI
一次性 / 快速驗證
把 tokens.css 直接上傳或貼入對話。
最低門檻，完全不需要設定，但每個對話都要重新提供，沒有持久性。
適合一次性的快速 demo 或對外簡報，不建議用於長期開發。
各工具取用方式一覽
| 工具 | 方案 A npm | 方案 B Figma MCP | 方案 C 直接提供 |
|---|---|---|---|
| Figma Make | 讀 setup.md，import tokens.css | 直接連 Figma 讀最新 variables | 把 token 規則貼入 kit guidelines |
| Claude Code | 讀 CLAUDE.md，用 var(--shp-*) 生成 HTML | 呼叫 Figma MCP 讀值，生成時自行詮釋 | 把 tokens.css 放入專案或貼入對話 |
| Cursor | .cursorrules 告知規則，補全時遵守 var(--shp-*) | 不支援 Figma MCP | 把 tokens.css 放在專案內，Cursor 讀到後能提示正確變數名 |
| Codex / Copilot | 從 codebase 學習命名慣例，補全時自動沿用 | 不支援 | 需把 token 定義放在專案裡才能學到規範 |
| 工程師 | npm install → import → CSS 變數可用，dark mode 免設定 | 不適用 | 手動複製 :root 變數進專案，與 Figma 脫鉤，維護困難 |
選擇方案的判斷依據
| 你的情境 | 建議方案 |
|---|---|
| 設計系統還在探索，token 還沒定案 | B 或 C |
| 要做一個快速的 prototype demo | C |
| 設計系統已穩定，多人協作 | A |
| 工程師要開發真實產品 | A |
| 需要 Cursor / Copilot 遵守 token 規範 | A |
| 需要 dark mode 自動切換 | A |
npm token 套件的建置成本不低——需要工程資源配合，也需要設計系統達到一定穩定度才值得投入。 但一旦建好，它帶來的不只是技術便利，而是整個協作方式的改變。
設計師視角：維護從「追人確認」變成「升版本號」
想像你把 SHP 品牌色 surface/element/brand 從 #7759FF 調整為一個新的紫色。
以下是 npm 套件方案下，這個改動的實際流程：
你在 Figma 改 token 值 → 執行腳本 + npm publish → 通知工程師升版本號。
Figma Make、Claude Code、Cursor、工程師的 production code 全部同步，不需要你逐一確認。
Token 改一次，所有工具同步
你的設計決策只需要說一遍
例如改了 --shp-surface-element-brand 的值，
下次 Figma Make 生成元件、Claude Code 建 HTML 稿、工程師的按鈕元件——
都會自動用新的顏色，不需要你追每個工具確認「這個紫對了嗎」。
Dark mode 你定義過一次就結束了
不是每次生成都要說「記得處理 dark mode」
你在 Figma 定義 token 時就決定了：text--icon/basic/primary 的 dark 值是 #F0F3F5。
工程師實作時不需要另外寫切換邏輯，
你也不需要在每次開設計稿 review 前提醒「要做 dark mode 版本」。
版本號讓改動有記錄
你知道什麼時候改了什麼，工程師也知道
v0.3.2 → v0.3.3 意味著某個 token 值調整了；major 版號更新代表有 breaking change（token 改名或刪除）。 設計決策的歷史不只活在 Figma 的版本記錄裡，也活在 npm 的版本號裡。
Token 改名是 breaking change
設計系統穩定後才值得建這套
如果你把 surface/element/brand 改名為 surface/brand/primary，
工程師用舊名稱的地方全部失效。
Token 命名要像 API 一樣認真對待——探索期先用方案 B 或 C，命名確定後再建 npm 套件。
工程師視角：從「逐一比對 hex」變成「一行 import」
一行 import，129 個 token 全部可用
import "@tofuydesign/shp-react/tokens.css" 之後，
所有 --shp-* 變數立刻可用。
例如：color: var(--shp-text-icon-basic-primary)、
background: var(--shp-surface-basic-level1)、
border-radius: var(--shp-radius-md)（= 8px）。
不需要自己建 :root 變數清單，也不需要逐一比對 Figma 的色值。
設計師更新 → 工程師升版本號就完成
設計師更新 Figma、npm 發布後，工程師只需要
npm update @tofuydesign/shp-react。
不需要逐一比對每個色值有沒有更新，升版本號就等於所有顏色同步完成。
AI 補全工具自動學到命名規範
Cursor 和 GitHub Copilot 會從 codebase 學習命名慣例。
套件安裝後，補全建議自然會沿用 var(--shp-*) 的命名——
AI 工具自動遵守設計規範，不需要額外的提示工程。
跨專案視覺自然統一
所有產品都 import 同一份套件，視覺規範自然統一。 不會出現「A 專案的品牌藍和 B 專案的品牌藍差了 2% 的色值」的問題。
「token 改名是 breaking change。這不是壞事，這正是版本管理的意義——讓你知道哪些改動會影響下游。」
SHP Design System 的 token 更新流程分五個步驟，其中三個已經完全自動化，只有 Figma MCP 資料讀取這一步需要手動觸發。 整個流程從 Figma 改完 token 到 npm 發布，一般在 10 分鐘內完成。
FIG.01 · Token 更新完整流程
灰色節點需要設計師操作；藍色節點可由 Claude Code 一鍵執行
五個步驟詳解
在 Figma 更新 Token
在 Figma 的 SHP Design System 檔案中，修改 Semantic Color（tier2）或 Semantic Dimensions（tier2）集合的 token 值。 Figma 會即時更新變數值，但這個更改還只在 Figma 裡——npm 套件尚未同步。
用 Figma MCP 讀取最新 Token 資料
在 Claude Code 中下達指令，觸發 Figma MCP 讀取兩個集合的所有變數，儲存為 JSON 檔案。 這是流程中唯一需要 Figma 開著、Figma MCP 工具載入的步驟。
執行 figma-to-tokens.mjs 轉換
自動化腳本讀取 JSON，解析 VARIABLE_ALIAS（遞迴解析 token 別名）、RGBA float → hex、
light/dark 模式分流，輸出標準格式的 src/tokens.css。
確認 diff，更新版本號
確認 src/tokens.css 的變動符合預期後，
依照改動性質更新版本號：token 值調整用 patch、新增 token 用 minor、
token 改名或刪除用 major（breaking change）。
npm build + publish
build 會將 src/tokens.css 複製到 dist，
publish 將新版本推送到 Figma private registry。所有工具升版本號後即同步。
在 Claude Code 下達的自動化指令
Step 2 · 觸發 Figma MCP 讀取
# 在 Claude Code 中輸入：
用 Figma MCP 讀取 SHP Design System 的所有 Design Token。
檔案 ID：QAWgDudzYgqQBqznMk2k0T
需要讀取兩個集合：
1. Semantic Color (tier2) — 包含 light 和 dark 兩個 mode
2. Semantic Dimensions (tier2) — 只有一個 mode
讀取完成後，將完整的 variables 和 variableCollections 儲存為
scripts/figma-variables.json
Step 3 · 執行轉換腳本
# 在 Claude Code 終端機中執行： cd ~/Documents/npm-shp-react node scripts/figma-to-tokens.mjs scripts/figma-variables.json # 或用 npm script： npm run sync-tokens scripts/figma-variables.json
Step 4–5 · 確認並發布
# 確認 diff git diff src/tokens.css # Token 值調整（patch） npm version patch # 新增 token（minor） npm version minor # Token 改名 / 刪除（major · breaking change） npm version major # Build + publish npm publish
figma-to-tokens.mjs 腳本做了什麼
這支腳本是整個流程的核心，它負責把 Figma MCP 輸出的原始 JSON 轉換成符合規格的 CSS 自訂屬性檔案。 主要處理三個技術細節：
VARIABLE_ALIAS 遞迴解析
Tier 2 指向 Tier 1 的別名處理
Figma 的 token 常常是別名（alias），指向另一個 token。 腳本會一路追蹤到最終的 RGBA 值為止，確保輸出的都是真實色值，而非別名引用。
RGBA float → hex 轉換
含 alpha 透明色自動處理
Figma 儲存的顏色是 0–1 的浮點數。腳本轉換為十六進位 hex，
含透明度的顏色（如 mask/dark-overlay40）自動輸出為 8 位元 hex（含 alpha channel）。
Zero-value 安全處理
radius/none = 0px 不會被略過
radius/none: 0 這類值，JavaScript 的 falsy 判斷
if (!rawVal) 會把它視為空值略過。
腳本改用嚴格的 rawVal === null || rawVal === undefined 判斷，確保 0 不會消失。
Light / Dark 模式分流
自動識別 mode 名稱
腳本依 mode 名稱自動識別哪個是 light、哪個是 dark， 只輸出值不同的 token 到 dark override 區塊，相同的 token 不重複輸出以減少 CSS 體積。
Claude Code 自動化指令：完整版
在 Claude Code 中，可以用一個連貫的指令完成步驟 2–5：
「幫我執行完整的 Figma token 同步流程：
1. 讀取 Figma 檔案 QAWgDudzYgqQBqznMk2k0T 的 Semantic Color 和 Semantic Dimensions 集合
2. 儲存為 scripts/figma-variables.json
3. 執行 npm run sync-tokens scripts/figma-variables.json
4. 確認輸出後 patch 版本號並 npm publish」
目前 SHP 的設置（figma-to-tokens.mjs + npm + Claude Code）是功能完整的——設計師改 Figma、跑腳本、發布，10 分鐘完成更新。 但流程中還有幾個節點可以進化：讓 token 讀取不再依賴 Figma 開著、讓發布不需要人在電腦前、讓同一份 token 輸出到 App 端。 以下工具都是對 npm 方案的補強，不是替代。
A. Figma REST API — 讓 token 讀取完全自動化
目前流程的 Step 2 需要 Claude Code + Figma MCP + Figma 開著，才能讀取最新的 token 值。 Figma 官方其實有一個 REST API 可以直接讀取 Variables， 不需要 MCP，也不需要 Figma 在任何電腦上開著：
Figma REST API · 直接讀取 Variables
# 呼叫官方 API，拿到和 MCP 一樣的 variables 資料 curl -H "X-Figma-Token: YOUR_API_TOKEN" \ "https://api.figma.com/v1/files/QAWgDudzYgqQBqznMk2k0T/variables/local" # 輸出直接餵給 figma-to-tokens.mjs — 格式相容
優點
設計師視角
你不需要在更新 token 時打開 Figma、打開 Claude Code、等 MCP 連線。 只要在 terminal 跑一行指令，就能拿到最新 token 資料。 未來可以讓這步完全自動化——設計師改完 Figma 後，後台自動讀取，你什麼都不需要做。
限制
工程師視角
需要管理一組 Figma API token（Personal Access Token），儲存在環境變數裡。 Figma 個人方案有 API 呼叫次數限制； Enterprise 方案才有 Variables API 的完整存取權限（個人方案目前已開放 read）。
B. GitHub Actions — 讓發布不需要人在電腦前
目前流程的 Step 4–5（確認 diff、升版本號、npm publish）需要在本機手動執行。
GitHub Actions 可以在 src/tokens.css 有變動時自動觸發發布——
設計師只需要確認 token 變動正確，剩下的讓 CI 處理。
.github/workflows/publish-tokens.yml · 最小可用設定
on: push: paths: - 'src/tokens.css' # 只有 token 檔案變動才觸發 jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
優點
設計師 + 工程師都受益
設計師確認 token 變動正確後 commit，GitHub Actions 自動跑完剩下的步驟。 發布有時間戳記、有觸發人、有 log——設計決策的歷史更完整。 可以在自動發布前加一個「需要 reviewer 核准」的步驟，讓 breaking change 不會意外上線。
限制
初次設定需要工程協助
需要把 npm registry 的 auth token 存入 GitHub Secrets。 設定完成後設計師不需要碰任何設定，但第一次需要工程師配合。 版本號的升級（patch / minor / major）仍需人工判斷，無法全自動。
C. Style Dictionary — 一份 token，三個平台同時輸出
Amazon 開源的工具，功能和 figma-to-tokens.mjs 一樣——把 token JSON 轉換成各平台的格式。
差別是 Style Dictionary 可以同時輸出多個平台，從同一份來源生成：
FIG.02 · Style Dictionary 跨平台輸出
設計師只維護一份 Figma token，三個平台的工程師各自拿到自己格式的輸出
優點
設計師視角：設計決策真的只有一份
現在 SHP 的 token 只輸出到 Web CSS 變數。如果 App 端也需要同一套顏色， 工程師目前要自己從 Figma 讀值再手動維護一份 iOS / Android 的顏色定義。 Style Dictionary 讓「設計決策只存在一份」從 Web 擴展到全平台。
缺點
現階段引入可能 over-engineering
需要重構現有的 figma-to-tokens.mjs，學習 Style Dictionary 的 transform pipeline 設定。
如果目前只有 Web 需求，現有腳本已經夠用——等到真正有 App 端需求再引入，避免過早投入維護成本。
D. Tokens Studio for Figma — 讓 Figma 直接 push token 到 GitHub
Figma 插件，在 Figma 裡管理 token 時，可以直接把 token JSON 同步到 GitHub repository。 概念上是把目前流程的 Step 1（Figma 改完）和 Step 2（讀取資料）合併—— 設計師改完 token，插件直接 push JSON，CI 自動接手後續步驟。
優點
減少中間步驟，設計師直接操作
不需要 Claude Code MCP、不需要 Figma REST API，設計師在插件裡點「Sync to GitHub」就完成資料讀取。 對設計師最友善的操作方式——改完 token 後的同步步驟在 Figma 裡就能完成。
限制
有自己的 token 格式，整合有摩擦
Tokens Studio 有自己的 JSON 格式，與 Figma Variables 的整合並不完美—— 部分 Figma 原生 Variables 特性（如 Variable Mode）在插件裡需要額外設定。 插件本身是第三方產品，有維護和相容性風險；現有的 figma-to-tokens.mjs 需要修改才能讀 Tokens Studio 的輸出格式。
E. W3C Design Tokens 標準格式 — 了解行業走向
這是方向，不是現在要做的事
W3C 正在制定 Design Token 的標準 JSON 格式（Design Tokens Community Group，DTCG）。
Figma、Style Dictionary、Tokens Studio 都在逐步對齊這個格式。標準格式長這樣：
{ "text-icon/basic/primary": { "$value": "#232A31", "$type": "color" } }
對你目前的工作沒有立即影響，但值得知道：當這個標準成熟後，
現在 figma-to-tokens.mjs 裡手工寫的解析邏輯，可以換成標準工具，不需要自己維護。
現在的 token 命名方式（--shp-text-icon-basic-primary）和這個標準並不衝突，不需要現在改名。
什麼時候引入哪個工具
| 工具 | 解決什麼問題 | 建議引入時機 | 門檻 |
|---|---|---|---|
| GitHub Actions | build + publish 不需要本機手動跑 | 現在就可以做，門檻最低 | 低（需工程師初次設定） |
| Figma REST API | token 讀取不需要 MCP + Figma 開著 | 想讓 Step 2 自動化時 | 中（需要 API token 管理） |
| Tokens Studio | Figma 端直接 push，減少手動步驟 | 設計師想要更簡化的操作時 | 中（插件學習 + 格式轉換） |
| Style Dictionary | 同一份 token 輸出 Web + iOS + Android | App 端真正需要 token 時再引入 | 高（需重構轉換腳本） |
| W3C DTCG 標準 | 長期對齊業界標準，減少自維護成本 | 標準正式發布後再評估 | 低（觀念性，暫不需要操作） |
「這些工具解決的都是同一個問題的不同節點：讓設計師改 Figma 之後，token 能以最少的人工操作抵達每一個需要它的地方。」
把 Design Token 打包成 npm 套件，表面上是一個技術決定， 實質上是設計系統對整個團隊的一個承諾： 這套設計規範是認真維護的，有版本記錄，有人負責，值得依賴。
方案 C（直接提供）是快，但它的隱含訊息是「這個 token 是一次性的快照，沒有人負責它的持續性」。 方案 B（Figma MCP 直讀）比方案 C 更即時，但它同樣是當次快照，AI 自行詮釋，沒有結構性的保證。
方案 A（npm 套件）的代價是真實的——它需要工程資源，需要設計系統的穩定度， 需要學習版本管理的語言（patch / minor / major）。 但它解決的也是真實的問題：讓設計決策只存在一份，讓所有工具都從同一個來源執行。
「三個方案不是互相排除的，是自然的演進路線。探索期用 B 或 C，設計系統穩定後建 A，然後維護 A 就是維護你的設計決策本身。」
SHP Design System 2026 目前已完成 token 套件的基礎建設（v0.3.2），
並建立了 figma-to-tokens.mjs 腳本，
讓 Figma → npm 的更新流程從完全手動壓縮到 10 分鐘內。
下一步是讓這個流程對所有接觸設計系統的人都變得透明、可預期、可重複。