@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-patterns/SKILL.md

@@ -1,212 +1,249 @@
 ---
 name: swiftui-patterns
-description: "Builds SwiftUI views with MV architecture: @Observable ownership, @State/@Bindable/@Environment wiring, view decomposition, custom ViewModifiers, .task data loading, iOS 26+ APIs and Writing Tools. Use when structuring a SwiftUI app, managing state with @Observable or composing view hierarchies; for a findings-by-file review use swiftui-pro, for screen wiring swiftui-ui-patterns."
+description: "SwiftUI Model-View structure: @Observable ownership, @State, @Bindable, @Environment, view decomposition, custom ViewModifiers, .task loading, iOS 26 APIs, Writing Tools. Use when structuring a SwiftUI app, managing state, composing or splitting views, or adopting iOS 26 APIs. Not for file-by-file review (swiftui-pro) or single-screen wiring (swiftui-ui-patterns)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # SwiftUI Patterns
 
-Modern SwiftUI patterns targeting iOS 26+ with Swift 6.3. Covers architecture, state management, view composition, environment wiring, async loading, design polish, and platform/share integration. Navigation and layout patterns live in dedicated sibling skills. Patterns are backward-compatible to iOS 17 unless noted.
+How to shape a SwiftUI code base so views stay small, state has one clear
+owner, and business logic lives outside `body`. Examples target iOS 26 and
+Swift 6.3. Everything here also compiles for an iOS 17 deployment target unless
+a line names a newer release.
 
