Audit uiux design system

UI Design System Audit Skill

Visual design system coherency audit: tokens, components, visual consistency, dark mode, animations, and WCAG visual compliance.

Before ANY browser interaction, read the browser-anti-stall skill and apply its rules to every step. That skill is protocol-browser-anti-stall.

CRITICAL: Anti-Template, Anti-AI-Generated Design

Every UI recommendation MUST result in output that looks hand-crafted by a senior designer, not generated by a template or AI. Before implementing or recommending ANY visual change:

1. Research real products — Search Firecrawl for award-winning sites in the product's domain (Awwwards, Muzli, SiteInspire). Study what makes them feel human and curated.
2. Break the grid intentionally — Uniform spacing, identical card sizes, and perfectly symmetric layouts are AI tells. Introduce deliberate visual rhythm: vary section padding, use asymmetric hero layouts, offset elements with purpose.
3. Microinteraction budget — Every interactive element needs a response. Not the same response. Buttons get press feedback (scale, shadow shift). Links get underline animations. Cards get subtle lift. Hover, focus, active, and disabled MUST all feel distinct.
4. Personality tokens — The design system must define personality, not just colors. What's the brand's visual "voice"? Sharp corners = precision. Rounded = friendly. Monospace accents = technical. Serif headings = editorial. This must be intentional.
5. Forbid these AI tells:

• Identical padding on every section
• Generic gradient backgrounds with no brand logic
• Icon-title-description cards in a 3-column grid as the default layout for everything
• "Lorem ipsum" placeholder patterns in empty states
• Perfectly uniform border-radius on all elements
• Stock illustration style (undraw, absurd-design) without brand adaptation

---

Step 0: Auto-Detect Design System

0a. Detect CSS Framework

Read package.json and config files:

Signal	Technology
tailwindcss v3 + tailwind.config.*	Tailwind CSS v3
tailwindcss v4 + @theme in CSS	Tailwind CSS v4
*.module.css files	CSS Modules
styled-components or @emotion/styled	CSS-in-JS
@chakra-ui/react	Chakra UI
@mui/material	Material UI
@mantine/core	Mantine

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:

Topic	Query
Token compliance	design token audit <CSS_FRAMEWORK> consistency
Component patterns	<FRAMEWORK> component modularity composition patterns
Dark mode	<CSS_FRAMEWORK> dark mode implementation best practices

Scrape the best result for detailed guidance.

1c. Firecrawl — Award-Winning Reference Sites

Research real products in the same domain to establish a visual benchmark:

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. Extract:

• How they break typical grid patterns
• Signature microinteractions (hover, scroll, transition)
• Typography personality (serif/sans mix, weight contrast, size jumps)
• Color usage patterns (accent frequency, gradient logic, muted vs saturated)
• What makes them NOT look like a template

---

Step 2: Token Compliance Audit

2a. Color Tokens

Rule	Standard	How to Check
Semantic naming	primary, secondary, destructive, muted, accent	No raw hex/rgb in components
CSS variables	hsl(var(--primary)) or oklch()	All colors reference variables
Foreground pairs	Every bg color has *-foreground	Text contrast maintained
Dark mode	All tokens have dark variant	.dark class or @media
Status colors	success, warning, error, info defined	Consistent across alerts, badges, toasts

Find violations:

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

2b. Typography Tokens

Rule	Standard
Font families	Max 2-3 families in theme
Size scale	Consistent (text-sm, text-base, text-lg)
Weight scale	Limited set (font-normal, font-medium, font-semibold, font-bold)
Heading hierarchy	h1 > h2 > h3 in visual weight AND DOM order
No arbitrary sizes	No text-[14px] when text-sm exists

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

2c. Spacing Tokens

Rule	Standard
Base unit	4px grid (Tailwind default)
Consistent gaps	Same spacing for same contexts
No arbitrary values	No p-[13px] when p-3 exists

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

Rule	Standard
Single responsibility	One component = one purpose
Composable	Small pieces compose into larger ones
Reusable	Same UI = same component everywhere
Consistent props	variant, size, disabled, className across all
Variants pattern	cva() or similar for style variants

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"

