UX Design: {{project_name}}

Flow 1: User Authentication
- US-001: User can sign up
- US-002: User can log in
- US-003: User can reset password
Screens needed: Sign up, Login, Forgot password

Flow 2: Dashboard
- US-004: User can view dashboard
- US-005: User can filter data
Screens needed: Dashboard (empty state), Dashboard (with data)

[Continue for all user stories...]

### Flow:  { { flow_name } } 

 **Entry Point:**  { { how_user_starts_flow } } 

 **Happy Path:**
1.  { { screen_1 } }   → User  { { action } }   →  { { screen_2 } } 
 2.  { { screen_2 } }   → User  { { action } }   →  { { screen_3 } } 
 3.  { { screen_3 } }   →  { { final_state } } 

 **Decision Points:**
- At  { { screen } } : If  { { condition } }   →  { { alternative_path } } 

 **Error Cases:**
-  { { error_scenario } }   → Show  { { error_message } }   →  { { recovery_action } } 

 **Exit Points:**
- Success:  { { success_screen } } 
 - Cancel:  { { cancel_destination } } 
 - Error:  { { error_screen } } 

 **Diagram:**

Screen:  { { screen_name } } 

 Mobile (320-767px):
┌─────────────────────┐
│ ☰  Logo        [?]  │ ← Header (60px)
├─────────────────────┤
│                     │
│  Page Title         │ ← H1 (32px)
│  Subtitle           │ ← H2 (18px)
│                     │
│  ┌───────────────┐  │
│  │ Card 1        │  │ ← Card (full-width)
│  │ Title         │  │
│  │ Description   │  │
│  │ [Button]      │  │
│  └───────────────┘  │
│                     │
│  ┌───────────────┐  │
│  │ Card 2        │  │
│  └───────────────┘  │
│                     │
│  [Primary CTA]      │ ← Button (48px height)
│                     │
└─────────────────────┘

Desktop (1024px+):
┌─────────────────────────────────────────┐
│ Logo        Nav1   Nav2   Nav3    [?]   │ ← Header
├─────────────────────────────────────────┤
│                                         │
│  Page Title              Subtitle       │
│                                         │
│  ┌──────────┐  ┌──────────┐            │
│  │ Card 1   │  │ Card 2   │            │ ← 2-column grid
│  │          │  │          │            │
│  │ [Button] │  │ [Button] │            │
│  └──────────┘  └──────────┘            │
│                                         │
│         [Primary CTA]                   │
│                                         │
└─────────────────────────────────────────┘

### Screen:  { { screen_name } } 

 **Purpose:**  { { what_user_does_here } } 

 **Layout Structure:**

**Header (fixed, 60px height):**
- Logo (left, 40px × 40px)
  - Click → Home page
- Navigation menu (center)
  - Nav Item 1, Nav Item 2, Nav Item 3
  - Active state: underline
- Help icon (right, 24px × 24px)
  - Click → Help modal

**Main Content (scrollable):**

**Hero Section (full-width, 400px height):**
- Headline (H1, 48px, center-aligned)
- Subheadline (H2, 24px, center-aligned)
- Background: gradient or image

**Card Grid (responsive):**
- Layout: 2 columns (desktop), 1 column (mobile)
- Gap: 24px between cards

**Card Component (300px × 250px):**
- Image (full-width, 150px height)
- Title (H3, 20px, 16px padding)
- Description (Body text, 14px, 16px padding)
- CTA Button (bottom, 16px padding)
  - Primary style
  - Full-width on mobile
  - Fixed-width on desktop (160px)

**CTA Section (center-aligned, 200px height):**
- Primary Button (200px × 56px)
  - Text:  " { { cta_text } } " 
   - Click →  { { destination } } 

 **Footer (full-width, 120px height):**
- Links (horizontal, center-aligned)
- Copyright notice (center, 12px text)

**Interactions:**
- Card hover → Elevation shadow
- Button hover → Darken 10%
- Button click →  { { action } } 
 - Links hover → Underline

**States:**
- Default
- Hover (for interactive elements)
- Focus (keyboard navigation)
- Active (click/tap)
- Disabled (when applicable)
- Loading (for async actions)

**Responsive Behavior:**
- **Mobile (320-767px):**
  - Single column layout
  - Stack cards vertically
  - Full-width buttons
  - Hamburger menu for navigation

- **Tablet (768-1023px):**
  - 2-column grid
  - Navigation visible
  - Moderate padding

- **Desktop (1024px+):**
  - 2-3 column grid
  - Maximum content width: 1200px
  - Centered with side margins

### Accessibility:  { { screen_name } } 

 **WCAG  { { wcag_level } }   Compliance:**

**Perceivable:**
- [ ] All images have alt text:  " { { alt_text } } " 
 - [ ] Color contrast checked:
  - Text on background:  { { ratio } }   (minimum 4.5:1)
  - UI components:  { { ratio } }   (minimum 3:1)
- [ ] Information not conveyed by color alone
- [ ] Text resizable to 200% without breaking layout
- [ ] No horizontal scrolling at 320px width

