Color Science for Design Systems

Unit 1 · A whole palette, badly

No theory first. Build the thing, then we take it apart.

Step 1 — write the ramp

Pick one brand hue. Something you actually use. Find its hue angle by pasting the hex into any OKLCH converter, or start from these: red ≈ 25°, orange ≈ 60°, yellow ≈ 95°, green ≈ 145°, teal ≈ 195°, blue ≈ 255°, purple ≈ 300°, magenta ≈ 340° Inference — these are rounded from my own conversions, good enough to start and wrong enough to fix later.

Now write nine steps at even lightness intervals, holding chroma and hue fixed:

:root {
  --brand-50:  oklch(0.97 0.16 255);
  --brand-100: oklch(0.92 0.16 255);
  --brand-200: oklch(0.85 0.16 255);
  --brand-300: oklch(0.77 0.16 255);
  --brand-400: oklch(0.68 0.16 255);
  --brand-500: oklch(0.58 0.16 255);
  --brand-600: oklch(0.48 0.16 255);
  --brand-700: oklch(0.38 0.16 255);
  --brand-800: oklch(0.28 0.16 255);
}

Put it in a real page — a scratch file, a Storybook story, whatever is fastest. Render the nine swatches as blocks. Look at them on the device you are reading this on.

Step 2 — the dark half

Make a dark variant by the most obvious method: reverse the ramp. --surface gets the darkest step in dark mode and the lightest in light mode, and so on. Do not think hard about it. Write it down.

Step 3 — guess, in writing

Create gamut.md. Two lines:

Steps I think my display cannot actually show: ___
Why I think that: ___

Step 4 — the policy

Create contrast-policy.md. One sentence, whatever you currently believe. Most people write something close to "all text pairs must hit 4.5:1 per WCAG AA." Write yours honestly, including if it is "whatever the linter says."

Unit 2 · "Lightness" is four different numbers

The word "lightness" is doing four jobs.

1. HSL's L — a geometric artifact

HSL's lightness is (max(R,G,B) + min(R,G,B)) / 2 on the gamma-encoded values. That is a definition of convenience: it makes the color space a tidy double cone that is easy to draw a picker for. It is not a claim about perception, and it was never intended as one. Every fully saturated hue — pure blue, pure yellow, pure red — has HSL lightness of exactly 50%. Inference (this follows directly from the formula; verify it in Unit 3 rather than taking it from me).

2. Relative luminance, Y — physics, weighted by the eye

Linearize each sRGB channel to undo the transfer function, then take 0.2126R + 0.7152G + 0.0722B Sourced fact S5. The weights reflect that the eye is far more sensitive to green light than to blue at equal power. Y is a real physical quantity — how much light is coming off the pixel, weighted by human spectral sensitivity. It is linear: double Y and you have doubled the light.

Crucially: doubling the light does not double the apparent lightness. Y is what a light meter measures, not what you see.

3. CIE L* — the 1976 model of perceived lightness

CIELAB's L* applies a cube-root-ish compression to Y and scales to 0–100. The compression is the whole point: perceived lightness grows roughly as the cube root of luminance, so a color at half the luminance of white looks much more than half as light. L* = 50 is the mid-grey your eye picks, and it sits at about 18% of white's luminance, not 50%.

4. Oklab's L — a 2020 refit of the same idea

Oklab keeps CIELAB's structure — cone-response matrix, cube root, opponent-axis matrix — and re-fits the numbers. Ottosson designed it because CIELAB predicts hue badly, most visibly in blues, where holding L* and hue constant and varying chroma visibly shifts the color toward purple Sourced fact S1. Oklab's L runs 0–1 rather than 0–100. oklch(0.58 0.16 255) — the first number is this one.

One more thing worth knowing before you meet it in the wild: the γ exponent in Ottosson's fit came out at 0.323 and he forced it to exactly 1/3, additionally constraining the fit so that blue colors would not fold inward and make the sRGB gamut non-convex. He reports the error was not noticeably affected Sourced fact S1. A convenient-looking constant that turns out to be a fitted parameter, rounded for a geometric reason, is a good example of what these spaces are made of.

