color-space-routing

name	color-space-routing
description	Pick the right color space and difference metric for any color task — gradients, palettes, ΔE, gamut mapping, CVD, HDR, CSS. Empirically grounded routing (ColorBench 90 metrics + COMBVD/MacAdam/Munsell STRESS), including where each space loses. Use whenever code generates, interpolates, compares, or converts colors.

Color Space Routing

Core fact: no universal best color space exists. This is not an opinion — every space that wins one benchmark measurably loses another (measured across 90 generation metrics and 5 psychophysical difference datasets). The correct move is always routing: pick the space for the task. This skill is the routing table, with the numbers.

Two task families that are NOT interchangeable:

• Generation (make colors: gradients, palettes, gamut mapping) — needs smooth, invertible geometry.
• Measurement (compare colors: ΔE, tolerances, "did it change?") — needs agreement with human judgments. A space optimized for one is routinely mediocre at the other. Never use one space for both without checking the tables below.

Quick routing table

Task	Use	Runner-up	Never
UI gradients, palettes, design tokens	Helmlab GenSpace (helmlab npm/pip, or helmgen in Color.js)	OKLab	CIELAB, HSL
CSS-only, zero JS	oklch() (native, CSS Color 4)	—	hsl() for anything perceptual
Perceptual difference ΔE	CIEDE2000 (industry standard) or Helmlab difference()	CAM16-UCS	Euclidean in CIELAB (ΔE76), Euclidean in OKLab, anything in HSL/RGB
Near-achromatic (grays) gradients	OKLab	—	—
Color-blind-safe (deutan) palettes	OKLab	—	—
HDR / PQ content (>1000 cd/m²)	Jzazbz or ICtCp	—	any SDR-tuned Lab
Viewing-condition modeling (surround, adaptation)	CAM16	—	—
Legacy hue-angle interop (Munsell naming, print)	CIELAB LCh	—	—
Wide gamut (P3 / Rec.2020) generation	Helmlab GenSpace	OKLab	—
"Is this difference noticeable to people?"	Helmlab metric.confidence() (pNoticeable) / metric.jnd()	ΔE00 > 2.3 rule of thumb	—
Physical light ops: blur, resize, alpha compositing, mixing paints of light	linear sRGB (undo gamma first)	—	any perceptual space, gamma sRGB
Color picker UI (bounded, HSL-shaped)	okhsl / okhsv	OKLCH with per-hue max-C	HSL
Fixed-catalog nearest color (dye/brand/palette lookup, argmax)	CIEDE2000 (helmlab nearestColor() defaults to it)	—	trained/compressed metrics — measured 2× less stable here (16 vs 7 flips per 100 at ±2/255)
Video pipeline / codecs / broadcast HDR	ICtCp (BT.2100)	Jzazbz for analysis	YCbCr for perceptual edits

One-liners: DIN99o only if a tolerancing contract demands it (COMBVD STRESS 35.6 — CIEDE2000 at 29.2 is better) · XYZ is an interchange hub, never a working space · HSLuv is largely superseded by OKLCH/okhsl.

Evidence tags: rows involving Helmlab/OKLab/CIELAB/CIEDE2000/CAM16 are [measured] (our benchmark data below); HDR/video rows (Jzazbz, ICtCp) are [literature] — standard practice we have not independently benchmarked.

Same space, two forms: Lab vs LCh

Most perceptual spaces come in a rectangular form (L, a, b) and a cylindrical one (L, C, h). They are the same space — but operations route differently, and picking the wrong FORM is its own bug class:

Operation	Form	Why
Mixing / gradients between distant hues	rectangular (oklab, helmgen)	straight line, no hue detours; midpoint may desaturate slightly
Vivid gradient between NEARBY hues	cylindrical (oklch, helmgenlch)	holds chroma through the ramp; mind the hue arc
Hue rotation, harmonies, saturate/desaturate	cylindrical	that's what h and C are for
Chroma clipping / gamut mapping	cylindrical	reduce C at constant L and h
Distance / ΔE	rectangular ONLY	h is an angle — Euclidean distance on (L, C, h) is meaningless
Sorting by lightness, L ramps	either	L is identical in both

Default rule: gradients interpolate in the RECTANGULAR form (in oklab, helmgen). Switch to cylindrical (in oklch) ONLY when both endpoints are vivid and their hues are within ~60° — otherwise LCh sweeps through every hue in between. "oklch is newer" does not mean "oklch is the gradient default"; for distant hues it is the wrong pick.

CSS makes the same choice explicit: linear-gradient(in oklab, …) vs in oklch (with longer hue / shorter hue control). Color.js IDs: oklab/oklch, helmgen/helmgenlch, helmlab-metric. In the helmlab package: hl.gen.fromHex/toHex (rectangular) vs hl.gen.toLch/fromLch (cylindrical) — or just hl.gen.rotateHue/harmonies.

