UX Specification Skill

Generate comprehensive UI/UX specifications with wireframes and design system for iOS/macOS apps.

Metadata

• Name: ux-spec
• Version: 1.0.0
• Role: UI/UX Designer
• Author: ProductAgent Team

When This Skill Activates

This skill activates when the user says:

• "generate UI spec"
• "create UX specification"
• "design wireframes"
• "create design system"
• "generate UX spec from PRD"

Description

You are a UI/UX Designer AI agent specializing in iOS/macOS app design. Your job is to transform product requirements and architecture into comprehensive, actionable UI/UX specifications that developers can implement directly.

Prerequisites

Before activating this skill, ensure:

1. PRD exists (from prd-generator skill)
2. ARCHITECTURE.md exists (from architecture-spec skill)
3. Product development plan with positioning and brand personality

Input Sources

Read and extract information from:

1. docs/PRD.md

• All features and requirements
• User flows and user stories
• Target audience
• Acceptance criteria

1. docs/ARCHITECTURE.md

• App structure and navigation
• Data models (to understand what to display)
• Platform (iOS/macOS)

1. Product development plan (product-plan-.md)

• Positioning and brand personality
• Value proposition
• Target market

1. User clarifications (ask if needed):

• Preferred design style (minimalist, colorful, professional, playful)
• Any brand colors or existing branding
• Key screens to prioritize

Output

Generate two comprehensive documents:

1. docs/UX_SPEC.md

markdown
# UI/UX Specification: [App Name]

**Version**: 1.0.0
**Last Updated**: [Date]
**Status**: Draft / In Review / Approved
**Designer**: UX Designer AI
**Platform**: iOS / macOS

---

## 1. Design Principles

### 1.1 Core Principles
1. **[Principle 1]**: [e.g., "Simplicity over features - Every screen should have one primary action"]
2. **[Principle 2]**: [e.g., "Glanceable information - Users should understand content in < 5 seconds"]
3. **[Principle 3]**: [e.g., "Gesture-first interaction - Leverage native iOS gestures"]
4. **[Principle 4]**: [e.g., "Progressive disclosure - Show advanced features only when needed"]

### 1.2 Brand Personality
**From Positioning**: [e.g., "Professional, trustworthy, modern with a human touch"]

**Design Expression**:
- Visual style: [Clean, minimal, lots of whitespace]
- Tone: [Friendly but professional]
- Imagery: [Photography-based vs. illustration-based]

---

## 2. Information Architecture

### 2.1 App Structure

**Navigation Pattern**: [TabView / NavigationStack / Sidebar (iPad)]

**Screen Hierarchy**:

App Root ├── Tab 1: Home] │ ├── Home Screen] │ ├── Item Detail Screen] │ └── Edit Item Screen] ├── Tab 2: Discover] │ ├── Discover Screen] │ └── Category Detail Screen] ├── Tab 3: Profile] │ ├── Profile Screen] │ └── Settings Screen] └── Shared ├── Login Screen] ├── Onboarding Flow] └── Error/Empty States]

### 2.2 Screen Inventory

| Screen Name | Purpose | Navigation | Priority |
|-------------|---------|------------|----------|
| Onboarding | First-time user education | Modal → Home | P0 |
| Home | Primary content view | Root tab | P0 |
| Item Detail | View single item details | Push from Home | P0 |
| Add/Edit Item | Create or modify item | Modal/Push | P0 |
| Profile | User profile and settings | Root tab | P1 |
| Settings | App preferences | Push from Profile | P1 |

### 2.3 Navigation Flow Diagram

Splash] → Onboarding] → Home (Tab 1)] ↓ Item Detail] ↓ Edit Item]

Profile (Tab 3)] → Settings] → Account]

---

## 3. Screen Specifications

### 3.1 Onboarding Flow

**Purpose**: Help new users understand value and complete initial setup

**Screens**: 3 screens + Welcome

#### Screen 1: Welcome

**Layout** (ASCII wireframe):

┌─────────────────────────────────────┐ │ │ │ │ │ App Icon/Logo] │ │ │ │ │ │ Welcome to AppName] │ │ │ │ One-line value proposition] │ │ │ │ │ │ │ │ Get Started Button] │ │ │ │ Already have an account? │ │ Sign In] │ │ │ └─────────────────────────────────────┘

**Components**:
- **App Icon/Logo**: Centered, large (120pt)
- **Welcome Title**: .largeTitle, bold, centered
- **Value Proposition**: .title3, secondary color, centered, max 2 lines
- **Get Started Button**: Primary button style, full width with margin
- **Sign In Link**: Text button, smaller, muted color

**Interactions**:
- Tap "Get Started" → Navigate to Onboarding Screen 1
- Tap "Sign In" → Navigate to Login Screen
- Swipe not enabled (no skip on welcome)

**States**:
- Default: All elements visible
- Loading: Show activity indicator if checking auth state

**Animations**:
- Fade in on appear (0.5s)
- Button press: Scale 0.95 with haptic feedback

---

#### Screen 2: Onboarding Step 1

**Purpose**: Explain primary feature/benefit

**Layout**:

┌─────────────────────────────────────┐ │ ○ ● ○ Skip] │ (Progress + Skip) ├─────────────────────────────────────┤ │ │ │ │ │ Feature Illustration] │ │ or Screenshot │ │ │ │ │ ├─────────────────────────────────────┤ │ │ │ Headline - Feature Name] │ │ │ │ Description - 2-3 lines │ │ explaining the benefit] │ │ │ ├─────────────────────────────────────┤ │ │ │ Next Button] │ │ │ └─────────────────────────────────────┘

**Components**:
- **Progress Indicator**: 3 dots, current = filled circle
- **Skip Button**: Text button, top-right
- **Illustration**: Hero image or screenshot, 300pt height
- **Headline**: .title2, bold, benefit-focused
- **Description**: .body, 2-3 lines, explain value not feature
- **Next Button**: Primary button, full width

**Interactions**:
- Tap "Next" → Navigate to Onboarding Step 2
- Tap "Skip" → Navigate to Home (mark onboarding complete)
- Swipe left → Next screen
- Swipe right → Previous screen

**Content Guidelines**:
- Focus on BENEFITS not features
- Use "you" language ("You can organize all your tasks")
- Keep concise (< 20 words per description)

---

#### Screen 3: Onboarding Step 2 & 3
[Repeat structure for remaining onboarding screens]

---

### 3.2 Home Screen

**Purpose**: Display primary content and enable main user actions

**Layout** (iPhone Portrait):

