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#

WrapperUse WhenOwnership@StateInternal view state (value type or @Observable class)View owns@BindingChild needs to modify parent's stateParent owns@BindableInjected @Observable object needing bindingsInjectedletRead-only value from parentInjectedvar + .onChange()Read-only value needing reactive updatesInjected

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#

DeprecatedModern AlternativeNotesforegroundColor()``foregroundStyle()Supports dynamic typecornerRadius()``.clipShape(.rect(cornerRadius:))More flexibleNavigationView``NavigationStackType-safe navigationtabItem()``Tab APIiOS 18+onTapGesture()``ButtonUnless need location/countonChange(of:) { value in }``onChange(of:) { old, new in } or onChange(of:) { }Two or zero parametersUIScreen.main.bounds``GeometryReader or layout APIsAvoid 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