# Design Audit

> DEPRECATED (RA-7057) — superseded by the installed pbakaus/impeccable skill v3.9.1. Use `impeccable` (`/impeccable audit`, `/impeccable critique`, `/impeccable polish`, `/impeccable bolder`) instead. Kept for the archaeological record; do not route new work here.

- Skill: `cleanexpo/design-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/design-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/design-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/design-audit

---


# Design Audit Skill

> **DEPRECATED (RA-7057, 2026-07-16).** Superseded by the installed `impeccable` skill
> (pbakaus/impeccable v3.9.1 — 46-rule set, 23 sub-commands), which covers `/impeccable audit`,
> `/impeccable critique`, `/impeccable polish`, and `/impeccable bolder` natively. `design-system` and the launch/UI chains now
> route to `impeccable`. This file is retained unchanged below as the archaeological record.

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
1. **Side-tab borders** — coloured left-border on tab/nav items is overused. Use background fill instead.
2. **3-equal-card hero** — three equal-width cards as the primary page layout. Asymmetry is stronger.
3. **Centered hero with centered text** — everything centered feels like a template. Offset the layout.
4. **Flexbox percentage math** — `flex: 0 0 33.333%` instead of CSS Grid. Breaks at edge cases.
5. **Off-scale spacing** — `mt-7`, `px-3.5`, `gap-[13px]` — values not in the design system.

### Color & Visual
6. **Purple/neon gradient** — `from-purple-500 to-blue-600` is the default AI aesthetic. Replace.
7. **Dark glow abuse** — `shadow-lg` on dark backgrounds has zero visibility. Shadows are for light UIs.
8. **Transparent overlay mismatch** — using `bg-black/50` on a dark surface — undetectable.
9. **Status colour decoration** — using green/red for non-status elements (purely decorative).
10. **Missing tinted neutrals** — `gray-*` classes instead of `zinc-*` or brand-tinted equivalents.

### Typography
11. **Skipped heading levels** — `<h1>` to `<h3>` with no `<h2>` — accessibility and hierarchy violation.
12. **Line-length violation** — prose wider than 75ch — illegible for reading.
13. **Uniform font weight** — all text `font-normal`. No hierarchy established through weight.
14. **Missing tabular numerals** — numbers in tables/metrics without `font-variant-numeric: tabular-nums` cause column misalignment.
15. **Monospace for prose** — using a code font for descriptive text.

### Motion & Interaction
16. **Bounce easing** — `cubic-bezier(0.34,1.56,0.64,1)` for UI transitions — feels cartoonish.
17. **Animating layout properties** — animating `top`, `left`, `width`, `height` instead of `transform`.
18. **No reduced-motion handling** — animations not wrapped with `prefers-reduced-motion: reduce`.
19. **useState for spring physics** — using React state for cursor magnetic effects causes jank. Use Framer Motion `useMotionValue`.

### Interaction States & Accessibility
20. **Missing focus ring** — `:focus-visible` with no visible indicator. Keyboard users invisible.
21. **Small touch targets** — interactive elements below 44×44px on mobile.
22. **Missing icon button labels** — `<button><svg /></button>` with no `aria-label`.
23. **Missing empty state** — list/collection component with no empty state — renders blank.
24. **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 |