@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,387 +1,233 @@
-# 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)
+# Liquid Glass API Reference
 
-## Overview
+Signatures and behaviour behind the `swiftui-liquid-glass` skill. Read its
+SKILL.md for the workflow and examples; this file is the detail.
 
-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.
+## Overview
 
-This reference covers the complete API surface for applying Liquid Glass to custom views.
+Release 26.0 of every Apple platform except visionOS brings these APIs: iOS
+and iPadOS, macOS and Mac Catalyst, tvOS and watchOS. The glass modifiers are
+marked unavailable on visionOS, which has its own material system. System
+chrome (bars, sheets and popovers) compiled against the 26 SDKs turns into
+glass without code changes.
 
 ## 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`.
+A `nonisolated` `View` method with two parameters:
 
-Apply this modifier **after** other modifiers that affect the view's appearance (padding,
-frame, font, foregroundStyle).
+| Parameter | Type | Default |
+| --- | --- | --- |
+| first, unlabeled | `Glass` | `.regular` |
+| `in` | `some Shape` | `DefaultGlassEffectShape()` |
 
-### 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))
-```
+Behind the view the system draws the shape in glass; over the view's own
+content it adds vibrancy and legibility treatment.
 
-Common shapes: `.capsule` (default), `.rect(cornerRadius:)`, `.circle`.
+Apply it after the modifiers that decide size and look: `padding`, `frame`,
+`font`, `foregroundStyle`.
 
-### Tinted and interactive
+Shapes you will use most:
 
 ```swift
-Text("Hello, World!")
-    .font(.title)
-    .padding()
-    .glassEffect(.regular.tint(.orange).interactive())
+Text("Capsule, the default").padding().glassEffect()
+Text("Rounded").padding(12).glassEffect(in: RoundedRectangle(cornerRadius: 22))
+Image(systemName: "bell").frame(width: 48, height: 48).glassEffect(in: .circle)
+Label("Alert", systemImage: "flame").padding()
+    .glassEffect(.regular.tint(.red).interactive(), in: .capsule)
 ```
 
 ## 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.
+struct Glass: Equatable, Sendable {
+    static var regular: Glass { get }
+    static var clear: Glass { get }
+    static var identity: Glass { get }
 
-```swift
-@MainActor @preconcurrency
-struct GlassEffectContainer<Content> where Content : View
-```
-
-Conforms to `View`, `Sendable`, `SendableMetatype`.
-
-### Initializer
-
-```swift
-init(spacing: CGFloat, @ViewBuilder content: () -> Content)
+    func tint(_ color: Color?) -> Glass
+    func interactive(_ isEnabled: Bool = true) -> Glass
+}
 ```
 
-The `spacing` parameter controls how glass shapes interact:
+`tint(_:)` hands back a tinted copy (a `nil` color clears it), and
+`interactive(_:)` hands back one that responds to fingers and pointer hover.
+Being `Sendable`, a `Glass` value can be computed anywhere and handed to a view.
 
-- **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.
+## GlassEffectContainer
 
-### Example
+A generic `View` over its `Content`, isolated to the main actor (declared
+`@MainActor @preconcurrency`) and also `Sendable`. Its initializer takes an
+optional `CGFloat` spacing, `nil` by default, and a `@ViewBuilder` closure. Every glass shape inside it is
+rendered in one pass, which is what lets shapes blend and morph.
 
-```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()
-    }
-}
-```
+`spacing` controls when shapes influence each other. A larger value lets
+shapes blend from further apart and makes morphing start earlier; a smaller
+value means shapes have to come closer first. Leaving it `nil` uses the system
+default.
 
 ## glassEffectID(_:in:)
 
-Associates a stable identity with a Liquid Glass effect for morphing during view
-hierarchy transitions.
+Nonisolated. The first argument is an optional identifier of any type that is
+both `Hashable` and `Sendable`; the `in:` argument is a `Namespace.ID`. It gives
+a glass shape a stable identity within a namespace. It only animates when
+three things are in place: a `@Namespace`, a shared `GlassEffectContainer`, and
+a state change wrapped in `withAnimation`.
 
-```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
+## glassEffectUnion(id:namespace:)
 