-## Contents
-
-- [Architecture: Model-View (MV) Pattern](#architecture-model-view-mv-pattern)
-- [State Management](#state-management)
-- [View Ordering Convention](#view-ordering-convention)
-- [View Composition](#view-composition)
-- [Environment](#environment)
-- [Async Data Loading](#async-data-loading)
-- [iOS 26+ New APIs](#ios-26-new-apis)
-- [Performance Guidelines](#performance-guidelines)
-- [HIG Alignment](#hig-alignment)
-- [Writing Tools (iOS 18+)](#writing-tools-ios-18)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-**Scope boundary:** This skill covers architecture, state ownership, composition, environment wiring, async loading, and related SwiftUI app structure patterns. Detailed navigation patterns are covered in the `swiftui-navigation` skill, including `NavigationStack`, `NavigationSplitView`, sheets, tabs, and deep-linking patterns. Detailed layout, container, and component patterns are covered in the `swiftui-layout-components` skill, including stacks, grids, lists, scroll view patterns, forms, controls, search UI with `.searchable`, overlays, and related layout components.
+Two neighbouring topics are handled elsewhere on purpose:
 
-## Architecture: Model-View (MV) Pattern
+- Navigation (`NavigationStack`, `NavigationSplitView`, sheets, tabs, deep
+  links): `swiftui-navigation`.
+- Layout and controls (stacks, grids, lists, scroll views, forms, `.searchable`,
+  overlays): `swiftui-layout-components`.
 
-Default to MV -- views are lightweight state expressions; models and services own business logic. Do not introduce view models unless the existing code already uses them.
+## Contents
 
-**Core principles:**
-- Favor `@State`, `@Environment`, `@Query`, `.task`, and `.onChange` for orchestration
-- Inject services and shared models via `@Environment`; keep views small and composable
-- Split large views into smaller subviews rather than introducing a view model
-- Test models, services, and business logic; keep views simple and declarative
+1. [Model-View by Default](#1-model-view-by-default)
+2. [Owning and Passing Observable State](#2-owning-and-passing-observable-state)
+3. [Member Order Inside a View](#3-member-order-inside-a-view)
+4. [Splitting Views Up](#4-splitting-views-up)
+5. [Environment Values](#5-environment-values)
+6. [Loading Data with .task](#6-loading-data-with-task)
+7. [iOS 26 Additions](#7-ios-26-additions)
+8. [Performance](#8-performance)
+9. [Following the HIG](#9-following-the-hig)
+10. [Writing Tools (iOS 18+)](#10-writing-tools-ios-18)
+11. [Common Mistakes](#11-common-mistakes)
+12. [Review Checklist](#12-review-checklist)
+13. [References](#13-references)
+
+## 1. Model-View by Default
+
+A view describes what the screen looks like for a given state. Models and
+services own the rules, the networking and the persistence. That split is the
+Model-View (MV) approach, and it is the default here.
+
+- Do not introduce a view model unless the project already uses them.
+- Let SwiftUI coordinate the flow: `@State`, `@Environment`, `@Query`, `.task`
+  and `.onChange` are the orchestration tools.
+- Put services and shared models in the environment. Keep each view small and
+  composable.
+- A growing view gets split into subviews, not given a view model.
+- Unit tests target models, services and business rules. Views stay declarative
+  enough that they do not need their own tests.
 
 ```swift
-struct FeedView: View {
-    @Environment(FeedClient.self) private var client
+struct RecipeListView: View {
+    @Environment(RecipeService.self) private var service
 
-    enum ViewState {
-        case loading, error(String), loaded([Post])
+    enum Phase {
+        case fetching
+        case failed(String)
+        case ready([Recipe])
     }
 
-    @State private var viewState: ViewState = .loading
+    @State private var phase: Phase = .fetching
 
     var body: some View {
         List {
-            switch viewState {
-            case .loading:
+            switch phase {
+            case .fetching:
                 ProgressView()
-            case .error(let message):
-                ContentUnavailableView("Error", systemImage: "exclamationmark.triangle",
+            case .failed(let message):
+                ContentUnavailableView("Recipes unavailable",
+                                       systemImage: "exclamationmark.triangle",
                                        description: Text(message))
-            case .loaded(let posts):
-                ForEach(posts) { post in
-                    PostRow(post: post)
-                }
+            case .ready(let recipes):
+                ForEach(recipes) { RecipeRow(recipe: $0) }
             }
         }
-        .task { await loadFeed() }
-        .refreshable { await loadFeed() }
+        .task { await reload() }
+        .refreshable { await reload() }
     }
 
-    private func loadFeed() async {
+    private func reload() async {
         do {
-            let posts = try await client.getFeed()
-            viewState = .loaded(posts)
+            phase = .ready(try await service.recipes())
         } catch {
-            viewState = .error(error.localizedDescription)
+            phase = .failed(error.localizedDescription)
         }
     }
 }
 ```
 
-For MV pattern rationale, app wiring, and lightweight client examples, see [references/architecture-patterns.md](references/architecture-patterns.md).
-
-## State Management
+Why MV, when a view model is still justified, and how to wire an app shell:
+[references/architecture-patterns.md](references/architecture-patterns.md).
 
-### `@Observable` Ownership Rules
+## 2. Owning and Passing Observable State
 
-**Important:** Always annotate `@Observable` view model classes with `@MainActor` to ensure UI-bound state is updated on the main thread. Required for Swift 6 concurrency safety.
+Mark every `@Observable` class that backs UI with `@MainActor`. Its properties
+are read by views on the main actor, and Swift 6 strict concurrency rejects
+unisolated mutation.
 
-| Wrapper | When to Use |
-|---------|-------------|
-| `@State` | View owns the object or value. Creates and manages lifecycle. |
-| `let` | View receives an `@Observable` object. Read-only observation -- no wrapper needed. |
-| `@Bindable` | View receives an `@Observable` object and needs two-way bindings (`$property`). |
-| `@Environment(Type.self)` | Access shared `@Observable` object from environment. |
-| `@State` (value types) | View-local simple state: toggles, counters, text field values. Always `private`. |
-| `@Binding` | Two-way connection to parent's `@State` or `@Bindable` property. |
+| Situation | Declaration |
+|---|---|
+| The view creates the object and controls its lifetime | `@State private var store = Store()` |
+| The view gets an `@Observable` object and only reads it | `let store: Store` (no wrapper) |
+| The view gets an `@Observable` object and needs `$` bindings | `@Bindable var store: Store` |
+| The object is shared through the environment | `@Environment(Store.self) private var store` |
+| Simple view-local value (flag, counter, field text) | `@State private var isExpanded = false` |
+| Two-way link to a parent's `@State` or `@Bindable` property | `@Binding var isExpanded: Bool` |
 
-### Ownership Pattern
+`@State` for values is always `private`: nobody outside the view should set it.
 
 ```swift
-// @Observable view model -- always @MainActor
-@MainActor
-@Observable final class ItemStore {
-    var title = ""
-    var items: [Item] = []
+@MainActor @Observable
+final class PlaylistStore {
+    var name = ""
+    var tracks: [Track] = []
+    var isSyncing = false
 }
 
-// View that OWNS the model
-struct ParentView: View {
-    @State var viewModel = ItemStore()
+struct PlaylistScreen: View {
+    @State private var store = PlaylistStore()
 
     var body: some View {
-        ChildView(store: viewModel)
-            .environment(viewModel)
+        VStack {
+            PlaylistHeader(store: store)
+            PlaylistNameField(store: store)
+            PlaylistFooter()
+        }
+        .environment(store)
     }
 }
 
-// View that READS (no wrapper needed for @Observable)
-struct ChildView: View {
-    let store: ItemStore
-
-    var body: some View { Text(store.title) }
+struct PlaylistHeader: View {
+    let store: PlaylistStore
+    var body: some View { Text(store.name) }
 }
 
-// View that BINDS (needs two-way access)
-struct EditView: View {
-    @Bindable var store: ItemStore
-
-    var body: some View {
-        TextField("Title", text: $store.title)
-    }
+struct PlaylistNameField: View {
+    @Bindable var store: PlaylistStore
+    var body: some View { TextField("Name", text: $store.name) }
 }
 
-// View that reads from ENVIRONMENT
-struct DeepView: View {
-    @Environment(ItemStore.self) var store
+struct PlaylistFooter: View {
+    @Environment(PlaylistStore.self) private var store
 
     var body: some View {
-        @Bindable var s = store
-        TextField("Title", text: $s.title)
+        @Bindable var editable = store
+        Toggle("Syncing", isOn: $editable.isSyncing)
     }
 }
 ```
 
-**Granular tracking:** SwiftUI only re-renders views that read properties that changed. If a view reads `items` but not `isLoading`, changing `isLoading` does not trigger a re-render. This is a major performance advantage over `ObservableObject`.
+The last view shows the trick for environment objects: declare a local
+`@Bindable` copy inside `body` to get `$` bindings.
 
-### Legacy ObservableObject
+Observation is tracked per property. `PlaylistHeader` reads only `name`, so a
+change to `tracks` or `isSyncing` does not re-evaluate it. `ObservableObject`
+invalidates every subscriber on any `@Published` change, so this alone removes
+a large share of wasted updates.
 
-Only use if supporting iOS 16 or earlier. `@StateObject` → `@State`, `@ObservedObject` → `let`, `@EnvironmentObject` → `@Environment(Type.self)`.
+### ObservableObject in older targets
 
-## View Ordering Convention
+Keep `ObservableObject` only for a deployment target of iOS 16 or earlier. When
+moving to Observation:
 
-Order members top to bottom: 1) `@Environment` 2) `let` properties 3) `@State` / stored properties 4) computed `var` 5) `init` 6) `body` 7) view builders / helpers 8) async functions
+| Before | After |
+|---|---|
+| `@StateObject` | `@State` |
+| `@ObservedObject` | `let` (or `@Bindable` for bindings) |
+| `@EnvironmentObject` | `@Environment(Type.self)` |
 
-## View Composition
+## 3. Member Order Inside a View
 
-### Extract Subviews
+Keep the same top-to-bottom order in every view file:
 
-Break views into focused subviews. Each should have a single responsibility.
+1. `@Environment` properties
+2. `let` properties
+3. `@State` and other stored properties
+4. computed `var`s
+5. `init`
+6. `body`
+7. view builders and other helpers
+8. `async` functions
+
+## 4. Splitting Views Up
+
+### Subview structs
+
+Give each piece one job and pass it plain values and closures:
 
 ```swift
 var body: some View {
-    VStack {
-        HeaderSection(title: title, isPinned: isPinned)
-        DetailsSection(details: details)
-        ActionsSection(onSave: onSave, onCancel: onCancel)
+    VStack(alignment: .leading) {
+        TicketSummary(event: event, seat: seat)
+        TicketBarcode(code: ticket.code)
+        TicketActions(onTransfer: transfer, onRefund: refund)
     }
 }
 ```
 
-### Computed View Properties
+### Computed view properties
 
-Keep related subviews as computed properties in the same file; extract to a standalone `View` struct when reuse is intended or the subview carries its own state.
+Pieces that only make sense in one file can stay as private computed
+properties. Promote one to its own `View` struct once it is reused elsewhere or
+needs its own state.
 
 ```swift
 var body: some View {
     List {
-        header
-        filters
-        results
+        banner
+        sortControls
+        matches
     }
 }
 
-private var header: some View {
+private var banner: some View {
     VStack(alignment: .leading) {
-        Text(title).font(.title2)
-        Text(subtitle).font(.subheadline)
+        Text(league.name).font(.title2)
+        Text(league.season).font(.subheadline)
     }
 }
 ```
 
-### ViewBuilder Functions
+### @ViewBuilder functions
 
-For conditional logic that does not warrant a separate struct:
+Branching that does not justify a struct fits a private builder function:
 
 ```swift
 @ViewBuilder
-private func statusBadge(for status: Status) -> some View {
-    switch status {
-    case .active: Text("Active").foregroundStyle(.green)
-    case .inactive: Text("Inactive").foregroundStyle(.secondary)
+private func deliveryLabel(for state: DeliveryState) -> some View {
+    switch state {
+    case .delivered:
+        Text("Delivered").foregroundStyle(.green)
+    case .inTransit, .pending:
+        Text("On the way").foregroundStyle(.secondary)
     }
 }
 ```
 
-### Custom View Modifiers
+### Custom view modifiers
 
-Extract repeated styling into `ViewModifier`:
+When the same styling appears in several places, move it into a
+`ViewModifier` and expose a `View` extension:
 
 ```swift
-struct CardStyle: ViewModifier {
+struct TileBackground: ViewModifier {
     func body(content: Content) -> some View {
         content
             .padding()
@@ -215,185 +252,212 @@ struct CardStyle: ViewModifier {
             .shadow(radius: 2)
     }
 }
-extension View { func cardStyle() -> some View { modifier(CardStyle()) } }
+
+extension View {
+    func tileBackground() -> some View { modifier(TileBackground()) }
+}
 ```
 
-### Stable View Tree
+### Keep the tree stable
 
-Avoid top-level conditional view swapping. Prefer a single stable base view with conditions inside sections or modifiers. When a view file exceeds ~300 lines, split with extensions and `// MARK: -` comments.
+Do not swap entire view hierarchies with an `if` at the top of `body`. Keep one
+base view and move conditions into sections or modifier arguments, so SwiftUI
+keeps identity and state. Once a view file passes roughly 300 lines, split it
+into extensions separated by `// MARK: -`.
 
-## Environment
+## 5. Environment Values
 
-### Custom Environment Values
+### Custom values with @Entry
 
-Use `@Entry` for custom environment values and actions. It generates the entry boilerplate for `EnvironmentValues`.
+Declare custom values and actions with the `@Entry` macro inside an
+`EnvironmentValues` extension. The macro writes the key type for you.
 
 ```swift
 extension EnvironmentValues {
-    @Entry var theme: Theme = .default
-    @Entry var refreshFeed: @Sendable () async -> Void = {}
+    @Entry var palette: Palette = .standard
+    @Entry var syncNow: @Sendable () async -> Void = {}
 }
 
-// Usage
-.environment(\.theme, customTheme)
-.environment(\.refreshFeed) { await feedStore.refresh() }
+// Supplying values
+InboxView()
+    .environment(\.palette, .highContrast)
+    .environment(\.syncNow) { await mailbox.sync() }
 
-@Environment(\.theme) private var theme
-@Environment(\.refreshFeed) private var refreshFeed
+// Reading them
+@Environment(\.palette) private var palette
+@Environment(\.syncNow) private var syncNow
 ```
 
-For iOS 17-compatible code or older compatibility shims, use manual `EnvironmentKey` types instead.
+`@Entry` is a macro that ships with the Xcode 16 SDK and expands to an ordinary
+`EnvironmentKey`, so it works for any deployment target, iOS 17 included. Write
+a manual `EnvironmentKey` conformance only when the project still builds with
+an older Xcode.
 
-### Common Built-in Environment Values
+### Built-in values used most often
 
-```swift
-@Environment(\.dismiss) var dismiss
-@Environment(\.colorScheme) var colorScheme
-@Environment(\.dynamicTypeSize) var dynamicTypeSize
-@Environment(\.horizontalSizeClass) var sizeClass
-@Environment(\.isSearching) var isSearching
-@Environment(\.openURL) var openURL
-@Environment(\.modelContext) var modelContext
-```
+`\.dismiss`, `\.colorScheme`, `\.dynamicTypeSize`, `\.horizontalSizeClass`,
+`\.isSearching`, `\.openURL`, `\.modelContext`.
 
-## Async Data Loading
+## 6. Loading Data with .task
 
-Always use `.task` -- it cancels automatically on view disappear:
+Start async work with `.task`. SwiftUI cancels it when the view goes away.
 
 ```swift
-struct ItemListView: View {
-    @State var store = ItemStore()
+struct ForecastView: View {
+    @State private var store = ForecastStore()
 
     var body: some View {
-        List(store.items) { item in
-            ItemRow(item: item)
-        }
-        .task { await store.load() }
-        .refreshable { await store.refresh() }
+        List(store.days) { DayRow(day: $0) }
+            .task { await store.load() }
+            .refreshable { await store.reload() }
     }
 }
 ```
 
-Use `.task(id:)` to re-run when a dependency changes:
+`.task(id:)` cancels and restarts whenever the id changes:
 
 ```swift
-.task(id: searchText) {
-    guard !searchText.isEmpty else { return }
-    await search(query: searchText)
+.task(id: query) {
+    guard !query.isEmpty else { return }
+    await lookUp(query)
 }
 ```
 
-Never create manual `Task` in `onAppear` unless you need to store a reference for cancellation. Exception: `Task {}` is acceptable in synchronous action closures (e.g., Button actions) for immediate state updates before async work.
-
-## iOS 26+ New APIs
-
-- **`.scrollEdgeEffectStyle(.soft, for: .top)`** -- fading edge effect on scroll edges
-- **`.backgroundExtensionEffect()`** -- mirror/blur at safe area edges
-- **`@Animatable`** macro -- synthesizes `AnimatableData` conformance automatically (see `swiftui-animation` skill)
-- **`TextEditor`** -- now accepts `AttributedString` for rich text
-
-## Performance Guidelines
-
-- **Lazy stacks/grids:** Use `LazyVStack`, `LazyHStack`, `LazyVGrid`, `LazyHGrid` for large collections. Regular stacks render all children immediately.
-- **Stable IDs:** All items in `List`/`ForEach` must conform to `Identifiable` with stable IDs. Never use array indices.
-- **Avoid body recomputation:** Move filtering and sorting to computed properties or the model, not inline in `body`.
-- **Equatable views:** For complex views that re-render unnecessarily, conform to `Equatable`.
-
-## HIG Alignment
-
-Follow Apple Human Interface Guidelines for layout, typography, color, and accessibility. Key rules:
-
-- Use semantic colors (`Color.primary`, `.secondary`, `Color(uiColor: .systemBackground)`) for automatic light/dark mode
-- Use system font styles (`.title`, `.headline`, `.body`, `.caption`) for Dynamic Type support
-- Use `ContentUnavailableView` for empty and error states
-- Omit `spacing:` on stacks unless a specific value is required  -  `nil` (the default) uses platform-appropriate adaptive spacing
-- Support adaptive layouts via `horizontalSizeClass`
-- Provide VoiceOver labels (`.accessibilityLabel`) and support Dynamic Type accessibility sizes by switching layout orientation
-
-See [references/design-polish.md](references/design-polish.md) for HIG, theming, haptics, focus, transitions, and loading patterns.
-
-## Writing Tools (iOS 18+)
-
-Control the Apple Intelligence Writing Tools experience on text views with `.writingToolsBehavior(_:)`.
-
-| Level | Effect | When to use |
-|-------|--------|-------------|
-| `.complete` | Full inline rewriting (proofread, rewrite, transform) | Notes, email, documents |
-| `.limited` | Reduced overlay-panel experience | Code editors, validated forms |
-| `.disabled` | Writing Tools hidden entirely | Passwords, search bars |
-| `.automatic` | System chooses based on context (default) | Most views |
+- Do not start an unmanaged `Task` in `onAppear` unless you store it and cancel
+  it yourself.
+- A `Task {}` inside a synchronous action, such as a button handler, is fine:
+  update state right away, then await the slow part.
+
+## 7. iOS 26 Additions
+
+| API | What it does |
+|---|---|
+| `.scrollEdgeEffectStyle(.soft, for: .top)` | Soft fade where content meets a scroll edge |
+| `.backgroundExtensionEffect()` | Extends a mirrored, blurred copy of the view under the safe areas |
+| `@Animatable` macro | Synthesises `animatableData` for a type; see `swiftui-animation` |
+| `TextEditor(text:)` with an `AttributedString` binding | Rich text editing |
+
+## 8. Performance
+
+- Large collections use `LazyVStack`, `LazyHStack`, `LazyVGrid` or
+  `LazyHGrid`. A plain stack creates every child immediately.
+- `List` and `ForEach` data must be `Identifiable` with stable ids. Never use
+  array positions as ids.
+- Filter and sort in the model or in a computed property, not inline in
+  `body`.
+- A complex view that re-evaluates without need can conform to `Equatable` so
+  SwiftUI can skip it when inputs match.
+
+## 9. Following the HIG
+
+- Semantic colors (`Color.primary`, `.secondary`,
+  `Color(uiColor: .systemBackground)`) adapt to light and dark mode.
+- Text styles (`.title`, `.headline`, `.body`, `.caption`) scale with Dynamic
+  Type.
+- Empty and error states use `ContentUnavailableView`.
+- Leave `spacing:` off stacks. The default `nil` picks platform spacing; pass a
+  number only for a deliberate choice.
+- Adapt layout to `horizontalSizeClass`.
+- Give controls an `.accessibilityLabel`, and switch stack axis when
+  `dynamicTypeSize.isAccessibilitySize` is true.
+
+Details, token scales and examples:
+[references/design-polish.md](references/design-polish.md).
+
+## 10. Writing Tools (iOS 18+)
+
+`.writingToolsBehavior(_:)` decides how Apple Intelligence Writing Tools appear
+on a text view.
+
+| Value | Experience | Good for |
+|---|---|---|
+| `.automatic` | System decides from context (default) | Most views |
+| `.complete` | Full inline proofread, rewrite and transform | Notes, mail, documents |
+| `.limited` | Reduced experience in an overlay panel | Code editors, validated fields |
+| `.disabled` | Writing Tools not offered | Passwords, search fields |
 
 ```swift
-TextEditor(text: $body)
+TextEditor(text: $journalEntry)
     .writingToolsBehavior(.complete)
-TextField("Search...", text: $query)
+
+TextField("Find", text: $filter)
     .writingToolsBehavior(.disabled)
 ```
 
-**Detecting active sessions:** Read `isWritingToolsActive` on `UITextView` (UIKit) to defer validation or suspend undo grouping until a rewrite finishes.
-
-> **Docs:** [WritingToolsBehavior](https://sosumi.ai/documentation/swiftui/writingtoolsbehavior) · [writingToolsBehavior(_:)](https://sosumi.ai/documentation/swiftui/view/writingtoolsbehavior(_:))
-
-## Common Mistakes
-
-1. Using `@ObservedObject` to create objects -- use `@StateObject` (legacy) or `@State` (modern)
-2. Heavy computation in view `body` -- move to model or computed property
-3. Not using `.task` for async work -- manual `Task` in `onAppear` leaks if not cancelled
-4. Array indices as `ForEach` IDs -- causes incorrect diffing and UI bugs
-5. Forgetting `@Bindable` -- `$property` syntax on `@Observable` requires `@Bindable`
-6. Over-using `@State` -- only for view-local state; shared state belongs in `@Observable`
-7. Not extracting subviews -- long body blocks are hard to read and optimize
-8. Using `NavigationView` -- deprecated; use `NavigationStack`
-9. Reaching for `foregroundColor(_:)` when `foregroundStyle(_:)` better matches semantic styling
-10. Inline closures in body -- extract complex closures to methods
-11. `.sheet(isPresented:)` when state represents a model -- use `.sheet(item:)` instead
-12. **Using `AnyView` for type erasure** -- causes identity resets and disables diffing. Use `@ViewBuilder`, `Group`, or generics instead. See [references/deprecated-migration.md](references/deprecated-migration.md)
-13. **Putting `@AppStorage` inside an `@Observable` class** -- `@AppStorage` is a SwiftUI `DynamicProperty`; it only triggers view updates when used directly in a `View`. Inside an `@Observable` class, observation tracking never sees the change. Keep `@AppStorage` in views, or read/write `UserDefaults` directly inside the `@Observable` class:
+In UIKit, `UITextView.isWritingToolsActive` is true while a session is running.
+Hold off validation and undo grouping until it turns false.
+
+Apple docs:
+[WritingToolsBehavior](https://developer.apple.com/documentation/swiftui/writingtoolsbehavior),
+[writingToolsBehavior(_:)](https://developer.apple.com/documentation/swiftui/view/writingtoolsbehavior(_:)).
+
+## 11. Common Mistakes
+
+| Mistake | Instead |
+|---|---|
+| Creating an object in `@ObservedObject` | `@State` (Observation) or `@StateObject` (legacy) |
+| Expensive work in `body` | Model or computed property |
+| `Task` started in `onAppear` | `.task`; an unstored `Task` is never cancelled |
+| Array indices as `ForEach` ids | Stable `Identifiable` ids; indices break diffing |
+| `$store.x` without `@Bindable` | Declare `@Bindable` for `$` on an `@Observable` |
+| `@State` used for shared data | `@State` is view-local; share through an `@Observable` |
+| One very long `body` | Extract subviews |
+| `NavigationView` | `NavigationStack` |
+| `foregroundColor(_:)` | `foregroundStyle(_:)` for semantic styles |
+| Large closures inline in `body` | Private methods |
+| `.sheet(isPresented:)` for a model value | `.sheet(item:)` |
+| `AnyView` to mix types | `@ViewBuilder`, `Group` or generics; `AnyView` defeats identity and diffing ([migration notes](references/deprecated-migration.md#10-anyview-to-viewbuilder-and-concrete-types)) |
+| `@AppStorage` inside an `@Observable` class | See below |
+| A `spacing:` value on every stack | Omit unless intentional |
+
+`@AppStorage` is a `DynamicProperty`. It only drives updates when it lives in a
+`View`; inside an `@Observable` class, observation never sees its changes. Keep
+it in the view, or use a stored property backed by `UserDefaults`:
 
 ```swift
-// Wrong -- @AppStorage is invisible to @Observable tracking
-@MainActor @Observable final class Settings {
-    @AppStorage("theme") var theme: String = "system" // view won't update
-}
-
-// Right -- UserDefaults read/write with a normal stored property
-@MainActor @Observable final class Settings {
-    var theme: String {
-        didSet { UserDefaults.standard.set(theme, forKey: "theme") }
+@MainActor @Observable
+final class ReaderPreferences {
+    var fontName: String {
+        didSet { UserDefaults.standard.set(fontName, forKey: "reader.font") }
     }
 
     init() {
-        theme = UserDefaults.standard.string(forKey: "theme") ?? "system"
+        fontName = UserDefaults.standard.string(forKey: "reader.font") ?? "Georgia"
     }
 }
 ```
 
-14. Hard-coding `spacing:` on every stack -- omit it to get adaptive platform spacing; only specify when the value is intentional
-
-## Review Checklist
-
-- [ ] `@Observable` used for shared state models (not `ObservableObject` on iOS 17+)
-- [ ] `@State` owns objects; `let`/`@Bindable` receives them
-- [ ] `NavigationStack` used (not `NavigationView`)
-- [ ] `.task` modifier for async data loading
-- [ ] `LazyVStack`/`LazyHStack` for large collections
-- [ ] Stable `Identifiable` IDs (not array indices)
-- [ ] Views decomposed into focused subviews
-- [ ] No heavy computation in view `body`
-- [ ] Environment used for deeply shared state
-- [ ] `foregroundStyle(_:)` used when semantic styling is preferable to a fixed color
-- [ ] Custom `ViewModifier` for repeated styling
-- [ ] `.sheet(item:)` preferred over `.sheet(isPresented:)`
-- [ ] Sheets own their actions and call `dismiss()` internally
-- [ ] MV pattern followed -- no unnecessary view models
-- [ ] `@Observable` view model classes are `@MainActor`-isolated
-- [ ] Model types passed across concurrency boundaries are `Sendable`
-- [ ] Stack `spacing:` omitted unless a specific value is required (prefer adaptive default)
-
-## References
-
-- Architecture, app wiring, and lightweight clients: [references/architecture-patterns.md](references/architecture-patterns.md)
-- Design polish (HIG, theming, haptics, transitions, loading, focus): [references/design-polish.md](references/design-polish.md)
-- Deprecated API migration: [references/deprecated-migration.md](references/deprecated-migration.md)
-- Platform and sharing patterns (Transferable, media, menus, macOS settings): [references/platform-and-sharing.md](references/platform-and-sharing.md)
-
+## 12. Review Checklist
+
+- [ ] Shared models use `@Observable` (iOS 17+), not `ObservableObject`
+- [ ] `@State` owns objects; children receive them as `let` or `@Bindable`
+- [ ] `NavigationStack` instead of `NavigationView`
+- [ ] Async loading goes through `.task`
+- [ ] Large collections use lazy stacks
+- [ ] `ForEach` ids are stable `Identifiable` ids, not indices
+- [ ] Views are split into focused subviews
+- [ ] `body` does no heavy work
+- [ ] Deeply shared state travels through the environment
+- [ ] `foregroundStyle(_:)` where a semantic style fits better than a fixed color
+- [ ] Repeated styling lives in a custom `ViewModifier`
+- [ ] `.sheet(item:)` preferred to `.sheet(isPresented:)`
+- [ ] Sheets own their actions and call `dismiss()` themselves
+- [ ] MV followed; no view model without a reason
+- [ ] `@Observable` view-facing classes are `@MainActor`
+- [ ] Model types that cross concurrency boundaries are `Sendable`
+- [ ] Stack `spacing:` omitted unless a specific value is needed
+
+## 13. References
+
+- [references/architecture-patterns.md](references/architecture-patterns.md):
+  the case for MV, when a view model is justified, environment versus init
+  injection, testing, app shell wiring, dependency modifier, `ModelContainer`,
+  enum sheets, deep links, closure-based clients.
+- [references/design-polish.md](references/design-polish.md): HIG layout,
+  typography and color, theming, haptics and Core Haptics, matched transitions,
+  loading placeholders, form focus.
+- [references/deprecated-migration.md](references/deprecated-migration.md):
+  old API to current API, with the release each replacement needs.
+- [references/platform-and-sharing.md](references/platform-and-sharing.md):
+  `Transferable`, share and drag and drop, pasteboard, media viewer, top bar
+  overlays, title menus, input bars, menu bar commands, macOS settings.