Hex to OKLCH: Migrating Design Tokens to Tailwind CSS v4

Step-by-step guide to upgrading Hex and HSL Tailwind v3 themes into CSS Color 4 @theme oklch() scales with perceptual brightness and Display P3 support.

6 min read · Updated 2026-11-22

Summary

DimensionLegacy Hex / HSL (Tailwind v3)OKLCH @theme (Tailwind v4)
Syntaxtailwind.config.js Hex stringsCSS @theme --color-* : oklch(...)
Perceptual uniformityNo — yellow looks far brighter than blueYes — constant L tracks perceived lightness
Wide-gamut P3Clipped to 8-bit sRGBNative Display P3 & Rec.2020 ready
Runtime tintingPreprocessor math requiredNative CSS oklch(from var(--c) ... ) & opacity

Why Tailwind v4 switched default palettes from Hex to OKLCH

Legacy sRGB Hex strings hide perceptual brightness behind hexadecimal triplets. Two 500-level shades in blue and yellow share zero contrast predictability without manual luminance audits.

OKLCH places perceptual Lightness (L) directly on the first axis, Chroma (C) on the second, and Hue angle (H) on the third. Swapping Hue keeps visual weight remarkably stable across buttons, badges, and status chips.

  • Consistent 50–950 contrast ladders: dark ink passes reliably on stops 50–400; white ink passes on 600–950.
  • Clean CSS-native relative colors without Sass or PostCSS color plugins.

Convert Tailwind v3 theme to v4 OKLCH

Mapping tailwind.config.js Hex tokens into CSS @theme

Paste your existing theme.extend.colors block or CSS :root variables into Colr's Tailwind v3-to-v4 converter. It transforms each stop via D65 linear sRGB into exact W3C oklch() strings.

Keep hue shifts subtle at very high lightness (50–100) and clamp out-of-sRGB chroma only when targeting strict sRGB brand logos.

Mapping tailwind.config.js Hex tokens into CSS @theme
CSS
@import "tailwindcss";

@theme {
  --color-brand-50: oklch(97.2% 0.014 261.2);
  --color-brand-500: oklch(54.6% 0.215 262.9);
  --color-brand-700: oklch(42.4% 0.178 263.5);
  --color-brand-950: oklch(23.1% 0.086 264.1);
}

Verifying WCAG 2.2 & APCA contrast after migration

Always run your converted 50–950 ramp through an accessibility matrix before shipping to production, especially for mid-tone buttons (500–600) against white text.

Our OKLCH Scale Generator flags APCA Lc and WCAG AA boundaries inline so you never ship illegible brand accents.

  • Check 500 vs 600 steps for crisp 4.5:1 body button text.
  • Test wide-gamut accents inside sRGB fallback previews.

Build an accessible OKLCH 50–950 scale

Tools featured in this guide

Related formats

Frequently asked questions

Will CSS oklch() colors break older browsers?

All evergreen Chrome, Safari, Firefox, and Edge versions shipped since 2023 support oklch() natively. You can optionally keep Hex variables for legacy enterprise targets.

Do Hex and OKLCH look identical on standard sRGB monitors?

Yes — any Hex converted straight to oklch() represents the exact same sRGB coordinate until you intentionally raise Chroma into Display P3.

More color guides