Design Tokens 完整教學：從 Figma 設計系統到程式碼同步的實戰指南

你有沒有遇過這種情況：設計師在 Figma 上改了品牌色，結果工程師要花三天手動更新散落在各處的色碼？或者暗色模式上線後，才發現有一半的元件根本沒換到對應的顏色？這些問題的根源，就是缺乏一套統一的 Design Token 系統。

我自己在導入 Design Tokens 之前，光是一次品牌色微調就搞得團隊雞飛狗跳。但導入之後，整個設計到開發的流程變得異常順暢。今天就來分享我的完整實戰經驗。

什麼是 Design Tokens？

Design Tokens 簡單來說，就是設計決策的最小單位。把顏色、間距、字型大小、圓角這些視覺屬性，用結構化的方式儲存成可以被程式讀取的格式。它不是某個工具的功能，而是一種設計與開發之間的共通語言。

舉個例子，與其在 CSS 裡寫死 #3B82F6，不如定義一個 Token 叫做 color.primary.500，然後在 Figma 和程式碼中都引用這個 Token。當你需要調整品牌色時，只要改 Token 的值，所有引用它的地方就會自動更新。

Token 通常分為三個層次：Global Tokens（原始值，例如 blue-500: #3B82F6）、Semantic Tokens（語義化命名，例如 color-primary: {blue-500}）、Component Tokens（元件級別，例如 button-bg: {color-primary}）。這種分層架構讓你在切換主題或品牌時極為靈活。如果你還在用傳統的元件庫管理方式，建議先參考 Figma Atomic Design 元件庫教學，了解原子設計的基礎概念。

W3C Design Token 規範簡介

W3C 的 Design Tokens Community Group 正在制定一套標準格式，目標是讓不同工具之間可以互通 Token 資料。規範採用 JSON 格式，每個 Token 包含 $value、$type 和可選的 $description 欄位。

一個符合規範的 Token 檔案長這樣：

