design-audit

Design Audit

A static-analysis design-system gate. Reads every page file in a project, runs a configurable ruleset, and reports per-file findings classified by severity. Built to catch the drift that visual QA misses — wrong CTA colors, skipped heading levels, raw tailwind color classes that should go through semantic tokens, missing alt text on images.

When to use

Trigger this skill when:

• A user asks to "audit the design", "check design system", "find design drift", or similar phrases
• After any significant UI change, before opening a PR
• As a CI gate on pull requests touching page.tsx files
• When a designer flags inconsistency and the source isn't obvious

Do NOT use for:

• Visual layout regressions or overflow (use visual-qa skill instead)
• Copy / brand voice issues (use voice-sweep skill instead)
• Runtime browser checks — this is pure static analysis

How to invoke

The skill ships a single CLI binary. Invoke it via npx:

npx @operator-skills/design-audit

Common flags:

Flag	What it does
--page <route>	Audit a single route (e.g. /operator-pass)
--glob <pattern>	Override the default src/app/**/page.tsx glob
--config <path>	Load a custom ruleset JSON
--remote-config <url>	Fetch a JSON ruleset from a URL (opt-in, no LLM)
--format table|json	Output format (default: table)
--verbose	Per-finding detail
--severity error|warn|info	Minimum severity to surface

Exit codes: 0 clean, 1 error-level findings, 2 config / file errors.

Default ruleset

The default ruleset covers seven rule families. Each project can override or extend via design-audit.config.json at the repo root.

ID	Severity	Catches
heading-hierarchy	error	Skipped h* levels (e.g. <h1> → <h3> without <h2>)
cta-color-destination	error	Buttons styled with bg-secondary but text color that fails WCAG AA contrast (text-background on deeper orange, etc.)
raw-color-classes	warn	Raw Tailwind colors (text-red-500) where a semantic token (text-danger) exists
missing-alt	error	<img> or next/image without alt attribute
container-pattern	warn	Hero / section wrappers missing the standard max-w-* container
font-display-mismatch	warn	Heading elements using font-sans instead of .font-display
internal-link-tag	warn	<a href="/..."> for internal routes — should be next/link

For the full rule list and per-rule examples, load references/design-audit-rules.md.

Per-file suppressions

Add a single-line comment to a page to suppress a specific rule:

// @audit-design: allow heading-hierarchy
// Reason: legacy h3 inside a marketing-card; rewrite planned 2026-Q3

Suppressions require a Reason: line within the next 5 lines, otherwise the rule still fires.

Config schema

design-audit.config.json at the repo root:

{
  "glob": "src/app/**/page.tsx",
  "rules": {
    "heading-hierarchy": "error",
    "cta-color-destination": "error",
    "raw-color-classes": "off",       // disable a default rule
    "custom-rule-id": {                // add a custom regex rule
      "severity": "warn",
      "pattern": "TODO\\([A-Z]+\\)",
      "message": "Replace TODO(...) with a tracked GitHub issue"
    }
  },
  "ignore": ["src/app/legacy/**"]
}

Output format

Default table output groups findings by route:

ROUTE                       ERR    WARN   INFO   TOTAL
-------------------------------------------------------
/operator-pass              0      1      0      1
/build/partnership          1      0      0      1
-------------------------------------------------------
2 page(s) w/ findings       1      1      0      2

--format json returns a structured { summary, findings[] } payload suitable for piping into other tools or posting as a PR comment.

Best-practice usage in CI

- name: Design audit
  run: npx @operator-skills/design-audit --severity error

Fails the build on any error-level finding. Warnings are surfaced in the log but do not block. Use suppression comments for known-acceptable exceptions.

Cross-runtime

This skill works in:

• Plain Node CLI — npx @operator-skills/design-audit
• Claude Code (Agent Skills) — install via /plugin install design-audit; Claude auto-invokes when trigger phrases match
• MCP — wire npx @operator-skills/design-audit mcp into any MCP-aware runtime
• Cursor / Gemini / Codex — planned Wave 2

Related skills

• visual-qa — runtime layout / overflow checks (Playwright)
• voice-sweep — brand-voice + tone violations