Unit 3 · Five colors with the same lightness and nothing in common

Here are five sRGB colors. Every one of them has HSL lightness of essentially 50%.

Look at them. Then compute.

The two formulas you need

Linearize a channel (undo the sRGB transfer function), for channel value c in 0–1 Sourced fact S5:

Relative luminance Sourced fact S5:

CIE L* from Y Sourced fact S2:

Worked example — #0000FF, all the way through

R = 0, G = 0, B = 255 → 1.0.

So pure blue carries 7.2% of white's luminance, and sits at L* = 32 on a 0–100 perceptual scale. HSL called it 50.

Oklab L for the same color is 0.452 Inference — computed by me with Ottosson's published linear-sRGB matrices, which I verified against his published XYZ→Oklab test table before using them Sourced fact S1. The Oklab arithmetic is a matrix multiply and three cube roots; it is not illuminating to do by hand, so I am handing you those values and asking you to compute the other three columns yourself.

Completion problem — #FFFF00, fill the gaps

Independent — the rest of the table

Compute Y and L* for #808080, #FF0000, and #00FF00 yourself, with no scaffold. Then check against this. The Oklab column is mine Inference; the Y and L* columns you should be able to reproduce to the digit.

Unit 4 · Measure the ramp you shipped

Open your Unit 1 page. Paste this in the console. It reads back what the browser resolved each token to, converts to Oklab, and prints requested vs. actual.

function lin(c){return c<=0.04045 ? c/12.92 : Math.pow((c+0.055)/1.055,2.4)}
function oklabL(r,g,b){
  const l=0.4122214708*r+0.5363325363*g+0.0514459929*b;
  const m=0.2119034982*r+0.6806995451*g+0.1073969566*b;
  const s=0.0883024619*r+0.2817188376*g+0.6299787005*b;
  return 0.2104542553*Math.cbrt(l)+0.7936177850*Math.cbrt(m)-0.0040720468*Math.cbrt(s);
}
const cs=getComputedStyle(document.documentElement);
for(let i of ['50','100','200','300','400','500','600','700','800']){
  const v=cs.getPropertyValue('--brand-'+i).trim();
  const p=document.createElement('span');
  p.style.color=v; document.body.appendChild(p);
  const m=getComputedStyle(p).color.match(/[\d.]+/g).slice(0,3).map(Number);
  p.remove();
  console.log(i, v, '→ actual Oklab L =',
    oklabL(...m.map(x=>lin(x/255))).toFixed(3));
}

Note what this script is doing and what it is not. getComputedStyle().color gives you the value the browser resolved — which, for an oklch() that falls outside the output gamut, is already gamut-mapped. You are not reading your request back. You are reading what survived.

Unit 5 · The horseshoe and the triangle

Scroll up. That shape has been watching you since Unit 1.

Where it comes from

In the 1920s, researchers measured how much of three reference lights people needed to mix to match each pure wavelength. The CIE standardised the averaged results in 1931 as three color matching functions, x̄, ȳ, z̄. Integrate a light's spectrum against them and you get three numbers — X, Y, Z — that fully determine what color a standard observer sees Sourced fact S9. Y is the same relative luminance you computed in Unit 3; that is not a coincidence, ȳ is the luminous efficiency curve.

Now throw the brightness away:

What is left is chromaticity — hue and colorfulness, with lightness divided out. Two dimensions, which is why it fits on a page. Plot every pure wavelength from about 410 nm to 645 nm and you get the curve: the spectral locus. Close it with a straight line and you get the line of purples, which are the colors with no single wavelength — mixtures of red and violet only. Inside that outline is every chromaticity a human can see.

Why a display is a triangle

A display has three primaries. Additive mixing is linear in XYZ, so any color it can produce is a non-negative combination of those three — which, once you divide out luminance, means the convex hull of the three primary chromaticities. Three points, convex hull, triangle. There is no clever engineering that escapes this; it is geometry.

sRGB's primaries, from BT.709 Sourced fact S10:

