Swift Patterns

1---
2name: swift-patterns
3description: Review, refactor, or build SwiftUI features with correct state management, modern API usage, optimal view composition, navigation patterns, performance optimization, and testing best practices.
4---
5 
6# swift-patterns
7 
8Review, 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.
9 
10## Workflow Decision Tree
11 
12### 1) Review existing SwiftUI code
13→ Read `references/workflows-review.md` for review methodology
14- Check state management against property wrapper selection (see `references/state.md`)
15- Verify view composition and extraction patterns (see `references/view-composition.md`)
16- Audit list performance and identity stability (see `references/lists-collections.md`)
17- Validate modern API usage (see `references/modern-swiftui-apis.md`)
18- Check async work patterns with .task (see `references/concurrency.md`)
19- Verify navigation implementation (see `references/navigation.md`)
20- Use Review Response Template (below)
21 
22### 2) Refactor existing SwiftUI code
23→ Read `references/workflows-refactor.md` for refactor methodology
24- Extract complex views using playbooks (see `references/refactor-playbooks.md`)
25- Migrate deprecated APIs to modern equivalents (see `references/modern-swiftui-apis.md`)
26- Optimize performance hot paths (see `references/performance.md`)
27- Restructure state ownership (see `references/state.md`)
28- Apply common patterns (see `references/patterns.md`)
29- Use Refactor Response Template (below)
30 
31### 3) Implement new SwiftUI features
32- Design data flow first: identify owned vs injected state (see `references/state.md`)
33- Structure views for optimal composition (see `references/view-composition.md`)
34- Use modern APIs only (see `references/modern-swiftui-apis.md`)
35- Handle async work with .task modifier (see `references/concurrency.md`)
36- Apply performance patterns early (see `references/performance.md`)
37- Implement navigation flows (see `references/navigation.md`)
38 
39### 4) Answer best practice questions
40- Load relevant reference file(s) based on topic (see Reference Files below)
41- Provide direct guidance with examples
42 
43**If intent unclear, ask:** "Do you want findings only (review), or should I change the code (refactor)?"
44 
45## Response Templates
46 
47**Review Response:**
481. **Scope** - What was reviewed
492. **Findings** - Grouped by severity with actionable statements
503. **Evidence** - File paths or code locations
514. **Risks and tradeoffs** - What could break or needs attention
525. **Next steps** - What to fix first or verify
53 
54**Refactor Response:**
551. **Intent + scope** - What is being changed and why
562. **Changes** - Bulleted list with file paths
573. **Behavior preservation** - What should remain unchanged
584. **Next steps** - Tests or verification needed
59 
60## Quick Reference: Property Wrapper Selection
61 
62| Wrapper | Use When | Ownership |
63|---------|----------|-----------|
64| `@State` | Internal view state (value type or `@Observable` class) | View owns |
65| `@Binding` | Child needs to modify parent's state | Parent owns |
66| `@Bindable` | Injected `@Observable` object needing bindings | Injected |
67| `let` | Read-only value from parent | Injected |
68| `var` + `.onChange()` | Read-only value needing reactive updates | Injected |
69 
70**Key rules:**
71- Always mark `@State` as `private` (makes ownership explicit)
72- Never use `@State` for passed values (accepts initial value only)
73- Use `@State` with `@Observable` classes (not `@StateObject`)
74 
75See `references/state.md` for detailed guidance and tradeoffs.
76 
77## Quick Reference: Modern API Replacements
78 
79| Deprecated | Modern Alternative | Notes |
80|------------|-------------------|-------|
81| `foregroundColor()` | `foregroundStyle()` | Supports dynamic type |
82| `cornerRadius()` | `.clipShape(.rect(cornerRadius:))` | More flexible |
83| `NavigationView` | `NavigationStack` | Type-safe navigation |
84| `tabItem()` | `Tab` API | iOS 18+ |
85| `onTapGesture()` | `Button` | Unless need location/count |
86| `onChange(of:) { value in }` | `onChange(of:) { old, new in }` or `onChange(of:) { }` | Two or zero parameters |
87| `UIScreen.main.bounds` | `GeometryReader` or layout APIs | Avoid hard-coded sizes |
88 
89See `references/modern-swiftui-apis.md` for complete migration guide.
90 
91## Review Checklist
92 
93Use this when reviewing SwiftUI code:
94 
95### State Management
96- [ ] `@State` properties marked `private`
97- [ ] Passed values NOT declared as `@State` or `@StateObject`
98- [ ] `@Binding` only where child modifies parent state
99- [ ] Property wrapper selection follows ownership rules
100- [ ] State ownership clear and intentional
101 
102### Modern APIs
103- [ ] No deprecated modifiers (foregroundColor, cornerRadius, etc.)
104- [ ] Using `NavigationStack` instead of `NavigationView`
105- [ ] Using `Button` instead of `onTapGesture` when appropriate
106- [ ] Using two-parameter or no-parameter `onChange()`
107 
108### View Composition
109- [ ] Using modifiers over conditionals for state changes (maintains identity)
110- [ ] Complex views extracted to separate subviews
111- [ ] Views kept small and focused
112- [ ] View `body` simple and pure (no side effects)
113 
114### Navigation & Sheets
115- [ ] Using `navigationDestination(for:)` for type-safe navigation
116- [ ] Using `.sheet(item:)` for model-based sheets
117- [ ] Sheets own their dismiss actions
118 
119### Lists & Collections
120- [ ] `ForEach` uses stable identity (never `.indices` for dynamic data)
121- [ ] Constant number of views per `ForEach` element
122- [ ] No inline filtering in `ForEach` (prefilter and cache)
123- [ ] No `AnyView` in list rows
124 
125### Performance
126- [ ] Passing only needed values to views (not large config objects)
127- [ ] Eliminating unnecessary dependencies
128- [ ] Checking value changes before state assignment in hot paths
129- [ ] Using `LazyVStack`/`LazyHStack` for large lists
130- [ ] No object creation in view `body`
131 
132### Async Work
133- [ ] Using `.task` for automatic cancellation
134- [ ] Using `.task(id:)` for value-dependent tasks
135- [ ] Not mixing `.onAppear` with async work
136 
137See reference files for detailed explanations of each item.
138 
139## Constraints
140 
141- **Swift/SwiftUI focus only** - Exclude server-side Swift and UIKit unless bridging required
142- **No Swift concurrency patterns** - Use `.task` for SwiftUI async work
143- **No architecture mandates** - Don't require MVVM/MVC/VIPER or specific structures
144- **No formatting/linting rules** - Focus on correctness and patterns
145- **No tool-specific guidance** - No Xcode, Instruments, or IDE instructions
146- **Citations allowed:** `developer.apple.com/documentation/swiftui/`, `developer.apple.com/documentation/swift/`
147 
148All workflows must follow these constraints.
149 
150## Philosophy
151 
152This skill focuses on **facts and best practices** from Apple's documentation:
153- Modern APIs over deprecated ones
154- Clear state ownership patterns
155- Performance-conscious view composition
156- Testable code structure
157- No architectural mandates (MVVM/VIPER not required)
158- Apple Human Interface Guidelines adherence
159 
160## Reference Files
161 
162All references in `references/`:
163- `workflows-review.md` - Review methodology and findings taxonomy
164- `workflows-refactor.md` - Refactor methodology and invariants
165- `refactor-playbooks.md` - Step-by-step refactor guides
166- `state.md` - Property wrappers and ownership patterns
167- `navigation.md` - Navigation implementation patterns
168- `view-composition.md` - View structure and extraction
169- `lists-collections.md` - Identity and ForEach patterns
170- `scrolling.md` - Scroll handling and pagination
171- `concurrency.md` - Async work with .task
172- `performance.md` - Optimization strategies
173- `testing-di.md` - Testing and dependency injection
174- `patterns.md` - Common SwiftUI patterns
175- `modern-swiftui-apis.md` - Legacy API migration
176- `code-review-refactoring.md` - Code quality checks
177