┌─────────────────────────────────────┐ │ ← Home +] ⚙️] │ (Navigation Bar) ├─────────────────────────────────────┤ │ │ │ Search... 🔍] │ (Search Bar) │ │ ├─────────────────────────────────────┤ │ │ │ ┌───────────────────────────────┐ │ │ │ Thumbnail] Card Title │ │ (Card Component) │ │ Subtitle • Meta │ │ │ │ Status Badge] │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Thumbnail] Card Title │ │ │ │ Subtitle • Meta │ │ │ │ Status Badge] │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Thumbnail] Card Title │ │ │ │ Subtitle • Meta │ │ │ │ Status Badge] │ │ │ └───────────────────────────────┘ │ │ │ ├─────────────────────────────────────┤ │ Tab1] Tab2] Tab3] Tab4] │ (Tab Bar) └─────────────────────────────────────┘

**Components**:

**Navigation Bar**:
- Title: "Home" (.largeTitle when scrolled to top, .inline when scrolling)
- Leading: Back button (if navigated from elsewhere)
- Trailing:
  - [+] Add button → Navigate to Add Item
  - [⚙️] Settings button → Navigate to Settings

**Search Bar** (Optional, based on requirements):
- Placeholder: "Search [items]..."
- Style: .searchable modifier
- Clear button when text entered
- Dismiss on scroll down

**Card List**:
- Container: SwiftUI List with .plain style
- Card spacing: 12pt between cards
- Card style: See "Card Component" section below

**Tab Bar** (if using tabs):
- 3-5 tabs maximum
- Active tab: Primary color
- Inactive tabs: Secondary/gray color
- Badge: Red dot for notifications (if applicable)

**Interactions**:
- **Tap card** → Navigate to Item Detail Screen
- **Swipe left on card** → Show Delete action (red background, trash icon)
- **Swipe right on card** → Show Archive action (if applicable)
- **Pull down** → Refresh content (show activity indicator)
- **Tap [+]** → Present Add Item sheet
- **Tap [⚙️]** → Navigate to Settings
- **Search** → Filter list in real-time as user types
- **Scroll to top** → Navigation bar title animates to large title

**States**:

**Empty State**:

┌─────────────────────────────────────┐ │ │ │ │ │ Empty Icon] │ │ (tray) │ │ │ │ No Items Yet │ │ │ │ Get started by tapping the │ │ + button above │ │ │ │ │ └─────────────────────────────────────┘

- Use ContentUnavailableView (iOS 17+)
- Icon: SF Symbol related to content type
- Title: Friendly, not error-focused
- Description: Clear call to action

**Loading State**:

┌─────────────────────────────────────┐ │ │ │ │ │ Loading Spinner] │ │ Loading... │ │ │ │ │ └─────────────────────────────────────┘

- Full-screen overlay with .ultraThinMaterial background
- Activity indicator (.large size)
- Optional "Loading..." text below

**Error State**:

┌─────────────────────────────────────┐ │ │ │ │ │ Error Icon] (exclamationmark) │ │ │ │ Couldn't load items │ │ │ │ Error description message] │ │ │ │ Try Again Button] │ │ │ └─────────────────────────────────────┘

- ContentUnavailableView with error styling
- Clear error message (user-friendly, not technical)
- Retry button to attempt reload

**Skeleton/Shimmer State** (Alternative to loading spinner):

┌─────────────────────────────────────┐ │ ┌───────────────────────────────┐ │ │ │ ▓▓▓] ▓▓▓▓▓▓▓▓▓▓ │ │ (Shimmer effect) │ │ ▓▓▓▓▓▓▓ • ▓▓▓ │ │ │ └───────────────────────────────┘ │ │ ┌───────────────────────────────┐ │ │ │ ▓▓▓] ▓▓▓▓▓▓▓▓▓▓ │ │ │ │ ▓▓▓▓▓▓▓ • ▓▓▓ │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────┘

- Show 3-5 placeholder cards
- Animated shimmer effect (subtle, not distracting)
- Replace with real content when loaded

**Data Requirements**:
- Array of items: [Item]
- Each item needs: id, title, subtitle, thumbnailURL, status, metadata
- Sorting: By date (newest first) or user preference
- Filtering: Based on search query

**Accessibility**:
- VoiceOver label for each card: "[Title], [Subtitle], [Status]"
- Add button: "Add new item"
- Settings button: "Settings"
- Swipe actions announced: "Swipe right or left for actions"
- Search bar: "Search [items]"

---

### 3.3 Item Detail Screen

**Purpose**: Display full details of a single item

**Layout**:

┌─────────────────────────────────────┐ │ ← Item Title] Edit] │ (Navigation Bar) ├─────────────────────────────────────┤ │ │ │ Hero Image/Thumbnail] │ │ (Full width) │ │ │ ├─────────────────────────────────────┤ │ │ │ Item Title] │ │ Subtitle or Category] │ │ │ │ Status Badge] Metadata] │ │ │ ├─────────────────────────────────────┤ │ │ │ Description │ │ ───────────── │ │ Full description text, can be │ │ multiple paragraphs. Lorem ipsum │ │ dolor sit amet...] │ │ │ ├─────────────────────────────────────┤ │ │ │ Details │ │ ──────── │ │ Created: Date] │ │ Modified: Date] │ │ Author: Name] │ │ │ ├─────────────────────────────────────┤ │ │ │ Related Items │ │ ────────────── │ │ ┌─────────┐ ┌─────────┐ │ │ │ Item1] │ │ Item2] │ │ │ └─────────┘ └─────────┘ │ │ │ ├─────────────────────────────────────┤ │ │ │ Primary Action] │ │ Secondary Action] │ │ │ └─────────────────────────────────────┘

**Components**:
- **Navigation Bar**: Item title (truncate if > 25 chars), Edit button
- **Hero Image**: Full-width, 16:9 aspect ratio, 250pt height
- **Title Section**: .title2 bold, subtitle .subheadline
- **Status Badge**: Rounded rectangle, color-coded by status
- **Description**: .body text, full paragraph formatting
- **Details Section**: Key-value pairs, .callout size, secondary color
- **Related Items**: Horizontal scroll, 100pt width cards
- **Action Buttons**: Primary (full width), Secondary (outlined)

**Interactions**:
- Tap "Edit" → Navigate to Edit Screen
- Tap Hero Image → Open full-screen image viewer (pinch to zoom)
- Tap Related Item → Navigate to that item's detail screen
- Swipe back → Return to Home
- Scroll → Navigation bar collapses to inline title

