projectwallace / projectwallace/css-analyzer
Perceptual color analysis: report perceptually-distinct color count + sprawl ratio
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 366
- Forks
- 15
- Avg merge
- 3h 23m
- Merged PRs (30d)
- 3
Description
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
- 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. - Δ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! 🙏
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing analyze() output and the working implementation with its vitest tests; confirm how values.colors is assembled and how the proposed perceptual block fits. Resolve the output-shape and ΔE choice with maintainers, then consider the work done when tests cover analyzable and unanalyzable counts, clustering, and sprawlRatio.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css, typescript
- Domain
- analytics
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100