UI Design System Audit Skill

Degree of freedom: MIXED — Steps 0–3, 5–6 [HIGH freedom]; Step 4 playwright captures [LOW freedom — run exactly]. Read protocol-browser-anti-stall before any browser step. Breakpoints-only → audit-responsive.

How to reason

1. Observe — quote the token file, raw hex, or screenshot
2. Interpret — is this the system token, a one-off, or an AI-tell?
3. Classify — token leak / duplicate component / missing state / template / correct
4. Severity — raw color on a core primitive = P0; missing hover = P1; radius nit = P2

Worked example

Observe: Button.tsx uses bg-[#3B82F6]; --primary exists in globals.css. Interpret: the primitive bypasses the token SSOT; dark mode cannot switch it. Classify: token leak on a core primitive. Severity: P0 — every button is a hardcoded hex. Finding: Button.tsx | color token | P0 | replace with bg-primary.

Self-critique before reporting [LOW freedom — do not skip]

1. Tokens first — do not invent a second scale
2. Evidenced — screenshot under .playwright-mcp/ or quoted class
3. Severity justified — P0 = core primitive off-token or unusable contrast
4. Right owner — linearized desktop → audit-responsive; WCAG keyboard → audit-accessibility
5. Hand-crafted — no recommendation that increases template sameness

Anti-template

Recommendations must name what to avoid, not ask for taste. Research award-winning sites in the domain; vary rhythm (not identical py-16); give each control a distinct hover/focus/active/disabled; define personality tokens (radius, type voice). Defaults to call out — extend this list from whatever the first draft reached for: identical section padding, generic or purple gradients, three equal cards / 3-col icon-title-desc as the default, cream or off-white page backgrounds, italic accent words in headlines, "01/02/03" numbered section labels, monospace labels, pill-shaped buttons everywhere, Inter/Roboto as the only type voice, lorem empty states, uniform radius, unadapted stock art.

Step 0: Auto-Detect Design System

0a. Detect CSS Framework

0b. Detect Component Library

Glob: **/components/ui/*.tsx → shadcn/ui
Glob: **/components/ui/*.vue → Vue component lib
Glob: **/components/ui/*.svelte → Svelte component lib
Grep: "from '@radix-ui" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'lucide-react" glob "*.{ts,tsx}" output_mode "count"
Grep: "from '@heroicons" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'react-icons" glob "*.{ts,tsx}" output_mode "count"

0c. Find Design Tokens

Glob: **/tailwind.config.*
Glob: **/app/globals.css
Glob: **/styles/tokens.*
Glob: **/theme.*
Grep: "--primary|--secondary|--accent|--muted" glob "*.css"

Read token source to extract: colors, spacing, typography, radii, shadows.

0d. Discover Forbidden Patterns

Grep: "NEVER|FORBIDDEN|DO NOT" glob "**/*README*" -i

0e. Record Discovery

DESIGN SYSTEM DISCOVERY:
- CSS framework: [Tailwind v3/v4 / CSS Modules / Styled Components / etc.]
- Component library: [shadcn/ui / Radix / MUI / Chakra / custom]
- Icon library: [Lucide / Heroicons / react-icons / mixed]
- Token source: [file path]
- Colors defined: [count]
- Typography scale: [list]
- Spacing base: [4px / 8px / etc.]
- Border radius: [list]
- Shadow levels: [list]
- Dark mode: [YES — class/media / NO]
- Forbidden patterns: [list from README]

Step 1: Research Design System Best Practices

1a. Context7 — Component Library Docs

context7:resolve-library-id
{
 "libraryName": "<DETECTED_COMPONENT_LIBRARY>",
 "query": "component variants accessibility patterns"
}

Then fetch docs with the resolved ID. Also fetch CSS framework docs.

1b. Firecrawl — Design System Standards

firecrawl:firecrawl_search
{
 "query": "<COMPONENT_LIBRARY> design system audit token compliance best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Additional queries:

1c. Firecrawl — Award-Winning Reference Sites

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> website design award Awwwards Muzli [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> SaaS UI design inspiration unique not generic [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Scrape 2–3 standout sites for grid breaks, signature motion, type voice, and accent logic.

Step 2: Token Compliance Audit

2a. Color Tokens

Find violations:

Grep: "(#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\([^v])" glob "*.tsx"
Grep: "\[(#|rgb|hsl)" glob "*.tsx"

2b. Typography Tokens

Grep: "text-\[" glob "*.tsx"
Grep: "font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)" glob "*.tsx" output_mode "count"

2c. Spacing Tokens

Grep: "(p|m|gap|space)-\[" glob "*.tsx"

2d. Borders, Radii, Shadows

Grep: "rounded-\[" glob "*.tsx"
Grep: "shadow-" glob "*.tsx" output_mode "count"

Step 3: Component Modularity Audit

3a. Component Health

3b. Find Duplicate Components

Grep: "<button " glob "*.tsx" — raw buttons outside ui/ (should use Button)
Grep: "<input " glob "*.tsx" — raw inputs (should use Input)
Grep: "<select " glob "*.tsx" — raw selects
Grep: "<a " glob "*.tsx" — raw anchors (should use Link)

Exclude components/ui/* — those are legitimate primitives.

3c. Check Component Consistency

Grep: "function (Button|Input|Modal|Dialog|Card)" glob "*.tsx" output_mode "files_with_matches"

3d. Mixed Icon Libraries

Grep: "from .lucide-react" glob "*.tsx" output_mode "count"
Grep: "from .@heroicons" glob "*.tsx" output_mode "count"
Grep: "from .react-icons" glob "*.tsx" output_mode "count"

Step 4: Live Visual Verification (playwright-cli)

4a. Navigate and Capture

PW="npx --yes @playwright/cli@latest"
$PW -s=ds-audit open --headed "http://localhost:<PORT>/<ROUTE>"
sleep 2
$PW -s=ds-audit snapshot                                              # verify content rendered
$PW -s=ds-audit screenshot --filename ".playwright-mcp/ds-<route>.png"  # visual evidence
$PW -s=ds-audit console                                               # check for errors

4b. Per-Page Checks

4c. Responsive Check

Test at three viewports:

• Desktop (1440px)
• Tablet (768px)
• Mobile (375px)

4d. Visual Accessibility

Step 5: Microinteractions and User Feedback

5a. Microinteraction Coverage Audit

Check each interactive:

Find in code:

Grep: "transition-all|transition-colors|transition-opacity|transition-transform" glob "*.tsx" output_mode "count"
Grep: "hover:|group-hover:|focus-visible:" glob "*.tsx" output_mode "count"
Grep: "animate-|animation-|@keyframes|framer-motion|motion\." glob "*.tsx" output_mode "count"
Grep: "scale-|translate-|rotate-" glob "*.tsx" output_mode "count"

5b. Interaction State Completeness

Verify ALL states exist per interactive:

States checklist per component:
□ Default (resting)
□ Hover (mouse over)
□ Focus-visible (keyboard navigation)
□ Active/pressed (during click)
□ Disabled (grayed, not clickable, cursor-not-allowed)
□ Loading (async action in progress)
□ Error (validation failed, destructive context)
□ Success (completed action)

Find missing states:

Grep: "focus-visible:|focus:" glob "*.tsx" output_mode "count"
Grep: "active:|pressed" glob "*.tsx" output_mode "count"
Grep: "disabled:|cursor-not-allowed|opacity-50" glob "*.tsx" output_mode "count"

5c. Visual Rhythm and Personality Audit

Intentional variety vs uniform repetition:

Step 6: Animation and Dark Mode

Animations

Grep: "duration-[0-9]+" glob "*.tsx" output_mode "count"
Grep: "transition-" glob "*.tsx" output_mode "count"
Grep: "prefers-reduced-motion|motion-safe|motion-reduce" glob "*.tsx"
Grep: "stagger|delay-\[|animation-delay" glob "*.tsx" output_mode "count"

Dark Mode

Grep: "(bg-white|bg-black|text-white|text-black)" glob "*.tsx" output_mode "count"

Output Template

## UI Design System Audit Report

**Date:** [date]
**Framework:** [detected]
**CSS:** [Tailwind v3/v4 / CSS Modules / etc.]
**Component library:** [shadcn / Radix / MUI / custom]
**Pages Audited:** [count]
**Issues Found:** [count]

---

### Design Token Compliance

| Token Category | Defined | Violations | Status |
|----------------|---------|------------|--------|
| Colors | [count] | [count] raw hex/rgb | [pass/warn/fail] |
| Typography | [count] | [count] arbitrary sizes | [pass/warn/fail] |
| Spacing | [count] | [count] arbitrary values | [pass/warn/fail] |
| Radii | [count] | [count] arbitrary radii | [pass/warn/fail] |
| Shadows | [count] | [count] inconsistent | [pass/warn/fail] |

---

### Component Health

| Component | Used In | Variants | Issues |
|-----------|---------|----------|--------|
| Button | [N] files | [N] | [notes] |
| Input | [N] files | [N] | [notes] |
| Card | [N] files | [N] | [notes] |

---

### Duplicate / Redundant Components

| Pattern | Locations | Recommendation |
|---------|-----------|----------------|
| Raw `<button>` | [files] | Use `<Button>` from `components/ui` |
| Custom modal | [file] | Use `<Dialog>` from `components/ui` |

---

### Visual Accessibility

| Criteria | Status | Issues |
|----------|--------|--------|
| Color contrast | [pass/warn/fail] | [details] |
| Focus indicators | [pass/warn/fail] | [details] |
| Alt text | [pass/warn/fail] | [details] |
| Semantic HTML | [pass/warn/fail] | [details] |

Further reading

• Microinteraction Coverage and more