# null

# iOS Component Library: AI-Powered Photo Journaling App

**Date**: 2025-11-10
**Version**: 1.0
**Author**: UX Designer
**Status**: Approved for UI Design
**Platform**: iOS 15+ (Native Swift/SwiftUI)

***

## Overview

This design system defines all reusable UI components for the AI-powered photo journaling iOS app. Each component includes specifications for all states, variants, anatomy, spacing, typography, colors, and accessibility requirements.

**Component Organization**:

1. **Navigation Components** - Tab bar, navigation bar, search bar
2. **Input Components** - Text fields, photo picker, camera, emotion selector
3. **Action Components** - Buttons, FAB, action sheets
4. **Content Components** - Photo cards, entry cards, loading/error/empty states
5. **Feedback Components** - Toasts, alerts, progress indicators
6. **Data Display** - Timeline grid, tags, labels, metadata
7. **Onboarding Components** - Welcome screens, permission requests
8. **Premium Components** - Paywall, subscription UI

***

## 1. Navigation Components

### 1.1 Tab Bar (Bottom Navigation)

**Purpose**: Primary navigation between main app sections

**Variants**:

* Standard (5 tabs max, iOS convention)

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  [Home]  [Search]  [+]  [Profile]        │ ← Tab Bar (49pt height)
└──────────────────────────────────────────┘
```

**Tabs**:

1. **Timeline** (Home)
   * Icon: house.fill
   * Label: "Timeline"

2. **Search**
   * Icon: magnifyingglass
   * Label: "Search"

3. **Create Entry** (Center, emphasized)
   * Icon: plus.circle.fill (larger, 32pt)
   * Label: None (icon-only)
   * Color: Primary Coral

4. **Profile**
   * Icon: person.circle.fill
   * Label: "Profile"

**Spacing**:

* Height: 49pt (iOS standard)
* Safe Area Inset: Respects home indicator
* Icon size: 24x24pt (standard), 32x32pt (center)
* Padding: 8pt top, 4pt bottom

**Typography**:

* Font: Caption 2 (11pt regular)
* Color: Secondary Gray (unselected), Primary Coral (selected)

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Divider: 0.5pt Light Gray (top border)
* Selected: Primary Coral
* Unselected: Secondary Gray

**States**:

* Default: Gray icon + label
* Selected: Coral icon + label, bold font
* Pressed: Scale 0.95 (0.1s animation)

**Accessibility**:

* ARIA role: tab, tablist
* VoiceOver: "Timeline, tab, 1 of 4, selected"
* Keyboard: Tab navigation, Enter to select
* Minimum touch target: 44x44pt per tab

**Usage Guidelines**:

* Always visible (sticky bottom navigation)
* Maximum 5 tabs (iOS convention)
* Center tab for primary action (Create Entry)
* Use icons + labels for clarity

***

### 1.2 Navigation Bar (Top Bar)

**Purpose**: Page titles, back navigation, contextual actions

**Variants**:

* Standard: Title only
* Large Title: Scrollable large title (iOS 11+)
* With Actions: Title + trailing buttons

**Anatomy** (Standard):

```
┌──────────────────────────────────────────┐
│  ← Back    Timeline          [Search]    │ ← 44pt height
└──────────────────────────────────────────┘
```

**Anatomy** (Large Title):

```
┌──────────────────────────────────────────┐
│  Timeline                      [Search]   │ ← 96pt height (expanded)
│                                           │
│  (Collapses to 44pt on scroll)           │
└──────────────────────────────────────────┘
```

**Elements**:

1. **Back Button** (leading):
   * Icon: chevron.left
   * Text: Previous screen title (truncated)
   * Color: Primary Coral

2. **Title** (center):
   * Font: Headline (17pt semibold) or Large Title (34pt bold)
   * Color: Charcoal (Light), Off-White (Dark)

3. **Actions** (trailing):
   * Icons: 24x24pt (search, filter, more)
   * Max 2-3 icons

**Spacing**:

* Height: 44pt (standard), 96pt (large title expanded)
* Horizontal padding: 16pt
* Safe Area Inset: Respects status bar

**Colors**:

* Background: Transparent (scrolls with content)
* Blur: iOS native blur effect (when scrolling)

**States**:

* Expanded: Large title visible
* Collapsed: Standard title visible (scroll-triggered)

**Accessibility**:

* VoiceOver: "Back to \[Previous Screen]", "Timeline, heading"
* Keyboard: Tab to navigate actions

***

### 1.3 Search Bar

**Purpose**: Keyword search for journal entries

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  🔍  Search your memories...      [×]    │ ← 44pt height
└──────────────────────────────────────────┘
```

**Elements**:

* Search Icon: magnifyingglass (leading, 20x20pt)
* Text Field: "Search your memories..."
* Clear Button: xmark.circle.fill (trailing, appears when typing)

**Spacing**:

* Height: 44pt
* Padding: 12pt horizontal, 8pt vertical
* Border Radius: 12pt

**Typography**:

* Font: Body (17pt regular)
* Placeholder: Secondary Gray
* Input Text: Charcoal (Light), Off-White (Dark)

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Border: None (uses background color)
* Focus: 2pt Primary Coral border

**States**:

* Default: Placeholder visible
* Active: Keyboard open, cursor blinking
* Typing: Clear button visible
* Results: Autocomplete suggestions (future)

**Accessibility**:

* VoiceOver: "Search your memories, search field"
* Keyboard: Auto-focus when tapped
* Clear button: "Clear search text"

**Usage Guidelines**:

* Debounce search: 300ms delay after typing stops
* Show results in real-time
* Highlight matching keywords in results

***