**Operable:**
- [ ] Tab order:  { { tab_order_sequence } } 
 - [ ] Focus indicators visible (2px outline, primary color)
- [ ] No keyboard traps
- [ ] Skip navigation link:  " Skip to main content " 
 - [ ] Touch targets minimum 44px × 44px
- [ ] Animations respect prefers-reduced-motion

**Understandable:**
- [ ] Page language: `lang= " en " `
- [ ] Form labels for all inputs
- [ ] Error messages:  " { { example_error } } "   (clear and actionable)
- [ ] Consistent navigation across pages
- [ ] Predictable interactions (no surprise navigation)

**Robust:**
- [ ] Semantic HTML: ` < header > `, ` < nav > `, ` < main > `, ` < footer > `
- [ ] ARIA labels where needed:
  - Button: `aria-label= " { { label } } " `
  - Icon-only: `aria-label= " { { description } } " `
- [ ] Form validation: `aria-invalid`, `aria-describedby`
- [ ] Modal: `role= " dialog " `, `aria-modal= " true " `

**Keyboard Navigation:**

 **Screen Reader Annotations:**
- Landmark regions: header, nav, main, footer
- Headings hierarchy: H1 (once), H2 (sections), H3 (subsections)
- Alternative text for images: descriptive, not decorative
- Live regions for dynamic content: `aria-live= " polite " `

## Component Library

### Button Component

**Variants:**
- **Primary:** Main actions (e.g., Submit, Save)
  - Background: Primary color
  - Text: White
  - Padding: 12px 24px
  - Border-radius: 4px
  - Font: 16px, 600 weight

- **Secondary:** Less important actions (e.g., Cancel)
  - Background: Transparent
  - Text: Primary color
  - Border: 1px solid primary
  - Padding: 12px 24px

- **Tertiary:** Minimal emphasis (e.g., text links)
  - Background: Transparent
  - Text: Primary color
  - No border

**States:**
- Default
- Hover: Background darkens 10%
- Focus: 2px outline, offset 2px
- Active: Background darkens 20%
- Disabled: Opacity 50%, cursor not-allowed

**Accessibility:**
- Minimum size: 44px × 44px
- Focus indicator visible
- aria-disabled when disabled

---

### Card Component

**Structure:**
- Image (optional, 16:9 aspect ratio)
- Title (H3)
- Description (Body text)
- Action button (optional)

**Sizing:**
- Mobile: Full-width
- Tablet: 48% width (2 columns)
- Desktop: 32% width (3 columns)

**Spacing:**
- Internal padding: 16px
- Gap between cards: 24px

**States:**
- Default: elevation 1
- Hover: elevation 2
- Focus: outline

---

### Form Input Component

**Structure:**
- Label (above input, required)
- Input field
- Help text (optional)
- Error message (when invalid)

**Styling:**
- Border: 1px solid neutral-300
- Padding: 12px
- Border-radius: 4px
- Font: 16px (prevent zoom on mobile)

**States:**
- Default: neutral border
- Focus: primary border, 2px
- Error: error border, show error message
- Disabled: gray background, not-allowed cursor

**Accessibility:**
- Label linked to input: `for= " { { id } } " `
- Required: `aria-required= " true " `
- Error: `aria-invalid= " true " `, `aria-describedby= " { { error-id } } " `

[Define all reusable components...]

## Design Tokens

### Colors

**Primary Palette:**
- Primary: #0066CC (contrast ratio: 4.57:1 on white)
- Primary-dark: #004C99
- Primary-light: #3385D6

**Semantic Colors:**
- Success: #00AA44 (WCAG AA compliant)
- Warning: #FF8800
- Error: #DD0000
- Info: #0066CC

**Neutral Palette:**
- Neutral-50: #F9F9F9 (backgrounds)
- Neutral-100: #F0F0F0
- Neutral-300: #CCCCCC (borders)
- Neutral-500: #999999 (secondary text)
- Neutral-700: #555555 (primary text)
- Neutral-900: #222222 (headings)

**Contrast Ratios (checked):**
- Neutral-700 on white: 7.5:1 ✓ (AAA)
- Primary on white: 4.57:1 ✓ (AA)
- Error on white: 6.2:1 ✓ (AA)

### Typography

**Font Family:**
- Primary: -apple-system, BlinkMacSystemFont,  " Segoe UI " , Roboto, sans-serif
- Monospace:  " SF Mono " , Monaco, monospace

**Type Scale:**
- H1: 48px / 600 / 1.2 line-height
- H2: 36px / 600 / 1.3
- H3: 24px / 600 / 1.4
- H4: 20px / 600 / 1.4
- Body: 16px / 400 / 1.6
- Small: 14px / 400 / 1.5
- Tiny: 12px / 400 / 1.4

**Responsive Type:**
- Mobile: Reduce by 20%
- Tablet: Reduce by 10%
- Desktop: Base scale

### Spacing

