ux-spec

What this skill does

# 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

```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