Gutenberg OKLCH Theme System

Perceptually uniform colors built on semantic hue families

Experience the future of accessible, mathematically precise color systems. All colors defined via hue symbols (sky, violet, rose, amber, emerald) that bind to OKLCH coordinates, generating algorithmically perfect 11-step scales.

View Documentation Explore Palettes

Why OKLCH?

Modern color science for digital design

Perceptual Uniformity

Equal numerical steps produce equal perceived color changes across all hues. No more adjusting brightness manually per hue.

Semantic Hue Binding

Primary, neutral, and accent colors are defined by hue symbols (sky, slate, rose) that can be swapped with one word change.

Browser Native

Full support in Chrome 111+, Firefox 113+, Safari 15.4+. Zero polyfills. CSS custom properties inject OKLCH values directly.

Zero Hex Colors

No legacy hex codes. All schema-level color specs are purely semantic (primary.500, neutral.50). HTML emits calculated oklch() values.

11-Step Scales

Each hue generates 11 perceptually spaced lightness steps: 50, 100, 200, 300, 400, 500 (peak chroma), 600, 700, 800, 900, 950.

Extensible

Add new hues to src/palettes.ts with OKLCH coordinates and chroma profiles. All components automatically support them.

The OKLCH Color System

Hue Families

The system defines seven semantic hue families, each with its own OKLCH coordinates and chroma profiles:

sky (H: 220°, cPeak: 0.190) — Cool, professional blue for primary actions
violet (H: 280°, cPeak: 0.215) — Bold, energetic purple for highlights
rose (H: 10°, cPeak: 0.220) — Warm, attention-grabbing red for alerts
amber (H: 75°, cPeak: 0.170) — Golden, warm yellow for warnings
emerald (H: 145°, cPeak: 0.175) — Vibrant, fresh green for success states
slate (H: 220°, cPeak: 0.009) — Cool neutral gray with blue tint
neutral (H: 0, cPeak: 0.000) — Pure achromatic gray

Token Expressions

Colors are specified as token expressions in your theme spec:

primary: "sky.500"              # Peak chroma step of sky hue
bg-page: "white"                # Special keyword
text-muted: "neutral.500"       # Mid-tone neutral

The color resolver parses these expressions and generates OKLCH values using the culori library:

primary.500 → oklch(63.7% 0.190 220)
neutral.50 → oklch(97.1% 0.000 0)
sky.900 → oklch(33.8% 0.038 220)

CSS Variable Injection

At render time, the theme system injects a <style> block into <head>:

:root {
  --sky-50: oklch(97.1% 0.013 220);
  --sky-100: oklch(93.8% 0.027 220);
  /* ... all 11 steps for each hue ... */
  --color-primary: var(--sky-500);
  --color-bg-page: oklch(100% 0 0);
}
.bg-primary { background-color: var(--color-primary); }
.text-muted { color: var(--color-text-muted); }

Zero Color Escapes

Gutenberg components never emit Tailwind fragment classes like bg-blue-600. Instead:

All color intent is expressed via the semantic tone field in components
Components emit semantic class names: bg-primary, text-muted, border-accent
At render time, these map to CSS variables that reference OKLCH values
Swapping the primary hue (sky → rose) updates every component instantly

Ready to build with OKLCH?

Start using the semantic color system in your Gutenberg schemas today

View Examples Read the Spec

Gutenberg

⚙ 𝕏