swift-patterns
Review, refactor, or build SwiftUI features with correct state management, modern API usage, optimal view composition, and performance-conscious patterns. Prioritize native APIs, Apple design guidance, and testable code structure. This skill focuses on facts and best practices without enforcing specific architectural patterns.
Workflow Decision Tree 1) Review existing SwiftUI code
→ Read references/workflows-review.md for review methodology
Check state management against property wrapper selection (see references/state.md) Verify view composition and extraction patterns (see references/view-composition.md) Audit list performance and identity stability (see references/lists-collections.md) Validate modern API usage (see references/modern-swiftui-apis.md) Check async work patterns with .task (see references/concurrency.md) Verify navigation implementation (see references/navigation.md) Use Review Response Template (below) 2) Refactor existing SwiftUI code
→ Read references/workflows-refactor.md for refactor methodology
Extract complex views using playbooks (see references/refactor-playbooks.md) Migrate deprecated APIs to modern equivalents (see references/modern-swiftui-apis.md) Optimize performance hot paths (see references/performance.md) Restructure state ownership (see references/state.md) Apply common patterns (see references/patterns.md) Use Refactor Response Template (below) 3) Implement new SwiftUI features Design data flow first: identify owned vs injected state (see references/state.md) Structure views for optimal composition (see references/view-composition.md) Use modern APIs only (see references/modern-swiftui-apis.md) Handle async work with .task modifier (see references/concurrency.md) Apply performance patterns early (see references/performance.md) Implement navigation flows (see references/navigation.md) 4) Answer best practice questions Load relevant reference file(s) based on topic (see Reference Files below) Provide direct guidance with examples
If intent unclear, ask: "Do you want findings only (review), or should I change the code (refactor)?"
Response Templates
Review Response:
Scope - What was reviewed Findings - Grouped by severity with actionable statements Evidence - File paths or code locations Risks and tradeoffs - What could break or needs attention Next steps - What to fix first or verify
Refactor Response:
Intent + scope - What is being changed and why Changes - Bulleted list with file paths Behavior preservation - What should remain unchanged Next steps - Tests or verification needed Quick Reference: Property Wrapper Selection Wrapper Use When Ownership @State Internal view state (value type or @Observable class) View owns @Binding Child needs to modify parent's state Parent owns @Bindable Injected @Observable object needing bindings Injected let Read-only value from parent Injected var + .onChange() Read-only value needing reactive updates Injected
Key rules:
Always mark @State as private (makes ownership explicit) Never use @State for passed values (accepts initial value only) Use @State with @Observable classes (not @StateObject)
See references/state.md for detailed guidance and tradeoffs.
Quick Reference: Modern API Replacements Deprecated Modern Alternative Notes foregroundColor() foregroundStyle() Supports dynamic type cornerRadius() .clipShape(.rect(cornerRadius:)) More flexible NavigationView NavigationStack Type-safe navigation tabItem() Tab API iOS 18+ onTapGesture() Button Unless need location/count onChange(of:) { value in } onChange(of:) { old, new in } or onChange(of:) { } Two or zero parameters UIScreen.main.bounds GeometryReader or layout APIs Avoid hard-coded sizes
See references/modern-swiftui-apis.md for complete migration guide.
Review Checklist
Use this when reviewing SwiftUI code:
State Management @State properties marked private Passed values NOT declared as @State or @StateObject @Binding only where child modifies parent state Property wrapper selection follows ownership rules State ownership clear and intentional Modern APIs No deprecated modifiers (foregroundColor, cornerRadius, etc.) Using NavigationStack instead of NavigationView Using Button instead of onTapGesture when appropriate Using two-parameter or no-parameter onChange() View Composition Using modifiers over conditionals for state changes (maintains identity) Complex views extracted to separate subviews Views kept small and focused View body simple and pure (no side effects) Navigation & Sheets Using navigationDestination(for:) for type-safe navigation Using .sheet(item:) for model-based sheets Sheets own their dismiss actions Lists & Collections ForEach uses stable identity (never .indices for dynamic data) Constant number of views per ForEach element No inline filtering in ForEach (prefilter and cache) No AnyView in list rows Performance Passing only needed values to views (not large config objects) Eliminating unnecessary dependencies Checking value changes before state assignment in hot paths Using LazyVStack/LazyHStack for large lists No object creation in view body Async Work Using .task for automatic cancellation Using .task(id:) for value-dependent tasks Not mixing .onAppear with async work
See reference files for detailed explanations of each item.
Constraints Swift/SwiftUI focus only - Exclude server-side Swift and UIKit unless bridging required No Swift concurrency patterns - Use .task for SwiftUI async work No architecture mandates - Don't require MVVM/MVC/VIPER or specific structures No formatting/linting rules - Focus on correctness and patterns No tool-specific guidance - No Xcode, Instruments, or IDE instructions Citations allowed: developer.apple.com/documentation/swiftui/, developer.apple.com/documentation/swift/
All workflows must follow these constraints.
Philosophy
This skill focuses on facts and best practices from Apple's documentation:
Modern APIs over deprecated ones Clear state ownership patterns Performance-conscious view composition Testable code structure No architectural mandates (MVVM/VIPER not required) Apple Human Interface Guidelines adherence Reference Files
All references in references/:
workflows-review.md - Review methodology and findings taxonomy workflows-refactor.md - Refactor methodology and invariants refactor-playbooks.md - Step-by-step refactor guides state.md - Property wrappers and ownership patterns navigation.md - Navigation implementation patterns view-composition.md - View structure and extraction lists-collections.md - Identity and ForEach patterns scrolling.md - Scroll handling and pagination concurrency.md - Async work with .task performance.md - Optimization strategies testing-di.md - Testing and dependency injection patterns.md - Common SwiftUI patterns modern-swiftui-apis.md - Legacy API migration code-review-refactoring.md - Code quality checks