Perceptual color analysis: report perceptually-distinct color count + sprawl ratio

[Atroci]

Problem

values.colors.unique is keyed on the color string, so #3a7bd5, #3b7cd6 and rgb(58, 123, 213) are reported as three unique colors even though they're perceptually identical. There's currently no signal for how many perceptually distinct colors a stylesheet actually uses.

For design-system auditing that distinction is the whole story: "47 unique colors" is noise if 40 are accidental near-duplicates. "47 declared → 9 perceptually distinct (5.2× sprawl)" is actionable.

(Related to #522 on wide-gamut detection — adjacent and complementary: that's syntactic, this is perceptual.)

Proposal

An additive perceptual block under values.colors:

"perceptual": {
  "totalUnique": 9,     // perceptually-distinct colors (analyzable subset)
  "analyzable": 44,     // unique colors parseable to sRGB (hex + rgb/rgba in v1)
  "unanalyzable": 3,    // hsl/lab/oklch/named/system — reported, not hidden
  "sprawlRatio": 4.89   // analyzable / totalUnique; 1.0 = all distinct, >1 = near-dup redundancy
}

Implementation: CIELAB ΔE76 single-linkage clustering, inlined with zero new dependencies (~120 LOC) — colors converted sRGB→Lab and grouped under a ΔE76 ≈ 2.5 just-noticeable-difference threshold. v1 scopes to hex + rgb()/rgba(); hsl()/lab()/oklch()/named/system are counted as unanalyzable (honest about coverage) and are easy follow-ups once the core lands. Clustering is O(n²) in the number of unique analyzable colors (low hundreds in practice), run once per analyze().

Questions before I open a PR

1. Would you prefer this wired into the analyze() output (changes the colors snapshot), or exposed as a standalone export to keep the output surface stable? Happy either way.
2. ΔE76 (simple, zero-dep) vs ΔE2000 (more perceptually uniform, heavier)? I'd start with ΔE76 at a JND threshold for dedup-grade clustering, but will follow your call.

I have a working implementation + vitest tests ready to PR once you point me at the shape you'd prefer. Thanks for the project! 🙏

[bartveneman]

TL;DR: this package isn't the right place, but I like the idea.

This library intentionally doesn't do this sort of analysis: our only goal is to list out relevant metrics. Fun fact: v1.3.0 introduced a 'color aliases' metric in 2018, but it was removed because it does deeper analysis than we want in this package. IMO, this sort of color proximity analysis belongs in another package, because if we go down this route we'd need to do this for all other design token values as well.
That said, I think https://github.com/projectwallace/css-design-tokens/#color does something along the lines of what you describe here, but only for exact matches, if I'm correct. The ideal place for this sort of concept could be in css-design-tokens since it normalizes tokens, but then you'd still miss the JND stuff.

[bartveneman]

I had forgotten about it, but I blogged about this in 2018, too: https://www.projectwallace.com/blog/detecting-color-aliases

[Atroci]

Oh, thanks for sharing these, I'll take a look