frontend-theming-color-palette-oklch

name	frontend-theming-color-palette-oklch
description	Use when generating a full shade ladder (50, 100, 200, ..., 900, 950) from a single brand seed colour, when a design system needs perceptually-even contrast at each step, when an HSL-derived palette looks visually uneven across hues, when a brand colour change needs to ripple through every token without rewriting hex values, when picking which shade pairs satisfy WCAG 1.4.3 (4.5:1 normal text) and 1.4.11 (3:1 UI components) at a glance, when a gradient or shade transition looks muddy or washed out, when wide-gamut display-p3 colours need an sRGB fallback gate, or when a colour custom property must animate or transition smoothly. Prevents the classic HSL shade-ladder anti-pattern (perceptually non-uniform; the same `50%` lightness in HSL means different visible brightness across hues), the constant-L-constant-chroma trap where the same numeric chroma is out-of-gamut for some hues and inside gamut for others (yellow vs blue at high chroma), the single-tier token chain (brand colour = button colour) that makes a brand refresh painful, the untyped custom property that snaps instead of transitioning, the unguarded display-p3 colour that clips on sRGB displays, and the assumption that text-on-shade-500 pairs are always AA-compliant without verifying the ratio. Covers the OKLCH model (perceptual L axis 0-1, chroma 0-0.4, hue 0-360 with hue 0 = magenta NOT red), the relative-colour-function syntax `oklch(from <seed> calc(l + N) c h)` to derive shades from a single brand seed, the 11-step ladder convention (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950) with L mapped to each step, contrast pair guarantees aligned to WCAG 2.2 SC 1.4.3 (4.5:1 normal, 3:1 large) and 1.4.11 (3:1 UI/graphical), the three-tier brand-to-system token chain (raw brand -> primitive -> semantic -> component), `@property` registration for animatable colour customs, `color-mix(in oklch, ...)` for perceptually-uniform interpolation, wide-gamut handling via `color()` + `display-p3` + `@supports` gating, and emission as CSS custom properties under `@layer tokens, theme, base, components, utilities;`. Keywords: oklch, OKLCH palette, OKLCH shade ladder, perceptually uniform palette, relative color, relative-color syntax, color-mix, oklab, brand seed, brand color, brand palette, shade ladder, color scale, 50 100 200 300 400 500 600 700 800 900 950, palette generation, hue rotation, chroma, L axis, gamut, gamut clipping, display-p3, wide-gamut, sRGB fallback, design tokens, primitive token, semantic token, component token, three-tier token chain, action-primary, surface, on-surface, @property typed custom property, animatable color, WCAG contrast, 4.5:1, 3:1, 1.4.3, 1.4.11, palette looks washed, colors do not look balanced, gradient muddy, shade ladder uneven, hardcoded hex everywhere, brand-color change painful, colors inconsistent at same L, contrast fails AA, how to generate palette from brand color, what is OKLCH, how to make accessible palette, oklch shade generator, color tokens for a design system, how to derive colors from one brand color.
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Theming Color Palette OKLCH

This skill defines a deterministic rule set for generating a perceptually-even shade ladder from a single brand seed using oklch() and the relative-colour function, then emitting the ladder as a three-tier design-token chain. OKLCH (Baseline Widely Available since May 2023) is the perceptually-uniform polar model on top of Oklab; the same numeric L delta produces the same visible brightness change across all hues, unlike HSL where the same 50% lightness looks different per hue.

This skill builds on [[frontend-syntax-css-color-modern]] (oklch / color-mix / light-dark / relative-colour syntax) and [[frontend-syntax-css-cascade-layers-scope]] (@layer for token layering). Contrast verification details are deferred to [[frontend-a11y-motion-contrast-wcag22]]. Dark / light scheme switching is deferred to [[frontend-theming-dark-light-mode]].

Sources : MDN: oklch() (verified 2026-05-19), MDN: color-mix() (verified 2026-05-19), W3C: CSS Color Module Level 4 (verified 2026-05-19), W3C: WCAG 2.2 SC 1.4.3 Contrast Minimum (verified 2026-05-19), MDN: @property (verified 2026-05-19).

Quick Reference

Why OKLCH for palettes (and not HSL)

Per MDN: oklch() (verified 2026-05-19), the L axis represents PERCEIVED brightness. A given numeric L corresponds to the same visible lightness across all hues. HSL's lightness is a geometric value in cylindrical sRGB; the same lightness: 50% produces a visibly brighter yellow than blue. A shade ladder built in HSL is therefore visually uneven; the same ladder built in OKLCH is even.

Channel	Range	Notes
L	0-1 or 0%-100%	0 black, 1 white; perceptual
C	0-~0.4 (numeric) or 0%-100% where