| name | design-audit |
| description | Design quality auditor. Detects 24 anti-patterns in UI code (impeccable patterns), critiques visual hierarchy and UX, polishes components to shipping quality. Provides /critique, /audit, /polish, and /bolder commands. |
| automation | manual |
| intents | design, review |
Design Audit Skill
The quality gate of the design stack. Runs after ui-component-builder ships a component
and before it goes to production. Identifies technical flaws, UX problems, and aesthetic
anti-patterns without touching functionality.
Read DESIGN.md before auditing. Audit against the project's design system, not generic best practices.
Slash Commands
/audit [area]
Technical quality check — no edits, only findings.
Reports issues across: accessibility, performance, responsive layout, token compliance, animation correctness.
Output format:
AUDIT FINDINGS — [component name]
🔴 Critical (must fix before ship)
- [issue] at [file:line]
🟡 Warning (should fix)
- [issue] at [file:line]
🟢 Passed
- [checks that passed]
Score: X/10
/critique [area]
UX + visual design review — no edits, only observations.
Evaluates: visual hierarchy, content clarity, emotional resonance, information density, consistency with DESIGN.md.
/polish [area]
Final pass before shipping. Makes targeted improvements to:
- Spacing consistency (enforce DESIGN.md spacing scale)
- Typography precision (line-height, letter-spacing, weight)
- Hover/focus state completeness
- Micro-animation quality
/bolder
Amplify a design that's too timid. Use when a design is correct but forgettable.
Increases visual contrast, strengthens typographic hierarchy, adds one deliberate moment of delight.
/quieter
Tone down a design that's fighting for attention. Use when too many elements compete.
Reduces weight of secondary elements, simplifies colour usage, creates clear focal point.
/distill
Strip to essence. Remove every element that doesn't answer: "does the user need this to complete their task?"
The 24 Anti-Patterns (run npx impeccable detect src/)
These are automatically detectable flaws. A design audit must check all 24:
Layout & Structure
- Side-tab borders — coloured left-border on tab/nav items is overused. Use background fill instead.
- 3-equal-card hero — three equal-width cards as the primary page layout. Asymmetry is stronger.
- Centered hero with centered text — everything centered feels like a template. Offset the layout.
- Flexbox percentage math —
flex: 0 0 33.333% instead of CSS Grid. Breaks at edge cases.
- Off-scale spacing —
mt-7, px-3.5, gap-[13px] — values not in the design system.
Color & Visual
- Purple/neon gradient —
from-purple-500 to-blue-600 is the default AI aesthetic. Replace.
- Dark glow abuse —
shadow-lg on dark backgrounds has zero visibility. Shadows are for light UIs.
- Transparent overlay mismatch — using
bg-black/50 on a dark surface — undetectable.
- Status colour decoration — using green/red for non-status elements (purely decorative).
- Missing tinted neutrals —
gray-* classes instead of zinc-* or brand-tinted equivalents.
Typography
- Skipped heading levels —
<h1> to <h3> with no <h2> — accessibility and hierarchy violation.
- Line-length violation — prose wider than 75ch — illegible for reading.
- Uniform font weight — all text
font-normal. No hierarchy established through weight.
- Missing tabular numerals — numbers in tables/metrics without
font-variant-numeric: tabular-nums cause column misalignment.
- Monospace for prose — using a code font for descriptive text.
Motion & Interaction
- Bounce easing —
cubic-bezier(0.34,1.56,0.64,1) for UI transitions — feels cartoonish.
- Animating layout properties — animating
top, left, width, height instead of transform.
- No reduced-motion handling — animations not wrapped with
prefers-reduced-motion: reduce.
- useState for spring physics — using React state for cursor magnetic effects causes jank. Use Framer Motion
useMotionValue.
Interaction States & Accessibility
- Missing focus ring —
:focus-visible with no visible indicator. Keyboard users invisible.
- Small touch targets — interactive elements below 44×44px on mobile.
- Missing icon button labels —
<button><svg /></button> with no aria-label.
- Missing empty state — list/collection component with no empty state — renders blank.
- Missing loading state — data-fetching component with no skeleton or spinner.
Typography Audit (impeccable patterns)
The 3-word brand test
Before selecting or validating a font choice, ask: what are 3 concrete words describing the brand personality?
- Pi-CEO: authoritative · precise · technical
- A font matching this: Geist (engineered, precise, modern) ✅ Not: Poppins (rounded, friendly ❌)
Anti-reflexes (fonts that don't fit despite feeling "safe")
- "It's a tech product → use Inter" — Inter is fine but generic. Geist is more precise.
- "It's serious → use a serif" — wrong reflex. Precision can be sans-serif.
- "It's friendly → use rounded fonts" — wrong if the brand is powerful, not approachable.
Font pair validation rules
- Heading and body fonts must have compatible x-heights
- Two fonts from the same category at the same size = mistake, not choice
- Weight jump of at least 300 between body and heading (e.g. 400 → 700)
Color Audit (OKLCH)
When auditing colour choices, evaluate in OKLCH space (not HSL):
- HSL
hsl(220, 70%, 50%) can look different at same lightness across hues
- OKLCH
oklch(55% 0.18 250) provides perceptually uniform lightness
- Tinted neutrals must be hued toward the brand colour specifically, not generic warm/cool
To convert hex → OKLCH: use oklch.com or the CSS color() function.
UX Writing Audit
Flag these in any copy within components:
| Bad | Better |
|---|
| "Click here" | "[specific action]" |
| "Error occurred" | "[what failed] — [how to fix]" |
| "Loading..." | "Loading [specific content]..." |
| "No data" | "No [specific content type] yet — [action to add]" |
| "Are you sure?" | "Kill session RA-1234? This cannot be undone." |
| "Success!" | "[What specifically succeeded]" |
| "Invalid input" | "[Which field] [what's wrong]" |
Audit Scoring Rubric
| Dimension | 1–3 (Fail) | 4–6 (Marginal) | 7–9 (Pass) | 10 (Ship) |
|---|
| DESIGN.md compliance | Token violations throughout | Minor deviations | All tokens correct | Exemplary — extends the system |
| State completeness | Missing 2+ states | Missing 1 state | All states present | All states + edge cases |
| Accessibility | Missing labels, focus, targets | One a11y gap | WCAG AA compliant | WCAG AAA |
| Anti-patterns | 5+ present | 2–4 present | 0–1 present | Zero, and pattern actively avoided |
| Typography | No hierarchy | Weak hierarchy | Clear hierarchy | Masterful — every level earns its role |