## 2. Input Components

### 2.1 Text Field (Journal Entry)

**Purpose**: Multi-line text entry for journal content

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  What do you want to remember about      │
│  this moment?                             │
│                                           │
│  [User types here...]                    │
│                                           │
│                                           │
│                              450 / 500 ◄─ Character count
└──────────────────────────────────────────┘
```

**Spacing**:

* Min Height: 120pt (3 lines of text)
* Max Height: Unlimited (scrollable)
* Padding: 16pt horizontal, 12pt vertical
* Border Radius: 12pt

**Typography**:

* Font: Body (17pt regular)
* Line Height: 22pt
* Placeholder: Secondary Gray
* Input Text: Charcoal (Light), Off-White (Dark)

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Border: 1pt Light Gray
* Focus: 2pt Primary Coral border
* Error: 2pt Error Red border

**States**:

* Default: Placeholder visible
* Focus: Keyboard open, cursor blinking
* Typing: Character count visible at 450+ chars (free tier)
* Error: Red border + error message below
* Disabled: 40% opacity, no interaction

**Character Limits**:

* Free Tier: 500 characters per entry
* Premium: Unlimited
* Show count at: 450 characters (90% of limit)

**Accessibility**:

* VoiceOver: "Journal entry, text area"
* Keyboard: Auto-capitalization, spell check enabled
* Dynamic Type: Respects user font size settings

**Usage Guidelines**:

* Auto-save draft every 10 seconds
* Preserve text on app backgrounding
* Show character count at 90% of limit
* Allow line breaks (Enter key)

***

### 2.2 Camera Capture

**Purpose**: In-app photo capture for journal entries

**Anatomy** (Camera View):

```
┌──────────────────────────────────────────┐
│                                     [×]   │ ← Close button
│                                           │
│                                           │
│          [Live Camera Feed]               │
│                                           │
│                                           │
│                                           │
│  [Flash] [Flip]     ⚪      [Gallery]    │ ← Controls
└──────────────────────────────────────────┘
```

**Elements**:

1. **Camera Preview**: Full-screen live feed
2. **Close Button**: xmark (top-left)
3. **Flash Control**: bolt.fill (bottom-left)
4. **Flip Camera**: arrow\.triangle.2.circlepath (bottom-left)
5. **Capture Button**: Large circle (center-bottom, 70x70pt)
6. **Gallery Button**: photo.on.rectangle (bottom-right)

**Spacing**:

* Full-screen: Safe Area respected
* Capture Button: 70x70pt, 16pt from bottom
* Control Icons: 44x44pt touch targets

**Colors**:

* Background: Black (camera feed)
* Capture Button: White with Primary Coral ring
* Control Icons: White with 50% black background blur

**States**:

* Default: Camera active, controls visible
* Capturing: Capture button animates (scale + flash)
* Review: Photo captured, "Use Photo" or "Retake" buttons

**Animations**:

* Capture: White flash (0.1s), scale capture button (0.2s)
* Flip Camera: Rotate animation (0.3s)

**Accessibility**:

* VoiceOver: "Capture photo, button"
* Alternative: "Choose from Library" for users who can't use camera
* Permission: Request camera access with clear explanation

**Usage Guidelines**:

* Request permissions on first use
* Show permission denied state with "Open Settings" button
* Support front and rear cameras
* Basic flash control (auto, on, off)

***

### 2.3 Photo Picker (Library)

**Purpose**: Select existing photos from device library

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  Photos                            Cancel │ ← Navigation bar
├──────────────────────────────────────────┤
│  ┌────┐ ┌────┐ ┌────┐ ┌────┐           │
│  │    │ │    │ │    │ │    │           │ ← Photo grid
│  └────┘ └────┘ └────┘ └────┘           │
│  ┌────┐ ┌────┐ ┌────┐ ┌────┐           │
│  │    │ │    │ │    │ │    │           │
│  └────┘ └────┘ └────┘ └────┘           │
└──────────────────────────────────────────┘
```

**Implementation**:

* Use **PHPickerViewController** (iOS 14+)
* Single photo selection (MVP)
* Support: JPEG, PNG, HEIC (max 25MB)

**Elements**:

* Navigation Bar: "Photos" title, "Cancel" button
* Photo Grid: 4 columns, 2pt gutters
* Selection: Checkmark overlay (Primary Coral)

**Spacing**:

* Grid: 4 columns, 2pt gutters, 16pt margins
* Thumbnail: Square aspect ratio

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Selection: Primary Coral checkmark

**States**:

* Default: Grid of photos
* Selected: Checkmark overlay + coral border
* Loading: Spinner while importing

**Accessibility**:

* VoiceOver: "Photo, \[Date Taken], double-tap to select"
* Permission: Request photo library access

**Usage Guidelines**:

* Request permissions on first use
* Show permission denied state with "Open Settings" button
* Import full-resolution photo (compress later)

***

### 2.4 Emotion Selector