-```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)
+Main-actor isolated (`@MainActor @preconcurrency`), with labeled `id:` (an
+optional `Hashable & Sendable` value) and `namespace:` (a `Namespace.ID`)
+arguments. Views whose glass effects share the same shape, the same `Glass` value and the
+same union ID are drawn as one combined shape. It helps when the views are
+generated dynamically or do not sit in one layout container.
+
+## glassEffectTransition(_:) and GlassEffectTransition
+
+The modifier is main-actor isolated and takes one `GlassEffectTransition`, a
+`Sendable` struct with three static values.
+
+| Transition | Behaviour | When |
+| --- | --- | --- |
+| `.matchedGeometry` | Morphs with nearby shapes; the default within the container's spacing | Elements that sit close together |
+| `.materialize` | Content fades while the glass itself grows in or shrinks away; shapes are not matched | Elements far from any other glass |
+| `.identity` | Nothing | Instant changes |
+
+```swift
+@available(iOS 26, *)
+struct DetailsToggle: View {
+    @State private var showDetails = false
+    @Namespace private var space
+
+    var body: some View {
+        let gap: CGFloat = 24
+        return GlassEffectContainer(spacing: gap) {
+            VStack(spacing: gap) {
+                Button("Details") { withAnimation { showDetails.toggle() } }
+                    .buttonStyle(.glass)
+                    .glassEffectID("toggle", in: space)
+
+                if showDetails {
+                    Text("Gate B12 closes at 09:40")
+                        .padding()
+                        .glassEffect(in: .rect(cornerRadius: 14))
+                        .glassEffectID("details", in: space)
+                        .glassEffectTransition(.materialize)
+                }
             }
         }
     }
-
-    Button("Toggle") {
-        withAnimation {
-            isExpanded.toggle()
-        }
-    }
-    .buttonStyle(.glass)
 }
 ```
 
-## glassEffectUnion(id:namespace:)
+## Button styles
 
-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.
+| Style | Type | Use |
+| --- | --- | --- |
+| `.glass` | `GlassButtonStyle` | Regular actions |
+| `.glassProminent` | `GlassProminentButtonStyle` | The primary action on a screen |
 
-```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)
-        }
-    }
-}
-```
+Both are `PrimitiveButtonStyle` types and already include the interactive
+behaviour, so prefer them to putting `.glassEffect(.regular.interactive())` on
+a `Button` yourself.
 
-## glassEffectTransition(_:)
+## DefaultGlassEffectShape
 
-Controls how a glass effect appears or disappears during view hierarchy changes.
+The default `in:` argument of `glassEffect`. It resolves to a `Capsule`.
 
-```swift
-@MainActor @preconcurrency func glassEffectTransition(
-    _ transition: GlassEffectTransition
-) -> some View
-```
+## Scroll edge effect
 
-## GlassEffectTransition
+A nonisolated modifier taking an optional `ScrollEdgeEffectStyle` and, after
+`for:`, an `Edge.Set`. Styles are `.automatic`, `.soft` (a gradual fade) and `.hard` (a crisper cut
+off). System bars already apply an edge effect; set the style yourself for
+custom bars that float over scrolling content, or to change the look.
 
-A structure describing changes when a glass effect is added to or removed from the
-view hierarchy. Conforms to `Sendable` and `SendableMetatype`.
+## Background extension (split views)
 
-### Type Properties
+Two main-actor overloads: `backgroundExtensionEffect()` and
+`backgroundExtensionEffect(isEnabled:)`.
 
-| 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
+Inside a `NavigationSplitView` detail column, this mirrors and blurs the view
+into the area under the sidebar or inspector, so artwork seems to continue
+behind them. Use the `isEnabled:` form to switch it conditionally. Usually only
+the backdrop view of the detail column should carry it.
 
 ```swift
