/design

Complete design thinking pipeline that ensures Claude builds better UIs by forcing structured analysis before any visual work. Now with audit, iterate, and specialized sub-skills.

Rough Idea → PRD (1-7) → UX Spec (9 passes) → /frontend-design
     OR
Existing UI → Audit → Issues Report → Iterate → Improvements

Subcommands

/design (Full Pipeline)

Runs all stages automatically:

1. •Ask for rough idea if not provided
2. •Generate PRD → .claude/design/PRD.md
3. •Generate UX spec (9 passes) → .claude/design/UX-spec.md
4. •Invoke /frontend-design with UX context

/design init - Rough Idea to PRD

Input: Rough MVP idea (vague, incomplete, "vibe-level")

Role: Senior product thinker turning rough idea into demo-grade PRD.

Output: .claude/design/PRD.md with sections 1-7:

Section 1: One-Sentence Problem

[User] struggles to [do X] because [reason], resulting in [impact].

Section 2: Demo Goal

• •What must work for demo success
• •What outcome the demo communicates
• •Non-goals (intentionally out of scope)

Section 3: Target User (Role-Based)

• •Role / context
• •Skill level
• •Key constraint (time, knowledge, access)

No personas or demographics.

Section 4: Core Use Case (Happy Path)

• •Start condition
• •Step-by-step flow (numbered)
• •End condition

If this flow works, the demo works.

Section 5: Functional Decisions

Phrase as capabilities, not implementation. No "nice-to-haves".

Section 6: UX Decisions

6.1 Entry Point: How user starts, what they see first 6.2 Inputs: What user provides 6.3 Outputs: What user receives, in what form 6.4 Feedback & States: Loading, success, failure, partial 6.5 Errors: Invalid input, system failure, user does nothing

Section 7: Data & Logic

7.1 Inputs: User / API / static / generated 7.2 Processing: High-level only (input → transform → output) 7.3 Outputs: UI only / temp stored / logged

Rules:

• •Optimize for speed + clarity
• •Label assumptions explicitly
• •If extremely vague, ask ONE clarifying question max, then proceed

See references/prd-template.md for detailed templates.

/design ux - PRD to UX Spec

Input: .claude/design/PRD.md (or user-provided PRD)

Output: .claude/design/UX-spec.md with 9 mandatory passes

THE IRON LAW

NO VISUAL SPECS UNTIL ALL 9 PASSES COMPLETE

Not negotiable:

• •Don't mention colors, typography, spacing until Pass 9 done
• •Don't describe screen layouts until IA is explicit
• •Don't design components until affordances mapped

Pass 1: Mental Model Alignment

Question: "What does the user think is happening?"

Output:

• •Primary user intent (one sentence)
• •Likely misconceptions
• •UX principle to reinforce/correct

Pass 2: Information Architecture

Question: "What exists, and how is it organized?"

Output:

• •ALL concepts user will encounter
• •Grouped structure
• •Each concept: Primary / Secondary / Hidden

Pass 3: Affordances & Action Clarity

Question: "What actions are obvious without explanation?"

Output:

• •What is clickable?
• •What looks editable?
• •What looks read-only?
• •What looks final vs in-progress?

Pass 4: Cognitive Load & Decision Minimization

Question: "Where will the user hesitate?"

Output:

• •Moments of choice (decisions required)
• •Moments of uncertainty (unclear what to do)
• •Moments of waiting (system processing)
• •Simplifications: collapse decisions, delay complexity, introduce defaults

Pass 5: State Design & Feedback

Question: "How does the system talk back?"

For EACH major element:

Pass 6: Flow Integrity Check

Question: "Does this feel inevitable?"

Output:

• •Flow risks (where could users get lost?)
• •Visibility decisions (must be visible vs can be implied)
• •UX constraints (hard rules for visual phase)

Pass 7: Accessibility (a11y)

Question: "Can everyone use this?"

Output:

