css-specificity

A specificity heat map for any CSS file, project, or URL

Specificity is invisible until something breaks. This CLI makes it legible — point it at a file, a whole project, or a live URL and every selector is scored and color-coded, with the over-specific offenders glowing red.

$ pnpm add -g css-specificity-cli View on GitHub
Example terminal output of running css-specificity on a stylesheet with a specificity budget, showing selectors sorted hottest-first and two selectors flagged as over budget.

Why it’s useful

Three things it does that a linter rule buried in a config never quite does.

Heat map at a glance

Every selector is scored and painted hot-to-cool, sorted most-specific-first. The selectors that cause your !important wars rise to the top in red.

Budget gate for CI

--threshold 0,3,0 exits non-zero the moment a selector gets too specific — so specificity creep fails the build instead of shipping.

File, project, or URL

Point it at one .css file, a whole project directory, or a live https:// URL — it pulls in every linked and inline stylesheet and reports on all of them together.

Install

Node 18+. Install it globally, or run it on demand with no install.

$ pnpm add -g css-specificity-cli
# or, without installing anything:
$ pnpm dlx css-specificity-cli styles.css

Common uses

The handful of invocations you’ll actually reach for.

Audit a stylesheet

Print the full heat map, hottest selectors first.

$ css-specificity styles.css

Scan a whole project

Walk a directory and report on every .css file at once.

$ css-specificity ./src

Analyze a live URL

Fetch a page and score every stylesheet it loads. Add --browser to capture runtime CSS-in-JS.

$ css-specificity https://example.com

Gate it in CI

Fail the build if any selector is more specific than two classes.

$ css-specificity styles.css --threshold 0,2,0

Just the worst offenders

Show only the ten most specific selectors.

$ css-specificity styles.css --top 10

Pipe from stdin

Read CSS straight off a pipe and emit JSON.

$ cat styles.css | css-specificity - --json