---

name: ios-ui-ux description: UI/UX design principles for iOS. Use when designing screens, making UI look good, user flow design, handling loading states, empty states, error states, animations, navigation patterns, accessibility, dark mode, form design, better UX. allowed-tools: Read, Grep, Glob

UI/UX Design Principles

Table of Contents

• 1. Design Philosophy ....... L15-L40
• 2. Navigation Patterns ... L42-L70
• 3. States & Feedback ........ L72-L110
• 4. Interaction Patterns . L112-L150
• 5. Visual Hierarchy ......... L152-L190
• 6. Accessibility ............... L192-L220
• 7. Performance UX ............. L222-L250
• 8. Checklist ....................... L252-L280

---

1. Design Philosophy

Core Values

• Simple first - Prioritize simplicity, avoid over-complication
• Consistency - Consistent throughout the app
• Feedback - Always respond to user actions
• Accessibility - Design for all users

Design Style

• Minimalist / Clean
• iOS native feel (follow Human Interface Guidelines)
• Light mode first, support dark mode

Key Principles

1. Content over chrome
2. Clarity over decoration
3. Depth through layering
4. Direct manipulation

---

2. Navigation Patterns

Main Structure

• Tab Bar for main navigation (max 5 tabs)
• Navigation Stack for drill-down
• Modal/Sheet for temporary actions

Rules

• No more than 3 levels deep in navigation stack
• Back button always visible
• Swipe back gesture enabled
• Clear navigation hierarchy

Navigation Types

---

3. States & Feedback

Every Screen Must Handle

State Diagram

Copy         ┌─────────┐
         │  Idle   │
         └────┬────┘
              │ load()
              ▼
         ┌─────────┐
    ┌────│ Loading │────┐
    │    └─────────┘    │
    │ error             │ success
    ▼                   ▼
┌─────────┐       ┌─────────┐
│  Error  │       │ Success │
└────┬────┘       └────┬────┘
     │ retry()         │ refresh()
     └────────┬────────┘
              ▼
         ┌─────────┐
         │ Loading │
         └─────────┘

User Feedback

• Haptic feedback for important actions
• Animation for state transitions (0.3s default)
• Toast/Snackbar for light confirmations
• Progress indicators for long operations

---

4. Interaction Patterns

Touch Targets

• Minimum 44x44pt for tappable elements
• Spacing between buttons: 8pt minimum
• Adequate padding around interactive elements

Gestures

Forms

• Inline validation
• Clear error messages
• Auto-focus next field
• Appropriate keyboard type
• Show/hide password toggle
• Clear button for text fields

Form Validation

---

5. Visual Hierarchy

Typography Scale

Spacing System

• Base unit: 8pt
• Use: 4, 8, 16, 24, 32, 48
• Consistent spacing throughout app

Colors

Elevation/Shadows

• Use sparingly
• Consistent shadow styles
• Higher elevation = more important

---

6. Accessibility

Required

• VoiceOver labels for all interactive elements
• Dynamic Type support
• Minimum contrast ratio 4.5:1
• Don't use color as only indicator
• Support reduced motion

VoiceOver

CopyButton("Submit") {
    // action
}
.accessibilityLabel("Submit form")
.accessibilityHint("Double tap to submit your information")

Dynamic Type

CopyText("Hello")
    .font(.body) // Automatically scales

Contrast

• Text on background: 4.5:1 minimum
• Large text: 3:1 minimum
• Interactive elements: clearly distinguishable

---

7. Performance UX

Loading

• Skeleton screens instead of spinners when possible
• Optimistic UI for fast actions
• Lazy loading for long lists
• Progressive loading for images

Skeleton Example

Copy┌────────────────────────────┐
│ ████████████               │  <- Title placeholder
│ ████████████████████████   │  <- Subtitle placeholder
│                            │
│ ████████████████████████   │  <- Content placeholder
│ ████████████████           │
└────────────────────────────┘

Offline

• Cache important data
• Show offline indicator
• Queue actions to sync later
• Graceful degradation

Performance Tips

• Avoid blocking main thread
• Use lazy loading for lists
• Cache computed values
• Optimize images
• Minimize re-renders

---

8. Checklist

When Designing New Screen

• Define user goal for the screen
• Handle all 4 states (loading, empty, error, success)
• Touch targets >= 44pt
• VoiceOver labels
• Dark mode compatible
• Keyboard handling (if has input)
• Animation for transitions
• Consistent with app style

When Implementing

• Use design tokens (colors, fonts, spacing)
• Add accessibility labels
• Support Dynamic Type
• Test with VoiceOver
• Test dark mode
• Test different screen sizes
• Handle keyboard appearance

Before Release

• All states implemented
• Accessibility audit passed
• Performance acceptable
• Animations smooth (60fps)
• No layout issues on different devices