ios-hig-design

Original source / Raw SKILL.md

---
name: ios-hig-design
description: Design native iOS apps following Apple's Human Interface Guidelines. Use this skill when building iPhone/iPad interfaces, creating SwiftUI/UIKit components, validating iOS design compliance, or ensuring accessibility. Covers layout, typography, navigation, components, gestures, colors, and platform conventions.
license: MIT
---

# iOS Human Interface Guidelines Design Skill

This skill guides creation of native iOS app interfaces that feel intuitive, consistent, and aligned with Apple's design philosophy.

## Core Design Principles

Apple's iOS design philosophy rests on three foundational principles:

### 1. Clarity
Every element must be legible and purposeful. Typography, iconography, and spacing communicate hierarchy and focus.

### 2. Deference
The interface should never overshadow the content. The UI exists to support user tasks, not distract from them.

### 3. Depth
Layering, transitions, and realistic motion provide hierarchy and spatial relationships.

---

## Screen Sizes & Layout

### iPhone Screen Sizes (Design Points)

| Device | Frame Size | Export Scale |
|--------|-----------|--------------|
| iPhone 15 Pro Max, 14 Pro Max | 430 × 932 | @3x |
| iPhone 15 Pro, 15, 14 Pro | 393 × 852 | @3x |
| iPhone 14, 13, 12 | 390 × 844 | @3x |
| iPhone SE (2nd/3rd gen) | 375 × 667 | @2x |

**Best Practice**: Design for smaller screens first (375pt width).

### Page Layout Structure

```
┌─────────────────────────────────┐
│         Status Bar (59pt)       │
├─────────────────────────────────┤
│         Nav Bar Row 1 (44pt)    │
├─────────────────────────────────┤
│         Nav Bar Row 2 (58pt)    │  ← Large title (optional)
├─────────────────────────────────┤
│         Content Area            │
├─────────────────────────────────┤
│         Tab Bar (49pt)          │
├─────────────────────────────────┤
│       Home Indicator (34pt)     │
└─────────────────────────────────┘
```

### Safe Areas

**Critical**: UI components must not overlap with hardware features (notch, Dynamic Island, home indicator).

```swift
VStack { Text("Content") }  // Default: respects safe area

VStack { Color.blue }.ignoresSafeArea()  // Extend beyond
```

---

## Quick Reference: Component Spacing

```
Touch Target Min:     44 × 44pt
Screen Edge Margin:   16-20pt
List Row Height:      44pt minimum
Standard Spacing:     8 / 16 / 24pt
```

---

## Common Pitfalls

**Don't:**
- Override standard gestures (swipe back, pull refresh)
- Use touch targets smaller than 44pt
- Ignore safe areas
- Force Android patterns (top tab bar, hamburger menus)
- Neglect Dark Mode
- Use low contrast text

**Do:**
- Use native components
- Test on real devices
- Support Dynamic Type
- Test with VoiceOver enabled
- Preview in both light and dark modes

---

## Detailed Reference Files

- [references/typography.md](references/typography.md) — Text styles, font sizes, Dark Mode typography
- [references/navigation.md](references/navigation.md) — Tab bar, navigation bar, modals, back navigation
- [references/components.md](references/components.md) — Buttons, lists, input controls, touch targets
- [references/colors-depth.md](references/colors-depth.md) — Semantic colors, Dark Mode, contrast ratios
- [references/gestures.md](references/gestures.md) — Standard gestures, haptics, animations
- [references/accessibility.md](references/accessibility.md) — VoiceOver, Dynamic Type, checklist
- [references/app-icons.md](references/app-icons.md) — Icon sizes, shape, guidelines

---

## Resources

- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
- [SF Symbols](https://developer.apple.com/sf-symbols/)
- [Apple Design Resources (Figma/Sketch)](https://developer.apple.com/design/resources/)
- [WWDC Design Sessions](https://developer.apple.com/videos/design/)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/typography.md

```markdown
# iOS Typography Guidelines

## System Font: San Francisco

iOS uses San Francisco (SF Pro) as the default typeface. Use system text styles for automatic Dynamic Type support.

## Standard Text Styles

| Element | Size | Weight | Color |
|---------|------|--------|-------|
| Large Title (unscrolled) | 34pt | Bold | #000000 |
| Title (scrolled) | 17pt | Medium | #000000 |
| Body text, List items | 17pt | Regular | #000000 |
| Secondary text | 15pt | Regular | #3C3C43 @ 60% |
| Caption, Tertiary | 12-13pt | Regular | #3C3C43 @ 60% |
| Tab bar labels | 10pt | Regular | #8A8A8E |

## Typography Rules

1. **Minimum text size**: 11pt (for captions/secondary info)
2. **Line height**: Minimum 1.3× font size for paragraphs
3. **Line length**: 35-50 characters per line for mobile
4. **Alignment**: Left-aligned, non-justified text
5. **Hierarchy**: Use weight and color variation, not size extremes
6. **Contrast**: Minimum 4.5:1 ratio (WCAG AA standard)

```swift
// Use semantic text styles for Dynamic Type support
Text("Title")
    .font(.title)

Text("Body content")
    .font(.body)

Text("Caption")
    .font(.caption)
    .foregroundColor(.secondary)
```

## Dark Mode Typography

- Black text (#000) → White (#FFF)
- Dark gray text → Light gray text
- Background colors shift darker (maintain relative hierarchy)

```

### references/navigation.md

```markdown
# iOS Navigation Patterns

## Tab Bar (Primary Navigation)

The tab bar provides access to main app destinations.

- **Position**: Bottom of screen, always visible (except modals/keyboards)
- **Items**: 2-5 tabs maximum
- **Overflow**: Use "More" tab if >5 destinations needed
- **Selected state**: Fill color indicates active tab
- **Labels**: 10-11pt SF text
- **Background**: Slightly translucent with background blur ("frosted glass")

**Behavior**:
- Each tab remembers its navigation state
- Tapping active tab returns to root screen of that tab
- Tab bar hidden during modals and keyboard display

## Navigation Bar (Contextual Navigation)

- **Back button**: Top-left, allows return to previous screen
- **Actions**: Top-right, context-specific actions
- **Title**: Center (scrolled state) or left-aligned large title (unscrolled)

**Scroll Behavior**:
- Large title collapses to compact centered title on scroll
- Search bar can move or hide on scroll
- Smooth animated transitions between states

## Navigating Back

| Method | Context |
|--------|---------|
| "Back" button (top-left) | Standard navigation |
| Swipe right from left edge | Standard navigation |
| "Cancel" / "Done" button | Modal views |
| Swipe down on content | Modals, fullscreen media |

## Modal Sheets

Use modals for focused tasks that shouldn't interrupt context completely.

- Slides up from bottom
- Previous screen visible (recessed) in background
- Dismiss via: close button, swipe down, or completing task

```

### references/components.md

```markdown
# iOS UI Components

## Buttons

**Page-level actions**: Appear in nav bar (top) or action bar (bottom)

```
┌─────────────────────────────────┐
│ Cancel              Save  Edit  │  ← Nav bar actions
├─────────────────────────────────┤
│                                 │
│         Page Content            │
│                                 │
├─────────────────────────────────┤
│   Share    Copy    Delete       │  ← Action bar
└─────────────────────────────────┘
```

**On-page buttons**: Often appear on cards or sections

- Primary buttons: Filled with theme color
- Secondary buttons: Outlined or text-only
- Destructive actions: Red text/color

## Lists (Table Views)

Lists are fundamental to iOS design. Configure each row with:

**Left side** (optional):
- Icon or image

**Center**:
- Primary text (17pt regular)
- Secondary text (15pt or 12pt, lighter color)
- Tertiary text (if needed)

**Right side** (choose one):
- Chevron (→) — navigates to detail screen
- Text + Chevron — shows current value, tappable to change
- Checkmark (✓) — single selection from list
- Switch — toggle on/off
- Text button — action link

## Input Controls

Most inputs are styled as list items:

**Text Input**:
```
┌─────────────────────────────────┐
│ Email                           │  ← Hint text disappears on typing
└─────────────────────────────────┘
```

**Switch**:
```
┌─────────────────────────────────┐
│ Notifications          [====○] │
└─────────────────────────────────┘
```

**Date/Time Picker**:
```
┌─────────────────────────────────┐
│ Date          [ Jan 15, 2025 ] │  ← Light gray button, expands inline
└─────────────────────────────────┘
```

**Picker Screen Pattern**:
- List item shows current value + chevron
- Tapping navigates to selection screen
- Selected option marked with checkmark

## Pull-Down Menus

For short option lists without navigation:

```swift
Menu("Options") {
    Button("Edit", action: edit)
    Button("Share", action: share)
    Divider()
    Button("Delete", role: .destructive, action: delete)
}
```

## Touch Targets & Spacing

### Minimum Touch Target

**44 × 44 points** — This is non-negotiable for all interactive elements.

```swift
Button("Tap") {
    // Action
}
.frame(minWidth: 44, minHeight: 44)
```

### Standard Spacing Values

| Spacing | Usage |
|---------|-------|
| 8pt | Tight spacing (related elements) |
| 16pt | Standard spacing (sections) |
| 20pt | Screen edge margins |
| 24pt | Loose spacing (major sections) |

```swift
VStack(spacing: 16) {
    // Standard component spacing
}
```

```

### references/colors-depth.md

```markdown
# iOS Colors & Theming

## Semantic Colors

Use semantic colors that automatically adapt to light/dark mode:

```swift
Color(.label)              // Primary text
Color(.secondaryLabel)     // Secondary text
Color(.tertiaryLabel)      // Tertiary text
Color(.systemBackground)   // Primary background
Color(.secondarySystemBackground)  // Elevated/grouped
Color(.systemBlue)         // Default tint/accent
Color(.systemRed)          // Destructive actions
Color(.systemGreen)        // Success/confirmation
```

## Dark Mode Guidelines

1. **Text**: Invert colors (dark → light)
2. **Backgrounds**: Shift darker while maintaining relative hierarchy
3. **Accent colors**: Adjust to pop against dark backgrounds (often lower brightness, higher saturation)

```swift
// Preview both modes during development
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
            .preferredColorScheme(.light)
        ContentView()
            .preferredColorScheme(.dark)
    }
}
```

## Color Contrast

Minimum contrast ratios (WCAG):
- **4.5:1** for normal text
- **3:1** for large text (18pt+ or 14pt+ bold)
- **3:1** for UI components

```

### references/gestures.md

```markdown
# iOS Gestures & Interactions

## Standard Gestures (Never Override)

| Gesture | Standard Action |
|---------|-----------------|
| Swipe right from left edge | Navigate back |
| Swipe down on modal | Dismiss modal |
| Pull down on list | Refresh content |
| Swipe left on row | Reveal actions (delete, etc.) |
| Pinch | Zoom in/out |
| Long press | Context menu |

## Haptic Feedback

Provide tactile feedback for meaningful interactions:

```swift
// Impact feedback (physical actions)
let impact = UIImpactFeedbackGenerator(style: .medium)
impact.impactOccurred()

// Notification feedback (outcomes)
let notification = UINotificationFeedbackGenerator()
notification.notificationOccurred(.success)  // or .warning, .error

// Selection feedback (UI changes)
let selection = UISelectionFeedbackGenerator()
selection.selectionChanged()
```

## Animation Guidelines

- Use spring animations for natural, bouncy feel
- Respect `reduceMotion` accessibility setting
- Keep animations brief and purposeful

```swift
@Environment(\.accessibilityReduceMotion) var reduceMotion

var animation: Animation {
    reduceMotion ? .none : .spring()
}

withAnimation(animation) {
    // Animate property changes
}
```

```

### references/accessibility.md

```markdown
# iOS Accessibility

## VoiceOver Support

Every interactive element needs accessibility labels:

```swift
// Accessible label (what it is)
Image(systemName: "heart.fill")
    .accessibilityLabel("Favorite")

// Accessible value (current state)
Slider(value: $volume)
    .accessibilityLabel("Volume")
    .accessibilityValue("\(Int(volume * 100))%")

// Accessible hint (what it does)
Button("Share") { share() }
    .accessibilityHint("Shares this item with others")

// Group related elements
HStack {
    Image(systemName: "person")
    Text("John Doe")
}
.accessibilityElement(children: .combine)
```

## Dynamic Type

Support user font size preferences:

```swift
// Use semantic text styles (automatically scales)
Text("Content")
    .font(.body)

// For custom fonts, scale with Dynamic Type
@ScaledMetric var customSize: CGFloat = 16

Text("Custom")
    .font(.system(size: customSize))
```

## High Contrast Mode

```swift
@Environment(\.colorSchemeContrast) var contrast

var textColor: Color {
    contrast == .increased ? .primary : .secondary
}
```

## Accessibility Checklist

- [ ] All images have accessibility labels
- [ ] Touch targets are minimum 44×44pt
- [ ] Text scales with Dynamic Type
- [ ] Color contrast meets WCAG standards
- [ ] Motion can be reduced
- [ ] VoiceOver navigation is logical
- [ ] Don't rely solely on color to convey meaning

```

### references/app-icons.md

```markdown
# iOS App Icons

## Required Sizes

| Size | Usage |
|------|-------|
| 1024 × 1024px | App Store |
| 180 × 180px | iPhone home screen (@3x) |
| 120 × 120px | iPhone home screen (@2x), Spotlight |
| 167 × 167px | iPad Pro |
| 152 × 152px | iPad (@2x) |
| 87 × 87px | Settings |

## Icon Shape

iOS applies a **superellipse** ("squircle") mask automatically. Export icons as squares.

For custom border matching the shape:
- Corner radius = side length × 0.222
- Corner smoothing = 61% (iOS preset in Figma)

## Icon Guidelines

- Simple, recognizable silhouette
- Works at all sizes (remove fine details for small sizes)
- Consider light, dark, and tinted variants (iOS 18+)
- Avoid text in icons

```