**States**:
- **Loading**: Show skeleton for all sections while data loads
- **Error**: Show error message inline (not full-screen)
- **No Image**: Show placeholder icon/gradient
- **No Description**: Hide section entirely (don't show empty)
- **No Related Items**: Hide section

---

### 3.4 Add/Edit Item Screen

**Purpose**: Create new item or modify existing

**Layout** (Sheet/Modal):

┌─────────────────────────────────────┐ │ Cancel] Add Item Save] │ (Modal Header) ├─────────────────────────────────────┤ │ │ │ ┌───────────────────────────────┐ │ │ │ + Add Photo │ │ (Image Picker) │ └───────────────────────────────┘ │ │ │ │ Title │ │ ┌───────────────────────────────┐ │ │ │ Enter title...] │ │ │ └───────────────────────────────┘ │ │ │ │ Category │ │ ┌───────────────────────────────┐ │ │ │ Select category] ▼] │ │ │ └───────────────────────────────┘ │ │ │ │ Description │ │ ┌───────────────────────────────┐ │ │ │ Enter description...] │ │ │ │ │ │ │ │ │ │ │ └───────────────────────────────┘ │ │ │ │ Status │ │ ○ Active ○ Pending ○ Done │ │ │ │ │ │ Delete Item] │ (Edit only) │ │ └─────────────────────────────────────┘

**Components**:
- **Modal Header**: Cancel (leading), Title (center), Save (trailing, blue)
- **Image Picker**: Dashed border, + icon, tap to open photo picker
- **Text Fields**: Native iOS style, floating labels
- **Dropdown**: Chevron indicator, opens picker/sheet
- **Text Area**: Multiline, min 3 lines
- **Radio Group**: Horizontal segmented control or vertical radio buttons
- **Delete Button**: Destructive style, bottom of form (edit mode only)

**Interactions**:
- Tap "Cancel" → Dismiss sheet, confirm if unsaved changes
- Tap "Save" → Validate, save, dismiss, return to previous screen
- Tap Image Picker → Present photo picker (Camera + Photo Library)
- Tap Dropdown → Present selection sheet/picker
- Typing → Show character count if there's a limit
- Tap Delete → Show destructive alert confirmation

**Validation**:
- Required fields: Show red outline + error message on save attempt
- Character limits: Show count (e.g., "120/150 characters")
- Invalid format: Show inline error below field

**States**:
- **Add Mode**: Empty fields, no Delete button
- **Edit Mode**: Pre-filled fields, Delete button visible
- **Saving**: Disable Save button, show spinner
- **Error**: Show alert with error message, keep form open

---

### 3.5 Settings Screen

**Purpose**: App preferences and account management

**Layout**:

┌─────────────────────────────────────┐ │ ← Settings │ ├─────────────────────────────────────┤ │ │ │ Account │ │ ┌───────────────────────────────┐ │ │ │ 👤] User Name] >] │ │ │ │ user@email.com │ │ │ └───────────────────────────────┘ │ │ │ │ Preferences │ │ ┌───────────────────────────────┐ │ │ │ Notifications ○●] │ │ (Toggle) │ │ Dark Mode ○●] │ │ │ │ Language >] │ │ │ └───────────────────────────────┘ │ │ │ │ Data & Privacy │ │ ┌───────────────────────────────┐ │ │ │ Privacy Policy >] │ │ │ │ Terms of Service >] │ │ │ │ Delete Account >] │ │ │ └───────────────────────────────┘ │ │ │ │ About │ │ ┌───────────────────────────────┐ │ │ │ App Version 1.0.0 │ │ │ │ Rate Us >] │ │ │ │ Contact Support >] │ │ │ └───────────────────────────────┘ │ │ │ │ │ │ Sign Out] │ │ │ └─────────────────────────────────────┘

**Components**:
- **Section Headers**: .caption uppercase, secondary color, 24pt top padding
- **Grouped List**: iOS native .insetGrouped style
- **Row**: 44pt min height, tap area full width
- **Toggle**: iOS native switch, tappable label + switch
- **Disclosure**: Chevron on trailing edge
- **Sign Out Button**: Destructive style, centered, bottom

**Interactions**:
- Tap row with [>] → Navigate to detail screen
- Tap toggle → Immediate change (save to UserDefaults/CloudKit)
- Tap "Sign Out" → Show confirmation alert

---

## 4. Component Library

### 4.1 Buttons

#### Primary Button
**Style**:
- Background: Brand Primary color
- Text: White, .headline font
- Corner radius: 12pt
- Height: 50pt
- Padding: 16pt horizontal
- Shadow: radius 4, y: 2, opacity 0.1

**States**:
- Normal: Full color
- Pressed: Opacity 0.8 + scale 0.98
- Disabled: Opacity 0.5, no interaction
- Loading: Show spinner, disable interaction

**Code Example**:

.font(.headline) .foregroundColor(.white) .frame(maxWidth: .infinity) .frame(height: 50) .background(Color.brandPrimary) .cornerRadius(12) .shadow(radius: 4, y: 2)

#### Secondary Button
**Style**:
- Background: Clear
- Border: 2pt, Brand Primary color
- Text: Brand Primary color, .headline
- Corner radius: 12pt
- Height: 50pt

**States**: Same as Primary Button

#### Text Button
**Style**:
- Background: None
- Text: Brand Primary color, .body or .callout
- No border
- Height: Auto (text height + padding)

**States**:
- Normal: Primary color
- Pressed: Opacity 0.6
- Disabled: Secondary color, no interaction

---

### 4.2 Cards

#### Standard Card
**Style**:
- Background: White (light mode) / .secondarySystemBackground (dark mode)
- Corner radius: 12pt
- Padding: 16pt
- Shadow: radius 8, y: 2, opacity 0.1
- Border: None (use shadow for elevation)

**Layout**:

┌───────────────────────────────┐ │ Thumbnail] Title │ │ (60x60pt) Subtitle │ │ Metadata │ └───────────────────────────────┘

**Spacing**:
- Thumbnail to text: 12pt
- Title to subtitle: 4pt
- Text to edge: 16pt

#### Highlighted Card
**Differences from Standard**:
- Border: 2pt, Brand Primary color
- Background: Tinted (Primary color at 5% opacity)
- Shadow: Slightly larger (radius 10)

---

### 4.3 Forms

#### Text Input
**Style**:
- Height: 50pt
- Padding: 16pt horizontal
- Background: .secondarySystemBackground
- Corner radius: 10pt
- Border: 1pt, clear (2pt primary color when focused)
- Font: .body

**States**:
- Default: Gray background, no border
- Focused: White background, blue border
- Error: Red border, red tint
- Disabled: Reduced opacity, no interaction

**With Label**:
- Label above input, .caption size, secondary color
- 8pt spacing between label and input

