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:

1. Scope - What was reviewed
2. Findings - Grouped by severity with actionable statements
3. Evidence - File paths or code locations
4. Risks and tradeoffs - What could break or needs attention
5. Next steps - What to fix first or verify

Refactor Response:

1. Intent + scope - What is being changed and why
2. Changes - Bulleted list with file paths
3. Behavior preservation - What should remain unchanged
4. Next steps - Tests or verification needed

Quick Reference: Property Wrapper Selection

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

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