**Purpose**: Multi-select emotion tags for journal entries

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  How did you feel?                 Done  │ ← Title + Done button
├──────────────────────────────────────────┤
│  Positive Emotions                       │ ← Category header
│  ┌────────┐ ┌────────┐ ┌────────┐      │
│  │ 😊 Happy│ │❤️ Grate│ │🎉 Excit│      │ ← Emotion chips
│  └────────┘ └────────┘ └────────┘      │
│  ┌────────┐                             │
│  │😌 Peace│                             │
│  └────────┘                             │
│                                          │
│  Reflective Emotions                    │
│  ┌────────┐ ┌────────┐ ┌────────┐      │
│  │🤔 Think│ │😢 Nosta│ │😊 Proud│      │
│  └────────┘ └────────┘ └────────┘      │
│  ┌────────┐                             │
│  │😍 Lovin│                             │
│  └────────┘                             │
│                                          │
│  Challenging Emotions                   │
│  ┌────────┐ ┌────────┐ ┌────────┐      │
│  │😔 Sad  │ │😰 Anxio│ │😤 Frust│      │
│  └────────┘ └────────┘ └────────┘      │
│  ┌────────┐                             │
│  │😌 Hopef│                             │
│  └────────┘                             │
└──────────────────────────────────────────┘
```

**12-Emotion Taxonomy**:

**Positive Emotions** (4):

* 😊 Happy (Warm Coral #FF6B6B)
* ❤️ Grateful (Soft Pink #FF8FA3)
* 🎉 Excited (Bright Yellow #FDCB6E)
* 😌 Peaceful (Light Teal #81ECEC)

**Reflective Emotions** (4):

* 🤔 Thoughtful (Cool Blue #74B9FF)
* 😢 Nostalgic (Muted Purple #A29BFE)
* 😊 Proud (Golden Orange #FAB1A0)
* 😍 Loving (Rose Pink #FD79A8)

**Challenging Emotions** (4):

* 😔 Sad (Muted Blue #6C5CE7)
* 😰 Anxious (Gray-Blue #636E72)
* 😤 Frustrated (Muted Red #E17055)
* 😌 Hopeful (Soft Teal #55EFC4)

**Emotion Chip Specifications**:

**Anatomy**:

```
┌────────────────┐
│ 😊 Happy   ✓  │ ← Icon + Label + Checkmark (if selected)
└────────────────┘
```

**Spacing**:

* Height: 44pt
* Padding: 12pt horizontal, 8pt vertical
* Icon: 24x24pt
* Gap: 8pt between icon and label
* Border Radius: 22pt (pill shape)

**Typography**:

* Font: Callout (16pt regular)
* Label: Emotion name

**Colors (Unselected)**:

* Background: Emotion color at 15% opacity
* Text: Emotion color at 100%
* Border: None
* Icon: Emotion color

**Colors (Selected)**:

* Background: Emotion color at 100%
* Text: White
* Border: None
* Icon: White
* Checkmark: White, 20x20pt

**States**:

* Unselected: Light background, colored text
* Selected: Full color background, white text + checkmark
* Hover: Background opacity 25% (iPad, future)
* Pressed: Scale 0.98 (0.1s animation)

**Accessibility**:

* VoiceOver: "Happy, positive emotion, selected, button"
* Keyboard: Tab to navigate, Space to toggle
* Minimum touch target: 44x44pt

**Usage Guidelines**:

* No limit on selections (encourage 1-3)
* Show hint if >5 selected: "Focus on your strongest feelings"
* Group by category for easier scanning
* Display in same order across app

***

## 3. Action Components

### 3.1 Primary Button

**Purpose**: Main call-to-action buttons

**Anatomy**:

```
┌────────────────────┐
│   Save Entry       │ ← Text centered
└────────────────────┘
```

**Spacing**:

* Height: 50pt
* Padding: 16pt horizontal
* Border Radius: 12pt
* Min Width: 120pt

**Typography**:

* Font: Headline (17pt semibold)
* Color: White

**Colors**:

* Background: Primary Coral (#FF6B6B)
* Shadow: Level 1 (subtle)

**States**:

* Default: Full coral background
* Hover: 10% darker coral (iPad)
* Pressed: 20% darker coral, scale 0.98
* Disabled: 40% opacity, no interaction
* Loading: Spinner replaces text

**Accessibility**:

* VoiceOver: "\[Action], button"
* Minimum touch target: 44x44pt (height)
* Dynamic Type: Text size adjusts

**Usage Guidelines**:

* Maximum 1 primary button per screen
* Use for main actions: Save, Continue, Start, Subscribe
* Place at bottom of forms or modals
* Full-width on mobile, fixed width on iPad

***

### 3.2 Secondary Button

**Purpose**: Alternative actions, less emphasis than primary

**Anatomy**:

```
┌────────────────────┐
│   Cancel           │ ← Text centered
└────────────────────┘
```

**Spacing**:

* Height: 50pt
* Padding: 16pt horizontal
* Border Radius: 12pt
* Border: 1pt solid Light Gray

**Typography**:

* Font: Headline (17pt semibold)
* Color: Charcoal (Light), Off-White (Dark)

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Border: 1pt Light Gray

**States**:

* Default: Light background, border
* Hover: Background 5% darker
* Pressed: Background 10% darker, scale 0.98
* Disabled: 40% opacity

**Usage Guidelines**:

* Use for secondary actions: Cancel, Skip, Later
* Pair with primary button (left/right or top/bottom)
* Never use two primary buttons

***

### 3.3 Text Button (Link)

**Purpose**: Tertiary actions, navigation links

**Anatomy**:

```
Forgot password?  ← Text only, no border/background
```

**Spacing**:

* Height: 44pt (touch target)
* Padding: 8pt horizontal

**Typography**:

* Font: Headline (17pt semibold)
* Color: Primary Coral

**Colors**:

* Background: None
* Underline: None (iOS convention)

**States**:

* Default: Coral text
* Hover: 10% darker coral
* Pressed: 20% darker coral, 0.8 opacity
* Disabled: 40% opacity

**Usage Guidelines**:

* Use for low-priority actions: Forgot password, Learn more, Skip
* Always use semantic link color (coral)
* Minimum touch target: 44x44pt

***

### 3.4 Floating Action Button (FAB)

**Purpose**: Quick access to create new journal entry

**Anatomy**:

```
    ┌─────┐
    │  +  │ ← Plus icon
    └─────┘