**With Error**:
- Error message below input, .caption size, red color
- Error icon (exclamationmark.circle) leading

---

### 4.4 Typography Styles

**Usage Guide**:
- **Large Title**: Screen titles (Home, Settings)
- **Title**: Section headers
- **Title 2**: Card titles, detail screen main heading
- **Title 3**: Subsection headers
- **Headline**: Button labels, emphasized text
- **Body**: Default text, descriptions
- **Callout**: Metadata, secondary information
- **Subheadline**: Subtitles, labels
- **Footnote**: Timestamps, hints
- **Caption**: Section headers (uppercase), disclaimers

---

## 5. Interaction Patterns

### 5.1 Gestures

| Gesture | Use Case | Feedback |
|---------|----------|----------|
| Tap | Primary action, select, open | Visual (highlight), Haptic (light) |
| Long Press | Context menu, preview | Visual (scale up), Haptic (medium) |
| Swipe Left | Delete, remove | Visual (red background), Haptic (none) |
| Swipe Right | Archive, mark done | Visual (green background), Haptic (success) |
| Pull Down | Refresh content | Visual (activity indicator), Haptic (light when triggered) |
| Pinch | Zoom image, map | Visual (scale), Haptic (none) |
| Edge Swipe | Back navigation | Visual (screen slide), Haptic (none) |

### 5.2 Animations

#### Screen Transitions
- **Push/Pop**: Native NavigationStack animation (slide from right)
- **Modal**: Sheet from bottom, 0.3s ease-in-out
- **Full Screen**: Fade in, 0.2s

#### Element Animations
- **List Item Appear**: Fade + slide up, 0.3s, staggered by 0.05s
- **Button Press**: Scale to 0.95, 0.1s
- **Toggle**: Native iOS switch animation
- **Skeleton → Content**: Fade out skeleton, fade in content, 0.2s

#### Loading States
- **Spinner**: Continuous rotation, native iOS style
- **Progress Bar**: Fill animation, 0.5s per segment
- **Shimmer**: Gradient sweep, 1.5s repeat

### 5.3 Haptic Feedback

**When to Use**:
- ✅ Button taps (light)
- ✅ Toggle switches (light)
- ✅ Pull-to-refresh triggered (medium)
- ✅ Successful action (success pattern)
- ✅ Error occurred (error pattern)
- ❌ Scrolling (no haptic)
- ❌ Text input (no haptic)
- ❌ Standard navigation (no haptic)

**Implementation**:

import CoreHaptics

// Light impact let impact = UIImpactFeedbackGenerator(style: .light) impact.impactOccurred()

// Success notification let notification = UINotificationFeedbackGenerator() notification.notificationOccurred(.success)

---

## 6. Accessibility

### 6.1 VoiceOver

**Requirements**:
- All interactive elements must have labels
- Labels should describe action, not appearance
- Images need descriptions (decorative = empty label)
- Status changes should be announced

**Examples**:
- Button: "Add new item" (not "Plus button")
- Card: "Meeting notes, Created 2 hours ago, Tap to view details"
- Image: "Profile photo of John Doe" or "" if decorative
- Toggle: "Notifications, On, Toggle switch" (system provides toggle part)

**Testing**:
- Enable VoiceOver in Simulator (Cmd+F5)
- Navigate with swipe gestures
- Verify all elements are reachable and labeled

### 6.2 Dynamic Type

**Support all text sizes**: Extra Small to Accessibility XXL

**Implementation**:

Text("Title") .font(.title) // Automatically scales .lineLimit(nil) // Allow wrapping .minimumScaleFactor(0.8) // If must fit one line

**Layout Adjustments**:
- Stack elements vertically at larger sizes
- Increase spacing proportionally
- Ensure minimum tap targets (44x44pt)

**Testing**:
- Settings → Accessibility → Display & Text Size → Larger Text
- Test at XS, default, and XXL sizes

### 6.3 Color Contrast

**WCAG AA Standards**:
- Text: 4.5:1 minimum contrast ratio
- Large text (18pt+): 3:1 minimum
- UI elements: 3:1 minimum

**Testing Tools**:
- Xcode Accessibility Inspector
- Online: WebAIM Contrast Checker
- Test in both light and dark modes

**Common Issues**:
- Light gray text on white background (increase contrast)
- Color-only indicators (add icon or label)
- Low opacity overlays (ensure text remains readable)

### 6.4 Reduced Motion

**Respect System Setting**:

@Environment(\.accessibilityReduceMotion) var reduceMotion

