Why 5,446 and not a preset library
Most color systems match inputs against a curated 100-200-color library. That works for broad categorization ('this is a blue') but fails at the precision needed for token design: when a designer picks #2563EB, they want to know *which* blue it is, not just 'blue'. The ColorArchive system is algorithmic — 48 hue roots × 14 lightness bands × 8 chroma bands for chromatic colors, plus 5 neutral gray roots × 14 lightness bands for neutrals, total 5,446 named cells. That density means almost any color you've chosen intentionally has a named neighbor within ~18 sRGB units: Cobalt Core Vivid, Apricot Pearl Muted, Cool Gray Shadow. The names become the tokens. Once your palette maps cleanly to a small subset of these cells, you have a design system. Until it does, you have a bag of hex values.
The audit algorithm in one paragraph
Parse the input with three regex passes: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), and hsl() — collapsing shorthand, dropping alpha, and counting duplicates. For each unique color, compute the nearest ColorArchive entry by HSL-weighted distance (hue × 1.8 + saturation × 0.7 + lightness × 1.15 — the same scoring our color-detail pages use). Cluster colors within 24 sRGB units of each other as probable duplicates. Build a pairwise contrast matrix using the standard sRGB luminance formula, flag every pair below 4.5:1 as an AA failure, then rank suggestions by actionability: duplicate consolidation first (biggest systemic win per fix), then WCAG failures (compliance risk), then off-system colors (organizational drift). Every suggestion with a named replacement links to its ColorArchive color-detail page.
What 'off-system' actually means
An off-system flag doesn't mean 'bad color' — the ColorArchive lattice is reference, not law. It means the color is far enough from every named cell (>18 sRGB units) that two designers would make different guesses about its identity. That's the exact source of drift: one PR calls it 'Cobalt Core Vivid,' another calls it 'new blue,' and within a year the token file has three near-identical blues from three PRs. Snapping off-system colors to their nearest named entry early is cheap; reconciling the drift later is not. We're not prescribing a fix — we're showing where the drift is.
What the audit won't tell you
It is a static scanner, not an opinion machine. It doesn't know your brand rationale, whether your primary needs to stay a specific hue for contractual reasons, or whether two 'near-duplicate' colors are actually semantic siblings (base and hover). The output is a punch list, not a prescription — specific, citation-heavy, and meant to be read against your own design intent. The PDF-export and Pro-gated team-report features are coming in a later release once we see how real teams actually use the free audit.
