Tailwind CSS 顏色：v4 OKLCH 調色盤、自訂顏色與色階

Tailwind 調色盤的結構

Tailwind v4.3 的預設調色盤有 26 組命名色階。其中 17 組是彩色：red、orange、amber、yellow、lime、green、emerald、teal、cyan、sky、blue、indigo、violet、purple、fuchsia、pink 和 rose。另外 9 組是中性色：沿用自 v3 的 slate、gray、zinc、neutral 和 stone，以及 v4 期間新增的 mauve、olive、mist 和 taupe。此外還有黑和白。

每組色階都有相同的 11 階：50、100、200 一路到 900，再加上 950。50 接近白色，950 接近黑色。class 名稱由功能、顏色和階數組成：bg-blue-500、text-rose-700、border-zinc-200。

階數代表在色階中的位置，不是亮度值。同樣是 500，gray 的 OKLCH 亮度是 55.1%，yellow 卻是 79.5%，所以 yellow-500 和 blue-500 當文字色時表現差很多。

Tailwind blue：每一階的 OKLCH、HEX 與對比

下表是 Tailwind v4 定義的完整 blue 色階。HEX 欄是最接近的 sRGB 顏色，做法是在維持亮度和色相的前提下降低彩度。對比值是以該 HEX 計算的 WCAG 2 數值。

blue-600 是第一個在白底讓內文達到 4.5:1 的色階。blue-500 在黑底有 5.58:1，可以通過，在白底只有 3.76:1，無法通過。沒有任何一階 blue 能在黑白兩種背景都達到 4.5:1，所以淺色和深色主題需要用不同的色階。

哪些 Tailwind 色階在白底通過 WCAG AA

最淺能通過的色階取決於色相。orange、amber、yellow、lime，以及綠色、藍綠色、青色和天藍色系在 500 時還很淺，內文要用到 700。red、blue、violet、purple、fuchsia、pink 和 rose 在 600 就能通過，indigo 則在 500 就過了。yellow 是例外：連 yellow-600 也只有 2.93:1，達不到大字的標準。

亮度比階數更能預測結果。在全部 286 個顏色中，OKLCH 亮度低於 58% 的色階在白底都能達到 4.5:1，高於 59.2% 的則全部不及格。看一眼 class 值裡的 L，不用測就知道答案。

除了 olive，所有中性色在 500 就能通過。olive-500 的亮度是 58%，色相偏黃，只能達到 4.25:1，所以 gray-500 和 olive-500 的文字不能互相替換。

Tailwind v3 與 v4 顏色比較

v3 把顏色寫成 HEX 值，放在 tailwind.config.js 的 theme.extend.colors 裡。v4 把設定搬進 CSS：顏色是 @theme 裡的主題變數，以 OKLCH 撰寫，並輸出成 CSS 變數，所以在一般 CSS 和行內樣式中都能用 var(--color-blue-500)。

調色盤本身是微調，不是重畫。換算成 OKLCH 後，v3 的 blue-500（#3b82f6）和 v4 的 blue-500 亮度與色相完全相同，只有彩度從 0.188 提高到 0.214。blue 色階的其他階也是同樣的模式，只有 blue-400 另外暗了 0.7 個百分點。對比幾乎沒變，顏色卻更鮮豔。

多出來的彩度超出了 sRGB。v4 的 286 個顏色中有 94 個在 sRGB 之外、Display P3 之內，全部都是彩色。orange 的 11 階中有 9 階超出，blue 有 4 階（200 到 500）。在 P3 螢幕上看得到完整的顏色，在 sRGB 螢幕上瀏覽器會改顯示相近的顏色。v4 的目標是 Safari 16.4、Chrome 111 和 Firefox 128 以上版本，這些瀏覽器都支援 oklch()。

@theme {
    --color-blue-500: oklch(62.3% 0.214 259.815);
}

.card {
    border-color: var(--color-blue-500);
}

如何在 Tailwind v4 加入自訂顏色