-if isExpanded {
-    Image(systemName: "note")
-        .frame(width: 20, height: 20)
-        .glassEffect()
-        .glassEffectID("note", in: namespace)
-        .glassEffectTransition(.materialize)
+NavigationSplitView {
+    SidebarList()
+} detail: {
+    Image("coastline")
+        .resizable()
+        .scaledToFill()
+        .backgroundExtensionEffect()
 }
 ```
 
-## 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.
+## ToolbarSpacer
 
 ```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()
-    }
+struct ToolbarSpacer: ToolbarContent {
+    init(_ sizing: SpacerSizing = .flexible, placement: ToolbarItemPlacement = .automatic)
 }
 ```
 
-Also available as `backgroundExtensionEffect(isEnabled:)` for conditional use.
-Apply with discretion  -  typically to a single background view in the detail column.
+`.fixed` inserts a fixed gap that separates glass groups; `.flexible` pushes
+groups apart. Available on iOS and macOS 26.
 
-## Availability Gating
+## Availability gating
 
-All Liquid Glass APIs require iOS 26.0+. Always provide a fallback:
+Every API above needs iOS 26. Give older systems a material background of the
+same shape:
 
 ```swift
-if #available(iOS 26, *) {
-    content
-        .padding()
-        .glassEffect(.regular, in: .rect(cornerRadius: 16))
-} else {
-    content
-        .padding()
-        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+extension View {
+    @ViewBuilder
+    func cardSurface(cornerRadius: CGFloat = 16) -> some View {
+        if #available(iOS 26, *) {
+            glassEffect(in: .rect(cornerRadius: cornerRadius))
+        } else {
+            background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: cornerRadius))
+        }
+    }
 }
 ```
 
-## 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)
+## Performance guidelines
+
+- Group glass in a container so the shapes render in one pass.
+- Keep the number of glass surfaces on screen small.
+- Prefer one container per group over many small containers.
+- Measure with Instruments (SwiftUI and Core Animation templates) before and
+  after adding glass to scrolling content.
+
+## Accessibility considerations
+
+- **Reduce Transparency**: system components switch to a more opaque
+  appearance on their own. Check that custom glass still reads well.
+- **Reduce Motion**: morphing and fluid animations are toned down. Make sure
+  the interface still makes sense without them.
+- **Contrast**: text and icons over glass need enough contrast against
+  whatever may scroll behind them.
+
+## Best practices summary
+
+1. Glass that shares the screen shares a `GlassEffectContainer`.
+2. `.glassEffect()` goes last, once size and styling are settled.
+3. The container's spacing equals the stack's spacing (or exceeds it).
+4. Only controls get `.interactive()`.
+5. Morphing needs `glassEffectID` plus a change inside `withAnimation`.
+6. Buttons take `.glass` or `.glassProminent`.
+7. Fewer glass surfaces read better than many.
+8. Anything glass sits behind an iOS 26 check with a fallback.
+9. Every screen is checked once with Reduce Transparency, once with Reduce Motion.
+
+## Apple documentation links
+
+- [Article: glass on custom views](https://developer.apple.com/documentation/swiftui/applying-liquid-glass-to-custom-views)
+- [Overview: adopting the new material](https://developer.apple.com/documentation/technologyoverviews/adopting-liquid-glass)
+- [Sample code: Landmarks](https://developer.apple.com/documentation/swiftui/landmarks-building-an-app-with-liquid-glass)
+- [glassEffect modifier](https://developer.apple.com/documentation/swiftui/view/glasseffect(_:in:))
+- [Glass](https://developer.apple.com/documentation/swiftui/glass)
+- [GlassEffectContainer](https://developer.apple.com/documentation/swiftui/glasseffectcontainer)
+- [GlassEffectTransition](https://developer.apple.com/documentation/swiftui/glasseffecttransition)
+- [GlassButtonStyle](https://developer.apple.com/documentation/swiftui/glassbuttonstyle)
+- [GlassProminentButtonStyle](https://developer.apple.com/documentation/swiftui/glassprominentbuttonstyle)