StyleStats documentation

Overview

StyleStats is a CLI and Node.js library that parses an HTML page or a CSS file and emits structured metrics describing the stylesheet. Treat the output like a smoke test for stylesheet complexity: most numbers are useful as trends over time rather than absolute thresholds.

Command line

The simplest invocation accepts a URL or file path:

$ stylestats https://example.com
$ stylestats public/styles.css

Multiple inputs and globs are supported. Output defaults to a human-readable table on stdout.

Metric reference

• Style sheets — count of linked <link rel="stylesheet"> resources.
• Style elements — count of inline <style> blocks in the document.
• Total unique font sizes — distinct font-size values found across all rules.
• Total unique colors — distinct color values, normalized to lowercase hex.
• ID selectors — selectors matching #id. High counts indicate tight coupling to markup.
• Universal selectors — selectors matching *. Should be near zero in production.
• Unqualified attribute selectors — [attr] without a tag, slow to match in old engines.
• JavaScript-specific selectors — selectors prefixed .js- or similar; should be styled, not behavioral.
• Important keywords — count of !important declarations.
• Float properties — count of float declarations. Modern layouts should be approaching zero.
• Average of cohesion — average number of declarations per selector. Higher = more grouped.
• Lowest cohesion / lowest cohesion selector — the worst offender, useful for triage.

Configuration

Pass --config path/to/.stylestatsrc to enable or disable individual metrics. The config is a JSON object where each key is a metric name and the value is true or false:

{
  "published": true,
  "paths": true,
  "styleSheets": true,
  "styleElements": false,
  "totalUniqueFontSizes": true,
  "importantKeywords": true,
  "floatProperties": false,
  "averageOfCohesion": true,
  "lowestCohesion": true
}

Output formats

Pass --type to control output:

• json — machine-readable; pipe into a file for CI processing.
• html — a single self-contained report.
• md — Markdown, handy for posting in pull-request comments.
• csv — flat tabular form for tracking metrics over time.

Using StyleStats in CI

The most common pattern is to run StyleStats against the production stylesheet on every pull request, save the JSON report, and diff it against the previous run. A growing count of unique colors or font sizes is usually a code-review conversation worth having.

# GitHub Actions example
- run: npm ci
- run: npm run build
- run: npx stylestats dist/style.css --type json > report.json
- uses: actions/upload-artifact@v4
  with:
    name: stylestats
    path: report.json

That's the whole tour. For deeper details on individual metrics, see the metric definitions in the original repository.