{
  "color": {
    "primary": {
      "$value": "#3B82F6",
      "$type": "color",
      "$description": "主要品牌色"
    }
  },
  "spacing": {
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

為什麼要關注這個規範？因為當你的 Token 格式符合標準，未來不管是換工具、換框架，甚至跨團隊合作，都能無痛銜接。目前 Tokens Studio 已經支援 W3C 格式輸出，這也是我推薦它的主要原因之一。

Tokens Studio 安裝與設定

Tokens Studio（原名 Figma Tokens）是目前 Figma 生態系中最成熟的 Design Token 管理外掛。安裝步驟很直覺：

1. 在 Figma 中搜尋「Tokens Studio for Figma」並安裝外掛
2. 開啟外掛後，選擇 Token 儲存方式（本機、GitHub、GitLab、JSONBin 等）
3. 建議直接選 GitHub 同步，這樣後續 CI/CD 整合最順暢
4. 連結你的 GitHub repo，設定 Token 檔案路徑（通常是 tokens/ 資料夾）

設定 GitHub 同步時，你需要產生一組 Personal Access Token，給予 repo 的讀寫權限。Tokens Studio 會在你每次修改 Token 時自動建立 commit，或者你可以選擇手動 push。

我個人偏好手動 push 的模式，因為設計過程中會有很多實驗性的調整，不想每個小改動都觸發 CI/CD pipeline。

建立語義化 Token 系統

這是整個 Design Token 架構中最關鍵的部分。你需要建立三組 Token Set：

1. Global Tokens（基礎色盤）

定義所有原始的設計值。例如整個藍色色階（blue-50 到 blue-900）、灰色色階、間距尺度（4px、8px、12px、16px、24px、32px、48px）、字型大小等。這些是純粹的數值，不帶任何語義。

2. Semantic Tokens（語義化層）

這層才是實際被元件引用的 Token。例如 color.bg.primary 引用 {white}、color.text.primary 引用 {gray.900}、color.border.default 引用 {gray.200}。命名要反映用途，而不是視覺描述。

3. Component Tokens（元件層）

針對特定元件的 Token，例如 button.primary.bg 引用 {color.bg.accent}。這層是可選的，適合大型設計系統使用。

在 Tokens Studio 中，你可以用 {} 語法來建立 Token 之間的引用關係，這是實現分層架構的基礎。設定完 Token 後，如何確保設計交付的品質也是重要環節，可以參考 Design Handoff 設計交付指南來優化你的交付流程。

暗色模式支援

Design Tokens 最強大的應用場景之一就是多主題支援。在 Tokens Studio 中，你可以建立不同的 Token Set 來代表不同的主題。

實作方式是這樣的：保持 Global Tokens 和 Component Tokens 不變，只針對 Semantic Tokens 建立暗色版本。例如：

• Light 主題：color.bg.primary → {white}、color.text.primary → {gray.900}
• Dark 主題：color.bg.primary → {gray.900}、color.text.primary → {gray.50}

在 Tokens Studio 中，你可以透過 Token Set 的排列順序來控制覆蓋邏輯。把 semantic-light 和 semantic-dark 設為可切換的 Set，然後用 Theme 功能來組合它們。

這樣在 Figma 中，設計師可以一鍵切換明暗主題來預覽效果。而在程式碼端，輸出的 Token 檔案會自動包含兩套值，配合 CSS custom properties 或 Tailwind 的 dark mode 設定就能無縫運作。

值得注意的是，暗色模式不只是顏色反轉這麼簡單。陰影、透明度、圖片處理都需要獨立考量。建議同時參考 包容性設計 WCAG 指南確保暗色模式也符合無障礙標準，特別是對比度的要求。

CI/CD 自動同步到程式碼

當 Token 檔案存在 GitHub repo 中，你可以設定 GitHub Actions 來自動化整個同步流程。每當設計師從 Tokens Studio push 新的 Token 變更，pipeline 會自動觸發以下步驟：

1. 偵測 tokens/ 資料夾的檔案變更
2. 執行 Style Dictionary 轉換（後面會詳細說明）
3. 產生對應平台的產出物（CSS variables、Tailwind config、iOS/Android 等）
4. 自動建立 Pull Request，附上變更摘要

一個基本的 GitHub Actions workflow 設定：

name: Transform Design Tokens
on:
  push:
    paths: ['tokens/**']
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx style-dictionary build
      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'chore: update design tokens'
          branch: design-tokens-update

這個流程的好處是：設計師不需要學 Git，工程師不需要手動搬運設計稿上的數值，整個過程完全自動化。

Style Dictionary 整合實戰

Style Dictionary 是 Amazon 開源的 Token 轉換工具，負責把 JSON 格式的 Token 轉換成各平台需要的格式。它是整個 pipeline 的核心。

安裝很簡單：npm install style-dictionary。然後建立一個設定檔 config.json：

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "build/css/",
      "files": [{
        "destination": "variables.css",
        "format": "css/variables"
      }]
    },
    "tailwind": {
      "transformGroup": "js",
      "buildPath": "build/",
      "files": [{
        "destination": "tailwind-tokens.js",
        "format": "javascript/es6"
      }]
    }
  }
}

執行 npx style-dictionary build 就會產生對應的檔案。CSS 產出的結果會是標準的 CSS custom properties，你可以直接在專案中引用。

進階用法包括自訂 transform（例如把 px 轉成 rem）、自訂 format（產生 TypeScript 型別定義檔），以及針對不同品牌或主題產生不同的產出物。Style Dictionary 的 transform pipeline 非常靈活，基本上可以輸出任何你需要的格式。

常見問題與最佳實踐

Token 命名要用什麼格式？
推薦使用 kebab-case 或 dot notation，例如 color.text.primary。關鍵是整個團隊統一就好，不要混用。

Token 數量會不會太多難以管理？
一個中型設計系統大約會有 200-400 個 Token，其實不算多。善用分組和命名規則，管理起來比想像中容易。重點是語義化層不要太深，三層已經足夠。

已有專案如何漸進導入？
建議從顏色開始，因為顏色通常是最容易出問題、也最容易看到成效的部分。先建立 Global 和 Semantic 兩層，把現有的 hard-coded 色碼替換掉。確認流程順暢後，再擴展到間距、字型等其他屬性。

Tokens Studio 免費版夠用嗎？
對小團隊來說，免費版已經涵蓋大部分功能。付費版主要多了 multi-file sync、branching、更細緻的權限控制。如果你的團隊超過五人，或者需要管理多品牌，建議升級。

Design Tokens 不只是一個技術方案，它代表的是設計團隊和工程團隊之間的協作方式升級。投入初期設定的時間，換來的是長期的效率提升和品質一致性。如果你的團隊還在用手動方式同步設計稿和程式碼，現在就是導入的最佳時機。