Apple SwiftUI iOS Design Best Practices

Comprehensive guide for building Apple-quality iOS UIs with SwiftUI. Contains 62 rules across 8 categories covering design systems, state management, layout, view composition, navigation, components, accessibility, and animation polish.

When to Apply

Reference these guidelines when:

• Building new SwiftUI views and screens
• Implementing design systems with semantic colors, typography, and spacing
• Managing state with @State, @Binding, @Observable, @Environment
• Laying out content with stacks, grids, and adaptive layouts
• Composing views with @ViewBuilder and custom modifiers
• Implementing navigation with NavigationStack, TabView, sheets
• Choosing and configuring SwiftUI components
• Ensuring VoiceOver support, touch targets, and reduce motion
• Adding semantic transitions and loading state animations

Rule Categories by Priority

Quick Reference

1. Design System (CRITICAL)

• design-semantic-colors - Use semantic and system colors
• design-typography - Use system typography styles
• design-visual-hierarchy - Establish clear visual hierarchy
• design-dark-mode - Support Dark Mode from day one
• design-material-backgrounds - Use material backgrounds for depth
• design-sf-symbols - Use SF Symbols for consistent iconography
• design-safe-areas - Respect safe areas for content layout
• design-gradients - Apply gradients for visual depth
• design-foreground-style - Use foregroundStyle over foregroundColor

2. State & Data Flow (CRITICAL)

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

3. Layout & Sizing (HIGH)

• layout-8pt-grid - Use 8pt grid for spacing
• layout-readable-width - Constrain text to readable width on iPad
• layout-adaptive - Use adaptive layouts for different size classes
• layout-standard-margins - Use system standard margins
• layout-scroll-indicators - Show scroll indicators for long content
• layout-stacks - Use stacks instead of manual positioning
• layout-stack-config - Configure stack alignment and spacing
• layout-spacer - Use Spacer for flexible distribution
• layout-frame-sizing - Use frame() for explicit size constraints
• layout-zstack - Use ZStack for layered view composition
• layout-grid - Use Grid for aligned tabular layouts
• layout-lazy-grids - Use LazyVGrid for scrollable grid layouts

4. View Composition (HIGH)

• view-body-some-view - Return some View from body property
• view-custom-properties - Use properties to make views configurable
• view-modifier-order - Apply modifiers in correct order
• view-viewbuilder - Use @ViewBuilder for flexible composition
• view-prefer-value-types - Prefer value types for view data
• view-prefer-composition - Prefer composition over inheritance

5. Navigation (HIGH)

• nav-navigationstack - Use NavigationStack for modern navigation
• nav-tabview - Organize app sections with TabView
• nav-sheet-item - Use item binding for sheet presentation
• nav-dismiss - Use environment dismiss for modal closure
• nav-toolbar - Place toolbar items correctly
• nav-tab-bar - Use tab bar for top-level navigation
• nav-bar - Configure navigation bar
• nav-hierarchy - Design clear navigation hierarchy
• nav-search - Integrate search using searchable modifier

6. Components & Controls (HIGH)

• comp-list-vs-lazyvstack - Choose List vs LazyVStack by feature needs
• comp-sheet-vs-fullscreen - Choose sheet vs fullScreenCover
• comp-picker - Choose the right picker style
• comp-grid-vs-lazygrid - Choose Grid vs LazyVGrid by data size
• comp-textfield - Configure text input components
• comp-button - Use appropriate button styles
• comp-list-cells - Design list cells with standard layouts
• comp-alerts - Use alerts sparingly for critical information
• comp-action-sheets - Use action sheets for contextual choices
• comp-segmented - Use segmented controls for exclusive options
• comp-menus - Use menus for secondary actions
• comp-content-unavailable - Use ContentUnavailableView for empty states

7. Accessibility (HIGH)

• access-voiceover-labels - Add VoiceOver labels to interactive elements
• access-touch-targets - Ensure minimum 44pt touch targets
• access-reduce-motion - Respect reduce motion preference

8. Animation & Polish (MEDIUM)

• anim-transitions - Use semantic transitions for appearing views
• anim-loading-states - Animate loading and empty states
• anim-with-animation - Use withAnimation for explicit state changes
• anim-matched-geometry - Use matchedGeometryEffect for smooth view transitions

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files