iOS Design

Apple SwiftUI iOS Design Best Practices

A builder's guide for implementing Apple-quality iOS interfaces in SwiftUI, grounded in two foundational design texts:

• Ken Kocienda — Creative Selection (empathy for the user, craft in coding, taste in choosing the best solution, demo culture of iterative refinement)
• John Edson — Design Like Apple (systems thinking, the product is the marketing, design out loud, design with conviction)

Contains 62 rules across 8 principle-based categories. Each rule identifies a specific anti-pattern, grounds the fix in a named principle, and provides the correct iOS 26 / Swift 6.2 SwiftUI implementation.

Scope & Relationship to Sibling Skills

This skill is the building and implementation guide — it teaches how to construct new SwiftUI interfaces from scratch using Apple-quality patterns. When loaded alongside ios-ui-refactor (reviewing/refactoring existing UI), this skill covers the greenfield implementation that ios-ui-refactor later audits. Use this skill for building new screens; use the sibling for evaluating and improving existing ones.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Building new SwiftUI views and screens from scratch
• Choosing between semantic colors, system typography, and spacing grids (Edson's Systems Thinking)
• Managing state with @State, @Binding, @Observable, @Environment (Kocienda's Craft)
• Selecting the right component: List vs LazyVStack, Sheet vs FullScreenCover (Kocienda's Taste)
• Composing views with @ViewBuilder, custom modifiers, and value types (Kocienda's Creative Selection)
• Implementing navigation with NavigationStack, TabView, sheets (Edson's Conversation)
• Laying out content with stacks, grids, frames, and adaptive layouts (Edson's Design Out Loud)
• Ensuring VoiceOver, touch targets, Dark Mode, and reduce motion support (Kocienda's Empathy)
• Adding transitions, loading states, and animation polish (Edson's Product Is the Marketing)

Rule Categories by Priority

Quick Reference

1. Empathy in Every Pixel (CRITICAL)

Kocienda: "Empathy — trying to see the world from other people's perspectives." Edson: design begins with the person holding the device.

• `empathy-semantic-colors` - Use semantic colors, never hard-coded values
• `empathy-dark-mode` - Support Dark Mode from day one
• `empathy-foreground-style` - Use foregroundStyle over foregroundColor
• `empathy-safe-areas` - Always respect safe areas for content
• `empathy-voiceover-labels` - Add VoiceOver labels to every interactive element
• `empathy-touch-targets` - Ensure 44x44 point minimum touch targets
• `empathy-reduce-motion` - Always provide reduce motion fallback
• `empathy-readable-width` - Constrain text to readable width on iPad

2. The Visual System (CRITICAL)

Edson: "Zoom out to see relationships between objects." Kocienda: convergence — many decisions narrowing toward one coherent whole.

• `system-typography` - Use system typography styles, never fixed sizes
• `system-visual-hierarchy` - Establish clear visual hierarchy through size, weight, and color
• `system-spacing-grid` - Use a 4pt base unit for all spacing
• `system-material-backgrounds` - Use material backgrounds for depth and layering
• `system-sf-symbols` - Use SF Symbols for consistent iconography
• `system-gradients` - Apply gradients for visual depth, not decoration
• `system-standard-margins` - Use system standard margins consistently
• `system-stack-config` - Configure stack alignment and spacing explicitly

3. Craft: State as Foundation (CRITICAL)

Kocienda: "Craft — applying skill to achieve a high-quality result."

• `craft-state-local` - Use @State for view-local value types
• `craft-state-binding` - Use @Binding for child view mutations
• `craft-state-environment` - Use @Environment for shared app-wide data
• `craft-state-observable` - Use @Observable for model classes
• `craft-avoid-body-state` - Never create state inside the view body
• `craft-minimize-scope` - Minimize state scope to reduce re-renders
• `craft-state-bindable` - Use @Bindable for @Observable bindings

4. Creative Composition (HIGH)

Kocienda: "Creative selection — great software is built through composition and recombination."

• `compose-body-some-view` - Return some View from body, never concrete types
• `compose-custom-properties` - Use properties to make views configurable
• `compose-modifier-order` - Apply view modifiers in the correct order
• `compose-viewbuilder` - Use @ViewBuilder for flexible slot-based composition
• `compose-prefer-value-types` - Prefer value types for view data
• `compose-prefer-composition` - Prefer composition over inheritance for view reuse

5. Taste: The Right Choice (HIGH)

Kocienda: "Taste — refined judgment, the ability to choose the one right solution." Edson: commit to one approach and perfect it.

• `taste-list-vs-lazyvstack` - Choose List for system features, LazyVStack for custom layouts
• `taste-sheet-vs-fullscreen` - Choose sheet for tasks, fullScreenCover for immersion