The area figures are mine, computed by shoelace against the same fitted locus Inference.

Unit 6 · Maximum chroma is not a number you can look up

In Unit 1 you wrote nine colors that all shared 0.16 chroma. That was a guess, and it had to be — nothing in the oklch() syntax tells you what chroma is available.

Here is why it can't. The sRGB gamut is a cube in linear RGB. Oklch is a polar coordinate system in a nonlinearly-warped space. When you push that cube through the warp, you get a lumpy solid, and the maximum chroma at a given lightness and hue is the distance from the neutral axis to that solid's surface in that direction. There is no closed form. You find it numerically.

The test: is this color in gamut?

Convert Oklch → Oklab → linear sRGB and check whether all three components sit in [0, 1]. Ottosson's inverse matrices Sourced fact S1:

function oklchToLinearSRGB(L, C, H){
  const a = C * Math.cos(H * Math.PI/180);
  const b = C * Math.sin(H * Math.PI/180);
  const l_ = L + 0.3963377774*a + 0.2158037573*b;
  const m_ = L - 0.1055613458*a - 0.0638541728*b;
  const s_ = L - 0.0894841775*a - 1.2914855480*b;
  const l = l_**3, m = m_**3, s = s_**3;
  return [
     4.0767416621*l - 3.3077115913*m + 0.2309699292*s,
    -1.2684380046*l + 2.6097574011*m - 0.3413193965*s,
    -0.0041960863*l - 0.7034186147*m + 1.7076147010*s
  ];
}
const inGamut = rgb => rgb.every(c => c >= -1e-6 && c <= 1 + 1e-6);

Completion problem — finish the bisection

The gamut is star-shaped from the neutral axis at fixed L and H: if chroma c is in gamut, everything below it is too. That monotonicity is what licenses a binary search. Fill in the four blanks.

function maxChroma(L, H){
  let lo = 0, hi = 0.5;            // 0.5 exceeds any real sRGB chroma
  for (let i = 0; i < 40; i++){
    const mid = ________;
    if (inGamut(oklchToLinearSRGB(L, ____, H)))  ____ = mid;
    else                                          ____ = mid;
  }
  return lo;                        // lo is always in gamut
}

Unit 7 · Three ways to fit a color that doesn't fit

You ask for oklch(0.55 0.32 264). sRGB cannot produce it. Something has to give. There are exactly three things that can give: chroma, lightness, or hue. Every gamut mapping strategy is a policy about which ones you are willing to spend.

Strategy 1 — clip

Convert to linear sRGB, clamp each channel into [0, 1], done. Fast, and it is what naïve code does by accident. It preserves nothing in particular: clamping channels independently moves you to a point on the gamut surface chosen by the arithmetic, not by any perceptual criterion. Lightness drifts. Hue can drift.

const clip = rgb => rgb.map(c => Math.min(1, Math.max(0, c)));

Strategy 2 — reduce chroma, hold L and H exactly

Binary search chroma down until you are inside — you wrote this in Unit 6. Lightness and hue are preserved to the digit. The cost is that it can be aggressive: it walks all the way in to the last strictly-in-gamut point, which for colors just barely outside can look noticeably duller than necessary.

const reduced = maxChroma(L, H);   // then rebuild at that chroma

Strategy 3 — what CSS actually does

The CSS Color 4 gamut mapping algorithm splits the difference. It binary-searches chroma in Oklch, but at each step it also clips the current candidate and measures the ΔE_OK between the candidate and its clipped version. If that difference is under one just-noticeable difference — the spec uses 0.02 — it returns the clipped color instead of continuing to reduce. Abridged from the specification's pseudocode Sourced fact S3:

const JND = 0.02, EPS = 0.0001;