Multiple files defining the same component name = duplication.

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"

Multiple icon libraries = inconsistency. Flag it.

---

Step 4: Live Visual Verification (Browser MCP)

4a. Navigate and Capture

browser_navigate → http://localhost:<PORT>/<ROUTE>
browser_wait_for → { time: 2 }
browser_snapshot → verify content rendered
browser_take_screenshot → visual evidence
browser_console_messages → check for errors

4b. Per-Page Checks

Check	How
Token compliance	Screenshot — inconsistent colors, spacing
Component reuse	Snapshot — shared primitives used?
Console errors	browser_console_messages — hydration, missing CSS vars
Layout shift	Snapshot before/after interaction
Dark mode	Toggle dark mode, re-screenshot, compare

4c. Responsive Check

Test at three viewports:

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

Capture screenshots at each.

4d. Visual Accessibility

Check	How
Color contrast	4.5:1 text, 3:1 large text/UI — inspect via screenshot
Focus rings	Tab through elements, verify visible focus indicator
Semantic HTML	`Grep: "<nav>
Alt text	`Grep: "<(img

---

Step 5: Microinteractions and User Feedback

5a. Microinteraction Coverage Audit

Every interactive element MUST provide tactile feedback. Check each:

Element	Expected Feedback	AI-Tell if Missing
Buttons	Hover: color shift + subtle shadow change. Active: scale(0.98) press. Loading: spinner replaces label or inline indicator	Flat, no state change — feels dead
Links	Hover: underline animation or color transition, not instant swap	Instant color jump with no transition
Cards (clickable)	Hover: lift (translateY + shadow increase). Not just color change	Color change only, or no hover at all
Inputs	Focus: ring animation or border color transition. Not just outline swap	Browser default outline, no custom focus
Toggles/switches	State transition animated, not instant. Haptic feel via easing	Instant snap between states
Dropdowns/menus	Open/close with slide or fade, not instant appear/disappear	Instant pop, no transition
Toasts/notifications	Enter with slide + fade, exit with fade. Auto-dismiss with progress	Instant appear/disappear
Modals/dialogs	Backdrop fade + content scale/slide. Exit reverses. Not instant	Instant appear, jarring
Tabs	Active indicator slides to new tab, not instant jump	Instant color swap
Tooltips	Slight delay (200-300ms), fade in. Don't flicker on mouse movement	Instant, flickers, no delay

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

For every interactive component, verify ALL states exist. Missing states = AI-generated feel:

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

Check that the design has intentional variety, not uniform repetition:

Pattern	Curated Feel	Template Feel
Section spacing	Varies by content type (hero: generous, form: tight, CTA: spacious)	Same py-16 on every section
Typography contrast	Large jumps between heading and body (e.g., 48px → 16px). Mix weights	Incremental scale, same weight everywhere
Color accent usage	Accent used sparingly for emphasis, not on every element	Primary color on every button, link, icon
Layout variation	Different layouts per section (text-left/image-right, full-width, sidebar)	Same 3-column card grid repeated
Border radius	Intentional variation (pills for tags, rounded for cards, sharp for data tables)	Same rounded-lg on everything
Shadow depth	Multiple shadow levels for elevation hierarchy	Same shadow on everything, or no shadows
Whitespace	Asymmetric margins create visual flow and reading rhythm	Perfectly symmetric, mechanical spacing

---

Step 6: Animation and Dark Mode

Animations

Rule	Standard
Duration scale	150ms (micro), 200ms (hover), 300ms (enter), 500ms (complex) — NOT all the same
Easing	ease-out for enter, ease-in for exit, ease-in-out for state changes — NOT all ease-in-out
Reduced motion	motion-safe: prefix or prefers-reduced-motion
No layout shift	Transitions don't cause CLS
Stagger effect	List items, card grids animate in with stagger delay, not all at once

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

Rule	Standard
All tokens switch	CSS variables change in dark mode
No hardcoded colors	No bg-white, text-black — use semantic tokens
Borders visible	In both modes
Contrast	WCAG in BOTH light and dark
Not an afterthought	Dark mode should feel designed, not inverted. Shadows become glows, borders become subtle

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](references/details.md)