Perceptual color clustering: the design token bug no one talks about
By The WAALEE Team · · 5 min read
Pull the colors off almost any real website with a naive extractor and you get garbage back. Not wrong-garbage, too-much-garbage: forty blues that are all basically the same blue, because a button's hover state, its focus ring and its disabled state each render at a slightly different hex. A palette like that is useless to hand to Claude or Cursor. It's also the default output of most tools in this space until very recently, and it's the quiet reason a lot of "extracted design systems" still look wrong once an AI coding agent builds from them.
Why raw computed styles lie
A browser's computed-style API will happily report `#2563EB`, `#2563EC` and `#2462EA` as three distinct colors, because they are, technically. To a human eye looking at the rendered page, they're one blue with rounding noise from opacity layers, box-shadows, and anti-aliasing. Average a page's styles without correcting for that and your "brand palette" balloons to 60+ swatches, most of them duplicates with no semantic meaning. Feed that straight into a prompt and the AI has no idea which blue is actually the brand's primary action color.
Two tools solving it two different ways
TokenScout, a newer open-core CLI and MCP server from developer Hugo Carvalho, attacks this head-on. Per its own release notes, it converts every sampled color from sRGB to CIELAB space and clusters them using the ΔE76 perceptual distance formula, the same math color scientists use to decide whether two colors are distinguishable to a human eye at all. Colors within a tight ΔE76 threshold get merged into one token; the rest survive as genuinely distinct brand colors. It does the same kind of reduction for type and spacing scales, so a page with 14 subtly different `font-size` values comes back as the 5 or 6 that are actually a deliberate scale.
DesignDNA, a Chrome and Firefox extension, goes wider instead of deeper on the same problem: one click on an open tab and it extracts colors, type, spacing, shadows and components, then hands back W3C tokens, CSS variables, a Tailwind v4 theme, and Figma-importable styles, plus an interactive page showing every extracted style rendered live so you can sanity-check it by eye before trusting it. It doesn't publish the clustering math TokenScout does, but the live-preview step is its answer to the same trust problem: let a human catch the duplicate-blue issue visually, fast, instead of hoping the algorithm nailed it.
- Naive extraction: every computed style value becomes a token. Dozens of near-duplicate colors, no signal.
- TokenScout's approach: CIELAB + ΔE76 clustering collapses perceptually identical colors before they ever reach the token file.
- DesignDNA's approach: wide extraction across colors, type, spacing and components, with a live visual review step to catch what the algorithm missed.
- Either way, the goal is the same: a palette small enough and clean enough that an AI coding agent can actually reason about which color means what.
What clustering still can't tell you
Collapsing near-duplicate blues into one token is a math problem, and both tools above are solving it well. Knowing that this particular blue is the primary CTA color and that other blue is just a disabled-state tint, while both survive clustering as technically distinct, is a judgment problem. No distance formula knows which color your team actually treats as "the brand color" versus an incidental one that happens to appear often. That's still the part a person checks, whichever extractor hands you the cleaned-up list.
Three ways to get a usable color palette and token set out of a live site right now:
- TokenScout: Open-core CLI and MCP server. Clusters colors with CIELAB ΔE76 perceptual distance before exporting DTCG JSON, CSS variables and Tailwind config. Best for teams who want the math done for them.
- DesignDNA: Free Chrome/Firefox extension. One click extracts colors, type, spacing, shadows and components, with a live visual preview to catch extraction errors by eye.
- WAALEE: Paste a live URL and get a cleaned-up palette plus full type, spacing and W3C tokens back as AI-ready prompts already shaped for Claude, Lovable, v0, Cursor and Bolt.
The output format was never the hard part
Every tool in this space now speaks DTCG, Tailwind config and CSS variables. That convergence is good, but it was always the easy half of the problem. The hard half is turning raw computed styles into a palette small enough and accurate enough that an AI agent builds consistent UI from it instead of inventing a slightly different shade of blue on every new component. Clustering gets you most of the way there. A quick visual check gets you the rest. Skip both and you're just handing your coding agent the same mess you started with, formatted more neatly.