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.
Summary
| Dimension | Legacy Hex / HSL (Tailwind v3) | OKLCH @theme (Tailwind v4) |
|---|---|---|
| Syntax | tailwind.config.js Hex strings | CSS @theme --color-* : oklch(...) |
| Perceptual uniformity | No — yellow looks far brighter than blue | Yes — constant L tracks perceived lightness |
| Wide-gamut P3 | Clipped to 8-bit sRGB | Native Display P3 & Rec.2020 ready |
| Runtime tinting | Preprocessor math required | Native 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.
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.
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.
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.
Authoritative Specifications & References
More color guides
- OKLCH vs HSL vs sRGB: Understanding Wide-Gamut Display P3Compare HSL, sRGB Hex, Display P3, and OKLCH across perceptual lightness, gradient dead zones, gamut volume, and CSS progressive enhancement.
- W3C Design Tokens (DTCG 2025.10): Figma Variables to CSSStructure vendor-neutral color tokens with W3C DTCG 2025.10 JSON ($type, $value colorSpace & components), aliases, and export to CSS & Tailwind v4.
- WCAG 2.2 Contrast Ratio vs APCA (Lc): Complete Color GuideCompare WCAG 2.2 relative luminance ratios (4.5:1) against modern APCA perceptual lightness contrast (Lc 60/75/90), dark-mode polarity, and CVD.
- Fix a muddy CSS gradient midpointCompare a CSS gradient midpoint in sRGB, OKLab and OKLCH using the same two stops. Choose a hue path or add a middle stop to control the transition.