• •Keyboard navigation map (tab order, focus traps)
• •Screen reader announcements (what gets read, when)
• •Color contrast requirements (WCAG AA minimum)
• •ARIA patterns needed
• •Touch target sizes (44x44 minimum)
• •Focus indicators

See references/a11y-checklist.md for detailed checklist.

Pass 8: Responsive Strategy

Question: "How does this adapt to different screens?"

Output:

• •Breakpoint decisions (mobile-first vs desktop-first)
• •Content priority per viewport
• •Navigation pattern changes (hamburger, tabs, sidebar)
• •Touch vs mouse interactions
• •Typography scaling
• •Layout reflow rules

Pass 9: Motion & Delight

Question: "How does this come alive?"

Output:

• •Entry animations (what animates in, from where)
• •Exit animations (what animates out, to where)
• •Micro-interactions (hover, click, success feedback)
• •Loading states animation
• •State transitions (smooth or instant)
• •Performance budget (max duration, complexity)

See references/motion-patterns.md for patterns.

See references/ux-passes.md for detailed methodology.

/design build - UX Spec to Frontend

Input: .claude/design/UX-spec.md

Action: Invoke /frontend-design skill with full UX context

Context passed to /frontend-design:

• •Mental model (what user expects)
• •Information architecture (all concepts, groupings)
• •Affordances (clickable, editable, read-only signals)
• •Cognitive load analysis (friction points, defaults)
• •State design (empty/loading/success/error per element)
• •Flow integrity (risks, visibility decisions, constraints)
• •Accessibility requirements
• •Responsive strategy
• •Motion specifications

Result: Production-grade UI built with proper design thinking already done.

/design audit - Analyze Existing UI

Input:

• •Page or component path (e.g., src/components/dashboard)
• •OR description of current UI behavior
• •OR screenshot description

Process:

1. •Read existing component code
2. •Run abbreviated 9-pass analysis
3. •Identify UX issues by pass
4. •Prioritize by severity (Critical / Major / Minor)
5. •Generate actionable improvement list

Output: .claude/design/audit-report.md

# UX Audit Report: [Component/Page Name]

## Summary
- Critical Issues: X
- Major Issues: Y
- Minor Issues: Z

## Issues by Pass

### Mental Model Issues
- [Issue]: [Description] → [Fix]

### Information Architecture Issues
- [Issue]: [Description] → [Fix]

### Affordance Issues
- [Issue]: [Description] → [Fix]

... (all 9 passes)

## Priority Actions
1. [Highest impact fix]
2. [Second highest]
3. [Third highest]

Use case: "Make this project's UI better"

See references/audit-checklist.md for criteria.

/design iterate - Improve Based on Feedback

Input:

• •User feedback (quotes, complaints, observations)
• •Analytics data (drop-off points, rage clicks)
• •Support tickets
• •Current component/page reference

Process:

1. •Categorize feedback by affected pass
2. •Re-run affected passes only
3. •Generate targeted improvements
4. •Preserve what's working

Output: .claude/design/iteration-spec.md

# Iteration Spec: [Component/Page Name]

## Feedback Analysis
| Feedback | Affected Pass | Severity |
|----------|---------------|----------|
| "I don't know where to click" | Pass 3 (Affordances) | Critical |
| "Loading takes forever" | Pass 5 (State Design) | Major |

## Targeted Fixes

