@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swiftui-patterns/references/design-polish.md

@@ -1,46 +1,43 @@
 # Design Polish
 
-## Contents
-- [HIG Alignment](#hig-alignment)
-- [Theming and Dynamic Type](#theming-and-dynamic-type)
-- [Haptics](#haptics)
-- [Matched Transitions](#matched-transitions)
-- [Loading and Placeholders](#loading-and-placeholders)
-- [Focus Handling](#focus-handling)
-
-## HIG Alignment
-
-iOS Human Interface Guidelines patterns for layout, typography, color, accessibility, and feedback in SwiftUI.
-
-### Contents
-
-- [Layout and Spacing](#layout-and-spacing)
-- [Typography](#typography)
-- [Color System](#color-system)
-- [Navigation Patterns](#navigation-patterns)
-- [Feedback](#feedback)
-- [Accessibility](#accessibility)
-- [Error and Empty States](#error-and-empty-states)
-
-### Layout and Spacing
-
-#### Spacing Grid
+Human Interface Guidelines applied in SwiftUI (layout, type, color, navigation
+chrome, feedback, accessibility, empty states), plus theming, haptics, matched
+transitions, loading placeholders and form focus.
 
-Omit `spacing:` on stacks to get SwiftUI's adaptive default. Only specify an explicit value when you need a deliberate departure from the default  -  and when you do, stick to the 4pt grid below.
+## Contents
 
-This is a common design convention, not an Apple-prescribed system, but it keeps layouts visually coherent. Avoid inventing values between grid stops.
+1. [HIG: Layout and Spacing](#1-hig-layout-and-spacing)
+2. [HIG: Typography](#2-hig-typography)
+3. [HIG: Color](#3-hig-color)
+4. [HIG: Navigation Chrome](#4-hig-navigation-chrome)
+5. [HIG: Feedback](#5-hig-feedback)
+6. [HIG: Accessibility](#6-hig-accessibility)
+7. [HIG: Error and Empty States](#7-hig-error-and-empty-states)
+8. [Theming and Dynamic Type](#8-theming-and-dynamic-type)
+9. [Haptics](#9-haptics)
+10. [Core Haptics](#10-core-haptics)
+11. [Matched Transitions](#11-matched-transitions)
+12. [Loading and Placeholders](#12-loading-and-placeholders)
+13. [Form Focus](#13-form-focus)
+
+## 1. HIG: Layout and Spacing
+
+Start by leaving `spacing:` off stacks; the adaptive default is usually right.
+When you do choose a value on purpose, take it from a 4 point grid. That grid is
+a widespread design convention, not something Apple requires, and values
+between its stops should not be invented.
 
 | Points | Token | Typical use |
-|--------|-------|-------------|
-| 4 | `.xxSmall` | Tight icon-to-label padding, inline badge offsets |
-| 8 | `.xSmall` | Related elements within a group, compact stack gaps |
-| 12 | `.small` | List row internal padding, label-to-secondary-text |
-| 16 | `.medium` | Standard margin, default section gap |
-| 20 | `.mediumLarge` | Comfortable breathing room between distinct controls |
-| 24 | `.large` | Section separators, card internal padding |
-| 32 | `.xLarge` | Major groupings, header-to-content gap |
-| 40 | `.xxLarge` | Large section breaks |
-| 48 | `.xxxLarge` | Hero/splash spacing, onboarding screens |
+|---|---|---|
+| 4 | `xxSmall` | Icon to label, inline badge offset |
+| 8 | `xSmall` | Related items in one group, tight stack gaps |
+| 12 | `small` | Row inner padding, label to secondary text |
+| 16 | `medium` | Standard margin, default gap between sections |
+| 20 | `mediumLarge` | Room between separate controls |
+| 24 | `large` | Section separators, card inner padding |
+| 32 | `xLarge` | Major groups, header to content |
+| 40 | `xxLarge` | Large section breaks |
+| 48 | `xxxLarge` | Hero, splash and onboarding layouts |
 
 ```swift
 enum Spacing {
@@ -56,477 +53,416 @@ enum Spacing {
 }
 ```
 
-#### Standard Margins
+Margins shared across screens can be named insets:
 
 ```swift
-private let standardMargin: CGFloat = 16
-private let compactMargin: CGFloat = 8
-private let largeMargin: CGFloat = 24
+private enum Margin {
+    static let regular: CGFloat = 16
+    static let tight: CGFloat = 8
+    static let wide: CGFloat = 24
+}
 
 extension EdgeInsets {
-    static let standard = EdgeInsets(top: 16, leading: 16, bottom: 16, trailing: 16)
-    static let listRow = EdgeInsets(top: 12, leading: 16, bottom: 12, trailing: 16)
+    static let regular = EdgeInsets(top: Margin.regular, leading: Margin.regular,
+                                    bottom: Margin.regular, trailing: Margin.regular)
+    static let rowContent = EdgeInsets(top: 12, leading: Margin.regular,
+                                       bottom: 12, trailing: Margin.regular)
 }
 ```
 
-#### Safe Area Handling
+Respect the safe area and pin persistent actions with `safeAreaInset`:
 
 ```swift
 ScrollView {
-    LazyVStack {
-        ForEach(items) { item in
-            ItemRow(item: item)
-        }
-    }
-    .padding(.horizontal)
+    LazyVStack { ForEach(lines) { OrderLineRow(line: $0) } }
+        .padding(.horizontal)
 }
 .safeAreaInset(edge: .bottom) {
     HStack {
-        Button("Cancel") { }
-            .buttonStyle(.bordered)
-        Spacer()
-        Button("Confirm") { }
-            .buttonStyle(.borderedProminent)
+        Button("Back", action: goBack).buttonStyle(.bordered)
+        Button("Place order", action: placeOrder).buttonStyle(.borderedProminent)
     }
     .padding()
     .background(.regularMaterial)
 }
 ```
 
-#### Adaptive Layouts
-
-Use `horizontalSizeClass` to adapt between compact and regular widths:
+Adapt compact and regular widths with the size class:
 
 ```swift
 @Environment(\.horizontalSizeClass) private var sizeClass
 
-private var columns: [GridItem] {
-    switch sizeClass {
-    case .compact:
-        [GridItem(.flexible())]
-    case .regular:
-        [GridItem(.flexible()), GridItem(.flexible()), GridItem(.flexible())]
-    default:
-        [GridItem(.flexible())]
-    }
+private var gridColumns: [GridItem] {
+    let count = sizeClass == .regular ? 3 : 1
+    return Array(repeating: GridItem(.flexible()), count: count)
 }
 ```
 
-### Typography
+## 2. HIG: Typography
 
-#### System Font Styles
+Text styles scale with Dynamic Type without extra work. Sizes below are the
+iOS defaults at the Large content size.
 
-Use system font styles for automatic Dynamic Type support:
+| Style | Size and weight | Use |
+|---|---|---|
+| `.largeTitle` | 34 pt regular | Screen title |
+| `.title` | 28 pt regular | Section header |
+| `.title2` | 22 pt regular | Sub-section header |
+| `.title3` | 20 pt regular | Group header |
+| `.headline` | 17 pt semibold | Row title |
+| `.body` | 17 pt regular | Main content |
+| `.callout` | 16 pt regular | Secondary content |
+| `.subheadline` | 15 pt regular | Supporting text |
+| `.footnote` | 13 pt regular | Tertiary information |
+| `.caption` | 12 pt regular | Labels |
+| `.caption2` | 11 pt regular | Small labels |
 
-| Style | Size | Weight | Usage |
-|-------|------|--------|-------|
-| `.largeTitle` | 34pt | Regular | Screen titles |
-| `.title` | 28pt | Regular | Section headers |
-| `.title2` | 22pt | Regular | Sub-section headers |
-| `.title3` | 20pt | Regular | Group headers |
-| `.headline` | 17pt | Semibold | Row titles |
-| `.body` | 17pt | Regular | Primary content |
-| `.callout` | 16pt | Regular | Secondary content |
-| `.subheadline` | 15pt | Regular | Supporting text |
-| `.footnote` | 13pt | Regular | Tertiary info |
-| `.caption` | 12pt | Regular | Labels |
-| `.caption2` | 11pt | Regular | Small labels |
-
-#### Custom Font with Dynamic Type
+A custom typeface keeps Dynamic Type when it is tied to a text style:
 
 ```swift
 extension Font {
-    static func customBody(_ name: String) -> Font {
-        .custom(name, size: 17, relativeTo: .body)
+    static func brandBody(_ family: String) -> Font {
+        .custom(family, size: 17, relativeTo: .body)
     }
 }
 ```
 
-### Color System
-
-#### Semantic Colors
-
-Use semantic colors for automatic light/dark mode support:
-
-```swift
-// Labels
-Color.primary           // Primary text
-Color.secondary         // Secondary text
-Color(uiColor: .tertiaryLabel)
-
-// Backgrounds
-Color(uiColor: .systemBackground)
-Color(uiColor: .secondarySystemBackground)
-Color(uiColor: .systemGroupedBackground)
-
-// Fills and Separators
-Color(uiColor: .systemFill)
-Color(uiColor: .separator)
-```
-
-#### Tint Colors
+## 3. HIG: Color
 
-```swift
-// Apply app-wide tint
-ContentView()
-    .tint(.blue)
-```
+Semantic colors switch between light and dark appearance on their own.
 
-Use `.tint(...)` or `.foregroundStyle(.tint)` for interactive elements and `Color.red` for destructive actions.
+| Role | Colors |
+|---|---|
+| Labels | `Color.primary`, `Color.secondary`, `Color(uiColor: .tertiaryLabel)` |
+| Backgrounds | `Color(uiColor: .systemBackground)`, `.secondarySystemBackground`, `.systemGroupedBackground` |
+| Fill and divider | `.systemFill` and `.separator`, both wrapped in `Color(uiColor:)` |
 
-### Navigation Patterns
+- Set the app tint once on the root view, for example `.tint(.indigo)`.
+- Interactive elements use the tint through `.tint(...)` or
+  `.foregroundStyle(.tint)`.
+- Destructive actions use red (`Color.red`, or a `.destructive` button role).
 
-#### Hierarchical (NavigationSplitView)
+## 4. HIG: Navigation Chrome
 
-Use for iPad/macOS multi-column layouts:
+Multi-column hierarchies on iPad and Mac use `NavigationSplitView`:
 
 ```swift
 NavigationSplitView {
-    List(items, selection: $selectedItem) { item in
-        NavigationLink(value: item) { ItemRow(item: item) }
+    List(folders, selection: $selectedFolder) { folder in
+        NavigationLink(folder.name, value: folder)
     }
-    .navigationTitle("Items")
+    .navigationTitle("Folders")
 } detail: {
-    if let item = selectedItem {
-        ItemDetailView(item: item)
+    if let selectedFolder {
+        FolderDetail(folder: selectedFolder)
     } else {
-        ContentUnavailableView("Select an Item", systemImage: "sidebar.leading")
+        ContentUnavailableView("Pick a folder", systemImage: "sidebar.leading")
     }
 }
 ```
 
-#### Tab-Based
+Tab-based apps give each tab its own `NavigationStack` inside a `TabView`. The
+full tab patterns are in `swiftui-navigation`.
 
-Use `TabView` with a `NavigationStack` per tab. See the `swiftui-navigation` skill for full tab patterns.
-
-#### Toolbar
+Toolbars (`.topBarLeading` and `.topBarTrailing` come with the iOS 17 SDK and
+are back-deployed to iOS 14):
 
 ```swift
 .toolbar {
-    ToolbarItem(placement: .topBarLeading) { EditButton() }
+    ToolbarItem(placement: .topBarLeading) {
+        EditButton()
+    }
     ToolbarItemGroup(placement: .topBarTrailing) {
-        Button("Filter", systemImage: "line.3.horizontal.decrease.circle") { }
-        Button("Add", systemImage: "plus") { }
+        Button("Mark all read", systemImage: "envelope.open", action: markAllRead)
+        Button("New", systemImage: "plus", action: createItem)
     }
     ToolbarItemGroup(placement: .bottomBar) {
-        Button("Archive", systemImage: "archivebox") { }
+        Button("Archive", systemImage: "archivebox", action: archiveSelection)
         Spacer()
-        Text("\(itemCount) items").font(.footnote).foregroundStyle(.secondary)
+        Text("\(messages.count) messages")
+            .font(.footnote)
+            .foregroundStyle(.secondary)
         Spacer()
-        Button("Share", systemImage: "square.and.arrow.up") { }
+        Button("Compose", systemImage: "square.and.pencil", action: compose)
     }
 }
 ```
 
-#### Search Integration
+Search with scopes (`.searchScopes` needs iOS 16.4):
 
 ```swift
-.searchable(text: $searchText, placement: .navigationBarDrawer(displayMode: .always))
-.searchScopes($searchScope) {
-    ForEach(SearchScope.allCases, id: \.self) { scope in
-        Text(scope.rawValue.capitalized).tag(scope)
+enum LibraryScope: String, CaseIterable {
+    case titles, authors, tags
+    var label: String { rawValue.localizedCapitalized }
+}
+
+.searchable(text: $query, placement: .navigationBarDrawer(displayMode: .always))
+.searchScopes($scope) {
+    ForEach(LibraryScope.allCases, id: \.self) { scope in
+        Text(scope.label).tag(scope)
     }
 }
 ```
 
-### Feedback
-
-#### Haptic Feedback
+## 5. HIG: Feedback
 
-Prefer SwiftUI's `sensoryFeedback(_:trigger:)` for state-driven feedback in SwiftUI views.
+For haptics that follow state, use `sensoryFeedback(_:trigger:)` (iOS 17+):
 
 ```swift
-Button("Save") {
-    didSave.toggle()
-}
-.sensoryFeedback(.success, trigger: didSave)
+Button("Bookmark") { isBookmarked.toggle() }
+    .sensoryFeedback(.success, trigger: isBookmarked)
 
-Picker("Sort", selection: $sortOrder) {
-    Text("Recent").tag(SortOrder.recent)
-    Text("Popular").tag(SortOrder.popular)
+Picker("Order", selection: $ordering) {
+    ForEach(Ordering.allCases) { Text($0.title).tag($0) }
 }
-.sensoryFeedback(.selection, trigger: sortOrder)
+.sensoryFeedback(.selection, trigger: ordering)
 ```
 
-Use the UIKit generators only when you need imperative feedback from UIKit or non-SwiftUI integration points.
-
-See the Haptics section below for structured patterns.
+Reach for UIKit feedback generators only when the trigger is imperative and
+comes from UIKit or other code outside SwiftUI views.
 
-### Accessibility
+## 6. HIG: Accessibility
 
-#### VoiceOver Support
+Combine a row into one VoiceOver element and describe it:
 
 ```swift
 VStack(alignment: .leading) {
-    Text(item.title).font(.headline)
-    Text(item.subtitle).font(.subheadline).foregroundStyle(.secondary)
-    HStack {
-        Image(systemName: "star.fill")
-        Text("\(item.rating, specifier: "%.1f")")
-    }
+    Text(course.title).font(.headline)
+    Text("\(course.score, specifier: "%.1f") out of 5")
 }
 .accessibilityElement(children: .combine)
-.accessibilityLabel("\(item.title), \(item.subtitle)")
-.accessibilityValue("Rating: \(item.rating) stars")
-.accessibilityHint("Double tap to view details")
+.accessibilityLabel(course.title)
+.accessibilityValue("Rated \(course.score, specifier: "%.1f") out of 5")
+.accessibilityHint("Opens the course overview")
 .accessibilityAddTraits(.isButton)
 ```
 
-#### Dynamic Type Support
-
-Adapt layout for accessibility sizes:
+Switch layout for the accessibility text sizes:
 
 ```swift
-@Environment(\.dynamicTypeSize) private var dynamicTypeSize
+@Environment(\.dynamicTypeSize) private var typeSize
 
 var body: some View {
-    if dynamicTypeSize.isAccessibilitySize {
-        VStack(alignment: .leading) {
-            leadingContent
-            trailingContent
-        }
+    if typeSize.isAccessibilitySize {
+        VStack(alignment: .leading) { avatar; details }
     } else {
-        HStack {
-            leadingContent
-            Spacer()
-            trailingContent
-        }
+        HStack { avatar; details; Spacer() }
     }
 }
 ```
 
-### Error and Empty States
+## 7. HIG: Error and Empty States
 
-Use `ContentUnavailableView` for both:
+`ContentUnavailableView` covers both. The builder form adds actions:
 
 ```swift
-// Error state
 ContentUnavailableView {
-    Label("Unable to Load", systemImage: "exclamationmark.triangle")
+    Label("Sync failed", systemImage: "icloud.slash")
 } description: {
     Text(error.localizedDescription)
 } actions: {
-    Button("Try Again") { Task { await retry() } }
+    Button("Retry") { Task { await resync() } }
         .buttonStyle(.borderedProminent)
 }
 
-// Empty state
 ContentUnavailableView {
-    Label("No Photos", systemImage: "camera")
+    Label("No receipts", systemImage: "doc.text.viewfinder")
 } description: {
-    Text("Take your first photo to get started.")
+    Text("Scan a paper receipt to add it here.")
 } actions: {
-    Button("Take Photo") { showCamera = true }
+    Button("Scan") { isScannerPresented = true }
         .buttonStyle(.borderedProminent)
 }
 ```
 
-## Theming and Dynamic Type
+## 8. Theming and Dynamic Type
 
-### Intent
+Goal: theming that grows with the app while view code stays semantic.
 
-Provide a clean, scalable theming approach that keeps view code semantic and consistent.
-
-### Core patterns
-
-- Use a single `Theme` object as the source of truth (colors, fonts, spacing).
-- Inject theme at the app root and read it via `@Environment(Theme.self)` in views.
-- Prefer semantic colors (`primaryBackground`, `secondaryBackground`, `label`, `tint`) instead of raw colors.
-- Keep user-facing theme controls in a dedicated settings screen.
-- Apply Dynamic Type scaling through text styles, `Font.custom(_:size:relativeTo:)`, or `@ScaledMetric` for numeric layout values.
-
-### Example: Theme object
+- One `Theme` object is the only source of colors, fonts and spacing.
+- Install it at the app root; views read it with `@Environment(Theme.self)`.
+- Name values by role (`primaryBackground`, `secondaryBackground`, `label`,
+  `tint`) rather than by hue.
+- Put user-facing theme choices on a dedicated settings screen.
+- Scaling with the user's text size comes from three places: built-in text
+  styles, a custom font tied to a style via `Font.custom(_:size:relativeTo:)`,
+  and `@ScaledMetric` for numeric layout values.
 
 ```swift
-@MainActor
-@Observable
+@MainActor @Observable
 final class Theme {
-  var tintColor: Color = .blue
-  var primaryBackground: Color = .white
-  var secondaryBackground: Color = .gray.opacity(0.1)
-  var labelColor: Color = .primary
-  var fontSizeScale: Double = 1.0
+    var accent: Color = .teal
+    var primaryBackground: Color = .white
+    var secondaryBackground: Color = .secondary.opacity(0.12)
+    var label: Color = .primary
+    var textScale: Double = 1.0
 }
-```
-
-### Example: inject at app root
 
-```swift
 @main
-struct MyApp: App {
-  @State private var theme = Theme()
+struct JournalApp: App {
+    @State private var theme = Theme()
 
-  var body: some Scene {
-    WindowGroup {
-      AppView()
-        .environment(theme)
+    var body: some Scene {
+        WindowGroup {
+            EntriesView().environment(theme)
+        }
     }
-  }
 }
-```
 
-### Example: view usage
-
-```swift
-struct ProfileView: View {
-  @Environment(Theme.self) private var theme
+struct EntryCard: View {
+    @Environment(Theme.self) private var currentTheme
+    let entry: Entry
 
-  var body: some View {
-    VStack {
-      Text("Profile")
-        .foregroundStyle(theme.labelColor)
+    var body: some View {
+        Text(entry.title)
+            .foregroundStyle(currentTheme.label)
+            .background(currentTheme.primaryBackground)
     }
-    .background(theme.primaryBackground)
-  }
 }
 ```
 
-### Design choices to keep
+Guidelines:
 
-- Keep theme values semantic and minimal; avoid duplicating system colors.
-- Store user-selected theme values in persistent storage if needed.
-- Ensure contrast between text and backgrounds.
+- Keep the set of theme values small and semantic; do not re-create system
+  colors.
+- Persist theme choices the user makes, if the app offers them.
+- Check contrast between every text color and its background.
 
-### Pitfalls
+Pitfalls:
 
-- Avoid sprinkling raw `Color` values in views; it breaks consistency.
-- Do not tie theme to a single view's local state.
-- Avoid using `@Environment(\.colorScheme)` as the only theme control; it should complement your theme.
+- Raw `Color` literals spread through views.
+- A theme stored in one view's local state.
+- Treating `@Environment(\.colorScheme)` as the whole theming story. Light or
+  dark mode is one input to the theme, not a substitute for it.
 
-## Haptics
+## 9. Haptics
 
-### Intent
+Use haptics for moments that matter (tab switch, refresh, success, failure) and
+respect the user's settings.
 
-Use haptics sparingly to reinforce user actions (tab selection, refresh, success/error) and respect user preferences.
+- In SwiftUI views, prefer `sensoryFeedback(_:trigger:)`.
+- Centralise imperative feedback in a manager only for UIKit interop or code
+  that is not a view.
+- Check both the user preference and hardware support.
+- Use different feedback types for different moments: selection, notification,
+  refresh.
+- Core Haptics is the step up when a pattern needs shaping that the built-in
+  feedback types do not offer.
 
-### Core patterns
-
-- Prefer `sensoryFeedback(_:trigger:)` in SwiftUI views for state-driven feedback.
-- Centralize imperative feedback in a `HapticManager` only when UIKit interop or non-view code requires it.
-- Gate haptics behind user preferences and hardware support.
-- Use distinct types for different UX moments (selection vs. notification vs. refresh).
-- Escalate to Core Haptics only for custom patterns that exceed SwiftUI's built-in feedback types.
-
-### SwiftUI-first pattern
+SwiftUI first:
 
 ```swift
-struct SaveButton: View {
-  @State private var saveToken = 0
+@State private var uploadCount = 0
 
-  var body: some View {
-    Button("Save") {
-      persistChanges()
-      saveToken += 1
-    }
-    .sensoryFeedback(.success, trigger: saveToken)
-  }
+Button("Upload") {
+    uploadCount += 1
+    startUpload()
 }
+.sensoryFeedback(.success, trigger: uploadCount)
 ```
 
-### UIKit interop pattern
+UIKit interop:
 
 ```swift
+import UIKit
+
 @MainActor
-final class HapticManager {
-  static let shared = HapticManager()
-
-  enum HapticType {
-    case buttonPress
-    case tabSelection
-    case dataRefresh(intensity: CGFloat)
-    case notification(UINotificationFeedbackGenerator.FeedbackType)
-  }
-
-  private let selectionGenerator = UISelectionFeedbackGenerator()
-  private let impactGenerator = UIImpactFeedbackGenerator(style: .heavy)
-  private let notificationGenerator = UINotificationFeedbackGenerator()
-
-  private init() { selectionGenerator.prepare() }
-
-  func fire(_ type: HapticType, isEnabled: Bool) {
-    guard isEnabled else { return }
-    switch type {
-    case .buttonPress:
-      impactGenerator.impactOccurred()
-    case .tabSelection:
-      selectionGenerator.selectionChanged()
-    case let .dataRefresh(intensity):
-      impactGenerator.impactOccurred(intensity: intensity)
-    case let .notification(style):
-      notificationGenerator.notificationOccurred(style)
+final class FeedbackPlayer {
+    static let shared = FeedbackPlayer()
+
+    enum Kind {
+        case tap
+        case tabChange
+        case refresh(strength: CGFloat)
+        case result(UINotificationFeedbackGenerator.FeedbackType)
+    }
+
+    private let selection = UISelectionFeedbackGenerator()
+    private let impact = UIImpactFeedbackGenerator(style: .heavy)
+    private let notification = UINotificationFeedbackGenerator()
+
+    private init() { selection.prepare() }
+
+    func play(_ kind: Kind, allowed: Bool) {
+        guard allowed else { return }
+        switch kind {
+        case .tap: impact.impactOccurred()
+        case .tabChange: selection.selectionChanged()
+        case .refresh(let strength): impact.impactOccurred(intensity: strength)
+        case .result(let type): notification.notificationOccurred(type)
+        }
     }
-  }
 }
 ```
 
-### Example: usage
-
 ```swift
-Button("Save") {
-  HapticManager.shared.fire(.notification(.success), isEnabled: preferences.hapticsEnabled)
+@AppStorage("hapticsOn") private var hapticsOn = true
+
+Button("Pay") {
+    FeedbackPlayer.shared.play(.result(.success), allowed: hapticsOn)
 }
 
-TabView(selection: $selectedTab) { /* tabs */ }
-  .onChange(of: selectedTab) { _, _ in
-    HapticManager.shared.fire(.tabSelection, isEnabled: preferences.hapticTabSelectionEnabled)
-  }
+TabView(selection: $tab) { tabs }
+    .onChange(of: tab) {
+        FeedbackPlayer.shared.play(.tabChange, allowed: hapticsOn)
+    }
 ```
 
-### Design choices to keep
-
-- Haptics should be subtle and not fire on every tiny interaction.
-- Respect user preferences (toggle to disable).
-- Keep haptic triggers close to the user action, not deep in data layers.
+Guidelines:
 
-### Pitfalls
+- Keep feedback subtle and skip it for minor interactions.
+- Offer a setting that turns haptics off.
+- Trigger feedback where the user acts, not from the data layer.
 
-- Avoid firing multiple haptics in quick succession.
-- Do not assume haptics are available; check support.
+Pitfalls:
 
-### Core Haptics (CHHapticEngine)
+- Several haptics fired back to back.
+- Assuming the device has a haptic engine.
 
-For advanced haptic patterns beyond the simple feedback generators, use Core Haptics. It provides precise control over haptic intensity, sharpness, and timing with support for audio-haptic synchronization.
+## 10. Core Haptics
 
-> **Docs:** [CHHapticEngine](https://sosumi.ai/documentation/corehaptics/chhapticengine) · [Preparing your app to play haptics](https://sosumi.ai/documentation/corehaptics/preparing-your-app-to-play-haptics)
+Core Haptics controls intensity, sharpness, timing and audio sync precisely,
+for patterns the simple generators cannot produce. Apple docs:
+[CHHapticEngine](https://developer.apple.com/documentation/corehaptics/chhapticengine),
+and the [Core Haptics](https://developer.apple.com/documentation/corehaptics)
+topic page, whose "Essentials" group holds the article on preparing an app to
+play haptics.
 
-#### Capabilities check
+### Engine lifecycle
 
-Always verify hardware support before creating an engine:
+Check the hardware before creating an engine.
 
 ```swift
 import CoreHaptics
+import OSLog
 
-let supportsHaptics = CHHapticEngine.capabilitiesForHardware().supportsHaptics
-let supportsAudio = CHHapticEngine.capabilitiesForHardware().supportsAudio
-```
-
-#### Engine setup and lifecycle
+extension Logger {
+    static let haptics = Logger(subsystem: "app.haptics", category: "engine")
+}
 
-```swift
 @MainActor
-final class CoreHapticManager {
+final class PatternPlayer {
     private var engine: CHHapticEngine?
 
-    func prepareEngine() throws {
-        guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else { return }
+    var canPlayHaptics: Bool {
+        CHHapticEngine.capabilitiesForHardware().supportsHaptics
+    }
 
-        engine = try CHHapticEngine()
+    var canPlayHapticAudio: Bool {
+        CHHapticEngine.capabilitiesForHardware().supportsAudio
+    }
 
-        // Called when the engine stops due to external cause (audio session interruption, app backgrounding)
-        engine?.stoppedHandler = { reason in
-            print("Haptic engine stopped: \(reason)")
+    func startEngine() throws {
+        guard canPlayHaptics else { return }
+        let engine = try CHHapticEngine()
+        engine.stoppedHandler = { @Sendable reason in
+            Logger.haptics.info("Engine stopped, reason \(reason.rawValue)")
         }
-
-        // Called after the engine is reset (e.g., after audio session interruption ends)
-        engine?.resetHandler = { [weak self] in
-            do {
-                try self?.engine?.start()
-            } catch {
-                print("Failed to restart engine: \(error)")
-            }
+        engine.resetHandler = { @Sendable [weak self] in
+            Task { @MainActor in try? self?.engine?.start() }
         }
-
-        try engine?.start()
+        try engine.start()
+        self.engine = engine
     }
 
     func stopEngine() {
@@ -535,304 +471,316 @@ final class CoreHapticManager {
 }
 ```
 
-Key lifecycle rules:
-- Call `engine.start()` before playing any patterns.
-- Handle `stoppedHandler`  -  the system can stop the engine when your app moves to the background or during audio interruptions.
-- Handle `resetHandler`  -  restart the engine when the system resets it.
-- Call `engine.stop()` when haptics are no longer needed to save battery.
-
-#### CHHapticPattern and CHHapticEvent
+- `stoppedHandler` runs when something outside the app stops the engine, such
+  as an audio session interruption or the app moving to the background.
+- Both handlers are called on a queue owned by the engine, so they are
+  `@Sendable`; any state change is scheduled onto the main actor first.
+- `resetHandler` runs after the system resets the engine, for instance once an
+  audio interruption is over. Start the engine again there.
+- Call `start()` before playing any pattern.
+- Once the screen no longer plays patterns, `stop()` the engine to save power.
 
-Build patterns from individual haptic and audio events:
+### A single tap
 
 ```swift
-func playTransientTap() throws {
-    let sharpness = CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.8)
-    let intensity = CHHapticEventParameter(parameterID: .hapticIntensity, value: 1.0)
-
-    // Transient: short, single-tap feel
-    let event = CHHapticEvent(
-        eventType: .hapticTransient,
-        parameters: [intensity, sharpness],
-        relativeTime: 0
-    )
-
-    let pattern = try CHHapticPattern(events: [event], parameters: [])
-    let player = try engine?.makePlayer(with: pattern)
-    try player?.start(atTime: CHHapticTimeImmediate)
+func playTap() throws {
+    let crisp = CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.75)
+    let strong = CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.95)
+    let tap = CHHapticEvent(eventType: .hapticTransient,
+                            parameters: [crisp, strong],
+                            relativeTime: 0)
+    let pattern = try CHHapticPattern(events: [tap], parameters: [])
+    try engine?.makePlayer(with: pattern).start(atTime: CHHapticTimeImmediate)
 }
 ```
 
-**Event types:**
+### Event types and parameters
 
-| Type | Description |
-|------|-------------|
-| `.hapticTransient` | Brief, tap-like impulse |
-| `.hapticContinuous` | Sustained vibration over a `duration` |
+| Event type | Effect |
+|---|---|
+| `.hapticTransient` | Short impulse, like a tap |
+| `.hapticContinuous` | Sustained vibration for a `duration` |
 | `.audioContinuous` | Sustained audio tone |
-| `.audioCustom` | Play a custom audio resource |
-
-**Common parameters:** `.hapticIntensity` (0-1), `.hapticSharpness` (0-1), `.attackTime`, `.decayTime`, `.releaseTime`.
+| `.audioCustom` | Plays an audio resource you register |
 
-#### Playing patterns with CHHapticPatternPlayer
+Common parameters: `.hapticIntensity` (0 to 1), `.hapticSharpness` (0 to 1),
+`.attackTime`, `.decayTime`, `.releaseTime`.
 
 ```swift
-func playContinuousBuzz() throws {
-    let intensity = CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.6)
-    let sharpness = CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.3)
-
-    let event = CHHapticEvent(
+func playHum() throws {
+    let hum = CHHapticEvent(
         eventType: .hapticContinuous,
-        parameters: [intensity, sharpness],
+        parameters: [
+            CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.55),
+            CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.35)
+        ],
         relativeTime: 0,
         duration: 0.5
     )
-
-    let pattern = try CHHapticPattern(events: [event], parameters: [])
-    let player = try engine?.makePlayer(with: pattern)
-    try player?.start(atTime: CHHapticTimeImmediate)
+    let humPattern = try CHHapticPattern(events: [hum], parameters: [])
+    try engine?.makePlayer(with: humPattern).start(atTime: CHHapticTimeImmediate)
 }
 ```
 
-For looping, seeking, and pausing, use `CHHapticAdvancedPatternPlayer` via `engine.makeAdvancedPlayer(with:)`.
+Looping, seeking and pausing need a `CHHapticAdvancedPatternPlayer` from
+`engine.makeAdvancedPlayer(with:)`.
 
-#### Haptic parameter curves (CHHapticParameterCurve)
+### Parameter curves
 
-Smoothly vary parameters over time within a pattern:
+A `CHHapticParameterCurve` changes a parameter smoothly while the pattern
+plays:
 
 ```swift
-func playRampingPattern() throws {
-    let event = CHHapticEvent(
+func playSwell() throws {
+    let base = CHHapticEvent(
         eventType: .hapticContinuous,
         parameters: [
-            CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.2),
-            CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.1)
+            CHHapticEventParameter(parameterID: .hapticIntensity, value: 0.25),
+            CHHapticEventParameter(parameterID: .hapticSharpness, value: 0.15)
         ],
         relativeTime: 0,
         duration: 1.0
     )
-
-    // Ramp intensity from 0.2 → 1.0 over 1 second
-    let curve = CHHapticParameterCurve(
+    let swell = CHHapticParameterCurve(
         parameterID: .hapticIntensityControl,
         controlPoints: [
-            .init(relativeTime: 0, value: 0.2),
-            .init(relativeTime: 0.5, value: 0.7),
-            .init(relativeTime: 1.0, value: 1.0)
+            CHHapticParameterCurve.ControlPoint(relativeTime: 0, value: 0.25),
+            CHHapticParameterCurve.ControlPoint(relativeTime: 0.4, value: 0.6),
+            CHHapticParameterCurve.ControlPoint(relativeTime: 0.9, value: 1)
         ],
         relativeTime: 0
     )
-
-    let pattern = try CHHapticPattern(events: [event], parameterCurves: [curve])
-    let player = try engine?.makePlayer(with: pattern)
-    try player?.start(atTime: CHHapticTimeImmediate)
+    let pattern = try CHHapticPattern(events: [base], parameterCurves: [swell])
+    try engine?.makePlayer(with: pattern).start(atTime: CHHapticTimeImmediate)
 }
 ```
 
-#### Audio-haptic synchronization (AHAP files)
+### AHAP files
 
-AHAP (Apple Haptic and Audio Pattern) files define haptic patterns in JSON for easy authoring and design iteration. Load them directly:
+Patterns can also live outside code, in an AHAP file: a JSON document you
+tune without recompiling.
 
 ```swift
-func playAHAPFile() throws {
-    guard let url = Bundle.main.url(forResource: "success", withExtension: "ahap") else { return }
-    try engine?.playPattern(from: url)
+func playFromFile() throws {
+    guard let patternURL = Bundle.main.url(forResource: "checkout", withExtension: "ahap") else {
+        return
+    }
+    try engine?.playPattern(from: patternURL)
 }
 ```
 
-AHAP files support the same events, parameters, and parameter curves as the programmatic API. Use the **Core Haptics** design tools in Xcode to preview patterns.
-
-> **Docs:** [Representing haptic patterns in AHAP files](https://sosumi.ai/documentation/corehaptics/representing-haptic-patterns-in-ahap-files)
-
-## Matched Transitions
+Everything the code API expresses (events, parameters, curves) can be written
+in AHAP too, and Xcode can play the file back for you while you iterate. File
+format reference: the AHAP article listed on the
+[Core Haptics](https://developer.apple.com/documentation/corehaptics) topic page.
 
-### Intent
+## 11. Matched Transitions
 
-Use matched transitions to create smooth continuity between a source view (thumbnail, avatar) and a destination view (sheet, detail, viewer).
+Goal: carry the eye from a source view (thumbnail, avatar) to its destination
+(sheet, detail, full-screen viewer).
 
-### Core patterns
-
-- Use a shared `Namespace` and a stable ID for the source.
-- Use `matchedTransitionSource` + `navigationTransition(.zoom(...))` on iOS 26+.
-- Use `matchedGeometryEffect` for in-place transitions within a view hierarchy.
-- Keep IDs stable across view updates (avoid random UUIDs).
-
-### Example: media preview to full-screen viewer (iOS 26+)
+- Share a `Namespace` between source and destination, and give the source a
+  stable id.
+- Across screens, use `matchedTransitionSource(id:in:)` with
+  `navigationTransition(.zoom(sourceID:in:))`. Both need iOS 18.
+- Inside one hierarchy, use `matchedGeometryEffect(id:in:)`.
+- Ids must stay the same across updates; never generate random UUIDs for them.
 
 ```swift
-struct MediaPreview: View {
-  @Namespace private var namespace
-  @State private var selected: MediaAttachment?
-
-  var body: some View {
-    ThumbnailView()
-      .matchedTransitionSource(id: selected?.id ?? "", in: namespace)
-      .sheet(item: $selected) { item in
-        MediaViewer(item: item)
-          .navigationTransition(.zoom(sourceID: item.id, in: namespace))
-      }
-  }
+struct GalleryGrid: View {
+    @Namespace private var zoom
+    @State private var opened: Photo?
+    let photos: [Photo]
+
+    var body: some View {
+        LazyVGrid(columns: [GridItem(.adaptive(minimum: 96))]) {
+            ForEach(photos) { photo in
+                Button { opened = photo } label: {
+                    PhotoThumbnail(photo: photo)
+                }
+                .matchedTransitionSource(id: photo.id, in: zoom)
+            }
+        }
+        .sheet(item: $opened) { photo in
+            PhotoViewer(photo: photo)
+                .navigationTransition(.zoom(sourceID: photo.id, in: zoom))
+        }
+    }
 }
 ```
 
-### Example: matched geometry within a view
+In-place change within one view:
 
 ```swift
-struct ToggleBadge: View {
-  @Namespace private var space
-  @State private var isOn = false
-
-  var body: some View {
-    Button {
-      withAnimation(.spring) { isOn.toggle() }
-    } label: {
-      Image(systemName: isOn ? "eye" : "eye.slash")
-        .matchedGeometryEffect(id: "icon", in: space)
+struct LockToggle: View {
+    @Namespace private var space
+    @State private var isLocked = false
+
+    var body: some View {
+        Button {
+            withAnimation(.spring) { isLocked.toggle() }
+        } label: {
+            Image(systemName: isLocked ? "lock" : "lock.open")
+                .matchedGeometryEffect(id: "lockGlyph", in: space)
+        }
     }
-  }
 }
 ```
 
-### Design choices to keep
-
-- Prefer `matchedTransitionSource` for cross-screen transitions.
-- Keep source and destination sizes reasonable to avoid jarring scale changes.
-- Use `withAnimation` for state-driven transitions.
-
-### Pitfalls
+Guidelines:
 
-- Don't use unstable IDs; it breaks the transition.
-- Avoid mismatched shapes (e.g., square to circle) unless the design expects it.
+- Prefer `matchedTransitionSource` for transitions between screens.
+- Keep source and destination sizes close so the scale change is not jarring.
+- Drive state-based transitions with `withAnimation`.
 
-## Loading and Placeholders
+Pitfalls:
 
-Use this when a view needs a consistent loading state (skeletons, redaction, empty state) without blocking interaction.
+- Ids that change between updates break the transition.
+- Shapes that do not match (a square into a circle) look wrong unless the
+  design asks for it.
 
-### Patterns to prefer
+## 12. Loading and Placeholders
 
-- **Redacted placeholders** for list/detail content to preserve layout while loading.
-- **ContentUnavailableView** for empty or error states after loading completes.
-- **ProgressView** only for short, global operations (use sparingly in content-heavy screens).
+Use this for loading states (skeletons, redaction, empty state) that stay
+consistent and never block interaction.
 
-### Recommended approach
+- For lists and detail content, prefer redacted placeholders; the layout stays
+  in place while data arrives.
+- Once loading ends with nothing to show, or with an error, show
+  `ContentUnavailableView`.
+- Keep `ProgressView` for short, global operations, and use it sparingly on
+  content-heavy screens.
 
-1. Keep the real layout, render placeholder data, then apply `.redacted(reason: .placeholder)`.
-2. For lists, show a fixed number of placeholder rows (avoid infinite spinners).
-3. Switch to `ContentUnavailableView` when load finishes but data is empty.
+Steps:
 
-### Pitfalls
-
-- Don't animate layout shifts during redaction; keep frames stable.
-- Avoid nesting multiple spinners; use one loading indicator per section.
-- Keep placeholder count small (3-6) to reduce jank on low-end devices.
-
-### Minimal usage
+1. Render the real layout with placeholder data and apply
+   `.redacted(reason: .placeholder)`.
+2. A list gets a small, fixed set of skeleton rows, never a spinner that runs
+   with no end in sight.
+3. When loading finishes with no data, switch to `ContentUnavailableView`.
 
 ```swift
-VStack {
-  if isLoading {
-    ForEach(0..<3, id: \.self) { _ in
-      RowView(model: .placeholder())
+List {
+    if isFetching {
+        ForEach(0..<4, id: \.self) { _ in
+            InvoiceRow(invoice: .sample)
+                .redacted(reason: .placeholder)
+        }
+    } else if invoices.isEmpty {
+        ContentUnavailableView("No invoices", systemImage: "tray")
+    } else {
+        ForEach(invoices) { InvoiceRow(invoice: $0) }
     }
-    .redacted(reason: .placeholder)
-  } else if items.isEmpty {
-    ContentUnavailableView("No items", systemImage: "tray")
-  } else {
-    ForEach(items) { item in RowView(model: item) }
-  }
 }
 ```
 
-## Focus Handling
+Pitfalls and limits:
 
-This file covers basic form-focus patterns only. For directional focus, focus sections, scene-focused values, and `UIFocusGuide`, see the `focus-engine` skill.
+- Layout that shifts or animates while redacted. Keep frames stable.
+- Spinners nested inside spinners. One indicator per section.
+- More than three to six placeholder rows, which costs frames on older
+  devices.
 
-### Intent
+## 13. Form Focus
 
-Use `@FocusState` to control keyboard focus, chain fields, and coordinate focus across complex forms.
+This section covers keyboard focus in forms. Directional focus, focus sections
+and focus on tvOS, macOS and iPadOS keyboards are covered in `hig-inputs`;
+VoiceOver and other assistive focus is covered in `ios-accessibility`.
 
-### Core patterns
+`@FocusState` sets keyboard focus, moves it from field to field, and
+coordinates it across a complex form.
 
-- Use an enum to represent focusable fields.
-- Set initial focus in `onAppear`.
-- Use `.onSubmit` to move focus to the next field.
-- For dynamic lists of fields, use an enum with associated values (e.g., `.option(Int)`).
+- Describe the focusable fields with an enum.
+- Set the first focus in `onAppear`.
+- Move to the following field in `.onSubmit`.
+- For a variable number of fields, use an enum case with an associated value,
+  such as `.answer(Int)`.
 
-### Example: single field focus
+One field:
 
 ```swift
-struct AddServerView: View {
-  @State private var server = ""
-  @FocusState private var isServerFieldFocused: Bool
-
-  var body: some View {
-    Form {
-      TextField("Server", text: $server)
-        .focused($isServerFieldFocused)
+struct HostEntryForm: View {
+    @State private var host = ""
+    @FocusState private var hostFocused: Bool
+
+    var body: some View {
+        Form {
+            TextField("Host", text: $host)
+                .focused($hostFocused)
+        }
+        .onAppear { hostFocused = true }
     }
-    .onAppear { isServerFieldFocused = true }
-  }
 }
 ```
 
-### Example: chained focus with enum
+Chained fields:
 
 ```swift
-struct EditTagView: View {
-  enum FocusField { case title, symbol, newTag }
-  @FocusState private var focusedField: FocusField?
-
-  var body: some View {
-    Form {
-      TextField("Title", text: $title)
-        .focused($focusedField, equals: .title)
-        .onSubmit { focusedField = .symbol }
-
-      TextField("Symbol", text: $symbol)
-        .focused($focusedField, equals: .symbol)
-        .onSubmit { focusedField = .newTag }
+struct ContactForm: View {
+    enum Field { case name, phone, note }
+
+    @State private var name = ""
+    @State private var phone = ""
+    @State private var note = ""
+    @FocusState private var focus: Field?
+
+    var body: some View {
+        Form {
+            TextField("Name", text: $name)
+                .focused($focus, equals: .name)
+                .onSubmit { focus = .phone }
+            TextField("Phone", text: $phone)
+                .focused($focus, equals: .phone)
+                .onSubmit { focus = .note }
+            TextField("Note", text: $note)
+                .focused($focus, equals: .note)
+        }
+        .onAppear { focus = .name }
     }
-    .onAppear { focusedField = .title }
-  }
 }
 ```
 
-### Example: dynamic focus for variable fields
+A growing list of fields:
 
 ```swift
-struct PollView: View {
-  enum FocusField: Hashable { case option(Int) }
-  @FocusState private var focused: FocusField?
-  @State private var options: [String] = ["", ""]
-  @State private var currentIndex = 0
-
-  var body: some View {
-    ForEach(options.indices, id: \.self) { index in
-      TextField("Option \(index + 1)", text: $options[index])
-        .focused($focused, equals: .option(index))
-        .onSubmit { addOption(at: index) }
+struct SurveyAnswers: View {
+    enum Field: Hashable { case answer(Int) }
+
+    @State private var answers = [""]
+    @FocusState private var focus: Field?
+
+    var body: some View {
+        Form {
+            ForEach(answers.indices, id: \.self) { index in
+                TextField("Answer \(index + 1)", text: $answers[index])
+                    .focused($focus, equals: .answer(index))
+                    .onSubmit { addAnswer(after: index) }
+            }
+        }
     }
-    .onAppear { focused = .option(0) }
-  }
-
-  private func addOption(at index: Int) {
-    options.append("")
-    currentIndex = index + 1
-    Task { @MainActor in
-      try? await Task.sleep(for: .milliseconds(10))
-      focused = .option(currentIndex)
+
+    private func addAnswer(after index: Int) {
+        answers.append("")
+        let next = answers.count - 1
+        Task { @MainActor in
+            try? await Task.sleep(for: Duration.milliseconds(15))
+            focus = .answer(next)
+        }
     }
-  }
 }
 ```
 
-### Design choices to keep
+The short sleep lets SwiftUI insert the new field before focus moves to it.
+
+Guidelines:
 
-- Keep focus state local to the view that owns the fields.
-- Use focus changes to drive UX (validation messages, helper UI).
-- Pair with `.scrollDismissesKeyboard(...)` when using ScrollView/Form.
+- The view holding the text fields also holds their `@FocusState`.
+- React to focus moving: show a validation message or a hint for the field
+  that just gained or lost focus.
+- Inside a `ScrollView` or `Form`, pair focus with `.scrollDismissesKeyboard(_:)`.
 
-### Pitfalls
+Pitfalls:
 
-- Don't store focus state in shared objects; it is view-local.
-- Avoid aggressive focus changes during animation; delay if needed.
+- Focus state stored in shared objects; it is local to the view.
+- Focus changed aggressively in the middle of an animation. Delay it when
+  needed.