// Use when implementing iOS 17+ SwiftUI patterns: @Observable/@Bindable, MVVM architecture, NavigationStack, lazy loading, UIKit interop, accessibility (VoiceOver/Dynamic Type), async operations (.task/.refreshable), or migrating from ObservableObject/@StateObject.
Use when building features with TCA (The Composable Architecture), structuring reducers, managing state, handling effects, navigation, or testing TCA features. Covers @Reducer, Store, Effect, TestStore, reducer composition, and TCA patterns.
Use when implementing iOS 26 features (Liquid Glass, new SwiftUI APIs, WebView, Chart3D), deploying iOS 26+ apps, or supporting backward compatibility with iOS 17/18.
Use when writing async/await code, enabling strict concurrency, fixing Sendable errors, migrating from completion handlers, managing shared state with actors, or using Task/TaskGroup for concurrency.
Use when implementing on-device AI with Apple's Foundation Models framework (iOS 26+), building summarization/extraction/classification features, or using @Generable for type-safe structured output.
Use when writing raw SQL with GRDB, complex joins across 4+ tables, window functions, ValueObservation for reactive queries, or dropping down from SQLiteData for performance. Direct SQLite access for iOS/macOS with type-safe queries and migrations.
Use when adding haptic feedback for user confirmations (button presses, toggles, purchases), error notifications, or custom tactile patterns (Core Haptics). Covers UIFeedbackGenerator and CHHapticEngine patterns.
| name | swiftui-patterns |
| description | Use when implementing iOS 17+ SwiftUI patterns: @Observable/@Bindable, MVVM architecture, NavigationStack, lazy loading, UIKit interop, accessibility (VoiceOver/Dynamic Type), async operations (.task/.refreshable), or migrating from ObservableObject/@StateObject. |
SwiftUI 17+ removes ObservableObject boilerplate with @Observable, simplifies environment injection with @Environment, and introduces task-based async patterns. The core principle: use Apple's modern APIs instead of reactive libraries.
| Need | Use (iOS 17+) | NOT |
|---|---|---|
| Observable model | @Observable | ObservableObject |
| Published property | Regular property | @Published |
| Own state | @State | @StateObject |
| Passed model (binding) | @Bindable | @ObservedObject |
| Environment injection | environment(_:) | environmentObject(_:) |
| Environment access | @Environment(Type.self) | @EnvironmentObject |
| Async on appear | .task { } | .onAppear { Task {} } |
| Value change | onChange(of:initial:_:) | onChange(of:perform:) |
@Observable for model classes (no @Published needed)@State for view-owned models, @Bindable for passed models.task { } for async work (auto-cancels on disappear)NavigationStack with NavigationPath for programmatic navigation.accessibilityLabel() and .accessibilityHint() to interactive elementsALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.
| Reference | Load When |
|---|---|
| Observable | Creating new @Observable model classes |
| State Management | Deciding between @State, @Bindable, @Environment |
| Environment | Injecting dependencies into view hierarchy |
| View Modifiers | Using onChange, task, or iOS 17+ modifiers |
| Migration Guide | Updating iOS 16 code to iOS 17+ |
| MVVM Observable | Setting up view model architecture |
| Navigation | Programmatic or deep-link navigation |
| Performance | Lists with 100+ items or excessive re-renders |
| UIKit Interop | Wrapping UIKit components (WKWebView, PHPicker) |
| Accessibility | VoiceOver, Dynamic Type, accessibility actions |
| Async Patterns | Loading states, refresh, background tasks |
| Composition | Reusable view modifiers or complex conditional UI |
Over-using @Bindable for passed models — Creating @Bindable for every property causes unnecessary view reloads. Use @Bindable only for mutable model properties that need two-way binding. Read-only computed properties should use regular properties.
State placement errors — Putting model state in the view instead of a dedicated @Observable model causes view logic to become tangled. Always separate model and view concerns.
NavigationPath state corruption — Mutating NavigationPath incorrectly can leave it in inconsistent state. Use navigationDestination(for:destination:) with proper state management to avoid path corruption.
Missing .task cancellation — .task handles cancellation on disappear automatically, but nested Tasks don't. Complex async flows need explicit cancellation tracking to avoid zombie tasks.
Ignoring environment invalidation — Changing environment values at parent doesn't invalidate child views automatically. Use @Environment consistently and understand when re-renders happen based on observation.
UIKit interop memory leaks — UIViewRepresentable and UIViewControllerRepresentable can leak if delegate cycles aren't broken. Weak references and explicit cleanup are required.