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