為什麼該用 Design Token:如何設計並導入專案
前言
由於最近在大翻修我的部落格,我發佈這篇文章時應該已經變成 2.0 版本,這次改版也將過去元件中寫死的樣式全改用 design token 管理,再次讚嘆 AI 的強大,又幫我省下許多時間。
改完後元件裡已經幾乎看不到任何色碼,dark mode 也不用在每個元件寫 dark,想換一套配色只要改一個檔案。
這篇就來整理這套做法的思路,然後也對照 Material Design、shadcn/ui 這些常用的 design system 跟 UI library 的做法。
沒有 token 時會遇到的問題
假設網站有一個「次要文字」的灰色,最直覺的寫法大概是這樣:
<span class="text-[#6e6e73] dark:text-[#828bb8]">2026-11-20</span>專案小的時候很快很方便,但專案一大就會出事:
- 同一個用途散落在幾十個地方。設計說次要文字要再淡一點,只能全域搜尋
#6e6e73,還要祈禱沒人寫成#6E6E73或rgb(110,110,115)。 - 色碼不帶意義。看到
#86868b不知道它是日期、裝飾編號還是 disabled 狀態,所以沒人敢改。 - 主題是乘法。每個元件寫一份 light 一份 dark;要加高對比主題,就是每個元件再改一遍。
- 設計和工程講不同語言。設計稿寫「Text/Secondary」,程式碼寫
#6e6e73,兩邊對不起來,每次改版都要人工比對。
為什麼建議用 token
Design token 這個詞來自 Salesforce 的 Lightning Design System,定義很簡單:
把設計上的決定(顏色、字級、間距、圓角、陰影、動畫時間)抽成有名字的變數,元件只引用名字,不碰實際的值。
聽起來只是「把色碼放進變數」,但它帶來的改變是結構性的:
- 單一來源。每個設計決定只存在一個地方。改一次,全站同步,不會漏。
- 名字就是文件。
color-fg-muted一看就知道是次要文字。新人不用猜,舊人也敢改。 - 主題變成加法。元件只認用途名字,主題只是「用途 → 值」的另一份對應表。加一個主題等於多寫一份對應,元件一行都不用動。
- 設計與工程共用詞彙。Figma Variables 和程式碼用同一組名字,設計改了 token,工程知道要改哪裡;W3C 底下的 Design Tokens Community Group 也在制定共用的 JSON 格式,讓工具之間能直接交換。
- 限制選項,品質反而穩定。間距只有 4、8、12、16……可以選,就不會出現 13px、15px 這種「差不多」的值,畫面自然一致。
反過來說,什麼時候不需要?
一次性的活動頁、活不過一個月的 prototype,直接寫值就好了。
主流 Design System 怎麼做
幾乎所有成熟的 design system 都把 token 分成三層,只是命名不同:
| Design system | 原始值 | 用途(主題在這層切換) | 元件 |
|---|---|---|---|
| Material Design 3 | referencemd.ref.palette.primary40 | systemmd.sys.color.on-surface | componentmd.comp.filled-button.container.color |
| Adobe Spectrum | global | alias | component-specific |
| GitHub Primer | base | functionalfgColor-muted | component |
| Chakra UI | tokens | semanticTokens | recipe |
| shadcn/ui | (直接寫色值) | --background、--muted-foreground | — |
幾個值得注意的地方:
- Material 3 的動態配色(從桌布取色產生主題)做得到,是因為元件只認 system token,底下整組 reference palette 換掉也不影響元件。
- GitHub Primer 同時支援多種 light、dark 和色盲友善主題,靠的就是只換 functional 那層。
- shadcn/ui 少了原始值那層,色值直接寫在用途變數裡。專案小時很省事,但「元件只用用途名字、主題只換值」這個核心是一樣的,所以它的主題產生器換一組變數就能換掉整站配色。
- Radix Colors 每個色系 12 階,每階都規定用途(前幾階是背景、最後兩階是文字),等於把用途層寫進色票規範。
三層解決的是同一個問題:把「值是多少」跟「拿來做什麼」分開。
設計一套 token:分成五個步驟
不管是要做一套給團隊用的 design system,還是自己專案的樣式基礎,順序都差不多。
1. 盤點原始值,建 primitive 層
先把專案裡出現過的顏色、字級、間距全部列出來,合併「差不多」的值,整理成一份色票和尺度:
:root { --palette-gray-50: #f5f5f7; --palette-gray-600: #6e6e73; --palette-gray-900: #1d1d1f; --palette-blue-600: #0066cc;}名字只描述它是什麼(灰色第 600 階),不描述用途。規則只有一條:元件永遠不能直接用這層。
2. 定義用途,建 semantic 層
這是整套系統最重要、也最難的一步。問自己:「畫面上有哪些角色?」主要文字、次要文字、頁面底色、卡片底色、分隔線、強調色、錯誤狀態……每個角色一個 token:
:root { --color-fg-default: var(--palette-gray-900); /* 標題、主要文字 */ --color-fg-muted: var(--palette-gray-600); /* 日期、說明、標籤 */ --color-bg-muted: var(--palette-gray-50); /* chip、搜尋框、hover */ --color-accent: var(--palette-blue-600);}命名建議用固定的結構,讓名字可以被猜出來:
color | fg | muted | hover |
|---|---|---|---|
| 類別 | 用在哪 | 變化 | 狀態(選用) |
組起來就是 --color-fg-muted-hover。
除了顏色,字級、行高、間距、圓角、z-index、動畫時間也放這層。字級可以直接放 fluid 值:
--text-base: clamp(1rem, 0.9775rem + 0.0922vw, 1.0625rem); /* 16 → 17px */--space-4: 1rem;--radius-md: 8px;--duration-fast: 0.15s;3. 主題只重新指派 semantic 層
html.dark { --color-fg-default: var(--palette-tokyo-fg); --color-fg-muted: var(--palette-tokyo-fg-muted); --color-bg-muted: var(--palette-tokyo-bg-surface); --color-accent: var(--palette-tokyo-blue);}元件完全不知道現在是哪個主題。實際玩一下:下面這塊的元件只用 semantic token,切換時元件的 CSS 沒有任何改變,只有對應到的值換了。「高對比」是最後才加的主題,只多寫了一個 selector。
4. 只在需要時加 component 層
component token 是「某個元件專屬、而且希望能單獨調整」的值,例如 header 高度、側欄寬度、按鈕圓角:
:root { --header-height: 56px; --content-measure: 720px; --button-radius: var(--radius-md); /* 預設跟著全域,但可以單獨覆寫 */}不要一開始就幫每個元件的每個屬性建 token,那會讓 token 數量爆炸、沒人記得住。判斷標準:有沒有人會想只改這個元件、不改全域?有才建。
5. 用測試或 lint 把規則固定下來
規則只寫在文件裡,三個月後一定會有人為了趕時間偷寫色碼。建議至少自動檢查:
- 元件引用的每個 token 都真的有定義。
- light 有的每個
--color-*,dark 也一定要有(新增顏色忘了補 dark,CI 直接紅)。 - primitive token 不能出現在 token 檔以外。
- 元件裡不能出現寫死的 hex 色碼。
這幾條用 Vitest 讀 CSS 檔、跑 regex 就能做,不用額外工具;或用 Stylelint 的 declaration-strict-value 這類規則。
在自己的專案導入
情境一:用現成的 UI library
大部分人其實不用自己設計整套 token。用 shadcn/ui、Material、Chakra 時,換品牌色就是覆寫它的 semantic token,不要去改元件原始碼:
/* shadcn/ui:只改變數,所有元件跟著換 */:root { --primary: oklch(0.55 0.2 260); --radius: 0.5rem;}需要 library 沒有的顏色(例如品牌的第二強調色)時,照它的命名方式新增一個 token,而不是在元件裡寫死。
情境二:既有專案,想逐步改成 token
- 先做顏色的 semantic 層,大概 10 到 15 個就夠:fg(3–4 階)、bg(2–3 階)、border(2 階)、accent、成功/警告/錯誤。顏色是最常改、最常出錯的。
- 接上 Tailwind。在 theme 裡讓 class 指向變數,元件就能寫
text-fg-muted而不是text-[#6e6e73](範例在下一節)。 - 新元件先用,舊元件碰到再換。不需要一次全部重寫;搭配上面的 hex 檢查測試,先只對新目錄開啟,範圍慢慢擴大。
- 穩定後再補間距、字級、圓角,最後才考慮 component 層。
值放 CSS 變數,不要只放 Tailwind config
用 Tailwind 的專案常見的疑問:直接把色碼寫進 tailwind.config 不是更簡單?差別在 CSS 變數是 runtime,Tailwind config 是 build time:
- 主題靠一個 class(
html.dark)就能切換,不用每個元件產生兩份 class。 - 非 Tailwind 的 CSS(文章 prose、第三方元件覆寫)也能讀同一份值。
- 可以放
clamp()這類 fluid 值。 - Tailwind v4 改用 CSS 裡的
@theme定義 token,本來就是 CSS 變數;semantic 層照--color-*、--text-*命名,升級時幾乎不用改。
案例:部落格 2.0
我的部落格在 2.0 照上面的步驟改成三層 token,結構如下:
Tailwind 那層只做對應,拿到的永遠是 var(—…):
const v = (name) => `var(--${name})`;
export const tokenTheme = { colors: { fg: { DEFAULT: v('color-fg-default'), muted: v('color-fg-muted') }, bg: { DEFAULT: v('color-bg-default'), muted: v('color-bg-muted') }, }, height: { chip: v('chip-height') },};於是元件裡沒有色碼、沒有 dark:、也沒有魔術數字:
<a class="min-h-chip rounded-full bg-bg-muted text-fg"> <span class="text-fg-muted">12</span></a>v2 的元件目錄裡 dark: 出現 0 次;第五步提到的四條規則都寫成了 Vitest 測試,跟著 pnpm test 一起跑。
常見的坑
- 用外觀命名。
--color-light-gray在 dark 主題會變成謊言。名字永遠描述用途。 - token 太多。每個元件每個屬性都建 token,最後沒人記得哪個是哪個。semantic 層夠用時,不要加 component token。
- primitive 外洩。元件直接用
--palette-*,換主題時這些地方不會跟著變。用測試擋。 - Arbitrary value 繞過 token。Tailwind 的 h-[34px] 很方便,但同一個值出現第二次時,就該考慮收成 token。
- 斷點沒辦法用 CSS 變數。media query 讀不到
var(),斷點只能另外管理:用測試檢查一致,或用 PostCSS 的@custom-media。
結語
Design token 說穿了就是一件事:把「值是多少」和「拿來做什麼」分開。
Primitive 管值,semantic 管用途,component 管元件專屬的例外;元件只跟用途說話,主題只換對應表。這是 Material、Primer、shadcn/ui 都走的路,也是為什麼它們能支援多主題、讓使用者換品牌色而不碰元件。
要自己做 design system,從 semantic 層的命名開始想;要在專案導入,從 10 幾個顏色 token 開始做。先讓顏色有名字,其他的會慢慢跟上。