@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/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/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/swiftui-navigation/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: swiftui-navigation
+description: "Implement SwiftUI navigation patterns including NavigationStack, NavigationSplitView, sheet presentation, tab-based navigation, and deep linking. Use when building push navigation, programmatic routing, multi-column layouts, modal sheets, tab bars, universal links, or custom URL scheme handling."
+---
+
+# 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.
+
+## Contents
+
+- [NavigationStack (Push Navigation)](#navigationstack-push-navigation)
+- [NavigationSplitView (Multi-Column)](#navigationsplitview-multi-column)
+- [Sheet Presentation](#sheet-presentation)
+- [Tab-Based Navigation](#tab-based-navigation)
+- [Deep Links](#deep-links)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## NavigationStack (Push Navigation)
+
+Use `NavigationStack` with a `NavigationPath` binding for programmatic, type-safe push navigation. Define routes as a `Hashable` enum and map them with `.navigationDestination(for:)`.
+
+```swift
+struct ContentView: View {
+    @State private var path = NavigationPath()
+
+    var body: some View {
+        NavigationStack(path: $path) {
+            List(items) { item in
+                NavigationLink(value: item) {
+                    ItemRow(item: item)
+                }
+            }
+            .navigationDestination(for: Item.self) { item in
+                DetailView(item: item)
+            }
+            .navigationTitle("Items")
+        }
+    }
+}
+```
+
+**Programmatic navigation:**
+
+```swift
+path.append(item)        // Push
+path.removeLast()        // Pop one
+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.
+
+## NavigationSplitView (Multi-Column)
+
+Use `NavigationSplitView` for sidebar-detail layouts on iPad and Mac. Falls back to stack navigation on iPhone.
+
+```swift
+struct MasterDetailView: View {
+    @State private var selectedItem: Item?
+
+    var body: some View {
+        NavigationSplitView {
+            List(items, selection: $selectedItem) { item in
+                NavigationLink(value: item) { ItemRow(item: item) }
+            }
+            .navigationTitle("Items")
+        } detail: {
+            if let item = selectedItem {
+                ItemDetailView(item: item)
+            } else {
+                ContentUnavailableView("Select an Item", systemImage: "sidebar.leading")
+            }
+        }
+    }
+}
+```
+
+### Custom Split Column (Manual HStack)
+
+For custom multi-column layouts (e.g., a dedicated notification column independent of selection), use a manual `HStack` split with `horizontalSizeClass` checks:
+
+```swift
+@MainActor
+struct AppView: View {
+  @Environment(\.horizontalSizeClass) private var horizontalSizeClass
+  @AppStorage("showSecondaryColumn") private var showSecondaryColumn = true
+
+  var body: some View {
+    HStack(spacing: 0) {
+      primaryColumn
+      if shouldShowSecondaryColumn {
+        Divider().edgesIgnoringSafeArea(.all)
+        secondaryColumn
+      }
+    }
+  }
+
+  private var shouldShowSecondaryColumn: Bool {
+    horizontalSizeClass == .regular
+      && showSecondaryColumn
+  }
+
+  private var primaryColumn: some View {
+    TabView { /* tabs */ }
+  }
+
+  private var secondaryColumn: some View {
+    NotificationsTab()
+      .environment(\.isSecondaryColumn, true)
+      .frame(maxWidth: .secondaryColumnWidth)
+  }
+}
+```
+
+Use the manual HStack split when you need full control or a non-standard secondary column. Use `NavigationSplitView` when you want a standard system layout with minimal customization.
+
+## Sheet Presentation
+
+Prefer `.sheet(item:)` over `.sheet(isPresented:)` when state represents a selected model. Sheets should own their actions and call `dismiss()` internally.
+
+```swift
+@State private var selectedItem: Item?
+
+.sheet(item: $selectedItem) { item in
+    EditItemSheet(item: item)
+}
+```
+
+**Presentation sizing (iOS 18+):** Control sheet dimensions with `.presentationSizing`:
+
+```swift
+.sheet(item: $selectedItem) { item in
+    EditItemSheet(item: item)
+        .presentationSizing(.form)  // .form, .page, .fitted, .automatic
+}
+```
+
+`PresentationSizing` values:
+- `.automatic` -- platform default
+- `.page` -- roughly paper size, for informational content
+- `.form` -- slightly narrower than page, for form-style UI
+- `.fitted` -- sized by the content's ideal size
+
+Fine-tuning: `.fitted(horizontal:vertical:)` constrains fitting axes; `.sticky(horizontal:vertical:)` grows but does not shrink in specified dimensions.
+
+**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.
+
+## Tab-Based Navigation
+
+Use the `Tab` API with a selection binding for scalable tab architecture. Each tab should wrap its content in an independent `NavigationStack`.
+
+```swift
+struct MainTabView: View {
+    @State private var selectedTab: AppTab = .home
+
+    var body: some View {
+        TabView(selection: $selectedTab) {
+            Tab("Home", systemImage: "house", value: .home) {
+                NavigationStack { HomeView() }
+            }
+            Tab("Search", systemImage: "magnifyingglass", value: .search) {
+                NavigationStack { SearchView() }
+            }
+            Tab("Profile", systemImage: "person", value: .profile) {
+                NavigationStack { ProfileView() }
+            }
+        }
+    }
+}
+```
+
+**Custom binding with side effects:** Route selection changes through a function to intercept special tabs (e.g., compose) that should trigger an action instead of changing selection.
+
+### iOS 26 Tab Additions
+
+- **`Tab(role: .search)`** -- replaces the tab bar with a search field when active
+- **`.tabBarMinimizeBehavior(_:)`** -- `.onScrollDown`, `.onScrollUp`, `.never` (iPhone only)
+- **`.tabViewSidebarHeader/Footer`** -- customize sidebar sections on iPadOS/macOS
+- **`.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.
+
+## Deep Links
+
+### Universal Links
+
+Universal links let iOS open your app for standard HTTPS URLs. They require:
+1. An Apple App Site Association (AASA) file at `/.well-known/apple-app-site-association`
+2. An Associated Domains entitlement (`applinks:example.com`)
+
+Handle in SwiftUI with `.onOpenURL` and `.onContinueUserActivity`:
+
+```swift
+@main
+struct MyApp: App {
+    @State private var router = Router()
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environment(router)
+                .onOpenURL { url in router.handle(url: url) }
+                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
+                    guard let url = activity.webpageURL else { return }
+                    router.handle(url: url)
+                }
+        }
+    }
+}
+```
+
+### Custom URL Schemes
+
+Register schemes in `Info.plist` under `CFBundleURLTypes`. Handle with `.onOpenURL`. Prefer universal links over custom schemes for publicly shared links -- they provide web fallback and domain verification.
+
+### Handoff (NSUserActivity)
+
+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.
+
+## Common Mistakes
+
+1. Using deprecated `NavigationView` -- use `NavigationStack` or `NavigationSplitView`
+2. Sharing one `NavigationPath` across all tabs -- each tab needs its own path
+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:)`
+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
+10. Missing `@MainActor` on router classes -- required for Swift 6 concurrency safety
+
+## Review Checklist
+
+- [ ] `NavigationStack` used (not `NavigationView`)
+- [ ] Each tab has its own `NavigationStack` with independent path
+- [ ] Route enum is `Hashable` with stable identifiers
+- [ ] `.navigationDestination(for:)` maps all route types
+- [ ] `.sheet(item:)` preferred over `.sheet(isPresented:)`
+- [ ] Sheets own their dismiss logic internally
+- [ ] Router object is `@MainActor` and `@Observable`
+- [ ] Deep link URLs parsed and validated before navigation
+- [ ] Universal links have AASA and Associated Domains configured
+- [ ] Tab selection uses `Tab(value:)` with binding
+
+## 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`
+- Architecture and state management: see `swiftui-patterns` skill
+- Layout and components: see `swiftui-layout-components` skill