function gamutMap(L, C, H){
  if (L >= 1) return [1,1,1];
  if (L <= 0) return [0,0,0];
  let cur = oklchToLinearSRGB(L, C, H);
  if (inGamut(cur)) return cur;

  let lo = 0, hi = C, loInGamut = true;
  if (deltaEOK(clip(cur), cur) < JND) return clip(cur);

  while (hi - lo > EPS){
    const c = (lo + hi) / 2;
    cur = oklchToLinearSRGB(L, c, H);
    if (loInGamut && inGamut(cur)) { lo = c; continue; }
    const cl = clip(cur), E = deltaEOK(cl, cur);
    if (E < JND){
      if (JND - E < EPS) return cl;
      loInGamut = false; lo = c;
    } else hi = c;
  }
  return oklchToLinearSRGB(L, lo, H);
}
// deltaEOK is plain Euclidean distance in Oklab — that is the point of Oklab
const deltaEOK = (p, q) => { const a = toOklab(p), b = toOklab(q);
  return Math.hypot(a[0]-b[0], a[1]-b[1], a[2]-b[2]); };

Run all three

Implement the three and produce this table for yourself. Mine Inference, for checking — and the results are more interesting than the descriptions above suggest:

Unit 8 · Which mechanism is this?

Everything below can be explained by one of these, and you have to pick which:

• A · Lightness model mismatch — something is using a lightness measure that doesn't predict perception (Units 2–4).
• B · Gamut boundary — the requested color doesn't exist on this display and got reconciled (Units 5–7).
• C · Both, interacting — the reconciliation in B moved a quantity that A depends on.
• D · Neither — the cause is somewhere else entirely.

Unit 9 · Where 4.5:1 came from

The formula

WCAG 2 defines contrast ratio as Sourced fact S5:

where L1 is the relative luminance of the lighter color and L2 the darker — the same Y you computed in Unit 3. Range: 1:1 to 21:1. The 0.05 is a constant standing in for ambient light reflecting off the screen; it is what stops black-on-black from dividing by zero and what caps the maximum at 21 rather than infinity.

Three structural properties follow immediately, and they are all consequences of the algebra rather than accidents of implementation Inference:

• It is symmetric. Swap foreground and background and the number is identical. Dark-on-light and light-on-dark score the same. Human vision does not work this way; the same luminance difference reads differently depending on polarity.
• Chroma is invisible to it. Y throws away everything except weighted luminance. Two colors of wildly different hue and identical Y score 1:1.
• The 0.05 compresses the dark end. At the top of the range, 0.05 is negligible next to Y ≈ 1. At the bottom, where Y ≈ 0.005, it dominates the numerator and denominator both — and ratios between dark colors get squashed toward 1. Unit 10 measures this.

The threshold

WCAG's own Understanding document gives the derivation of 4.5:1 explicitly. It is two numbers multiplied Sourced fact S4:

1. A 3:1 minimum for observers with typical vision, adopted from an ANSI standard.
2. A factor of 1.5, described as the contrast sensitivity loss associated with visual acuity of 20/40, cited to Arditi & Faye.

The same logic yields 7:1 for AAA, aimed at roughly 20/80 acuity Sourced fact S4.

Before going further, note something in the historical record. A 2007 working draft of the same document set the AA threshold at 5:1, explaining that 20/40 "calculates to approximately 4.5:1 which is rounded up to 5 providing a slight additional increase in contrast" Sourced fact S11. The threshold moved. That is normal standards work, and it is also evidence about what kind of number this is: a committee judgment informed by evidence, not a measurement.

What this does not establish: that 4.5:1 is a bad threshold. Thresholds can be well-chosen and badly documented. Decades of practice have found 4.5:1 to be a workable floor, and that operational track record is real evidence independent of the derivation. What it establishes is narrower and still important: the number is not a measurement, and treating it as one will lead you to defend it in the wrong places.

Why dark mode is where it hurts

The formula's symmetry and its flare constant were specified when the overwhelming majority of interfaces were dark text on light backgrounds. Dark mode inverts the regime, and puts most of the important color pairs down at the compressed end of the scale.

This is not a fringe complaint. In a W3C mailing-list archive from June 2022, Chris Lilley — an editor of the CSS Color specifications — responded to the claim that WCAG 2 contrast only works against light backgrounds by writing that he found this particular failing of the WCAG 2.1 algorithm especially troubling Sourced fact S7. That is a spec editor at the same standards body, on the record, not a vendor with an alternative to sell.

