OKLCH in Tailwind CSS v4: Colors, Palette and @theme

When Did Tailwind Start Using OKLCH?

With Tailwind CSS v4.0, released January 22, 2025. The v4.0 release notes state: "We've upgraded the entire default color palette from rgb to oklch, taking advantage of the wider gamut to make the colors more vivid in places where we were previously limited by the sRGB color space."

So from v4.0 onward, every value behind bg-blue-500, text-red-500 and the rest of the default palette is an oklch() color. v3.x and earlier stayed on RGB. The utility class names did not change — only the color notation underneath.

Verified source: Tailwind CSS — v4.0 release blog post

Why OKLCH Instead of RGB?

Two reasons, both stated in the release notes: wider gamut and perceptual structure. OKLCH is not confined to sRGB, so on wide-gamut Display-P3 displays the same color can render more vividly than its RGB definition ever allowed. And because lightness in OKLCH is perceptually uniform, a 500-to-600 step in the palette moves by a consistent amount of perceived brightness — the property that makes generated scales feel evenly spaced.

• Same classes, richer output: no class renames — bg-emerald-500 keeps working, the value behind it changed notation.
• Ready for wide gamut: when a v4 project lands on a P3 display, the palette can actually show the extra color.
• Consistent lightness ramps: the 50–950 steps line up with perceptual brightness rather than channel math.

Writing OKLCH Colors in @theme

Tailwind v4 moved configuration into CSS. Custom colors live in the @theme block under the --color-{name} namespace, and any value the browser accepts as a color — including oklch() — can be assigned:

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(62.3% 0.188 259.8);
  --color-brand-600: oklch(55% 0.18 259.8);
  --color-surface: oklch(98% 0.005 250);
}

<div class="bg-brand-500 text-surface">
<a class="hover:bg-brand-600">

Because the token is an ordinary custom property, every downstream Tailwind feature — opacity modifiers like bg-brand-500/50, dark: variants, and color-mix() under the hood — operates on the OKLCH value directly. A HEX value still works in the same slot; writing oklch() simply keeps the whole theme in one color space.

Migrating Custom Colors from v3

v4's upgrade guide covers the tooling side (the config moves from tailwind.config.js into CSS). For the colors themselves, the recipe is small and mechanical:

1. Move each color from the v3 theme.extend.colors entry into an @theme --color-{name} variable.
2. Convert the value with a converter (HEX → OKLCH, RGB → OKLCH, or HSL → OKLCH) and paste the oklch() result. Keeping the same name means no class changes anywhere.
3. Leave names that contain theme breakpoints or DEFAULT for a pass on their own — they map to slightly different variable patterns in v4.
4. Spot-check opacity modifiers: bg-brand/40 should still render — v4 resolves it through color-mix() regardless of the source notation.

Verified source: Tailwind CSS — Upgrade guide (v3 → v4)

Related Guides