CSS 與 Tailwind 的色彩 Token — 顏色變數命名與管理

· 閱讀時間 3 分鐘

如何依角色為顏色變數命名和整理、在 CSS 中串起淺色和深色模式,以及在 Tailwind v4 主題中沿用同一套 Token 的方法。

散落在樣式表各處、寫死的 HEX 值,是改顏色變得痛苦的主要原因。品牌更新、加入深色模式或修正對比度問題,都會變成在數百行程式碼裡搜尋取代。色彩 Token,也就是描述顏色用途的具名變數,正好能解決這個問題。這篇指南示範如何在純 CSS 中建立它們,並在 Tailwind 中沿用同一套 Token。

兩層結構:原始 Token 與角色 Token

穩固的架構會把顏色是什麼和顏色怎麼用分開。

原始 Token 是原始的色票,依色相和階層命名。它們永遠不會直接出現在元件樣式裡。

:root {
  --blue-100: #E3E8FF;
  --blue-500: #3D5AFE;
  --blue-700: #2638C4;
  --sand-50:  #F7F5F0;
  --ink-900:  #1D2433;
}

語意(角色)Token 描述介面中的一項任務,指向某個原始 Token,或自己持有一個值。元件只使用這一層。

:root {
  --color-bg:         var(--sand-50);
  --color-surface:    #EFECE4;
  --color-border:     #DAD6CC;
  --color-text:       var(--ink-900);
  --color-muted:      #5C6475;
  --color-primary:    var(--blue-500);
  --color-on-primary: #FFFFFF;
  --color-accent:     #C2410C;
}
.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  color: var(--color-text);
}

現在,按鈕並不知道自己是藍色的。如果品牌改成綠色,你只要改一行。如果對比度檢查沒通過,你只要調整一個 Token,所有元件都會跟著變。

依角色命名,而不是依外觀命名

像 --light-gray 或 --brand-blue 這樣的名稱,描述的是顏色今天看起來的樣子。值一改,名稱就錯了,到了深色模式,--light-gray 甚至會存著一個深色。角色名稱則始終正確:

  • 結構用 --color-bg、--color-surface、--color-border。
  • 內容用 --color-text 和 --color-muted。
  • 強調用 --color-primary、--color-accent。
  • 放在填色上的文字用 --color-on-primary、--color-on-accent。
  • 可選的狀態角色:--color-success、--color-warning、--color-danger。

清單要保持精簡。十幾個角色 Token 就能涵蓋大部分產品;為每個元件都加一個 Token,又會回到原本的問題。

深色模式變成一組新的值

有了角色 Token,深色模式就不是第二份樣式表,而是同樣的名稱配上不同的值。下面的寫法會跟隨系統設定,同時也讓切換開關能透過 data-theme 屬性強制使用任一主題:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg:         #14161F;
    --color-surface:    #1C1F2B;
    --color-border:     #2C3040;
    --color-text:       #E6E8EF;
    --color-muted:      #9AA1B2;
    --color-primary:    #8C9EFF;
    --color-on-primary: #14161F;
    --color-accent:     #FB923C;
  }
}

:root[data-theme="dark"] {
  /* 相同的值,給手動選擇深色模式的人 */
}

注意,深色模式的主色是較淺的藍色,按鈕文字則是深色。深色的值應該經過挑選,而不是用反轉算出來,原因請見深色模式指南。

現代瀏覽器也支援 light-dark() 函式,可以把兩個值寫在同一行。它依循 color-scheme 屬性,所以需要加上那個宣告才會生效:

:root {
  color-scheme: light dark;
  --color-bg:   light-dark(#F7F5F0, #14161F);
  --color-text: light-dark(#1D2433, #E6E8EF);
}

推導出低調的顏色

表面和邊框可以用背景和文字混出來,不必手動挑選。CSS 的 color-mix() 就能做到,而在 OKLCH 中混色,能得到均勻又自然的層次:

:root {
  --color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
  --color-border:  color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}

因為它們參照其他 Token,到了深色模式也會自動更新。如果邊框用來標示輸入框或其他控制項,記得檢查是否達到 3:1。

在 Tailwind CSS v4 中使用 Token

Tailwind v4 在 CSS 中設定。在 @theme 中宣告的任何 --color-* 變數,都會變成一整組工具類別(bg-*、text-*、border-* 等)。產生的工具類別會在執行時讀取變數,bg-primary 會變成 background-color: var(--color-primary),所以只要在深色模式中覆寫變數就夠了:

@import "tailwindcss";

/* 淺色的值會變成工具類別:bg-bg、text-text、bg-primary … */
@theme {
  --color-bg:         #F7F5F0;
  --color-surface:    #EFECE4;
  --color-text:       #1D2433;
  --color-muted:      #5C6475;
  --color-primary:    #3D5AFE;
  --color-on-primary: #FFFFFF;
  --color-accent:     #C2410C;
}

/* 深色的值覆寫同樣的變數 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg:         #14161F;
    --color-text:       #E6E8EF;
    --color-primary:    #8C9EFF;
    --color-on-primary: #14161F;
    /* ... */
  }
}
<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>

不需要在每個元素上加 dark: 變體:Token 本身已經會切換,所以 bg-primary 在兩種主題下都是正確的。

Tailwind v3

在 v3 中,於設定檔裡對應同樣的變數:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        bg: 'var(--color-bg)',
        surface: 'var(--color-surface)',
        text: 'var(--color-text)',
        primary: 'var(--color-primary)',
        accent: 'var(--color-accent)',
      },
    },
  },
}

用 OKLCH 撰寫數值

HEX 很適合用來儲存顏色,但編輯顏色時,OKLCH 更容易掌握。它的三個通道是明度、彩度(飽和度)和色相,而明度和眼睛所見非常接近。想做出品牌色的深色版本來當文字色,只要降低 L、其他不動:oklch(55% 0.2 265) 會變成 oklch(42% 0.2 265)。目前所有主流瀏覽器都支援 oklch()。

省下打字的時間

Colorset 上的每組配色都能匯出正是這樣的結構:淺色和深色模式的角色 Token,可以是 CSS 變數、Tailwind v4 主題、Tailwind v3 設定、SCSS、JSON 或設計 Token,數值格式可選 HEX、RGB、HSL 或 OKLCH。挑一組喜歡的配色,打開匯出,貼上就好。如果想自己建立原始 Token 這一層,色階產生器能從任何顏色產生 50–950 的原始色階。