if reduceMotion { // Use fade instead of slide // Reduce animation duration // Remove complex animations }

**Alternatives**:
- Replace slide animations with instant transitions
- Replace complex spring animations with linear fades
- Reduce animation duration by 50%
- Keep critical animations (loading, errors)

---

## 7. Dark Mode

### 7.1 Color Adaptation

**Semantic Colors** (Automatic):
- Use system colors when possible (they adapt automatically)
- `.primary`, `.secondary` for text
- `.background`, `.secondaryBackground` for surfaces

**Custom Colors**:
- Define in Assets.xcassets with Appearances: "Any, Dark"
- Provide separate values for each mode
- Test all screens in both modes

### 7.2 Image Adaptation

**Techniques**:
- Template images (tint to match color scheme)
- Separate dark mode assets (image_name~dark.png)
- Reduce opacity of photos in dark mode (optional)

### 7.3 Dark Mode Best Practices

**Do**:
- Use true black (#000000) sparingly (only for OLED optimization)
- Use elevated surfaces (lighter) for cards/modals
- Maintain visual hierarchy (contrast between levels)
- Test with "Increase Contrast" enabled

**Don't**:
- Don't invert light mode colors (design separately)
- Don't use pure white text (#FFFFFF) - use slightly off-white
- Don't forget shadows (they disappear on dark backgrounds)

---

## 8. Responsive Design

### 8.1 iPhone Sizes

**Layouts to Support**:
- **iPhone SE (3rd gen)**: 375pt width (smallest)
- **iPhone 15**: 393pt width
- **iPhone 15 Pro Max**: 430pt width (largest)

**Adaptation Strategy**:
- Use flexible layouts (HStack, VStack, Grid)
- Set minimum widths, allow expansion
- Test safe area insets (notch, Dynamic Island)

### 8.2 iPad (Optional)

**Layout Changes**:
- Sidebar navigation instead of tabs
- Multi-column layouts (master-detail)
- Larger cards (2-3 columns in grid)
- Utilize horizontal space

**Keyboard Support**:
- Cmd+N: New item
- Cmd+F: Focus search
- Cmd+S: Save
- Cmd+W: Close modal

### 8.3 Orientation

**Portrait**: Default, all screens optimized
**Landscape**:
- iPhone: Optional (usually lock to portrait)
- iPad: Required, adjust layout

---

## 9. Edge Cases & Error Handling

### 9.1 Network States

| State | User Experience | System Behavior |
|-------|-----------------|-----------------|
| No connection | "No internet connection. Showing saved data." banner at top | Use cached data, disable sync, queue changes |
| Slow connection | Loading indicator, timeout after 30s | Show skeleton screens, async load images |
| Connection restored | "Back online" banner (auto-dismiss 3s) | Trigger sync, upload queued changes |

### 9.2 Data States

| State | User Experience | System Behavior |
|-------|-----------------|-----------------|
| Empty list | ContentUnavailableView with CTA | Hide list, show empty state |
| Single item | Show list with one item (not special case) | Same as multiple items |
| Thousands of items | Paginated, lazy loading, search encouraged | Load 50 at a time, virtual scrolling |

### 9.3 Input Validation

| Invalid Input | User Experience | Prevention |
|---------------|-----------------|------------|
| Empty required field | Red outline, "This field is required" below | Disable Save button |
| Invalid email | "Please enter a valid email" | Real-time validation |
| Duplicate entry | Alert: "Item already exists. Continue?" | Check on save, allow override |

### 9.4 Permission States

| Permission | Denied | Granted |
|------------|--------|---------|
| Camera | Show alert: "Camera access needed. Open Settings?" | Open camera picker |
| Photos | Show placeholder, "Tap to allow photo access" | Open photo picker |
| Notifications | App works without, show banner once | Send notifications |
| Location | Feature disabled, show upgrade message | Show map with location |

---

## 10. Platform-Specific Considerations

### 10.1 iOS Human Interface Guidelines

**Follow These Patterns**:
- Navigation: Use NavigationStack, not custom
- Tabs: Max 5 tabs, use "More" tab if needed
- Modals: Sheet for forms, fullScreenCover for immersive
- Lists: Use native List with proper row heights (44pt min)
- Search: Use .searchable modifier
- Pull-to-refresh: Use .refreshable modifier
- Context menus: Long press for actions

**Avoid**:
- Custom navigation that doesn't follow back button patterns
- Non-standard gestures (users expect iOS conventions)
- Hamburger menus (use tabs or sidebar on iPad)
- Bottom sheets (use native sheets from bottom)

### 10.2 iOS 17+ Features to Leverage

**Adopt New APIs**:
- ContentUnavailableView for empty states
- @Observable for view models (instead of ObservableObject)
- SwiftData for persistence (instead of Core Data)
- #Preview macros (instead of PreviewProvider)
- Sensory feedback API (instead of UIImpactFeedbackGenerator)

**Test on iOS 17+**: Set minimum deployment target to iOS 17.0

---

## 11. Design Handoff Checklist

Before considering UX spec complete:

- [ ] All screens from PRD are designed with wireframes
- [ ] Empty, loading, and error states defined for all screens
- [ ] All interactive elements specified (tap, swipe, long press)
- [ ] Navigation flow is clear and consistent
- [ ] Component library covers all UI elements used
- [ ] Accessibility requirements documented (VoiceOver, Dynamic Type)
- [ ] Dark mode adaptations specified
- [ ] Responsive behavior defined (iPhone sizes)
- [ ] Edge cases and error scenarios handled
- [ ] Animation and haptic feedback specified
- [ ] Colors, typography, spacing all reference design system
- [ ] No placeholder or "TBD" items remain

---

## Appendix A: Screen Specifications Template

Use this template for additional screens not detailed above:

X.X Screen Name]

Purpose: One sentence describing what user accomplishes]

Layout (ASCII wireframe):

┌─────────────────────────────────────┐
│  [Navigation Bar]                   │
├─────────────────────────────────────┤
│                                     │
│  [Main Content Area]                │
│                                     │
├─────────────────────────────────────┤
│  [Bottom Bar / Actions]             │
└─────────────────────────────────────┘

Components:

• Component 1]: Description]
• Component 2]: Description]

Interactions:

• Tap Element] → Result]
• Swipe Direction] → Action]

States:

• Empty: How it looks]
• Loading: How it looks]
• Error: How it looks]

Data Requirements:

• Data needed from backend/storage]

Accessibility:

• VoiceOver labels]
• Special considerations]

---

**Document History**:
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0.0 | [Date] | UX Designer AI | Initial UX specification |

2. docs/DESIGN_SYSTEM.md

markdown
# Design System: [App Name]

**Version**: 1.0.0
**Last Updated**: [Date]
**Platform**: iOS 17+
**Language**: SwiftUI

---

## 1. Brand Identity

### 1.1 Brand Personality
**From Positioning**: [e.g., "Professional, trustworthy, modern with a human touch"]

**Visual Expression**:
- **Modern**: Clean lines, generous whitespace, sans-serif typography
- **Professional**: Muted color palette, consistent spacing, subtle animations
- **Approachable**: Friendly copy, helpful empty states, forgiving errors

### 1.2 Voice & Tone

**Voice** (Consistent):
- Clear and concise
- Helpful, not bossy
- Human, not robotic
- Confident, not arrogant

**Tone** (Context-dependent):
- **Success**: Encouraging ("Great job!")
- **Error**: Apologetic and helpful ("Oops! Let's try that again.")
- **Onboarding**: Excited and welcoming ("Welcome! Let's get started.")
- **Empty state**: Optimistic ("Ready to create your first item?")

---

## 2. Color Palette

### 2.1 Primary Colors

**Brand Primary** (Main CTA, key actions):

// Light mode static let brandPrimary = Color(hex: "#007AFF") // iOS Blue

// Dark mode static let brandPrimaryDark = Color(hex: "#0A84FF") // Lighter blue

**Brand Secondary** (Accents, highlights):

// Light mode static let brandSecondary = Color(hex: "#5856D6") // Purple

// Dark mode static let brandSecondaryDark = Color(hex: "#5E5CE6")

**Brand Accent** (Destructive actions, warnings):

// Light mode static let brandAccent = Color(hex: "#FF3B30") // Red

// Dark mode static let brandAccentDark = Color(hex: "#FF453A")

### 2.2 Semantic Colors

**Success** (Confirmation, completion):

static let success = Color(hex: "#34C759") // Green

**Warning** (Caution, attention needed):

static let warning = Color(hex: "#FF9500") // Orange

**Error** (Errors, destructive actions):

static let error = Color(hex: "#FF3B30") // Red (same as accent)

**Info** (Tips, information):

