Agent Skills: Apple Swift/SwiftUI Performance Optimization Best Practices

Apple Swift/SwiftUI Performance Optimization Best Practices

Comprehensive guide for Swift and SwiftUI performance optimization. Contains 19 rules across 3 categories covering modern concurrency, render performance, and animation performance. Targets iOS 26 / Swift 6.2 with @Observable and Swift 6 strict concurrency.

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:

• Migrating to Swift 6 strict concurrency (Sendable, actor isolation)
• Replacing Combine publishers with async/await
• Implementing @MainActor isolation and actor-based concurrency
• Decomposing views to reduce state invalidation blast radius
• Optimizing scroll and render performance with lazy containers
• Using Canvas/TimelineView for high-performance rendering
• Profiling with SwiftUI Instruments before optimizing
• Building performant spring animations and transitions

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Concurrency & Async | CRITICAL | conc- | | 2 | Render & Scroll Performance | HIGH | perf- | | 3 | Animation Performance | MEDIUM | anim- |

Quick Reference

1. Concurrency & Async (CRITICAL)

• conc-combine-to-async - Replace Combine publishers with async/await
• conc-mainactor-isolation - Use @MainActor instead of DispatchQueue.main
• conc-swift6-sendable - Adopt Sendable and Swift 6 strict concurrency
• conc-task-id-pattern - Use .task(id:) for reactive data loading
• conc-actor-for-shared-state - Replace lock-based shared state with actors
• conc-asyncsequence-streams - Replace NotificationCenter observers with AsyncSequence

2. Render & Scroll Performance (HIGH)

• perf-view-decomposition - Decompose views to limit state invalidation blast radius
• perf-instruments-profiling - Profile with SwiftUI Instruments before optimizing
• perf-lazy-containers - Use lazy containers for large collections
• perf-canvas-timeline - Use Canvas and TimelineView for high-performance rendering
• perf-drawinggroup - Use drawingGroup for complex graphics
• perf-equatable-views - Add Equatable conformance to prevent spurious redraws
• perf-task-modifier - Use .task modifier instead of .onAppear for async work
• perf-async-image - Use AsyncImage with caching strategy for remote images

3. Animation Performance (MEDIUM)

• anim-spring - Use spring animations as default
• anim-matchedgeometry - Use matchedGeometryEffect for shared transitions
• anim-gesture-driven - Make animations gesture-driven
• anim-with-animation - Use withAnimation for state-driven transitions
• anim-transition-effects - Apply transition effects for view insertion and removal

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

| File | Description | |------|-------------| | references/_sections.md | Category definitions and ordering | | assets/templates/_template.md | Template for new rules |