PavloK

Posted on Mar 3

I built a CLI that catches design inconsistencies — like Lighthouse, but for your design system

#cli #css #design #showdev

You run Lighthouse to catch performance issues. You run axe to catch accessibility issues. But what catches the moment your site ends up with 54 shades of blue and 22 different line-heights?

I built design-auditor for exactly that.

The problem

You’re three sprints in. The designer is happy. The client is happy. Then someone opens the site on a large monitor and notices the buttons have four different border-radiuses. The headings are using six font sizes that don’t follow any scale. There are at least five “grays” that are almost — but not quite — the same.

None of this breaks anything. Linters don’t catch it. Lighthouse doesn’t catch it. PR reviewers miss it because it lives in computed styles, not source code.

This is design drift. And it’s invisible until it isn’t.

What design-auditor does

It opens your URL in a real browser (via Playwright), reads every element’s computed styles, and runs them through a set of design system rules.

npx design-auditor https://yoursite.com

No config. No installation. One command.

What it checks

🔤 Typography

How many font families are actually in use (recommended: ≤ 3)
Whether font sizes follow a modular scale
Line-height consistency — does your site have a baseline grid, or chaos?

🎨 Colors

Total unique colors across the page
Perceptual color clustering using delta-E (CIE76) — catches #f0f6fc and #f6f8fa as “basically the same color”
WCAG AA contrast validation for every text/background pair
Whether colors are tokenized in CSS variables or hardcoded everywhere

📐 Spacing

Detects your rhythm unit (font-size × line-height)
Checks if spacing follows a 4px or 8px grid
Flags outliers like 13px, 17px, 22px — the “magic numbers” that creep in

🧩 Components

Touch target sizes (WCAG 2.5.5 minimum: 44×44px)
Button padding variations — are you using sm/md/lg or 11 random sizes?
Border-radius consistency
Z-index organization

Real output example

────────────────────────────────────────────────────────────
  TYPOGRAPHY
────────────────────────────────────────────────────────────
  ✅ Font families: 2 — OK
  ⚠️  Font sizes: 11 unique — recommended ≤ 8
  ❌ Line-heights: 22 unique — no vertical rhythm detected

  COLORS
────────────────────────────────────────────────────────────
  ❌ 54 unique colors found — recommended < 20
  ❌ 40 similar color pairs — palette can be consolidated
     ██ #f0f6fc ≈ ██ #f6f8fa (ΔE=2.6)
     ██ #24292f ≈ ██ #1f2328 (ΔE=2.9)

  COMPONENTS
────────────────────────────────────────────────────────────
  ❌ 28/50 buttons smaller than 44px touch target (56%)
  ⚠️  Buttons: 11 padding variations — recommended ≤ 3
  ✅ Interactive states: :hover and :focus present

────────────────────────────────────────────────────────────
  SUMMARY:  6 ❌  5 ⚠️   7 ✅
────────────────────────────────────────────────────────────

Every color renders as a live color swatch right in your terminal.

Why a real browser matters

Most CSS audit tools parse your source files. design-auditor uses Playwright to open the actual page and runs getComputedStyle() on every element.

That means it catches:

Styles injected by JavaScript at runtime
CSS custom properties resolved to their actual values
Styles from third-party scripts and embeds

It sees what your user sees — not what your source code says.

Save reports for CI or tracking design drift

npx design-auditor https://yoursite.com --save-report
# → design-audit-yoursite-com-2026-02-28.json

The JSON output is structured for dashboards, CI pipelines, or just tracking how your design consistency changes over time across deploys.

Who this is for

This tool is most useful if you’re:

A freelancer or agency doing QA before handing off a site to a client
A frontend dev on a team where design system adoption is inconsistent
Anyone who’s inherited a codebase and wants to understand the “shape” of its CSS before touching it

It’s especially powerful for landing pages and marketing sites — the places where design consistency matters most visually, but automated tooling is usually absent.

Try it

# No install needed
npx design-auditor https://yoursite.com

# Specific modules only
npx design-auditor https://yoursite.com --only colors,typography

# Local dev server
npx design-auditor http://localhost:3000 --local

Requires Node.js 18+

GitHub: https://github.com/PashaSchool/design-auditor
Website: https://pashaschool.github.io/design-auditor/

I’m actively developing this — feedback on what checks would be most useful to you is very welcome. What design inconsistencies do you find hardest to catch in code review?

DEV Community