How PaintGuide Picks Your Shade & Highlight Ladder

The problem the ladder solves

The one thing this article teaches is trust with receipts: exactly why the shade and highlight paints PaintGuide suggests are what they are — enough transparency that you can accept a suggestion knowing what produced it, or override it knowing what you are overriding.

The problem statement is simple. Given one base paint’s color, suggest up to two real, purchasable shade paints and up to two real highlight paints — from your own scanned rack when possible, from the wider catalog otherwise. Not a hex code: an actual bottle with a name on it.

One thing to state plainly before the math, because people reasonably assume otherwise about an app that generates AI paint guides: the ladder is not AI. It is deterministic color math — a fixed pipeline of conversions and a nearest-neighbor search that returns the identical answer for the same paint every time and can be audited line by line. This article is that audit, in plain language. The design philosophy behind every constant you are about to meet comes from the first five articles in this series — chromatic shadows, warm vs. cool, and hue shifting in particular.

The OKLCH color space, briefly

Every ladder starts by converting your paint’s color into OKLCH — the cylindrical form of Oklab, a color space published by Björn Ottosson in December 2020 and included in the CSS Color Level 4 and 5 drafts since December 2021. Its three axes are L (lightness), C (chroma — the absolute colorfulness quantity from Article 1), and H (hue angle in degrees). Its selling point is being close to perceptually uniform: equal numeric moves correspond to roughly equal visible changes, regardless of which hue you start from.

Why not just use HSL, the familiar web color model? Because HSL’s axes lie to your eyes. Two colors at the same HSL “lightness” can differ wildly in perceived lightness — a yellow and a blue at the same nominal L are nowhere near equally bright, a disparity that perceptual-uniformity references demonstrate directly. Since the entire point of a shading ladder is “take equal visual steps down and up from the base,” a space where the L axis does not track visual lightness is disqualified. In OKLCH, one step of −L looks like the same amount of darkening whether the base is a yellow, a teal, or a violet — which is exactly the property the ladder’s fixed step sizes depend on.

The conversion itself, for the curious: the paint’s hex color is decoded to sRGB, linearized through the standard sRGB transfer function, run through Ottosson’s published matrices into Oklab, and finally expressed as L, C, and H. One orientation note: OKLCH hue angles are not the sRGB hue angles you may know — the CSS reference scale places sRGB red at 0° and yellow at 60°, while in OKLCH’s wheel (per the constants our code documents) pink-red sits near 0°, yellow near 90°, green near 150°, cyan near 210°, blue near 260°, and magenta near 330°. Same colors, different ruler.

Why we nudge hue, not just lightness

From the base paint’s OKLCH position, the ladder computes up to two shadow targets and two highlight targets — never more than two steps in each direction, a deliberate cap, because rung five of a paint ladder is a purchase nobody needs. Each step applies three fixed nudges at once.

Lightness: L moves by 0.14 per step — down for shadows, up for highlights — clamped so targets never chase unpaintable extremes (no target below L 0.04 or above 0.97). Chroma: shadows gain chroma, +0.025 per step, and highlights lose a little, −0.018 per step, within a practical band that roughly matches what sRGB can display. Richer shadows, softer highlights — Article 1’s “richer, not muddier” rule and the chalky-highlight fix from hue shifting, each turned into one signed constant. Hue: shadows rotate +10° per step toward cool, highlights rotate −9° per step toward warm — asymmetric on purpose, and modest on purpose.

Now the honesty this section owes you: that hue rotation is a hobby heuristic encoded as a fixed rotation, not a law of physics. Our own source code says so in as many words — the convention that positive rotation means “cooler” walks the OKLCH wheel from red through yellow, green, and cyan to blue, which the code comment notes “matches the traditional warm/cool half-split closely enough for a hobby suggestion (not a colorimetric claim).” There is real vision science adjacent to hue-lightness interaction — the Bezold–Brücke shift we covered honestly in Article 3 — but that is not what this code models. It models the consensus practice of good painters, tuned until the suggestions looked right — and we would rather say so than dress a convention in a lab coat.

Sometimes a computed target lands outside the sRGB gamut — the range of colors a screen (and our hex-based catalog) can represent. The ladder handles this by simple per-channel clipping, not by a dedicated gamut-mapping algorithm. That is acceptable for one specific reason: the clipped target is never shown to you as a color — it is only ever used as a search anchor for finding the nearest real paint.

Matching targets back to real paints

A target color is useless until it becomes a bottle. For each of the up-to-four targets, the ladder searches real paints and ranks them by color distance, using CIE76 delta-E — the plain Euclidean distance between two colors in CIELAB space. This is deliberately the same metric PaintGuide’s cross-brand equivalents pages use: one definition of “how close are two paint colors” across the whole app rather than two subtly disagreeing ones.

Transparency point, stated without flinching: CIE76 is the older, simpler delta-E formula. CIEDE2000 is the more perceptually refined revision, and well-built competitor tools — Paint Vault and Minimatch both state it outright — match with CIEDE2000. We use CIE76 for consistency and simplicity, and for ladder purposes the difference is modest: the search only needs the nearest few paints in the right neighborhood, not a colorimetric verdict at the third decimal. But it is a real simplification, and we would rather name it than oversell precision.

The search also applies painter’s guardrails, each encoding a real hobby judgment. Metallics only ladder against metallics — a metallic edge highlight on a matte base reads as a mistake, so the two pools never cross (the case where you want metal effects in pure matte color is non-metallic metal, a different discipline). Candidates within 4 delta-E of your base are excluded as visually indistinguishable from it. Near-black bases (L below 0.15) skip further shading and near-white bases (L above 0.92) skip further highlighting, because “darker than almost-black” is not a purchasable idea. Pre-mixed Shade-type paints get a small ranking bonus for shadow rungs, and Layer/Base types for highlight rungs (a translucent shade paint makes a poor highlight — it is built to sink into recesses); crucially, this bonus only breaks ties among near-equal matches, and the distance you see displayed is always the true, un-nudged number.

Reading the results — and overriding them

Each suggested rung wears a quality label derived from its delta-E distance: under 12 is “good,” under 20 is “decent,” beyond that “poor.” If nothing lands within 30 delta-E of a target, the ladder leaves that rung empty rather than dressing up a bad match as advice. (The equivalents pages grade much stricter — they compare real bottle to real bottle, while the ladder matches against a synthetic target no manufacturer mixed on purpose. Looser thresholds here are calibration, not grade inflation.)

How to use all this at the desk: accept a “good” rung as-is and get on with washing and layering. Read a “poor” rung as “no strong match exists near this target — here is the nearest real option,” which is genuinely useful shopping information. And once the first five articles are in your bones, override freely: push the hue rotation further for a moodier scheme, hold chroma flat for a grimdark one, swap the suggested bottle for its neighbor you already own. The ladder is a starting point built from the same decisions those articles teach — informed override was always the goal, not obedience.

See it run: pick any paint below and watch the ladder build — base in the middle, two chroma-holding cool rungs below, two softened warm rungs above, each one a real paint with its quality label showing. Every number you just read is at work in that little strip of swatches.