在 @theme 裡宣告一個 --color- 命名空間的變數。--color- 後面的部分會成為 class 名稱，所以 --color-brand 會產生 bg-brand、text-brand、border-brand、ring-brand 和其他所有顏色 utility class，在 CSS 中也能用 var(--color-brand)。HEX、rgb()、hsl() 和 oklch() 都可以使用。

如果要取代而不是擴充預設調色盤，先用 --color-*: initial 重設命名空間，再只定義你要的顏色。Tailwind 只會為實際用到的 class 產生樣式，所以大多數專案都保留預設值。

@import 'tailwindcss';

@theme {
    --color-brand: #e4572e;
    --color-ink: oklch(21% 0.02 260);
}

只需要一個強調色時，單一的 --color-brand 就夠了。一旦需要 hover 狀態、淡色背景或深色模式，就該定義一整組帶階數的色階。

如何建立完整的 50 到 950 自訂色階

下面這組色階是由 #e4572e 產生的。它的亮度 63.7% 剛好對應 500，所以品牌色正好落在 500。其他階沿用 Tailwind 的亮度曲線並維持相同色相，彩度在 500 和 600 最高、往兩端遞減，而且全部都在 sRGB 之內，所以 HEX 值是精確的。

和 Tailwind 本身的暖色系一樣，這組色階在白底的內文要用 600。brand-500 只有 3.68:1，只適合大字和圖示。

@theme {
    --color-brand-50: oklch(97% 0.01103 36.478);
    --color-brand-100: oklch(93.477% 0.02574 36.478);
    --color-brand-200: oklch(88.485% 0.04964 36.478);
    --color-brand-300: oklch(81.145% 0.08641 36.478);
    --color-brand-400: oklch(71.064% 0.14524 36.478);
    --color-brand-500: oklch(63.723% 0.18385 36.478);
    --color-brand-600: oklch(56.583% 0.19167 36.478);
    --color-brand-700: oklch(49.952% 0.16921 36.478);
    --color-brand-800: oklch(43.729% 0.14814 36.478);
    --color-brand-900: oklch(38.935% 0.11766 36.478);
    --color-brand-950: oklch(27% 0.07538 36.478);
}

貼上時請保留完整精度。如果把亮度四捨五入到 0.1%、彩度取到小數點後三位，brand-600 會稍微超出 sRGB。這不會造成問題，但就和 HEX 值不再完全一致了。

bg-blue-500/50 這類透明度修飾詞如何運作

在顏色後面加上斜線就能設定透明度：bg-blue-500/50 就是 50% 的 blue-500。v3 會把它編譯成 rgb(59 130 246 / 0.5)，只適用於 Tailwind 能拆成色版的顏色。以 CSS 變數定義的自訂顏色，必須寫成特殊的 rgb(var(--brand) / <alpha-value>) 格式。

v4 把修飾詞編譯成 Oklab 的 color-mix()，把顏色和 transparent 混合。這對任何顏色都有效：主題變數、bg-[#e4572e]/50 這類任意值，以及你自己的 CSS 變數。

透明度會改變對比。在白底上，blue-500/50 會顯示成 #95bfff，blue-500/10 則是 #eaf2ff。blue-600 的文字有 5.25:1，但 text-blue-600/60 會降到 2.62:1，連大字的標準都達不到。

• blue-500#2b7fff
• blue-500/50 疊在白底#95bfff
• blue-500/20 疊在白底#d5e5ff
• blue-500/10 疊在白底#eaf2ff

.bg-blue-500\/50 {
    background-color: color-mix(in oklab, var(--color-blue-500) 50%, transparent);
}

如何為任何 HEX 找到最接近的 Tailwind class

在 Oklab 中以感知距離（ΔEOK）把這個 HEX 和全部 286 個色階逐一比較。距離低於約 0.02 時，並排比較也很難看出差異，可以直接改用 Tailwind 的 class。高於約 0.04 時，就該另外加入自訂顏色。

下表是實際的比對結果。舊的 v3 HEX 值會對應回同一個 v4 class，而像 #ff5733 這種常見的品牌橘，則落在 orange-600 和 red-400 之間。PickShade 的 Tailwind 頁面能為任何顏色做這項查詢，並列出最接近的三個 class。

常見問題