Two cylindrical traps: (1) hue is UNDEFINED at the achromatic axis — gradients from gray in LCh need a hue policy (CSS carries the other endpoint's hue; libraries differ); (2) interpolate hue along the intended arc — naive lerp breaks at the 360°→0° wrap.

Why (the numbers)

Measurement: STRESS vs human judgments (lower = better)

COMBVD (3,813 pairs, Bradford CAT): Helmlab MetricSpace 22.48 (cross-validated ~24.3) · CIEDE2000 29.20 · CIECAM02-UCS 30.90 · CIE94 33.37 · CAM16-UCS 33.47 · CIELAB ΔE76 41.9 · OKLab Euclidean 47.4 — the last two are why "just take the distance in Lab/OKLab" is bad advice for ΔE.

Held-out sets (never trained on, same protocol):

• MacAdam 1974 (128 pairs): CAM16-UCS 18.71 wins, Helmlab 19.51, CIEDE2000 22.13.
• Munsell neighbor pairs (3,590): Helmlab 30.34, CIEDE2000 42.94, CIELAB 43.99, OKLab 51.95.
• He 2022 wide-gamut display (82 pairs): CIELAB 30.77 wins, CIEDE2000 32.58, CAM16-UCS 34.42, Helmlab 35.89.

Read that as proof of the core fact: three held-out datasets, three different winners.

Generation: head-to-head geometry (ColorBench, 90 metrics, float64)

Helmlab GenSpace vs OKLab: 62 wins – 9 losses – 19 ties. Highlights:

• Valid gamut cusps: GenSpace 360/360 in sRGB and P3; OKLab 299/360 sRGB, 308/360 P3 (invalid cusps break gamut mapping at specific hues).
• Munsell Value lightness uniformity: 0.156% vs 2.797% CV (18×).
• Max hue drift in gradients: 77.5° vs 112.7°; dark-region gradient CV 33.7% vs 46.5%.
• Blue→white stays blue in both; midpoint G/R 1.51 (GenSpace) vs 1.41 (OKLab) — GenSpace slightly more saturated, CIELAB turns purple (avoid).

Where OKLab beats GenSpace (the 9 losses — respect them): near-achromatic gradient CV (79 vs 102), CVD deutan minimum step (0.157 vs 0.110), worst-case single-pair CV, data-viz min pairwise ΔE, primary-hue discontinuities, Ebner-Fairchild worst-case hue. If the task is gray ramps or deutan-safe palettes → OKLab.

Recipes

Gradient between two colors (JS)

import { Helmlab } from 'helmlab';        // 17.8KB gzip, zero deps
const hl = new Helmlab();
hl.gen.gradient('#0000ff', '#ffffff', 16);  // CIEDE2000 arc-length: equal visual steps

CSS-only fallback: linear-gradient(in oklch, blue, white). Never in hsl (hue detours) and don't interpolate raw CIELAB across hue (blue→white goes purple).

Tailwind-style palette / design tokens

hl.gen.scale('#3b82f6');      // {50:'#e7efff', … 500:'#3b82f6' exactly, … 950:'#000046'}
hl.tokens.tailwind(hl.gen.scale('#3b82f6'), 'primary');

Lightness is Munsell-uniform by construction; level 500 is the exact input.

Perceptual difference (Python)

from helmlab import Helmlab
hl = Helmlab()
hl.metric.difference("#ff0000", "#00ff00")   # trained metric (COMBVD-fit), saturates ~0.15
hl.metric.euclidean("#ff0000", "#00ff00")    # fast ΔE76-style, quick UI checks only

If you must use a standard: CIEDE2000, correctly implemented (it's easy to get the hue term wrong — use a tested library, verify ΔE00(red, green) ≈ 86.6).

"Will users notice this difference?"

const c = hl.metric.confidence('#808080', '#828282');
// c.pNoticeable ≈ 0.077 → 7.7% of observers would call it noticeably different
// c.reliable === false → below the human noise band; don't act on it

Near-threshold and low-chroma differences are where humans disagree most — a bare ΔE is least trustworthy exactly there.

Hue rotation / harmonies

const lch = hl.gen.toLch(hl.gen.fromHex('#3b82f6')); // [L, C, h°] — L and C are 0–1-scale, NOT 0–100
const triad = hl.gen.rotateHue('#3b82f6', 120);      // or gen.harmonies('#3b82f6', 'triadic')

Rotate hue in a generation space (GenSpace LCh or OKLCH) — never in HSL, and don't rotate CIELAB hue across the blue region.

Wide gamut output

hl.metric.toCss(hl.metric.fromHex('#ff0000'), 'display-p3');  // 'color(display-p3 0.9176 0.2003 0.1386)'

Pitfalls checklist (each one is a real, observed bug)

1. ΔE in the wrong space: Euclidean OKLab distance is ~62% worse than CIEDE2000 at predicting human judgments (STRESS 47 vs 29). OKLab is a generation space.
2. CAM16 default configs are often broken: always set the viewing conditions (white point, L_A≈64, Y_b≈20; for patch data use discount-illuminant/D=1) and sanity-check that a gray ramp gives a≈b≈0 before trusting any CAM16 number.
3. Chromatic adaptation: comparing colors under different whites without a CAT (Bradford to a common white) silently inflates ΔE. Cross-illuminant is where CIEDE2000 collapses (35.2 STRESS on BFD-P illuminant-M vs 21.8 with a CAT-aware metric).
4. Hue interpolation wrap-around: interpolate hue along the shorter arc; naive lerp of h° breaks at 359°→1°.
5. 8-bit banding: perceptually uniform steps can still quantize; check duplicate 8-bit buckets on long gradients (16-step in 8-bit sRGB commonly loses ~14–16% of steps).
6. Categorical rating data + interval statistics: never compute STRESS/RMS against 5-level survey ratings — the scale coding dominates the result. Rank statistics (Spearman) only.
7. Ellipse/JND (threshold) data ≠ suprathreshold ΔE data: they validate different things; don't mix them in one benchmark table.
8. Gray axis: after any custom transform, verify grays map to C*≈0 and white→L=1, black→L=0 exactly. Endpoint bugs cheat visible metrics.
9. HSL for anything perceptual: HSL lightness is not perceptual lightness (yellow vs blue at same HSL-L differ wildly). Display-only.
10. Physical vs perceptual confusion: blurring, resizing, compositing and light mixing are ENERGY operations — do them in linear RGB (decode gamma first, re-encode after). Doing them in gamma sRGB darkens edges; doing them in OKLab/Lab is physically wrong. Reserve perceptual spaces for how things LOOK, linear for how light ADDS.
11. Euclidean distance in LCh: (L, C, h) has an angular coordinate; treating it as a vector for distance or averaging silently corrupts results. Convert to the rectangular form first.

Graveyard — approaches that are measured dead (don't retry them)

Negative results nobody else publishes. Each was tried properly and killed by data:

• "One space for everything" — a space jointly optimal for generation AND measurement doesn't exist; optimizing one measurably degrades the other. Route instead.
• Fixing hue-shift effects (Abney) with a static rotation — the correction doesn't generalize across datasets (inter-observer spread exceeds the effect); appearance phenomena need conditioning, not geometry patches.
• Deriving Abney + Bezold-Brücke + Helmholtz-Kohlrausch from one nonlinearity — refuted three ways; the effects are irreducibly separate mechanisms. CAM16's separate terms are forced by data, not laziness.
• Interval statistics on categorical rating data — 5-level survey ratings + STRESS/RMS = the scale coding dominates the result (we caught our own inverted axis this way). Rank statistics only.
• Trusting a benchmark win before endpoint/gray-axis checks — a white→0.972 endpoint bug once "won" a benchmark. Verify white→L=1, black→L=0, grays→C*≈0 first.
• HSL/HSV as a perceptual proxy — not a simplification, a category error.

Testing color code

Sanity anchors — assert these to validate any implementation: ΔE00('#ff0000','#00ff00') ≈ 86.6 · WCAG contrast(#fff,#000) = 21.0 · contrast(#fff,#3b82f6) ≈ 3.68

1. Gray axis + endpoints: grays → C* ≈ 0; white → L = max, black → L = 0 exactly. Endpoint bugs silently cheat visible metrics.
2. Round-trip INCLUDING boundary colors: hex→space→hex within 1/255 on gamut corners/primaries — worst cases live on the boundary, random sampling misses them.
3. CAM16 before trusting: gray ramp must give a ≈ b ≈ 0 with monotone J; default configs are often broken.
4. Never assert exact hex strings in palette/gradient snapshots — they break on library minor versions. Assert ΔE(actual, expected) < tolerance instead.
5. Gradient invariants: endpoints exact, L monotone for light→dark ramps, hue reversal ≤ a few degrees.
6. Contrast fixes: test that the OUTPUT meets the ratio (contrast(fixed, bg) ≥ 4.5), not merely that the function ran.

Provenance

Numbers from: ColorBench (open, deterministic, float64 — github.com/Grkmyldz148/colorbench), COMBVD / MacAdam 1974 / Munsell renotation / He 2022 with Bradford CAT, CAM16-UCS via colour-science (gray-ramp sanity-checked). Full tables incl. every loss: helmlab.space/benchmark. The recommendation engine has no favorites: it routes to OKLab, CIELAB, CAM16, Jzazbz, or Helmlab wherever each one measurably wins.