Apple Design Patterns SwiftUI Best Practices

Comprehensive guide for building Apple-quality iOS app UIs with SwiftUI, designed for AI agents to achieve principal-level one-shot native app development. Contains 51 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Building new SwiftUI views and screens

• Implementing navigation flows and modal presentations

• Adding animations, haptics, and transitions

• Ensuring accessibility compliance (VoiceOver, Dynamic Type)

• Optimizing performance for smooth 120fps scrolling

Rule Categories by Priority

Priority Category Impact Prefix

1 Data Flow & State Management CRITICAL state-

2 Visual Design System CRITICAL design-

3 Component Selection HIGH comp-

4 Navigation Patterns HIGH nav-

5 View Composition HIGH view-

6 Animation & Haptics MEDIUM-HIGH anim-

7 Accessibility MEDIUM-HIGH acc-

8 Lists & Scroll Performance MEDIUM perf-

9 Platform Integration MEDIUM platform-

Quick Reference

1. Data Flow & State Management (CRITICAL)

• state-observable-macro

• Use @Observable for model classes

• state-use-state-for-view-local

• Use @State for view-local value types

• state-binding-for-child-mutation

• Use @Binding for child view mutations

• state-environment-for-shared-data

• Use @Environment for shared app data

• state-avoid-state-in-body

• Avoid creating state inside view body

• state-minimize-state-scope

• Minimize state scope to reduce re-renders

2. Visual Design System (CRITICAL)

• design-typography-system-fonts

• Use system typography styles

• design-spacing-hig-values

• Use HIG-compliant spacing values

• design-colors-semantic-system

• Use semantic system colors

• design-safe-areas

• Respect safe areas for content layout

• design-visual-hierarchy

• Establish clear visual hierarchy

• design-padding-consistency

• Apply consistent padding patterns

• design-dark-mode-support

• Support Dark Mode from day one

• design-material-backgrounds

• Use material backgrounds for depth

3. Component Selection (HIGH)

• comp-list-vs-lazyvstack

• Choose List vs LazyVStack by feature needs

• comp-sheet-vs-fullscreen

• Choose sheet vs fullScreenCover by content type

• comp-picker-variants

• Choose the right picker style

• comp-grid-vs-lazygrid

• Choose Grid vs LazyVGrid by data size

• comp-textfield-vs-texteditor

• Choose TextField vs TextEditor by content length

• comp-button-vs-toggle

• Choose Button vs Toggle by interaction type

4. Navigation Patterns (HIGH)

• nav-navigationstack-modern

• Use NavigationStack for modern navigation

• nav-tabview-organization

• Organize app sections with TabView

• nav-sheet-item-binding

• Use item binding for sheet presentation

• nav-dismiss-environment

• Use environment dismiss for modal closure

• nav-toolbar-placement

• Place toolbar items correctly

5. View Composition (HIGH)

• view-extract-subviews

• Extract subviews for composition

• view-avoid-anyview

• Avoid AnyView for type erasure

• view-equatable-conformance

• Conform views to Equatable for diffing

• view-prefer-value-types

• Prefer value types for view data

• view-viewbuilder-composition

• Use @ViewBuilder for flexible composition

• view-modifier-order

• Apply modifiers in correct order

6. Animation & Haptics (MEDIUM-HIGH)

• anim-spring-default

• Use spring animations as default

• anim-haptic-feedback

• Add haptic feedback for interactions

• anim-matchedgeometry

• Use matchedGeometryEffect for shared transitions

• anim-transition-modifiers

• Use semantic transitions for appearing views

• anim-gesture-driven

• Make animations gesture-driven

• anim-loading-states

• Animate loading and empty states

7. Accessibility (MEDIUM-HIGH)

• acc-accessibility-labels

• Add accessibility labels to interactive elements

• acc-dynamic-type-support

• Support Dynamic Type for all text

• acc-touch-targets

• Ensure minimum touch target size

• acc-color-contrast

• Maintain sufficient color contrast

• acc-reduce-motion

• Respect reduce motion preference

8. Lists & Scroll Performance (MEDIUM)

• perf-lazy-loading

• Use lazy containers for large collections

• perf-async-image

• Use AsyncImage for remote images

• perf-task-modifier

• Use task modifier for async work

• perf-drawinggroup

• Use drawingGroup for complex graphics

• perf-instruments-profiling

• Profile SwiftUI with Instruments

9. Platform Integration (MEDIUM)

• platform-sf-symbols

• Use SF Symbols for consistent iconography

• platform-system-features

• Integrate system features natively

• platform-app-storage

• Use AppStorage for user preferences

• platform-scene-phase

• Respond to app lifecycle with ScenePhase

• platform-widget-integration

• Design for widget and Live Activity integration

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

Full Compiled Document

For a complete compiled guide with all rules in a single document, see AGENTS.md.

Reference Files

File Description

AGENTS.md Complete compiled guide with all rules

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information