**Scale (based on 8px):**
- xs: 4px
- sm: 8px
- md: 16px
- lg: 24px
- xl: 32px
- 2xl: 48px
- 3xl: 64px

**Layout:**
- Container max-width: 1200px
- Gutter: 16px (mobile), 24px (desktop)
- Section spacing: 48px (mobile), 96px (desktop)

### Shadows

**Elevation:**
- Level 1: 0 1px 3px rgba(0,0,0,0.12)
- Level 2: 0 4px 6px rgba(0,0,0,0.16)
- Level 3: 0 10px 20px rgba(0,0,0,0.20)

### Border Radius

- Small: 4px (buttons, inputs)
- Medium: 8px (cards)
- Large: 16px (modals)
- Circle: 50% (avatars, icon buttons)

### Breakpoints

- Mobile: 320px - 767px
- Tablet: 768px - 1023px
- Desktop: 1024px+

## Developer Handoff

### Implementation Priorities

**Phase 1 - Foundation:**
1. Set up design tokens (colors, spacing, typography)
2. Implement base components (Button, Input, Card)
3. Create responsive grid system
4. Set up accessibility infrastructure

**Phase 2 - Screens:**
1.  { { highest_priority_screen } } 
 2.  { { second_priority_screen } } 
 3.  { { third_priority_screen } } 

 **Phase 3 - Polish:**
1. Animations and transitions
2. Loading states
3. Error states
4. Edge cases

### Component Implementation Notes

**Button Component:**

 ### Responsive Implementation

**Mobile-first approach:**

 ### Accessibility Implementation

**Required attributes:**
- All images: `alt= " { { description } } " `
- Form inputs: `id`, `aria-label` or ` < label for > `
- Buttons: `aria-label` if icon-only
- Modals: `role= " dialog " `, `aria-modal= " true " `
- Live regions: `aria-live= " polite " `

**Testing:**
- Keyboard navigation (Tab, Enter, Escape)
- Screen reader (test with NVDA/JAWS/VoiceOver)
- Color contrast (use Axe DevTools)
- Zoom to 200% (check layout)

### Assets Needed

**Images:**
- Logo (SVG preferred, PNG fallback)
- Icons (SVG, 24px × 24px)
- Placeholder images (16:9 ratio)

**Fonts:**
- System fonts (no web fonts for performance)

**Third-party:**
- None (using native HTML/CSS/JS)

# UX Design:  { { project_name } } 

 **Date:**  { { date } } 
 **Designer:**  { { user_name } } 
 **Version:** 1.0

## Project Overview

**Project:**  { { project_name } } 
 **Target Platforms:**  { { target_platforms } } 
 **Accessibility:** WCAG  { { wcag_level } } 

 ## Design Scope

**Screens:**  { { screen_count } } 
 **User Flows:**  { { flow_count } } 
 **Components:**  { { component_count } } 

 ## User Flows

 { { all_flows_from_part_3 } } 

 ## Wireframes

 { { all_wireframes_from_part_4 } } 

 ## Accessibility

 { { accessibility_annotations_from_part_5 } } 

 ## Component Library

 { { components_from_part_6 } } 

 ## Design Tokens

 { { design_tokens_from_part_7 } } 

 ## Developer Handoff

 { { handoff_from_part_8 } } 

 ## Validation

**Requirements Coverage:**
- [ ] US-001:  { { requirement } }   →  { { screen } } 
 - [ ] US-002:  { { requirement } }   →  { { screen } } 
 [All user stories mapped to screens]

**Accessibility Checklist:**
- [ ] WCAG  { { level } }   compliance verified
- [ ] Keyboard navigation tested
- [ ] Screen reader compatible
- [ ] Color contrast verified
- [ ] Responsive on all target platforms

**Sign-off:**
- [ ] Product Manager approved
- [ ] System Architect reviewed
- [ ] Ready for implementation

---

*Generated by BMAD Method v6 - UX Designer*
*Design Date:  { { date } } *

✓ UX Design Complete!

Screens:  { { screen_count } } 
 User Flows:  { { flow_count } } 
 Components:  { { component_count } } 
 Accessibility: WCAG  { { level } } 

 Document:  { { file_path } } 

 Ready for developer handoff!

phase_2_planning:
  ux_design_completed: true
  ux_design_date:  { { current_date } } 
   screens_designed:  { { screen_count } } 
   accessibility_level:  { { wcag_level } } 

 last_workflow: create-ux-design
last_workflow_date:  { { current_date } }

✓ UX Design Complete!

Next Steps:

1. **Review with Product Manager**
   - Validate designs meet requirements
   - Confirm all user stories covered
   - Approve design direction

2. **Architecture Review**
   Run: /architecture
   - Architect should validate UX constraints
   - Ensure feasibility
   - Identify technical considerations

3. **Implementation Planning**
   Run: /sprint-planning
   - Break design into implementation stories
   - Prioritize screens
   - Estimate effort

4. **Begin Development**
   Run: /dev-story
   - Start with highest-priority screen
   - Implement design system tokens first
   - Build components before screens