static let info = Color(hex: "#007AFF") // Blue (same as primary)

### 2.3 Neutral Colors

**Backgrounds**:

// Light mode static let background = Color.white static let secondaryBackground = Color(hex: "#F2F2F7") // iOS gray static let tertiaryBackground = Color(hex: "#FFFFFF")

// Dark mode static let backgroundDark = Color(hex: "#000000") static let secondaryBackgroundDark = Color(hex: "#1C1C1E") static let tertiaryBackgroundDark = Color(hex: "#2C2C2E")

**Text**:

// Light mode static let textPrimary = Color(hex: "#000000") static let textSecondary = Color(hex: "#3C3C43", opacity: 0.6) // iOS secondary label static let textTertiary = Color(hex: "#3C3C43", opacity: 0.3)

// Dark mode static let textPrimaryDark = Color(hex: "#FFFFFF") static let textSecondaryDark = Color(hex: "#EBEBF5", opacity: 0.6) static let textTertiaryDark = Color(hex: "#EBEBF5", opacity: 0.3)

**Borders & Dividers**:

static let separator = Color(hex: "#3C3C43", opacity: 0.36) static let border = Color(hex: "#C7C7CC")

### 2.4 Usage Guidelines

**Primary Color**:
- Primary CTAs (Save, Submit, Continue)
- Active tab bar items
- Selected state
- Links

**Secondary Color**:
- Secondary actions
- Highlights
- Badges (non-critical)

**Accent Color**:
- Delete buttons
- Error states
- Critical alerts

**Backgrounds**:
- background: Screen background
- secondaryBackground: Card backgrounds, input fields
- tertiaryBackground: Nested cards, elevated surfaces

---

## 3. Typography

### 3.1 Type Scale

**iOS Dynamic Type** (Automatically scales with user preference):

// Display .largeTitle // 34pt, Bold - Screen titles .title // 28pt, Bold - Major sections .title2 // 22pt, Bold - Subsections, cards .title3 // 20pt, Semibold - Groups

// Body .headline // 17pt, Semibold - Emphasized text, button labels .body // 17pt, Regular - Default body text .callout // 16pt, Regular - Secondary content

// Supporting .subheadline // 15pt, Regular - Subtitles, labels .footnote // 13pt, Regular - Timestamps, metadata .caption // 12pt, Regular - Section headers (uppercase) .caption2 // 11pt, Regular - Fine print

### 3.2 Font Family

**Default**: System Font (SF Pro)
- No custom fonts needed (SF Pro is optimized for iOS)
- If custom font required: Choose legible, web-safe fallback

### 3.3 Font Weights

.ultraLight // Avoid, too thin .thin // Avoid .light // Occasional use .regular // Default for body text .medium // Occasional emphasis .semibold // Headings, emphasized text .bold // Titles, important actions .heavy // Avoid, too thick .black // Avoid

### 3.4 Line Height & Spacing

**Default**: SwiftUI handles automatically
**Custom** (if needed):

.lineSpacing(4) // Add 4pt between lines (for dense text)

**Paragraph Spacing**: 12pt between paragraphs

### 3.5 Usage Guidelines

| Element | Style | Use Case |
|---------|-------|----------|
| Screen Title | .largeTitle | Home, Settings navigation bar |
| Section Header | .title2 | "Recent Items", "Profile" |
| Card Title | .headline | Item name in list |
| Body Text | .body | Descriptions, paragraphs |
| Metadata | .footnote | Timestamps, "Created 2h ago" |
| Button Label | .headline | All buttons |
| Input Label | .caption | Above text fields |
| Placeholder | .body + opacity 0.5 | Text field placeholder |

---

## 4. Spacing System

### 4.1 Spacing Scale

**Base Unit**: 4pt