### Pass 3: Affordances (Re-run)
- Current: [What it does now]
- Problem: [Why it's confusing]
- Fix: [Specific change]

### Pass 5: State Design (Re-run)
- Current: [What it does now]
- Problem: [Why it's frustrating]
- Fix: [Specific change]

## Implementation Checklist
- [ ] Fix 1: [Description]
- [ ] Fix 2: [Description]

Use case: "Users say the form is confusing"

See references/iterate-workflow.md for process.

/design a11y - Accessibility Audit

Input: Component or page path

Process:

1. •Analyze semantic HTML structure
2. •Check keyboard navigation
3. •Verify ARIA usage
4. •Test color contrast (via code analysis)
5. •Check focus management
6. •Validate form accessibility

Output: .claude/design/a11y-report.md

# Accessibility Report: [Component Name]

## WCAG 2.1 AA Compliance

### Perceivable
- [ ] 1.1.1 Non-text Content: [Status]
- [ ] 1.3.1 Info and Relationships: [Status]
- [ ] 1.4.3 Contrast (Minimum): [Status]

### Operable
- [ ] 2.1.1 Keyboard: [Status]
- [ ] 2.4.3 Focus Order: [Status]
- [ ] 2.4.7 Focus Visible: [Status]

### Understandable
- [ ] 3.1.1 Language of Page: [Status]
- [ ] 3.2.1 On Focus: [Status]
- [ ] 3.3.1 Error Identification: [Status]

### Robust
- [ ] 4.1.1 Parsing: [Status]
- [ ] 4.1.2 Name, Role, Value: [Status]

## Issues Found
| Issue | WCAG | Severity | Fix |
|-------|------|----------|-----|
| [Description] | [Criterion] | [Level] | [Solution] |

## Keyboard Navigation Map
[Tab order diagram]

## Screen Reader Flow
[Announcement sequence]

See references/a11y-checklist.md for complete checklist.

/design motion - Animation Design

Input:

• •UX spec or component
• •OR description of desired interaction

Process:

1. •Identify animation opportunities
2. •Choose appropriate patterns
3. •Define timing and easing
4. •Consider reduced motion preferences
5. •Set performance budget

Output: .claude/design/motion-spec.md

# Motion Specification: [Component Name]

## Animation Inventory

### Entry Animations
| Element | Animation | Duration | Easing | Delay |
|---------|-----------|----------|--------|-------|
| Modal | Fade + Scale | 200ms | ease-out | 0ms |
| Items | Stagger fade | 150ms | ease-out | 50ms each |

### Exit Animations
| Element | Animation | Duration | Easing |
|---------|-----------|----------|--------|
| Modal | Fade + Scale down | 150ms | ease-in |

### Micro-interactions
| Trigger | Response | Duration |
|---------|----------|----------|
| Button hover | Scale 1.02 | 100ms |
| Button click | Scale 0.98 | 50ms |
| Success | Checkmark draw | 300ms |

### Loading States
| State | Animation | Notes |
|-------|-----------|-------|
| Skeleton | Shimmer | 1.5s loop |
| Spinner | Rotate | 1s loop |

## Reduced Motion Fallbacks
- All animations → instant transitions
- Shimmer → static gray
- Spinners → static indicator

## Performance Budget
- Total animation time: < 500ms
- Concurrent animations: < 3
- Use transform/opacity only (no layout thrash)

See references/motion-patterns.md for patterns library.

/design tokens - Design System Tokens

Input:

• •Existing codebase (reads tailwind.config.js, CSS variables)
• •OR brand guidelines description
• •OR "generate from scratch"

Process:

1. •Extract existing tokens (if any)
2. •Identify gaps
3. •Generate complete token set
4. •Output in multiple formats

Output: .claude/design/tokens.md + optional config files

# Design Tokens: [Project Name]

## Colors

### Brand
| Token | Value | Usage |
|-------|-------|-------|
| --color-primary | #3B82F6 | Primary actions, links |
| --color-primary-hover | #2563EB | Primary hover state |

### Semantic
| Token | Value | Usage |
|-------|-------|-------|
| --color-success | #10B981 | Success states |
| --color-error | #EF4444 | Error states |
| --color-warning | #F59E0B | Warning states |

### Neutral
| Token | Value | Usage |
|-------|-------|-------|
| --color-background | #FFFFFF | Page background |
| --color-surface | #F9FAFB | Card backgrounds |
| --color-border | #E5E7EB | Borders, dividers |

## Typography

| Token | Value | Usage |
|-------|-------|-------|
| --font-size-xs | 0.75rem | Helper text |
| --font-size-sm | 0.875rem | Body small |
| --font-size-base | 1rem | Body |
| --font-size-lg | 1.125rem | Body large |
| --font-size-xl | 1.25rem | H4 |
| --font-size-2xl | 1.5rem | H3 |
| --font-size-3xl | 1.875rem | H2 |
| --font-size-4xl | 2.25rem | H1 |

## Spacing

| Token | Value | Usage |
|-------|-------|-------|
| --space-1 | 0.25rem | Tight spacing |
| --space-2 | 0.5rem | Element padding |
| --space-3 | 0.75rem | Small gaps |
| --space-4 | 1rem | Standard gaps |
| --space-6 | 1.5rem | Section spacing |
| --space-8 | 2rem | Large gaps |

## Border Radius

| Token | Value | Usage |
|-------|-------|-------|
| --radius-sm | 0.25rem | Small elements |
| --radius-md | 0.375rem | Buttons, inputs |
| --radius-lg | 0.5rem | Cards |
| --radius-full | 9999px | Pills, avatars |

## Shadows

| Token | Value | Usage |
|-------|-------|-------|
| --shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | Subtle elevation |
| --shadow-md | 0 4px 6px rgba(0,0,0,0.1) | Cards |
| --shadow-lg | 0 10px 15px rgba(0,0,0,0.1) | Modals |

## Breakpoints

| Token | Value | Usage |
|-------|-------|-------|
| --breakpoint-sm | 640px | Small tablets |
| --breakpoint-md | 768px | Tablets |
| --breakpoint-lg | 1024px | Laptops |
| --breakpoint-xl | 1280px | Desktops |

See references/token-extraction.md for extraction process.

/design components - Component Patterns

Input: Description of component need (e.g., "multi-step form", "data table with sorting")

Process:

1. •Identify component category
2. •Select best-practice pattern
3. •Adapt to project's design system
4. •Include all states and variants

Output: Component specification with:

• •Structure (hierarchy, slots)
• •States (default, hover, focus, disabled, error)
• •Variants (sizes, styles)
• •Accessibility requirements
• •Example usage

Available Patterns

Forms:

• •Single-field forms
• •Multi-step wizards
• •Inline editing
• •Search with autocomplete

Data Display:

• •Data tables (sortable, filterable)
• •Card grids
• •Lists (simple, complex)
• •Empty states

Navigation:

• •Tabs
• •Breadcrumbs
• •Pagination
• •Sidebar navigation

Feedback:

• •Toasts/Notifications
• •Progress indicators
• •Skeleton loaders
• •Error states

Overlays:

• •Modals/Dialogs
• •Drawers/Sheets
• •Popovers
• •Tooltips

See references/component-patterns.md for full pattern library.

File Structure

.claude/design/
├── PRD.md              # Stage 1 output
├── UX-spec.md          # Stage 2 output (9 passes)
├── audit-report.md     # Audit output
├── iteration-spec.md   # Iterate output
├── a11y-report.md      # Accessibility output
├── motion-spec.md      # Motion output
├── tokens.md           # Tokens output
└── component-spec.md   # Component pattern output

Context Awareness

Design System Detection

Before any design work, automatically check for:

1. •

   Tailwind config: tailwind.config.js or tailwind.config.ts

   • •Extract color palette
   • •Extract spacing scale
   • •Extract breakpoints
2. •

   CSS variables: :root definitions in global CSS

   • •Map existing tokens
3. •

   Component library: Check for shadcn, Radix, MUI, etc.

   • •Match existing patterns
4. •

   Existing components: Scan src/components/ui/

   • •Identify reusable elements
   • •Match naming conventions

Codebase Pattern Detection

Before designing new components:

1. •Read existing components in the same category
2. •Identify patterns: How do existing forms work? How are errors shown?
3. •Match conventions: Don't introduce new patterns unnecessarily
4. •Reuse: Suggest existing components when applicable

Red Flags - Stop and Restart

If you catch yourself doing any of these during /design ux, STOP:

When to Use Each Command