squirrelscan
GitHub

Color sprawl: near-duplicate colors and palette outliers

Fifty grays, a dozen of them indistinguishable, means the palette drifted. squirrel clusters the colors in your inline styles by perceptual distance and reports near-duplicates and one-page outliers.

What color sprawl is

A palette drifts when #333, #343434 and rgb(51 51 51 / 90%) all end up in the CSS for the same dark gray. Nobody chose three grays; three people pasted three values. This rule measures that drift and points at the clusters.

What squirrel checks

The rule is site-wide and needs no account, no model and no credits. It reads every color literal in color, background, border, outline, fill, stroke, shadow and text-decoration declarations, in any syntax: hex, rgb(), hsl(), oklch(), oklab() and named colors. Each is converted to OKLab and clustered by perceptual distance (under 0.02, about one just-noticeable difference). The same color written as #f00, rgb(255 0 0) and oklch(0.628 0.2577 29.23) is one color. Alpha is ignored and fully transparent values are skipped.

Checks, by name:

  • color-sprawl is skipped below 10 crawled pages (Only 6 page(s) crawled; 10 needed to judge color consistency), and skipped when no page declares a color in an inline style.
  • color-sprawl warns when more colors are visually indistinguishable from another than max_redundant (default 6), and fails at three times the limit. Message: 47 distinct colors in use, 12 visually indistinguishable from another (31 gray(s), 9 visually indistinguishable; limit 6).
  • palette-outlier warns for a clearly chromatic color that exactly one page uses inline and no linked stylesheet the audit read uses or defines. It only runs when at least 5 pages declare colors, so there is a palette to depart from.
  • color-sprawl passes when none of the above applies.

Custom properties are not punished

A literal on the right-hand side of --gray-500: #6b7280 is the design system defining its scale, not using it. Token definitions are never counted as use, and var(--gray-500) references are not read as the named color gray. A site that defines a full scale in :root and references it with var() throughout stays clean. The result details report tokenColorsDefined and varReferences so you can see what was attributed.

Coverage: inline styles, with linked stylesheets as the palette

Near-duplicates are counted from <style> blocks and style= attributes in each page’s HTML.

Linked stylesheets define the palette. squirrel reads up to 20 same-site linked stylesheets (the most widely linked first, up to 1 MB each), and every color they use or define as a custom property counts as a palette color. A brand color your stylesheet applies on every page is therefore never reported as an outlier because only one page also writes it inline. Results then say inline styles counted; 3 linked stylesheet(s) read for the palette (with , 1 not read when some could not be read) and carry details.coverage = "inline-plus-stylesheet-palette", stylesheetsRead, stylesheetsNotRead and stylesheetPaletteColors.

When no stylesheet body was read (none linked, all cross-origin, over the cap or failed), every result says inline styles only; linked stylesheets are not read and carries details.coverage = "inline-only". A site that declares no colors inline is skipped, never reported as clean.

How to fix it

Collapse each cluster to one value, define it once as a custom property such as --gray-700, and reference it with var(). For an outlier, switch the color to a palette token or delete the pasted snippet that added it.

Options

[rule_options."content/color-sprawl"]
max_redundant = 10
Rule IDcontent/color-sprawl
CategoryContent
ScopeSite-wide
Severitywarning
Weight2/10

Enable / disable

Disable this rule

[rules]
disable = ["content/color-sprawl"]

Disable all Content rules

[rules]
disable = ["content/*"]

Enable only this rule

[rules]
enable = ["content/color-sprawl"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Check names by outcome

Each check name this rule can emit, by what it means to a tool comparing two audits. A problem check is a finding. A clean check says the rule ran over what it covers and found nothing; it clears the problem checks listed beside it, so a finding is fixed when the rule ran over the same scope and a clean check took its place. A not checked check says the rule did not evaluate, and never clears a finding.

Check nameOutcomeClears
color-sprawlProblem
palette-outlierProblem
color-sprawlCleancolor-sprawl, palette-outlier
color-sprawlNot checked

Check your site

Run squirrel audit https://example.com and open the Content section of the report. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.

Type to search…

↑↓ navigate↵ openesc close