The alternative, and its actual status

You will encounter APCA — the Advanced Perceptual Contrast Algorithm. It is polarity-aware, accounts for font size and weight, and returns a signed Lc value rather than a ratio. It is the most developed candidate for a replacement.

Its status is widely misreported, so here it is carefully Contested: APCA was included in WCAG 3 working drafts as exploratory content, and was removed in July 2023 under the WCAG 3 process rule that exploratory material which does not gain Working Group support within six months is removed automatically. The current WCAG 3 draft states that the contrast algorithm is yet to be determined. WCAG 3 is not expected to reach Recommendation before roughly 2030 Sourced fact S8.

Meanwhile, a great deal of otherwise-good writing describes APCA as "the WCAG 3 contrast algorithm" or says it "is replacing" the WCAG 2 formula. I found several such articles dated 2026 while researching this unit. They are not lying; they are amplifying — a claim that was true of a 2021 draft propagated forward through secondary sources that never rechecked the primary. Vendor framing applies to some of it and plain staleness to the rest, and the two are hard to tell apart from the outside. Which is the argument for going to the spec text.

Unit 10 · Equal perceptual steps, unequal ratios

Everything in this unit is built from two formulas you already have — Unit 3's relative luminance and Unit 9's ratio. No new inputs. The claim comes out of the arithmetic.

Build it

1. Write greyAtOklabL(target) — binary search an sRGB grey value whose Oklab L equals the target. (You wrote a bisection in Unit 6; this is the same shape.)
2. For each pair below, generate both greys, compute Y for each, and compute the WCAG ratio.
3. Every pair is separated by exactly ΔL = 0.20 in Oklab.

Unit 11 · Audit your own tokens

No worked example this time, and no skeleton. You have every formula you need. This is a specification; build to it.

Specification

1. Input: your token set, as pairs that will actually appear together as foreground and background — not the cross product. In each theme separately.
2. For each pair, output: WCAG 2 contrast ratio to two decimals; Oklab ΔL to three decimals; and the AA verdict at 4.5 (normal text) and 3.0 (large text and UI components).
3. Sort by WCAG ratio ascending.
4. Flag any pair where the two measures disagree in direction — that is, pair X has a higher WCAG ratio than pair Y but a lower ΔL. Those are the interesting rows.

Everything you need: lin() and Y from Unit 3, the Oklab forward transform from Unit 4, the ratio from Unit 9.

Then write the policy

Replace contrast-policy.md. It has to answer four questions, and it has to be something a colleague could apply without asking you:

1. What we conform to, and why. If the answer is "WCAG 2 AA because it is what procurement, the EAA, and every automated checker reference" — say that. It is a good reason and it is a different reason than "because 4.5:1 is the legibility threshold."
2. Where we hold a higher bar than the standard, and where. Unit 10 gives you the argument: the ratio compresses at the dark end, so a dark theme that clears 4.5 by a hair is in worse shape than a light theme that clears it by a hair.
3. What we do about the pairs the ratio can't see. Chroma differences, borders between two dark surfaces, disabled states.
4. What would change our mind. Name the event. "If WCAG 3 adopts a contrast algorithm, we re-audit." Naming it converts a standing argument into a scheduled task.

Unit 12 · The rebuild and the rationale

Go back to Unit 1. Rebuild all of it.

The rubric

rationale.md — the actual test

One page. Five headings:

1. What we optimized for. Lightness fidelity, chroma richness, wide-gamut reach, ordering stability — you cannot have all four. Name the ranking.
2. What we gave up to get it. Specifically, with a color or a step named.
3. What we're taking on authority, and from whom. Every load-bearing claim under your palette, with its source and its type. Oklab's fit — including the part that comes from CAM16 rather than from people. The CSS mapping algorithm's JND constant. The 4.5:1 derivation. Mark each one the way this course marked its claims.
4. What would falsify this. The observation that would tell you the palette is wrong, not just unfashionable.
5. What we didn't do. Your own non-goals. If writing them feels awkward, the scope isn't bounded yet.