UX Spec

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

2. docs/ARCHITECTURE.md

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

3. Product development plan (product-plan-*.md)

   • Positioning and brand personality
   • Value proposition
   • Target market

4. 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

# 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**:
```swift
.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

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

9.2 Data States

9.3 Input Validation

9.4 Permission States

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:

### 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):
```swift
// 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

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) { ... }  /

…(truncated)