```

**Spacing**:

* Size: 56x56pt circle
* Icon: 32x32pt plus icon
* Position: Bottom-right corner, 16pt from edges
* Safe Area: Above tab bar (if visible)

**Typography**:

* N/A (icon-only)

**Colors**:

* Background: Primary Coral
* Icon: White
* Shadow: Level 3 (floating, prominent)

**States**:

* Default: Full coral circle
* Hover: 10% darker coral
* Pressed: 20% darker coral, scale 0.9
* Hidden: Scroll down (hide), scroll up (show)

**Animations**:

* Scroll hide: Slide down + fade out (0.3s)
* Scroll show: Slide up + fade in (0.3s)
* Press: Scale 0.9 (0.1s)

**Accessibility**:

* VoiceOver: "Create new entry, button"
* Keyboard: Tab accessible
* Touch target: Full 56x56pt

**Usage Guidelines**:

* Always visible on Timeline screen
* Hide on scroll down (reduce clutter)
* Show on scroll up (quick access)
* Tapping opens camera or photo picker

***

### 3.5 Icon Button

**Purpose**: Small action buttons with icons

**Anatomy**:

```
 [🔍]  ← Icon only, square or circular
```

**Spacing**:

* Size: 44x44pt (minimum touch target)
* Icon: 24x24pt
* Padding: 10pt (makes 44x44pt total)

**Colors**:

* Icon: Charcoal (Light), Off-White (Dark)
* Background: None (transparent)

**States**:

* Default: Icon visible
* Hover: 20% gray background circle
* Pressed: 30% gray background, scale 0.95
* Disabled: 40% opacity

**Usage Guidelines**:

* Use in navigation bars (search, filter, more)
* Always pair with accessibility label
* Never use ambiguous icons

***

## 4. Content Components

### 4.1 Photo Card (Timeline Grid)

**Purpose**: Display journal entry in timeline grid

**Anatomy**:

```
┌────────────────────┐
│                    │
│      [Photo]       │ ← Photo (aspect ratio preserved)
│                    │
├────────────────────┤
│ Nov 10          😊❤️│ ← Date + Emotions (max 3 visible)
│ What a beautiful...│ ← Text preview (1 line, truncated)
└────────────────────┘
```

**Spacing**:

* Photo: Full-width, aspect ratio preserved
* Padding: 12pt internal padding (bottom section)
* Border Radius: 12pt
* Gutter: 8pt between cards

**Typography**:

* Date: Footnote (13pt regular), Secondary Gray
* Text Preview: Callout (16pt regular), Charcoal

**Colors**:

* Background: White (Light), Elevated Surface (Dark)
* Shadow: Level 1 (subtle)
* Border: None

**Elements**:

1. **Photo**: Lazy-loaded thumbnail (400x400pt)
2. **Date Badge**: "Nov 10" (top-left overlay on photo)
3. **Emotion Icons**: Max 3 visible, "+" if more (top-right)
4. **Text Preview**: First 50 characters of journal text

**States**:

* Default: Shadow Level 1
* Hover: Shadow Level 2 (iPad)
* Pressed: Scale 0.98, opacity 0.95
* Loading: Skeleton screen (gray rectangle with shimmer)

**Accessibility**:

* VoiceOver: "Entry from November 10, Happy, Grateful, What a beautiful day..."
* Touch target: Entire card (not just photo)
* Alt text: Photo description (if AI-generated)

**Usage Guidelines**:

* Grid: 2 columns (portrait), 3 columns (landscape)
* Masonry layout: Variable heights based on content
* Lazy load: Photos load on scroll
* Tap: Navigate to entry detail view

***

### 4.2 Entry Detail View

**Purpose**: Full view of a single journal entry

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  ←                                  [⋮]  │ ← Navigation + Menu
├──────────────────────────────────────────┤
│                                           │
│                                           │
│          [Full-Size Photo]                │ ← Photo (tappable for full-screen)
│                                           │
│                                           │
├──────────────────────────────────────────┤
│  November 10, 2025 • 2:30 PM             │ ← Date + Time
│  📍 San Francisco, CA                    │ ← Location (if available)
│                                           │
│  😊 Happy  ❤️ Grateful  🎉 Excited       │ ← Emotion tags
│                                           │
│  What a beautiful day! The weather was   │ ← Journal text
│  perfect and I spent time with family.   │
│  These moments are what I want to        │
│  remember forever.                       │
└──────────────────────────────────────────┘
```

**Spacing**:

* Photo: Full-width, aspect ratio preserved
* Content Padding: 16pt horizontal
* Section Spacing: 16pt between sections

**Typography**:

* Date/Time: Callout (16pt regular), Secondary Gray
* Location: Callout (16pt regular), Secondary Gray
* Journal Text: Body (17pt regular), Charcoal

**Elements**:

1. **Navigation Bar**: Back button + Menu (edit/delete)
2. **Photo**: Full-width, tappable for full-screen
3. **Metadata**: Date, time, location
4. **Emotion Tags**: All selected emotions as chips
5. **Journal Text**: Full text, scrollable

**States**:

* Default: All content visible
* Photo Loading: Skeleton screen
* Photo Error: Error state with retry button
* Full-Screen Photo: Black background, pinch-to-zoom

**Accessibility**:

* VoiceOver: Read all content in order
* Photo: "Photo from November 10, double-tap to view full screen"
* Dynamic Type: Text size adjusts

**Usage Guidelines**:

* Always show full journal text (no truncation)
* Emotion tags: Show all (no "+" indicator)
* Metadata: Gray, subtle (not main focus)
* Edit/Delete: Menu button (⋮) in navigation bar

***

### 4.3 AI Prompt Card

**Purpose**: Display AI-generated journal prompts

**Anatomy**:

```
┌────────────────────────────────────────┐
│  What made this moment special?        │ ← Prompt text
└────────────────────────────────────────┘
```

**Spacing**:

* Height: Variable (2-3 lines of text)
* Padding: 16pt horizontal, 12pt vertical
* Border Radius: 12pt
* Gap: 12pt between prompt cards

**Typography**:

* Font: Body (17pt regular)
* Color: Charcoal (Light), Off-White (Dark)

**Colors**:

* Background: Off-White (Light), Elevated Surface (Dark)
* Border: 1pt Light Gray
* Selected: 2pt Primary Coral border

**States**:

* Default: Light background, border
* Selected: Coral border, coral text
* Pressed: Scale 0.98
* Loading: Skeleton with shimmer animation

**Accessibility**:

* VoiceOver: "\[Prompt text], button, tap to use this prompt"
* Touch target: Entire card

**Usage Guidelines**:

* Show 3 prompts at a time
* "Refresh prompts" button for new suggestions
* Tapping inserts prompt into text field
* Loading state: "Thinking about your photo..."

***

### 4.4 Loading State (Skeleton Screen)

**Purpose**: Show content structure while loading

**Anatomy** (Timeline Grid):

```
┌────────┐ ┌────────┐
│░░░░░░░░│ │░░░░░░░░│ ← Gray rectangles
│░░░░░░░░│ │░░░░░░░░│
│░░░░░░░░│ │░░░░░░░░│
└────────┘ └────────┘
┌────────┐ ┌────────┐
│░░░░░░░░│ │░░░░░░░░│
│░░░░░░░░│ │░░░░░░░░│
└────────┘ └────────┘
```

**Spacing**:

* Match actual content dimensions
* Same grid layout as loaded content

**Colors**:

* Background: Light Gray (#E0E0E0)
* Shimmer: White gradient (left to right)

**Animation**:

* Shimmer: 1.5s loop, left to right gradient
* Smooth, continuous (no flicker)

**Usage Guidelines**:

* Show immediately on load (no blank screen)
* Preserve layout structure
* Replace with real content when loaded

***

### 4.5 Empty State

**Purpose**: Guide users when no content exists

**Anatomy** (Timeline Empty):

```
┌──────────────────────────────────────────┐
│                                           │
│                                           │
│         [Illustration: Camera + Journal]  │ ← Friendly illustration
│                                           │
│         Your story starts here            │ ← Headline
│                                           │
│     Capture a moment and let AI help     │ ← Body text
│     you remember it forever.              │
│                                           │
│     ┌──────────────────────────────┐     │
│     │  + Create Your First Memory  │     │ ← CTA button
│     └──────────────────────────────┘     │
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Center-aligned vertically and horizontally
* Illustration: 200x200pt
* Spacing: 24pt between elements

**Typography**:

* Headline: Title 2 (22pt bold), Charcoal
* Body: Body (17pt regular), Secondary Gray

**Colors**:

* Illustration: Coral + Teal accents
* CTA: Primary button styling

**Variants**:

1. **Timeline Empty**: "Your story starts here"
2. **Search Empty**: "No entries found"
3. **AI Loading**: "Thinking about your photo..."
4. **Error State**: "Something went wrong"

**Usage Guidelines**:

* Always show empty state (never blank screen)
* Provide clear next action
* Use friendly, encouraging tone
* Include illustration or icon

***

### 4.6 Error State

**Purpose**: Communicate errors clearly and provide solutions

**Anatomy**:

```
┌──────────────────────────────────────────┐
│           ⚠️                              │ ← Icon (48x48pt)
│                                           │
│      Something went wrong                 │ ← Headline
│                                           │
│  We couldn't upload your photo.           │ ← Error message
│  Please check your connection and         │
│  try again.                               │
│                                           │
│     ┌──────────────────────────────┐     │
│     │       Try Again              │     │ ← CTA button
│     └──────────────────────────────┘     │
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Center-aligned
* Icon: 48x48pt
* Spacing: 16pt between elements

**Typography**:

* Headline: Title 3 (20pt semibold), Charcoal
* Error Message: Body (17pt regular), Secondary Gray

**Colors**:

* Icon: Warning Amber or Error Red (based on severity)
* CTA: Primary button styling

**Error Types**:

1. **Network Error**: "Check your connection and try again"
2. **AI Failure**: "AI couldn't generate prompts. Try manual entry."
3. **Upload Failure**: "Photo upload failed. Try again."
4. **Permission Denied**: "Camera access required. Open Settings."

**Usage Guidelines**:

* Clear, non-technical language
* Actionable (what can user do?)
* Friendly tone, not blaming
* Always provide "Try Again" or alternative action

***

## 5. Feedback Components

### 5.1 Toast Notification

**Purpose**: Brief, non-blocking feedback messages

**Anatomy**:

```
┌────────────────────────────────┐
│ ✓  Entry saved successfully    │ ← Icon + Message
└────────────────────────────────┘
```

**Spacing**:

* Height: 44pt
* Padding: 16pt horizontal, 12pt vertical
* Border Radius: 12pt
* Position: Top center, 16pt from top (Safe Area)

**Typography**:

* Font: Callout (16pt regular)
* Color: White

**Colors**:

* Background: Success Green (#00B894) or Error Red (#D63031)
* Shadow: Level 2

**States**:

* Appear: Slide down + fade in (0.3s)
* Visible: 3 seconds
* Dismiss: Slide up + fade out (0.3s)

**Variants**:

1. **Success**: Green background, checkmark icon
2. **Error**: Red background, xmark icon
3. **Info**: Primary Coral, info icon

**Accessibility**:

* VoiceOver: Announce immediately
* Reduce Motion: Fade in/out instead of slide

**Usage Guidelines**:

* Auto-dismiss after 3 seconds
* User can swipe up to dismiss early
* Maximum 1 toast at a time
* Use for confirmations, not errors (use error state for errors)

***

### 5.2 Alert Dialog

**Purpose**: Critical decisions or confirmations

**Anatomy**:

```
┌──────────────────────────────────┐
│  Delete Entry?                   │ ← Title
│                                  │
│  This action cannot be undone.   │ ← Message
│  Are you sure?                   │
│                                  │
│  ┌────────────┐ ┌────────────┐  │
│  │   Cancel   │ │   Delete   │  │ ← Actions
│  └────────────┘ └────────────┘  │
└──────────────────────────────────┘
```

**Spacing**:

* Width: 270pt (iOS standard)
* Padding: 16pt
* Border Radius: 14pt

**Typography**:

* Title: Headline (17pt semibold), Charcoal
* Message: Callout (16pt regular), Secondary Gray
* Actions: Headline (17pt semibold)

**Colors**:

* Background: White (Light), Elevated Surface (Dark)
* Overlay: 40% black dim
* Destructive Action: Error Red text

**Variants**:

1. **Confirmation**: "Delete Entry?" (destructive)
2. **Information**: "Permission Required"
3. **Warning**: "Unsaved Changes"

**Accessibility**:

* VoiceOver: Read title, message, actions
* Keyboard: Tab between actions, Enter to confirm
* Reduce Motion: Fade in instead of scale

**Usage Guidelines**:

* Use sparingly (only for critical decisions)
* Title: Short, clear question
* Message: Explain consequence
* Destructive action: Red text, right side (iOS convention)

***

### 5.3 Progress Indicator

**Purpose**: Show progress for long operations

**Variants**:

1. **Linear Progress Bar** (Photo Upload)
2. **Circular Spinner** (AI Processing)

**Linear Progress Bar**:

```
┌──────────────────────────────────┐
│ Uploading...                 45% │ ← Label + Percentage
│ ████████████░░░░░░░░░░░░░░░░░░░ │ ← Progress bar
└──────────────────────────────────┘
```

**Spacing**:

* Height: 4pt (bar), 44pt (total with label)
* Width: Full-width or fixed
* Border Radius: 2pt

**Colors**:

* Background: Light Gray
* Fill: Primary Coral
* Label: Secondary Gray

**Circular Spinner**:

```
    ⟲  ← Rotating spinner
```

**Spacing**:

* Size: 32x32pt (medium), 48x48pt (large)

**Colors**:

* Spinner: Primary Coral or Secondary Gray

**Animation**:

* Linear: Fill from 0% to 100%
* Circular: Rotate 360° continuously (1s loop)

**Usage Guidelines**:

* Linear: Use for deterministic progress (photo upload)
* Circular: Use for indeterminate progress (AI processing)
* Always show estimated time if possible

***

## 6. Data Display Components

### 6.1 Emotion Tag (Chip)

**Purpose**: Display selected emotion on entry

**Anatomy**:

```
┌──────────────┐
│ 😊 Happy     │ ← Icon + Label
└──────────────┘
```

**Spacing**:

* Height: 32pt
* Padding: 8pt horizontal
* Icon: 20x20pt
* Gap: 6pt between icon and label
* Border Radius: 16pt (pill shape)

**Typography**:

* Font: Callout (16pt regular)
* Color: Emotion color (unselected), White (selected)

**Colors** (Unselected - Display Mode):

* Background: Emotion color at 20% opacity
* Text: Emotion color at 100%
* Icon: Emotion color

**Colors** (Selected - Selection Mode):

* Background: Emotion color at 100%
* Text: White
* Icon: White

**Usage Guidelines**:

* Display mode: Show all emotions on entry (20% opacity)
* Selection mode: Show selected emotions (100% opacity)
* Always show icon + label (not icon-only)
* Wrap to multiple lines if needed

***

### 6.2 Metadata Label

**Purpose**: Display entry metadata (date, time, location)

**Anatomy**:

```
November 10, 2025 • 2:30 PM • 📍 San Francisco, CA
```

**Spacing**:

* Height: 20pt (single line)
* Gap: 8pt between elements
* Icon: 16x16pt

**Typography**:

* Font: Callout (16pt regular)
* Color: Secondary Gray

**Elements**:

* Date: "November 10, 2025"
* Time: "2:30 PM" (12-hour format)
* Location: "📍 San Francisco, CA" (if available)
* Separator: " • " (bullet point)

**Usage Guidelines**:

* Always show date and time
* Show location only if user granted permission
* Use relative dates for recent entries: "Today", "Yesterday", "3 days ago"

***

### 6.3 Timeline Grid

**Purpose**: Masonry grid layout for photo timeline

**Anatomy**:

```
┌────────┐ ┌────────┐
│        │ │        │
│ Card 1 │ │ Card 2 │ ← Variable heights
│        │ │        │
│        │ └────────┘
└────────┘ ┌────────┐
┌────────┐ │        │
│        │ │ Card 4 │
│ Card 3 │ │        │
└────────┘ └────────┘
```

**Spacing**:

* Columns: 2 (portrait), 3 (landscape)
* Gutter: 8pt
* Margins: 16pt horizontal
* Row Gap: 8pt

**Grid Behavior**:

* Masonry layout: Variable heights
* Aspect ratio: Preserved from photo
* Lazy loading: Load on scroll
* Infinite scroll: Load more at bottom

**Performance**:

* Thumbnail size: 400x400pt
* Prefetch: 2 screens ahead
* Cache: 200MB limit (Kingfisher)

**Usage Guidelines**:

* Newest entries first (reverse chronological)
* Show 20 entries initially
* Load 20 more on scroll to bottom
* Pull-to-refresh at top

***

## 7. Onboarding Components

### 7.1 Welcome Screen (Onboarding Step 1)

**Purpose**: Introduce app value proposition

**Anatomy**:

```
┌──────────────────────────────────────────┐
│                                           │
│                                           │
│         [Hero Image: Photo + Journal]     │ ← Beautiful hero image
│                                           │
│                                           │
│      Your life, beautifully remembered    │ ← Headline
│                                           │
│  Capture moments, let AI help you journal,│ ← Subheadline
│  and rediscover your memories.            │
│                                           │
│     ┌──────────────────────────────┐     │
│     │      Get Started             │     │ ← Primary CTA
│     └──────────────────────────────┘     │
│                                           │
│     Already have an account? Log in       │ ← Secondary action
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Hero Image: 300x300pt
* Vertical Spacing: 32pt between sections
* Padding: 24pt horizontal

**Typography**:

* Headline: Large Title (34pt bold), Charcoal
* Subheadline: Body (17pt regular), Secondary Gray

**Colors**:

* Hero Image: Coral + Teal gradient
* CTA: Primary button

**Usage Guidelines**:

* Show only on first app launch
* Skip if user already logged in
* Warm, welcoming tone
* Focus on value, not features

***

### 7.2 How It Works (Onboarding Step 2)

**Purpose**: Explain core workflow in 3 steps

**Anatomy**:

```
┌──────────────────────────────────────────┐
│                                           │
│  ┌─────┐                                  │
│  │  1  │  Snap a photo                    │ ← Step 1
│  └─────┘  Use your camera or library      │
│                                           │
│  ┌─────┐                                  │
│  │  2  │  AI suggests prompts             │ ← Step 2
│  └─────┘  Get thoughtful journal prompts  │
│                                           │
│  ┌─────┐                                  │
│  │  3  │  Save your memory                │ ← Step 3
│  └─────┘  Build your visual timeline      │
│                                           │
│     ┌──────────────────────────────┐     │
│     │          Next                │     │ ← CTA
│     └──────────────────────────────┘     │
│                                           │
│              ● ● ○  (Page indicators)     │ ← Progress
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Icon: 48x48pt circles
* Gap: 32pt between steps
* Padding: 24pt horizontal

**Typography**:

* Step Title: Headline (17pt semibold), Charcoal
* Step Description: Callout (16pt regular), Secondary Gray

**Colors**:

* Step Numbers: Primary Coral background, white text
* Icons: Coral

**Usage Guidelines**:

* Show 3 steps maximum
* Support swipe left/right navigation
* Page indicators at bottom
* "Skip" option in top-right

***

### 7.3 Permission Request (Onboarding Step 3)

**Purpose**: Request camera and notification permissions

**Anatomy**:

```
┌──────────────────────────────────────────┐
│                                           │
│         We need a few permissions         │ ← Headline
│                                           │
│  📷 Camera                                │ ← Permission 1
│  To capture photos for your journal       │
│  ┌──────────────────────────────────┐    │
│  │      Allow Camera Access         │    │ ← CTA
│  └──────────────────────────────────┘    │
│                                           │
│  🔔 Notifications (Optional)              │ ← Permission 2
│  Daily reminders to journal                │
│  ┌──────────────────────────────────┐    │
│  │   Allow Notifications            │    │ ← CTA
│  └──────────────────────────────────┘    │
│                                           │
│     I'll do this later                    │ ← Skip option
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Icon: 48x48pt
* Gap: 24pt between permissions
* Padding: 24pt horizontal

**Typography**:

* Headline: Title 2 (22pt bold), Charcoal
* Permission Title: Headline (17pt semibold), Charcoal
* Description: Callout (16pt regular), Secondary Gray

**Colors**:

* Icons: Primary Coral
* CTA: Primary button

**Usage Guidelines**:

* Explain why each permission is needed
* Request permissions sequentially (not all at once)
* Provide skip option for optional permissions (notifications)
* Handle "Don't Allow" gracefully (show settings link later)

***

## 8. Premium Components

### 8.1 Paywall Screen

**Purpose**: Encourage free users to upgrade to Premium

**Anatomy**:

```
┌──────────────────────────────────────────┐
│  ×                                        │ ← Close button
│                                           │
│      Unlock Your Full Story               │ ← Headline
│                                           │
│  ✓ Unlimited photos per month            │ ← Feature list
│  ✓ Advanced search filters               │
│  ✓ HD quality photo storage              │
│  ✓ Priority AI processing                │
│                                           │
│  ┌──────────────────────────────────┐    │
│  │  Annual  $60/year  (Save 25%)    │    │ ← Pricing option 1 (recommended)
│  └──────────────────────────────────┘    │
│  ┌──────────────────────────────────┐    │
│  │  Monthly  $8/month               │    │ ← Pricing option 2
│  └──────────────────────────────────┘    │
│                                           │
│     ┌──────────────────────────────┐     │
│     │   Start 14-Day Free Trial    │     │ ← CTA
│     └──────────────────────────────┘     │
│                                           │
│  Cancel anytime. No commitment.           │ ← Fine print
│                                           │
│         Maybe later                       │ ← Skip option
│                                           │
└──────────────────────────────────────────┘
```

**Spacing**:

* Padding: 24pt horizontal
* Gap: 16pt between features
* Gap: 12pt between pricing options

**Typography**:

* Headline: Title 1 (28pt bold), Charcoal
* Features: Body (17pt regular), Charcoal
* Pricing: Headline (17pt semibold), Charcoal
* Fine Print: Footnote (13pt regular), Secondary Gray

**Colors**:

* Checkmarks: Success Green
* Pricing Options: Off-White background, 2pt coral border (selected)
* CTA: Primary button
* Badge: "Save 25%" in coral

**Usage Guidelines**:

* Show when user hits free tier limit (50 photos/month)
* Emphasize value, not limitations
* Highlight savings on annual plan
* Free trial: 14 days, requires payment method
* Dismissible (not blocking)

***

### 8.2 Premium Badge

**Purpose**: Indicate Premium subscription status

**Anatomy**:

```
┌────────────┐
│ 👑 Premium │ ← Crown icon + Label
└────────────┘
```

**Spacing**:

* Height: 24pt
* Padding: 6pt horizontal
* Icon: 16x16pt
* Gap: 4pt between icon and label
* Border Radius: 12pt

**Typography**:

* Font: Caption 1 (12pt semibold)
* Color: Golden Orange (#FAB1A0)

**Colors**:

* Background: Golden Orange at 15% opacity
* Text: Golden Orange at 100%
* Icon: Golden Orange

**Usage Guidelines**:

* Show in profile section
* Small, subtle (not ostentatious)
* Gold color (premium feel)

***

## Accessibility Summary

### WCAG 2.1 AA Compliance Checklist

**Color & Contrast**:

* ✅ Text contrast: 4.5:1 minimum (normal text), 3:1 (large text)
* ✅ UI component contrast: 3:1 minimum
* ✅ Never rely on color alone (use icons, labels, shapes)
* ✅ Colorblind-friendly emotion colors

**Typography & Legibility**:

* ✅ Dynamic Type support (all text styles)
* ✅ Readable font sizes (17pt body minimum)
* ✅ Adequate line height (1.3x font size)
* ✅ No fixed font sizes (always use text styles)

**Touch Targets & Interaction**:

* ✅ Minimum touch target: 44x44pt
* ✅ Adequate spacing between interactive elements (8pt minimum)
* ✅ Clear focus indicators (2pt blue ring)
* ✅ No time limits on interactions

**Navigation & Structure**:

* ✅ Logical VoiceOver reading order
* ✅ Meaningful accessibility labels (not "Button" or "Image")
* ✅ Grouped related elements
* ✅ Clear hierarchy (headings, sections)

**Motion & Animation**:

* ✅ Respect Reduce Motion setting
* ✅ No flashing content (seizure risk)
* ✅ Alternative to motion-based interactions

**Alternative Input**:

* ✅ Keyboard navigation support (iPad, future)
* ✅ Voice Control compatibility
* ✅ External keyboard support

***

## Implementation Notes for @frontend-developer

### SwiftUI Components

All components are designed for SwiftUI implementation:

```swift  theme={null}
// Example: Primary Button
Button(action: { /* action */ }) {
    Text("Save Entry")
        .font(.headline)
        .foregroundColor(.white)
        .frame(height: 50)
        .frame(maxWidth: .infinity)
        .background(Color("PrimaryCoral"))
        .cornerRadius(12)
        .shadow(color: Color.black.opacity(0.08), radius: 2, x: 0, y: 1)
}
.buttonStyle(.plain) // Disable default button style
.accessibilityLabel("Save entry")

// Example: Emotion Tag
HStack(spacing: 6) {
    Image(systemName: "face.smiling")
        .resizable()
        .frame(width: 20, height: 20)
    Text("Happy")
        .font(.callout)
}
.padding(.horizontal, 8)
.padding(.vertical, 4)
.background(Color("EmotionHappy").opacity(0.2))
.foregroundColor(Color("EmotionHappy"))
.cornerRadius(16)
```

### Design Tokens Usage

All colors, spacing, and typography values are defined in `design-tokens.json`. Import and use tokens:

```swift  theme={null}
// Color tokens
Color("PrimaryCoral")
Color("TextPrimary")
Color("BackgroundSurface")

// Spacing tokens
.padding(.horizontal, Spacing.md) // 16pt
.padding(.vertical, Spacing.xs)   // 8pt

// Typography tokens
.font(.title2) // 22pt bold
.font(.body)   // 17pt regular
```

***

## Related Documents

* **Style Guide**: `/docs/design/ux/style-guide.md` - Typography, colors, spacing, accessibility
* **Design Tokens**: `/docs/design/ux/design-tokens.json` - SwiftUI-ready tokens
* **PRD**: `/docs/product/prds/mvp-q1-2025-prd.md` - Product requirements
* **Apple HIG**: [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)

***

## Approval

* [ ] **UX Designer** (self) - Design system complete
* [ ] **Product Designer** - Reviewed and ready for UI design
* [ ] **Frontend Developer (iOS)** - Reviewed and implementable
* [ ] **Chief Product Officer** - Approved for brand alignment

***

**END OF DESIGN SYSTEM**

**Next Steps**:

1. @product-designer: Use components to create high-fidelity UI designs in Figma
2. @frontend-developer: Implement components in SwiftUI using design tokens
3. Create Figma component library for design handoff

**Version History**:

| Version | Date       | Changes                                           | Author      |
| ------- | ---------- | ------------------------------------------------- | ----------- |
| 1.0     | 2025-11-10 | Initial design system with full component library | UX Designer |


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.agentsoflearning.com/llms.txt