oklch-skill

Guidance for working with the OKLCH color space in web projects, where the channel values are perceptually meaningful. The premise is that many CSS color problems, including broken palette ramps, failing contrast, and hue drift, stem from color models that do not match human perception, and that OKLCH corrects the model so the tooling behaves predictably. Coverage spans converting hex, rgb, and hsl to oklch; generating scales, multi-hue palettes, and dark-mode variants; checking contrast; and handling gamut boundaries and Tailwind v4 theming.

The document explains why OKLCH is preferred: equal lightness steps read as equal brightness, hue stays constant across the lightness range instead of drifting the way HSL blue shifts toward purple, chroma is an absolute measure independent of lightness, and the gamut is finite so high-chroma values at some hues will clip and require awareness. It documents the oklch(L C H / alpha) syntax and channel ranges, formatting conventions (three decimals for L and C, up to three for H, dropping trailing zeros, normalizing negative zero), and notes browser support as Baseline 2023.

A thresholds table encodes practical rules: the light/dark boundary at L greater than 0.6, foreground-versus-background lightness gaps, a hue-drift threshold above ten degrees, and APCA and WCAG 2 targets, with the guidance that contrast should be fixed by adjusting the L channel while keeping chroma and hue. Color changes are always presented as a Before/After markdown table covering every changed color, keeping feedback scannable and diff-friendly. A common-mistakes table maps problems to fixes, such as rebuilding HSL ramps with constant oklch hue or adding an sRGB fallback for P3 colors. Four reference files go deeper on conversion, palette generation, accessibility contrast, and gamut plus Tailwind.