OKLCH colors in shadcn/ui, explained

If you've opened a recent shadcn/ui project, your globals.css is full of values like oklch(0.646 0.222 41.116). Tailwind CSS v4 and shadcn/ui moved from HSL to OKLCH, and once you know how to read it, it's a much better format for building themes.

Reading an OKLCH value

oklch(L C H) has three channels:

• L, lightness, from 0 (black) to 1 (white). Unlike HSL, this is perceptual: two colors with the same L look equally light to the human eye.
• C, chroma: how colorful the color is. 0 is gray. Most UI colors sit between 0.05 and 0.25; very vivid colors reach about 0.37.
• H, hue: the angle on the color wheel, from 0 to 360. Roughly: red ≈ 25, orange ≈ 50, yellow ≈ 90, green ≈ 145, teal ≈ 185, blue ≈ 260, purple ≈ 300, pink ≈ 350.

An optional alpha channel goes after a slash: oklch(1 0 0 / 10%) is white at 10% opacity, which shadcn uses for dark-mode borders.

--primary: oklch(0.62 0.19 260);   /* a medium, saturated blue */
--muted: oklch(0.97 0.005 260);    /* almost-white with a hint of blue */
--foreground: oklch(0.15 0.01 260); /* near-black, very slightly cool */

Why OKLCH beats HSL for themes

Consistent lightness. In HSL, hsl(60 100% 50%) (yellow) looks far brighter than hsl(240 100% 50%) (blue), even though both have 50% lightness. In OKLCH, equal L means equal perceived lightness. That makes it much easier to build a palette where every accent has the same visual weight, and to predict contrast.

Predictable shades. To make a darker or lighter version of a color, change only L. The hue stays put instead of drifting toward gray or purple the way it often does in HSL.

Wider gamut. OKLCH can describe the more vivid colors that modern P3 displays show. Browsers clip out-of-gamut colors to the nearest displayable color, so vivid themes degrade gracefully on older screens.

Practical tips for theme palettes

• Tint your neutrals. Give backgrounds, borders and muted surfaces a tiny chroma (0.005–0.02) at your brand hue. It's barely noticeable, but the whole UI feels cohesive.
• Keep text pairs far apart in L. As a rule of thumb, a difference of about 0.45 or more in lightness between a surface and its foreground clears WCAG AA for body text. Always verify, though; the editor checks every pair for you.
• Raise primary lightness in dark mode. A primary at L 0.55 in light mode usually needs about L 0.65–0.75 on a dark background to keep the same presence.
• Space chart colors by hue and lightness. Five hues at the same L can be hard to tell apart for color-blind users; vary L a little too.

Converting existing colors

Have hex or HSL values from an old theme or a brand guide? Use the OKLCH color converter for single colors or whole blocks of variables, or paste them into the editor's color picker, which accepts hex, HSL, RGB and OKLCH, or paste an entire Tailwind v3 globals.css into Import. Everything is converted to OKLCH automatically. If you're upgrading a whole project, see Migrating a shadcn theme to Tailwind v4.