css-audit-cli

Audit CSS files for issues: duplicate selectors, high specificity, !important abuse, undefined/unused CSS variables, color inventory, and empty rules.

Install

npm install -g css-audit-cli

Usage

# Full audit of a single file
css-audit styles.css

# Audit all CSS in a directory
css-audit src/**/*.css

# Only check for duplicate selectors
css-audit styles.css --check duplicates

# Only flag high-specificity selectors
css-audit styles.css --check specificity

# Only check CSS custom property usage
css-audit styles.css --check variables

# Extract all color values used
css-audit styles.css --check colors

# Count !important usage
css-audit styles.css --check important

# Find empty rules
css-audit styles.css --check empty

# Machine-readable JSON output
css-audit styles.css --json

Checks

| Check | What it finds | |---|---| | duplicates | Selectors defined more than once | | specificity | Selectors with score ≥ 30 (IDs, long chains) | | important | All !important declarations | | variables | Undefined vars (used but not declared), unused vars (declared but never used) | | colors | All unique hex/rgb/hsl/named color values | | empty | Rules with no declarations |

JSON Output

css-audit styles.css --json | jq '.[] | .duplicates'

Each file produces:

{
  "filePath": "styles.css",
  "stats": { "totalRules": 42, "totalProperties": 187, "fileSizeKB": "3.21" },
  "duplicates": [{ "selector": ".btn", "count": 2 }],
  "highSpecificity": [{ "selector": "#nav .active a:hover", "score": 130 }],
  "importantUsages": [...],
  "variables": { "defined": [...], "used": [...], "undefined": [...], "unused": [...] },
  "colors": ["#333", "#fff", "rgba(0,0,0,0.5)"],
  "emptyRules": [".placeholder {}"]
}

License

MIT