enum Spacing { static let xxs: CGFloat = 2 // Tight spacing (icon to text) static let xs: CGFloat = 4 // Very small (between related elements) static let s: CGFloat = 8 // Small (list item internal padding) static let m: CGFloat = 12 // Medium (between components) static let l: CGFloat = 16 // Large (card padding, margins) ⭐ Default static let xl: CGFloat = 24 // Extra large (section spacing) static let xxl: CGFloat = 32 // Screen margins, major sections static let xxxl: CGFloat = 48 // Between major screen areas }

### 4.2 Usage Guidelines

**Padding** (Inside components):
- Cards: 16pt all sides
- Buttons: 16pt horizontal, 12pt vertical
- Text fields: 16pt horizontal, 12pt vertical
- List rows: 16pt horizontal, 8pt vertical

**Margins** (Between components):
- List items: 8pt vertical
- Sections: 24pt vertical
- Screen edges: 16pt horizontal

**Stack Spacing**:

VStack(spacing: 12) { ... } // Default HStack(spacing: 8) { ... } // Tight VStack(spacing: 24) { ... } // Loose

---

## 5. Layout Grid

### 5.1 Grid System

**Columns**: 12-column grid (flexible)
**Gutter**: 16pt between columns
**Margins**: 16pt (iPhone), 20pt (iPad)

**Usage**:
- Single column: Full width (12/12)
- Two columns: 6/12 each (rare on iPhone)
- Three columns: 4/12 each (iPad only)

### 5.2 Breakpoints

| Device | Width (pt) | Columns | Margins |
|--------|-----------|---------|---------|
| iPhone SE | 375 | 1 | 16pt |
| iPhone 15 | 393 | 1 | 16pt |
| iPhone Pro Max | 430 | 1 | 16pt |
| iPad Portrait | 768 | 2 | 20pt |
| iPad Landscape | 1024 | 3 | 20pt |

---

## 6. Iconography

### 6.1 Icon Set

**Primary**: SF Symbols (native, 4000+ icons)
**Custom**: Only if SF Symbols doesn't have the icon

### 6.2 Icon Sizes

.small // 16x16pt - Inline with text .medium // 20x20pt - Default .large // 24x24pt - Emphasized .xlarge // 28x28pt - Hero icons

### 6.3 Icon Weights

**Match text weight**:
- Body text (.regular) → .regular weight icon
- Headline (.semibold) → .semibold weight icon
- Title (.bold) → .bold weight icon

Image(systemName: "star.fill") .font(.title2) // Size .fontWeight(.semibold) // Weight

### 6.4 Icon Colors

**Default**: Match text color
**Tinted**: Brand primary for active/selected
**Multicolor**: SF Symbols multicolor variant (sparingly)

### 6.5 Common Icons

| Use Case | SF Symbol | Alternative |
|----------|-----------|-------------|
| Add | plus | plus.circle.fill |
| Delete | trash | trash.fill |
| Edit | pencil | pencil.circle |
| Search | magnifyingglass | - |
| Settings | gearshape | gearshape.fill |
| Profile | person | person.circle |
| Home | house | house.fill |
| Favorites | star | star.fill |
| Share | square.and.arrow.up | - |
| Close | xmark | xmark.circle.fill |
| Back | chevron.left | arrow.left |
| Success | checkmark.circle.fill | - |
| Error | xmark.circle.fill | exclamationmark.triangle.fill |
| Warning | exclamationmark.triangle | - |
| Info | info.circle | questionmark.circle |

---

## 7. Shadows & Elevation

### 7.1 Shadow Levels

**Level 1** (Cards, subtle elevation):

.shadow(color: .black.opacity(0.1), radius: 8, y: 2)

**Level 2** (Modals, popovers):

.shadow(color: .black.opacity(0.15), radius: 16, y: 4)

**Level 3** (Dropdowns, tooltips):

.shadow(color: .black.opacity(0.2), radius: 24, y: 8)

### 7.2 Usage Guidelines

**When to Use Shadows**:
- Cards on plain background (differentiation)
- Floating action buttons
- Modals and sheets
- Popovers and dropdowns

**When NOT to Use**:
- Dark mode (use borders or different background colors)
- List items (use dividers instead)
- Flat design (intentionally no elevation)

### 7.3 Dark Mode Adaptation

**Replace shadows with borders**:

if colorScheme == .dark { .border(Color.white.opacity(0.1), width: 1) } else { .shadow(radius: 8, y: 2) }

---

## 8. Corner Radius

### 8.1 Radius Scale

enum CornerRadius { static let xs: CGFloat = 4 // Very subtle (badges) static let s: CGFloat = 8 // Small (buttons, inputs) static let m: CGFloat = 12 // Medium (cards) ⭐ Default static let l: CGFloat = 16 // Large (modals, sheets) static let xl: CGFloat = 24 // Extra large (hero cards) static let full: CGFloat = 9999 // Fully rounded (pills, avatars) }

### 8.2 Usage Guidelines

| Element | Radius | Rationale |
|---------|--------|-----------|
| Buttons | 12pt | iOS standard, comfortable |
| Text inputs | 10pt | Slightly less than buttons (visual distinction) |
| Cards | 12pt | Consistent with buttons |
| Modals/Sheets | 16pt | Larger surface, more prominence |
| Badges | 8pt or full | Depends on style (rounded or pill) |
| Avatars | full | Circular |
| Thumbnails | 8pt | Subtle rounding |

---

## 9. Animation & Motion

### 9.1 Animation Timings

enum AnimationDuration { static let fast: Double = 0.2 // Button press, toggle static let standard: Double = 0.3 // Screen transition, fade ⭐ Default static let slow: Double = 0.5 // Complex animations static let verySlow: Double = 1.0 // Onboarding, celebration }

### 9.2 Easing Curves

**Default**: `.easeInOut` (most natural)

.animation(.easeInOut(duration: 0.3), value: someValue)

**Spring**: For playful, bouncy effects

.animation(.spring(response: 0.3, dampingFraction: 0.7), value: someValue)

**Linear**: For progress bars, loaders

.animation(.linear(duration: 2.0), value: progress)

### 9.3 Common Animations

**Fade In/Out**:

.opacity(isVisible ? 1 : 0) .animation(.easeInOut(duration: 0.3), value: isVisible)

**Slide In**:

.offset(y: isVisible ? 0 : 50) .opacity(isVisible ? 1 : 0) .animation(.easeOut(duration: 0.4), value: isVisible)

**Scale (Button Press)**:

.scaleEffect(isPressed ? 0.95 : 1.0) .animation(.easeInOut(duration: 0.1), value: isPressed)

**Rotation**:

.rotationEffect(.degrees(isLoading ? 360 : 0)) .animation(.linear(duration: 1.0).repeatForever(autoreverses: false), value: isLoading)

### 9.4 Reduced Motion

**Respect accessibility setting**:

@Environment(\.accessibilityReduceMotion) var reduceMotion

if reduceMotion { // Use fade instead of slide .opacity(isVisible ? 1 : 0) } else { // Use full animation .offset(y: isVisible ? 0 : 50) .opacity(isVisible ? 1 : 0) }

---

## 10. Component Styles (SwiftUI Code)

### 10.1 Button Styles

struct PrimaryButtonStyle: ButtonStyle { func makeBody(configuration: Configuration) -> some View { configuration.label .font(.headline) .foregroundColor(.white) .frame(maxWidth: .infinity) .frame(height: 50) .background(Color.brandPrimary) .cornerRadius(12) .scaleEffect(configuration.isPressed ? 0.98 : 1.0) .animation(.easeInOut(duration: 0.1), value: configuration.isPressed) } }

// Usage: Button("Continue") { } .buttonStyle(PrimaryButtonStyle())

### 10.2 Card Modifier

extension View { func cardStyle() -> some View { self .padding(16) .background(Color(.secondarySystemBackground)) .cornerRadius(12) .shadow(color: .black.opacity(0.1), radius: 8, y: 2) } }

// Usage: VStack { ... } .cardStyle()

### 10.3 Text Field Style

struct CustomTextFieldStyle: TextFieldStyle { func _body(configuration: TextField<Self._Label>) -> some View { configuration .padding(16) .background(Color(.secondarySystemBackground)) .cornerRadius(10) .overlay( RoundedRectangle(cornerRadius: 10) .stroke(Color.brandPrimary.opacity(0.3), lineWidth: 1) ) } }

// Usage: TextField("Enter name", text: $name) .textFieldStyle(CustomTextFieldStyle())

---

## 11. Assets Organization

### 11.1 Color Assets

**Location**: `Assets.xcassets/Colors/`

**Naming Convention**:
- `BrandPrimary` (with Light + Dark appearances)
- `BrandSecondary`
- `TextPrimary`
- `BackgroundSecondary`

### 11.2 Image Assets

**Location**: `Assets.xcassets/Images/`

**Naming Convention**:
- `icon-name` (lowercase, hyphen-separated)
- `illustration-onboarding-1`
- `placeholder-avatar`

**Formats**:
- Icons: PDF (vector) or PNG @2x, @3x
- Photos: PNG or JPEG @2x, @3x
- Illustrations: PDF (preferred) or PNG

### 11.3 SF Symbols

**No need to add to assets** - use directly by name:

Image(systemName: "star.fill")

---

## 12. Design Tokens (Reference)

For developers: centralized constants file

// DesignTokens.swift

import SwiftUI

enum DesignSystem { // Colors enum Colors { static let brandPrimary = Color("BrandPrimary") static let brandSecondary = Color("BrandSecondary") static let textPrimary = Color.primary static let textSecondary = Color.secondary static let success = Color.green static let error = Color.red static let warning = Color.orange }

// Typography enum Typography { static let largeTitle = Font.largeTitle static let title = Font.title static let headline = Font.headline static let body = Font.body static let caption = Font.caption }

// Spacing enum Spacing { static let xs: CGFloat = 4 static let s: CGFloat = 8 static let m: CGFloat = 12 static let l: CGFloat = 16 static let xl: CGFloat = 24 static let xxl: CGFloat = 32 }

// Corner Radius enum Radius { static let small: CGFloat = 8 static let medium: CGFloat = 12 static let large: CGFloat = 16 static let full: CGFloat = 9999 }

// Shadows enum Shadow { static let card = (color: Color.black.opacity(0.1), radius: CGFloat(8), y: CGFloat(2)) static let modal = (color: Color.black.opacity(0.15), radius: CGFloat(16), y: CGFloat(4)) }

// Animation enum Animation { static let fast = 0.2 static let standard = 0.3 static let slow = 0.5 } }

// Usage: Text("Hello") .font(DesignSystem.Typography.headline) .foregroundColor(DesignSystem.Colors.brandPrimary) .padding(DesignSystem.Spacing.l)

---

## 13. Implementation Checklist

Before considering design system complete:

- [ ] All colors defined in Assets.xcassets with Dark mode variants
- [ ] Typography scale documented and tested at multiple sizes
- [ ] Spacing scale applied consistently across all screens
- [ ] Corner radius values standardized
- [ ] Shadow styles defined for different elevation levels
- [ ] Icon library documented (SF Symbols references)
- [ ] Animation timings and easing curves specified
- [ ] Component styles implemented as reusable SwiftUI modifiers
- [ ] Design tokens file created for developer reference
- [ ] Dark mode tested for all colors and components
- [ ] Accessibility: Dynamic Type, VoiceOver, Contrast verified
- [ ] Responsive behavior tested on all iPhone sizes

---

**Document History**:
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0.0 | [Date] | UX Designer AI | Initial design system |

Execution Instructions

When activated, follow these steps:

1. Locate and Read Input Documents

• Read docs/PRD.md (all features and user flows)
• Read docs/ARCHITECTURE.md (app structure, data models)
• Read product-plan-.md (positioning, brand personality)

If any missing, ask user for file path

1. Extract Key Information

From inputs, extract:

• All screens needed (from PRD features)
• Navigation structure (from architecture)
• Brand personality (from positioning)
• Core features to design (from PRD MVP scope)
• Platform (iOS/macOS)

1. Design Information Architecture

• List all screens
• Determine navigation pattern (tabs, stack, sidebar)
• Create navigation flow diagram
• Prioritize screens (P0, P1, P2)

1. Create Wireframes for Core Screens

For each P0 screen:

• Draw ASCII wireframe (clear layout)
• Specify all components
• Document all interactions
• Define states (empty, loading, error)
• List data requirements

1. Define Design System

Based on brand personality:

• Choose color palette (align with positioning)
• Define typography scale (iOS standard)
• Set spacing system (8pt grid)
• Specify component styles (buttons, cards, inputs)
• Document animation timings

1. Generate Output Files

Write comprehensive UX_SPEC.md to: docs/UX_SPEC.md Write complete DESIGN_SYSTEM.md to: docs/DESIGN_SYSTEM.md

1. Present to User

After generating files, present summary:

✅ UI/UX Specifications generated!

📱 UX_SPEC.md Summary:

• Screens designed: X] screens with wireframes
• User flows documented: Y] flows
• Interaction patterns: Defined for all screens
• Accessibility: VoiceOver labels, Dynamic Type, contrast ratios

🎨 DESIGN_SYSTEM.md Summary:

• Color palette: X] colors (light + dark mode)
• Typography: iOS Dynamic Type scale
• Component library: Y] reusable components
• Animation guidelines: Timings and easing curves

Next Steps:

1. Review the wireframes in docs/UX_SPEC.md
2. Check the design system in docs/DESIGN_SYSTEM.md
3. Provide feedback on any screens or components
4. Once approved, we can proceed to implementation guide

Would you like me to make any changes to the UI design?

1. Iterate Based on Feedback

If user requests changes:

• Ask clarifying questions
• Update UX_SPEC.md and/or DESIGN_SYSTEM.md
• Maintain consistency across both documents

Quality Guidelines

When generating the UX specifications:

1. Be Visual: ASCII wireframes should be clear and detailed

• BAD: Just describe "A list of items"
• GOOD: Draw the actual layout with boxes, labels, and spacing

1. Be Specific: Every interaction should be defined

• BAD: "User can tap the button"
• GOOD: "Tap 'Save' button → Validate fields → Show loading spinner → Dismiss sheet → Return to Home with success toast"

1. Be Complete: Cover all states

• Happy path (default)
• Empty state (no data)
• Loading state (data fetching)
• Error state (failed to load)
• Skeleton/placeholder (progressive loading)

1. Follow iOS HIG: Use native patterns

• NavigationStack for hierarchical navigation
• TabView for flat navigation
• Sheet for forms/modals
• List for collections
• SwiftUI standard components

1. Design for Accessibility: Not an afterthought

• VoiceOver labels for every element
• Dynamic Type support
• Color contrast 4.5:1 minimum
• Reduced motion alternatives

1. Be Consistent: Reference design system

• Use defined colors (don't introduce new ones)
• Use spacing scale (not random values)
• Use typography scale (not arbitrary sizes)
• Reuse components (don't create one-offs)

Example Activation

User: "Generate UX spec from PRD"

You:

1. Read docs/PRD.md
2. Read docs/ARCHITECTURE.md
3. Read product-plan-.md for positioning
4. Extract all features needing screens
5. Design wireframes for each screen (ASCII art)
6. Create comprehensive design system
7. Write both documents to docs/
8. Present summary with next steps

Integration with Workflow

This skill is typically:

• Third step in specification generation
• Activated after PRD and Architecture are complete
• Followed by implementation-guide, test-spec, release-spec

The UX specifications serve as the visual blueprint that developers use to implement the UI.

Notes

• Focus on iOS patterns - don't reinvent the wheel
• ASCII wireframes are sufficient - no need for high-fidelity mockups
• Provide enough detail that a developer can implement without guessing
• Reference Apple's Human Interface Guidelines throughout
• Ensure all specifications are actionable and unambiguous
• Keep design system tokens consistent across both documents
• Test all designs mentally for accessibility before documenting