swift-patterns

name	swift-patterns
description	Review, refactor, or build SwiftUI features with correct state management, modern API usage, optimal view composition, navigation patterns, performance optimization, and testing best practices.

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

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