@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/swiftui-liquid-glass/references/liquid-glass.md

@@ -0,0 +1,387 @@
+# Liquid Glass API Reference for SwiftUI
+
+## Contents
+
+- [Overview](#overview)
+- [glassEffect(_:in:)](#glasseffect_in)
+- [Glass](#glass)
+- [GlassEffectContainer](#glasseffectcontainer)
+- [glassEffectID(_:in:)](#glasseffectid_in)
+- [glassEffectUnion(id:namespace:)](#glasseffectunionidnamespace)
+- [glassEffectTransition(_:)](#glasseffecttransition_)
+- [GlassEffectTransition](#glasseffecttransition)
+- [Button Styles](#button-styles)
+- [DefaultGlassEffectShape](#defaultglasseffectshape)
+- [Scroll Edge Effect](#scroll-edge-effect)
+- [Background Extension (Split Views)](#background-extension-split-views)
+- [Availability Gating](#availability-gating)
+- [Performance Guidelines](#performance-guidelines)
+- [Accessibility Considerations](#accessibility-considerations)
+- [Best Practices Summary](#best-practices-summary)
+- [Apple Documentation Links](#apple-documentation-links)
+
+## Overview
+
+Liquid Glass is a dynamic translucent material available on iOS 26.0+, iPadOS 26.0+,
+macOS 26.0+, Mac Catalyst 26.0+, tvOS 26.0+, and watchOS 26.0+. It blurs content
+behind it, reflects color and light from surrounding content, and reacts to touch and
+pointer interactions in real time. Standard SwiftUI components (tab bars, toolbars,
+navigation bars, sheets, popovers) adopt Liquid Glass automatically when built with
+the latest SDK.
+
+This reference covers the complete API surface for applying Liquid Glass to custom views.
+
+## glassEffect(_:in:)
+
+Applies the Liquid Glass effect behind a view.
+
+```swift
+nonisolated func glassEffect(
+    _ glass: Glass = .regular,
+    in shape: some Shape = DefaultGlassEffectShape()
+) -> some View
+```
+
+The system renders a shape anchored behind the view with the Liquid Glass material and
+applies foreground effects over the view content. The default shape is `Capsule`.
+
+Apply this modifier **after** other modifiers that affect the view's appearance (padding,
+frame, font, foregroundStyle).
+
+### Basic usage
+
+```swift
+Text("Hello, World!")
+    .font(.title)
+    .padding()
+    .glassEffect()
+```
+
+### Custom shape
+
+```swift
+Text("Hello, World!")
+    .font(.title)
+    .padding()
+    .glassEffect(in: .rect(cornerRadius: 16.0))
+```
+
+Common shapes: `.capsule` (default), `.rect(cornerRadius:)`, `.circle`.
+
+### Tinted and interactive
+
+```swift
+Text("Hello, World!")
+    .font(.title)
+    .padding()
+    .glassEffect(.regular.tint(.orange).interactive())
+```
+
+## Glass
+
+A structure that defines the configuration of the Liquid Glass material. Conforms to
+`Equatable`, `Sendable`, and `SendableMetatype`.
+
+### Type Properties
+
+| Property | Description |
+|---|---|
+| `.regular` | Standard Liquid Glass material |
+| `.clear` | Clear variant with minimal visual weight |
+| `.identity` | No-op; content appears as if no glass effect was applied |
+
+### Instance Methods
+
+| Method | Description |
+|---|---|
+| `.tint(_ color: Color)` | Returns a copy with a color tint to suggest prominence |
+| `.interactive(_ isInteractive: Bool = true)` | Returns a copy that reacts to touch and pointer interactions |
+
+Methods are chainable:
+
+```swift
+.glassEffect(.regular.tint(.blue).interactive())
+```
+
+## GlassEffectContainer
+
+A view that combines multiple Liquid Glass shapes into a single rendering pass. Enables
+blending and morphing between individual shapes.
+
+```swift
+@MainActor @preconcurrency
+struct GlassEffectContainer<Content> where Content : View
+```
+
+Conforms to `View`, `Sendable`, `SendableMetatype`.
+
+### Initializer
+
+```swift
+init(spacing: CGFloat, @ViewBuilder content: () -> Content)
+```
+
+The `spacing` parameter controls how glass shapes interact:
+
+- **Larger spacing**: Shapes begin blending at greater distances; morphing starts sooner.
+- **Smaller spacing**: Shapes must be closer before blending occurs.
+
+Match the container spacing to the interior layout spacing so shapes remain separate at
+rest but merge during animated transitions.
+
+### Example
+
+```swift
+GlassEffectContainer(spacing: 40.0) {
+    HStack(spacing: 40.0) {
+        Image(systemName: "scribble.variable")
+            .frame(width: 80.0, height: 80.0)
+            .font(.system(size: 36))
+            .glassEffect()
+
+        Image(systemName: "eraser.fill")
+            .frame(width: 80.0, height: 80.0)
+            .font(.system(size: 36))
+            .glassEffect()
+    }
+}
+```
+
+## glassEffectID(_:in:)
+
+Associates a stable identity with a Liquid Glass effect for morphing during view
+hierarchy transitions.
+
+```swift
+nonisolated func glassEffectID(
+    _ id: (some Hashable & Sendable)?,
+    in namespace: Namespace.ID
+) -> some View
+```
+
+Use with `@Namespace`, `GlassEffectContainer`, and `withAnimation` to animate shapes
+morphing into each other when views appear or disappear.
+
+### Morphing example
+
+```swift
+@State private var isExpanded = false
+@Namespace private var namespace
+
+var body: some View {
+    GlassEffectContainer(spacing: 40.0) {
+        HStack(spacing: 40.0) {
+            Image(systemName: "scribble.variable")
+                .frame(width: 80.0, height: 80.0)
+                .font(.system(size: 36))
+                .glassEffect()
+                .glassEffectID("pencil", in: namespace)
+
+            if isExpanded {
+                Image(systemName: "eraser.fill")
+                    .frame(width: 80.0, height: 80.0)
+                    .font(.system(size: 36))
+                    .glassEffect()
+                    .glassEffectID("eraser", in: namespace)
+            }
+        }
+    }
+
+    Button("Toggle") {
+        withAnimation {
+            isExpanded.toggle()
+        }
+    }
+    .buttonStyle(.glass)
+}
+```
+
+## glassEffectUnion(id:namespace:)
+
+Merges multiple views into a single Liquid Glass shape. All effects with the same shape,
+Glass variant, and union ID combine into one rendered shape.
+
+```swift
+@MainActor @preconcurrency func glassEffectUnion(
+    id: (some Hashable & Sendable)?,
+    namespace: Namespace.ID
+) -> some View
+```
+
+Useful for dynamically created views or views outside a shared layout container.
+
+### Example
+
+```swift
+@Namespace private var namespace
+let symbols = ["cloud.bolt.rain.fill", "sun.rain.fill", "moon.stars.fill", "moon.fill"]
+
+GlassEffectContainer(spacing: 20.0) {
+    HStack(spacing: 20.0) {
+        ForEach(symbols.indices, id: \.self) { i in
+            Image(systemName: symbols[i])
+                .frame(width: 80.0, height: 80.0)
+                .font(.system(size: 36))
+                .glassEffect()
+                .glassEffectUnion(id: i < 2 ? "weather" : "night", namespace: namespace)
+        }
+    }
+}
+```
+
+## glassEffectTransition(_:)
+
+Controls how a glass effect appears or disappears during view hierarchy changes.
+
+```swift
+@MainActor @preconcurrency func glassEffectTransition(
+    _ transition: GlassEffectTransition
+) -> some View
+```
+
+## GlassEffectTransition
+
+A structure describing changes when a glass effect is added to or removed from the
+view hierarchy. Conforms to `Sendable` and `SendableMetatype`.
+
+### Type Properties
+
+| Transition | Behavior |
+|---|---|
+| `.matchedGeometry` | Morphs the shape to/from nearby glass effects. Default when within container spacing. |
+| `.materialize` | Fades content and animates the glass material in/out without geometry matching. Use for distant effects. |
+| `.identity` | No transition animation. |
+
+### Example with explicit transition
+
+```swift
+if isExpanded {
+    Image(systemName: "note")
+        .frame(width: 20, height: 20)
+        .glassEffect()
+        .glassEffectID("note", in: namespace)
+        .glassEffectTransition(.materialize)
+}
+```
+
+## Button Styles
+
+SwiftUI provides two built-in Liquid Glass button styles.
+
+### GlassButtonStyle
+
+Standard glass appearance for buttons.
+
+```swift
+Button("Action") { }
+    .buttonStyle(.glass)
+```
+
+### GlassProminentButtonStyle
+
+A more prominent glass appearance for primary actions.
+
+```swift
+Button("Confirm") { }
+    .buttonStyle(.glassProminent)
+```
+
+These button styles automatically include interactivity (touch/pointer reactions).
+Prefer these over manually applying `.glassEffect(.regular.interactive())` to buttons.
+
+## DefaultGlassEffectShape
+
+The default shape used by `glassEffect(_:in:)` when no shape is specified. Resolves
+to `Capsule`.
+
+## Scroll Edge Effect
+
+Configures the scroll edge effect style for scroll views within a view hierarchy.
+
+```swift
+nonisolated func scrollEdgeEffectStyle(
+    _ style: ScrollEdgeEffectStyle?,
+    for edges: Edge.Set
+) -> some View
+```
+
+Available styles include `.soft` (soft edge) and `.hard`. System bars adopt this
+automatically. Apply to custom bars that float over scrollable content.
+
+```swift
+.scrollEdgeEffectStyle(.soft, for: .top)
+```
+
+## Background Extension (Split Views)
+
+Extend content visually under sidebars and inspectors by duplicating the view into
+mirrored copies with a blur effect applied on top:
+
+```swift
+NavigationSplitView {
+    // sidebar content
+} detail: {
+    ZStack {
+        BannerView()
+            .backgroundExtensionEffect()
+    }
+}
+```
+
+Also available as `backgroundExtensionEffect(isEnabled:)` for conditional use.
+Apply with discretion  -  typically to a single background view in the detail column.
+
+## Availability Gating
+
+All Liquid Glass APIs require iOS 26.0+. Always provide a fallback:
+
+```swift
+if #available(iOS 26, *) {
+    content
+        .padding()
+        .glassEffect(.regular, in: .rect(cornerRadius: 16))
+} else {
+    content
+        .padding()
+        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+```
+
+## Performance Guidelines
+
+- Use `GlassEffectContainer` to batch multiple glass effects into a single render pass.
+- Limit the total number of glass effects visible on screen at once.
+- Avoid creating many separate `GlassEffectContainer` instances when one can suffice.
+- Profile with Instruments to check rendering performance.
+
+## Accessibility Considerations
+
+- Test with **Reduce Transparency** enabled (glass effects adapt automatically for
+  standard components; verify custom implementations).
+- Test with **Reduce Motion** enabled (morphing and fluid animations are simplified).
+- Ensure sufficient contrast for text and icons rendered over glass.
+- Standard components from SwiftUI adapt to these settings automatically.
+
+## Best Practices Summary
+
+1. Use `GlassEffectContainer` when multiple glass views coexist.
+2. Apply `.glassEffect()` after layout and appearance modifiers.
+3. Match container `spacing` to interior layout spacing.
+4. Use `.interactive()` only on tappable/focusable elements.
+5. Use `withAnimation` when toggling views with `glassEffectID` for morphing.
+6. Prefer `.buttonStyle(.glass)` / `.buttonStyle(.glassProminent)` for buttons.
+7. Avoid overusing Liquid Glass -- reserve it for key functional elements.
+8. Always gate with `if #available(iOS 26, *)` and provide fallback UI.
+9. Test with Reduce Transparency and Reduce Motion accessibility settings.
+
+## Apple Documentation Links
+
+- [Applying Liquid Glass to custom views](https://sosumi.ai/documentation/swiftui/Applying-Liquid-Glass-to-custom-views)
+- [Adopting Liquid Glass](https://sosumi.ai/documentation/technologyoverviews/adopting-liquid-glass)
+- [Landmarks: Building an app with Liquid Glass](https://sosumi.ai/documentation/swiftui/Landmarks-Building-an-app-with-Liquid-Glass)
+- [View.glassEffect(_:in:)](https://sosumi.ai/documentation/swiftui/View/glassEffect(_:in:))
+- [Glass](https://sosumi.ai/documentation/swiftui/Glass)
+- [GlassEffectContainer](https://sosumi.ai/documentation/swiftui/GlassEffectContainer)
+- [GlassEffectTransition](https://sosumi.ai/documentation/swiftui/GlassEffectTransition)
+- [GlassButtonStyle](https://sosumi.ai/documentation/swiftui/GlassButtonStyle)
+- [GlassProminentButtonStyle](https://sosumi.ai/documentation/swiftui/GlassProminentButtonStyle)

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

@@ -5,7 +5,7 @@ description: "Implement SwiftUI navigation patterns including NavigationStack, N
 
 # SwiftUI Navigation
 
-Navigation patterns for SwiftUI apps targeting iOS 26+ with Swift 6.2. Covers push navigation, multi-column layouts, sheet presentation, tab architecture, and deep linking. Patterns are backward-compatible to iOS 17 unless noted.
+Navigation patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers push navigation, multi-column layouts, sheet presentation, tab architecture, and deep linking. Patterns are backward-compatible to iOS 17 unless noted.
 
 ## Contents
 
@@ -52,7 +52,7 @@ path = NavigationPath()  // Pop to root
 
 **Router pattern:** For apps with complex navigation, use a router object that owns the path and sheet state. Each tab gets its own router instance injected via `.environment()`. Centralize destination mapping with a single `.navigationDestination(for:)` block or a shared `withAppRouter()` modifier.
 
-See `references/navigationstack.md` for full router examples including per-tab stacks, centralized destination mapping, and generic tab routing.
+See [references/navigationstack.md](references/navigationstack.md) for full router examples including per-tab stacks, centralized destination mapping, and generic tab routing.
 
 ## NavigationSplitView (Multi-Column)
 
@@ -149,7 +149,7 @@ Fine-tuning: `.fitted(horizontal:vertical:)` constrains fitting axes; `.sticky(h
 
 **Dismissal confirmation (macOS 15+ / iOS 26+):** Use `.dismissalConfirmationDialog("Discard?", shouldPresent: hasUnsavedChanges)` to prevent accidental dismissal of sheets with unsaved changes.
 
-**Enum-driven sheet routing:** Define a `SheetDestination` enum that is `Identifiable`, store it on the router, and map it with a shared view modifier. This lets any child view present sheets without prop-drilling. See `references/sheets.md` for the full centralized sheet routing pattern.
+**Enum-driven sheet routing:** Define a `SheetDestination` enum that is `Identifiable`, store it on the router, and map it with a shared view modifier. This lets any child view present sheets without prop-drilling. See [references/sheets.md](references/sheets.md) for the full centralized sheet routing pattern.
 
 ## Tab-Based Navigation
 
@@ -185,7 +185,7 @@ struct MainTabView: View {
 - **`.tabViewBottomAccessory { }`** -- attach content below the tab bar (e.g., Now Playing bar)
 - **`TabSection`** -- group tabs into sidebar sections with `.tabPlacement(.sidebarOnly)`
 
-See `references/tabview.md` for full TabView patterns including custom bindings, dynamic tabs, and sidebar customization.
+See [references/tabview.md](references/tabview.md) for full TabView patterns including custom bindings, dynamic tabs, and sidebar customization.
 
 ## Deep Links
 
@@ -224,7 +224,7 @@ Register schemes in `Info.plist` under `CFBundleURLTypes`. Handle with `.onOpenU
 
 Advertise activities with `.userActivity()` and receive them with `.onContinueUserActivity()`. Declare activity types in `Info.plist` under `NSUserActivityTypes`. Set `isEligibleForHandoff = true` and provide a `webpageURL` as fallback.
 
-See `references/deeplinks.md` for full examples of AASA configuration, router URL handling, custom URL schemes, and NSUserActivity continuation.
+See [references/deeplinks.md](references/deeplinks.md) for full examples of AASA configuration, router URL handling, custom URL schemes, and NSUserActivity continuation.
 
 ## Common Mistakes
 
@@ -233,7 +233,7 @@ See `references/deeplinks.md` for full examples of AASA configuration, router UR
 3. Using `.sheet(isPresented:)` when state represents a model -- use `.sheet(item:)` instead
 4. Storing view instances in `NavigationPath` -- store lightweight `Hashable` route data
 5. Nesting `@Observable` router objects inside other `@Observable` objects
-6. Using deprecated `.tabItem { }` API -- use `Tab(value:)` with `TabView(selection:)`
+6. Prefer `Tab(value:)` with `TabView(selection:)` over the older `.tabItem { }` API
 7. Assuming `tabBarMinimizeBehavior` works on iPad -- it is iPhone only
 8. Handling deep links in multiple places -- centralize URL parsing in the router
 9. Hard-coding sheet frame dimensions -- use `.presentationSizing(.form)` instead
@@ -254,9 +254,9 @@ See `references/deeplinks.md` for full examples of AASA configuration, router UR
 
 ## References
 
-- NavigationStack and router patterns: `references/navigationstack.md`
-- Sheet presentation and routing: `references/sheets.md`
-- TabView patterns and iOS 26 API: `references/tabview.md`
-- Deep links, universal links, and Handoff: `references/deeplinks.md`
+- NavigationStack and router patterns: [references/navigationstack.md](references/navigationstack.md)
+- Sheet presentation and routing: [references/sheets.md](references/sheets.md)
+- TabView patterns and iOS 26 API: [references/tabview.md](references/tabview.md)
+- Deep links, universal links, and Handoff: [references/deeplinks.md](references/deeplinks.md)
 - Architecture and state management: see `swiftui-patterns` skill
 - Layout and components: see `swiftui-layout-components` skill

package/pipeline/skills/shared/external/swiftui-navigation/references/deeplinks.md

@@ -1,5 +1,17 @@
 # Deep links and navigation
 
+## Contents
+
+- [Intent](#intent)
+- [Core patterns](#core-patterns)
+- [Example: router entry points](#example-router-entry-points)
+- [Example: attach to a root view](#example-attach-to-a-root-view)
+- [Design choices to keep](#design-choices-to-keep)
+- [Pitfalls](#pitfalls)
+- [Universal Links](#universal-links)
+- [Custom URL Schemes](#custom-url-schemes)
+- [NSUserActivity Continuation (Handoff)](#nsuseractivity-continuation-handoff)
+
 ## Intent
 
 Route external URLs into in-app destinations while falling back to system handling when needed.
@@ -62,7 +74,7 @@ extension View {
 
 ## Pitfalls
 
-- Don’t assume the URL is internal; validate first.
+- Don't assume the URL is internal; validate first.
 - Avoid blocking UI while resolving remote links; use `Task`.
 
 ## Universal Links
@@ -90,7 +102,7 @@ Host a JSON file at `https://example.com/.well-known/apple-app-site-association`
 ```
 
 Key rules:
-- AASA must be served over HTTPS with a valid certificate — no redirects.
+- AASA must be served over HTTPS with a valid certificate  -  no redirects.
 - Apple's CDN caches the file; updates can take 24-48 hours. Use `https://app-site-association.cdn-apple.com/a/v1/example.com` to verify the cached version.
 - Use `components` (modern) over the legacy `paths` array.
 
@@ -167,7 +179,7 @@ Add `CFBundleURLTypes` to your target's Info.plist:
 }
 ```
 
-Prefer universal links over custom schemes for publicly shared links — they provide a better UX (web fallback) and are more secure (domain-verified).
+Prefer universal links over custom schemes for publicly shared links  -  they provide a better UX (web fallback) and are more secure (domain-verified).
 
 ## NSUserActivity Continuation (Handoff)
 

package/pipeline/skills/shared/external/swiftui-navigation/references/navigationstack.md

@@ -142,8 +142,8 @@ struct TabsView: View {
 }
 ```
 
-@MainActor
-@Observable
+`@MainActor`
+`@Observable`
 final class TabRouter {
   private var routers: [AppTab: RouterPath] = [:]
 

package/pipeline/skills/shared/external/swiftui-navigation/references/tabview.md

@@ -174,5 +174,5 @@ TabView {
 - Do not nest `@Observable` objects inside other `@Observable` objects.
 - Ensure `AppTab.id` values are stable; dynamic cases should hash on stable IDs.
 - Special tabs (compose) should not change selection.
-- Use `Tab(value:)` with `TabView(selection:)` -- do not use the deprecated `.tabItem { }` API.
+- Prefer `Tab(value:)` with `TabView(selection:)` over the older `.tabItem { }` API for typed tab selection.
 - `tabBarMinimizeBehavior` only works on iPhone; it has no effect on iPad or Mac.

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

@@ -1,11 +1,11 @@
 ---
 name: swiftui-patterns
-description: "Build SwiftUI views with modern MV architecture, state management, and view composition patterns. Covers @Observable ownership rules, @State/@Bindable/@Environment wiring, view decomposition, custom ViewModifiers, environment values, async data loading with .task, iOS 26+ APIs, Writing Tools, and performance guidelines. Use when structuring a SwiftUI app, managing state with @Observable, composing view hierarchies, or applying SwiftUI best practices."
+description: "Builds SwiftUI views with modern MV architecture, state management, and view composition patterns. Covers @Observable ownership rules, @State/@Bindable/@Environment wiring, view decomposition, custom ViewModifiers, environment values, async data loading with .task, iOS 26+ APIs, Writing Tools, and performance guidelines. Use when structuring a SwiftUI app, managing state with @Observable, composing view hierarchies, or applying SwiftUI best practices."
 ---
 
 # SwiftUI Patterns
 
-Modern SwiftUI patterns targeting iOS 26+ with Swift 6.2. 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.
+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.
 
 ## Contents
 
@@ -74,11 +74,11 @@ struct FeedView: View {
 }
 ```
 
-For MV pattern rationale, app wiring, and lightweight client examples, see `references/architecture-patterns.md`.
+For MV pattern rationale, app wiring, and lightweight client examples, see [references/architecture-patterns.md](references/architecture-patterns.md).
 
 ## State Management
 
-### @Observable Ownership Rules
+### `@Observable` Ownership Rules
 
 **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.
 
@@ -178,7 +178,7 @@ var body: some View {
 }
 
 private var header: some View {
-    VStack(alignment: .leading, spacing: 6) {
+    VStack(alignment: .leading) {
         Text(title).font(.title2)
         Text(subtitle).font(.subheadline)
     }
@@ -209,7 +209,7 @@ struct CardStyle: ViewModifier {
         content
             .padding()
             .background(.background)
-            .clipShape(RoundedRectangle(cornerRadius: 12))
+            .clipShape(.rect(cornerRadius: 12))
             .shadow(radius: 2)
     }
 }
@@ -224,23 +224,24 @@ Avoid top-level conditional view swapping. Prefer a single stable base view with
 
 ### Custom Environment Values
 
-```swift
-private struct ThemeKey: EnvironmentKey {
-    static let defaultValue: Theme = .default
-}
+Use `@Entry` for custom environment values and actions. It generates the entry boilerplate for `EnvironmentValues`.
 
+```swift
 extension EnvironmentValues {
-    var theme: Theme {
-        get { self[ThemeKey.self] }
-        set { self[ThemeKey.self] = newValue }
-    }
+    @Entry var theme: Theme = .default
+    @Entry var refreshFeed: @Sendable () async -> Void = {}
 }
 
 // Usage
 .environment(\.theme, customTheme)
-@Environment(\.theme) var theme
+.environment(\.refreshFeed) { await feedStore.refresh() }
+
+@Environment(\.theme) private var theme
+@Environment(\.refreshFeed) private var refreshFeed
 ```
 
+For iOS 17-compatible code or older compatibility shims, use manual `EnvironmentKey` types instead.
+
 ### Common Built-in Environment Values
 
 ```swift
@@ -303,10 +304,11 @@ Follow Apple Human Interface Guidelines for layout, typography, color, and acces
 - 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` for HIG, theming, haptics, focus, transitions, and loading patterns.
+See [references/design-polish.md](references/design-polish.md) for HIG, theming, haptics, focus, transitions, and loading patterns.
 
 ## Writing Tools (iOS 18+)
 
@@ -315,14 +317,14 @@ Control the Apple Intelligence Writing Tools experience on text views with `.wri
 | Level | Effect | When to use |
 |-------|--------|-------------|
 | `.complete` | Full inline rewriting (proofread, rewrite, transform) | Notes, email, documents |
-| `.limited` | Overlay panel only — original text untouched | Code editors, validated forms |
+| `.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 |
 
 ```swift
 TextEditor(text: $body)
     .writingToolsBehavior(.complete)
-TextField("Search…", text: $query)
+TextField("Search...", text: $query)
     .writingToolsBehavior(.disabled)
 ```
 
@@ -340,9 +342,31 @@ TextField("Search…", text: $query)
 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. Inline closures in body -- extract complex closures to methods
-10. `.sheet(isPresented:)` when state represents a model -- use `.sheet(item:)` instead
-11. **Using `AnyView` for type erasure** -- causes identity resets and disables diffing. Use `@ViewBuilder`, `Group`, or generics instead. See `references/deprecated-migration.md`
+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:
+
+```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") }
+    }
+
+    init() {
+        theme = UserDefaults.standard.string(forKey: "theme") ?? "system"
+    }
+}
+```
+
+14. Hard-coding `spacing:` on every stack -- omit it to get adaptive platform spacing; only specify when the value is intentional
 
 ## Review Checklist
 
@@ -355,17 +379,19 @@ TextField("Search…", text: $query)
 - [ ] 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`
-- Design polish (HIG, theming, haptics, transitions, loading, focus): `references/design-polish.md`
-- Deprecated API migration: `references/deprecated-migration.md`
-- Platform and sharing patterns (Transferable, media, menus, macOS settings): `references/platform-and-sharing.md`
+- 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)