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