Skill: steipete/swiftui-liquid-glass (version 1.0.0)

--- name: swiftui-liquid-glass description: Implement, review, or improve SwiftUI features using the iOS 26+ Liquid Glass API. Use when asked to adopt Liquid Glass in new SwiftUI UI, refactor an existing feature to Liquid Glass, or review Liquid Glass usage for correctness, performance, and design alignment. --- # SwiftUI Liquid Glass _Attribution: copied from @Dimillian’s `Dimillian/Skills` (2025-12-31)._ ## Overview Use this skill to build or review SwiftUI features that fully align with the iOS 26+ Liquid Glass API. Prioritize native APIs (`glassEffect`, `GlassEffectContainer`, glass button styles) and Apple design guidance. Keep usage consistent, interactive where needed, and performance aware. ## Workflow Decision Tree Choose the path that matches the request: ### 1) Review an existing feature - Inspect where Liquid Glass should be used and where it should not. - Verify correct modifier order, shape usage, and container placement. - Check for iOS 26+ availability handling and sensible fallbacks. ### 2) Improve a feature using Liquid Glass - Identify target components for glass treatment (surfaces, chips, buttons, cards). - Refactor to use `GlassEffectContainer` where multiple glass elements appear. - Introduce interactive glass only for tappable or focusable elements. ### 3) Implement a new feature using Liquid Glass - Design the glass surfaces and interactions first (shape, prominence, grouping). - Add glass modifiers after layout/appearance modifiers. - Add morphing transitions only when the view hierarchy changes with animation. ## Core Guidelines - Prefer native Liquid Glass APIs over custom blurs. - Use `GlassEffectContainer` when multiple glass elements coexist. - Apply `.glassEffect(...)` after layout and visual modifiers. - Use `.interactive()` for elements that respond to touch/pointer. - Keep shapes consistent across related elements for a cohesive look. - Gate with `#available(iOS 26, *)` and provide a non-glass fallback. ## Review Checklist - **Availability**: `#available(iOS 26, *)` present with fallback UI. - **Composition**: Multiple glass views wrapped in `GlassEffectContainer`. - **Modifier order**: `glassEffect` applied after layout/appearance modifiers. - **Interactivity**: `interactive()` only where user interaction exists. - **Transitions**: `glassEffectID` used with `@Namespace` for morphing. - **Consistency**: Shapes, tinting, and spacing align across the feature. ## Implementation Checklist - Define target elements and desired glass prominence. - Wrap grouped glass elements in `GlassEffectContainer` and tune spacing. - Use `.glassEffect(.regular.tint(...).interactive(), in: .rect(cornerRadius: ...))` as needed. - Use `.buttonStyle(.glass)` / `.buttonStyle(.glassProminent)` for actions. - Add morphing transitions with `glassEffectID` when hierarchy changes. - Provide fallback materials and visuals for earlier iOS versions. ## Quick Snippets Use these patterns directly and tailor shapes/tints/spacing. ```swift if #available(iOS 26, *) { Text("Hello") .padding() .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16)) } else { Text("Hello") .padding() .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16)) } ``` ```swift GlassEffectContainer(spacing: 24) { HStack(spacing: 24) { Image(systemName: "scribble.variable") .frame(width: 72, height: 72) .font(.system(size: 32)) .glassEffect() Image(systemName: "eraser.fill") .frame(width: 72, height: 72) .font(.system(size: 32)) .glassEffect() } } ``` ```swift Button("Confirm") { } .buttonStyle(.glassProminent) ``` ## Resources - Reference guide: `references/liquid-glass.md` - Prefer Apple docs for up-to-date API details.

path: references/liquid-glass.md
content: # Implementing Liquid Glass Design in SwiftUI

## Overview

Liquid Glass is a dynamic material introduced in iOS that combines the optical properties of glass with a sense of fluidity. It blurs content behind it, reflects color and light from surrounding content, and reacts to touch and pointer interactions in real time. This guide covers how to implement and customize Liquid Glass effects in SwiftUI applications. You should always seek guides on Liquid Glass when asked for help adopting new Apple design.

Key features of Liquid Glass:
- Blurs content behind the material
- Reflects color and light from surrounding content
- Reacts to touch and pointer interactions
- Can morph between shapes during transitions
- Available for standard and custom components

## Basic Implementation

### Adding Liquid Glass to a View

The simplest way to add Liquid Glass to a view is using the `glassEffect()` modifier:

```swift
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect()
```

By default, this applies the regular variant of Glass within a Capsule shape behind the view's content.

### Customizing the Shape

You can specify a different shape for the Liquid Glass effect:

```swift
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16.0))
```

Common shape options:
- `.capsule` (default)
- `.rect(cornerRadius: CGFloat)`
- `.circle`

## Customizing Liquid Glass Effects

### Glass Variants and Properties

You can customize the Liquid Glass effect by configuring the `Glass` structure:

```swift
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.tint(.orange).interactive())
```

Key customization options:
- `.regular` - Standard glass effect
- `.tint(Color)` - Add a color tint to suggest prominence
- `.interactive(Bool)` - Make the glass react to touch and pointer interactions

### Making Interactive Glass

To make Liquid Glass react to touch and pointer interactions:

```swift
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.interactive(true))
```

Or more concisely:

```swift
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.interactive())
```

## Working with Multiple Glass Effects

### Using GlassEffectContainer

When applying Liquid Glass effects to multiple views, use `GlassEffectContainer` for better rendering performance and to enable blending and morphing effects:

```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()
    }
}
```

The `spacing` parameter controls how the Liquid Glass effects interact with each other:
- Smaller spacing: Views need to be closer to merge effects
- Larger spacing: Effects merge at greater distances

### Uniting Multiple Glass Effects

To combine multiple views into a single Liquid Glass effect, use the `glassEffectUnion` modifier:

```swift
@Namespace private var namespace

// Later in your view:
GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(symbolSet.indices, id: \.self) { item in
            Image(systemName: symbolSet[item])
                .frame(width: 80.0, height: 80.0)
                .font(.system(size: 36))
                .glassEffect()
                .glassEffectUnion(id: item < 2 ? "1" : "2", namespace: namespace)
        }
    }
}
```

This is useful when creating views dynamically or with views that live outside of an HStack or VStack.

## Morphing Effects and Transitions

### Creating Morphing Transitions

To create morphing effects during transitions between views with Liquid Glass:

1. Create a namespace using the `@Namespace` property wrapper
2. Associate each Liquid Glass effect with a unique identifier using `glassEffectID`
3. Use animations when changing the view hierarchy

```swift
@State private var isExpanded: Bool = 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)
}
```

The morphing effect occurs when views with Liquid Glass appear or disappear due to view hierarchy changes.

## Button Styling with Liquid Glass

### Glass Button Style

SwiftUI provides built-in button styles for Liquid Glass:

```swift
Button("Click Me") {
    // Action
}
.buttonStyle(.glass)
```

### Glass Prominent Button Style

For a more prominent glass button:

```swift
Button("Important Action") {
    // Action
}
.buttonStyle(.glassProminent)
```

## Advanced Techniques

### Background Extension Effect

To stretch content behind a sidebar or inspector with the background extension effect:

```swift
NavigationSplitView {
    // Sidebar content
} detail: {
    // Detail content
        .background {
            // Background content that extends under the sidebar
        }
}
```

### Extending Horizontal Scrolling Under Sidebar

To extend horizontal scroll views under a sidebar or inspector:

```swift
ScrollView(.horizontal) {
    // Scrollable content
}
.scrollExtensionMode(.underSidebar)
```

## Best Practices

1. **Container Usage**: Always use `GlassEffectContainer` when applying Liquid Glass to multiple views for better performance and morphing effects.

2. **Effect Order**: Apply the `.glassEffect()` modifier after other modifiers that affect the appearance of the view.

3. **Spacing Consideration**: Carefully choose spacing values in containers to control how and when glass effects merge.

4. **Animation**: Use animations when changing view hierarchies to enable smooth morphing transitions.

5. **Interactivity**: Add `.interactive()` to glass effects that should respond to user interaction.

6. **Consistent Design**: Maintain consistent shapes and styles across your app for a cohesive look and feel.

## Example: Custom Badge with Liquid Glass

```swift
struct BadgeView: View {
    let symbol: String
    let color: Color

    var body: some View {
        ZStack {
            Image(systemName: "hexagon.fill")
                .foregroundColor(color)
                .font(.system(size: 50))

            Image(systemName: symbol)
                .foregroundColor(.white)
                .font(.system(size: 30))
        }
        .glassEffect(.regular, in: .rect(cornerRadius: 16))
    }
}

// Usage:
GlassEffectContainer(spacing: 20) {
    HStack(spacing: 20) {
        BadgeView(symbol: "star.fill", color: .blue)
        BadgeView(symbol: "heart.fill", color: .red)
        BadgeView(symbol: "leaf.fill", color: .green)
    }
}
```

## References

- [Applying Liquid Glass to custom views](https://developer.apple.com/documentation/SwiftUI/Applying-Liquid-Glass-to-custom-views)
- [Landmarks: Building an app with Liquid Glass](https://developer.apple.com/documentation/SwiftUI/Landmarks-Building-an-app-with-Liquid-Glass)
- [SwiftUI View.glassEffect(_:in:isEnabled:)](https://developer.apple.com/documentation/SwiftUI/View/glassEffect(_:in:isEnabled:))
- [SwiftUI GlassEffectContainer](https://developer.apple.com/documentation/SwiftUI/GlassEffectContainer)
- [SwiftUI GlassEffectTransition](https://developer.apple.com/documentation/SwiftUI/GlassEffectTransition)
- [SwiftUI GlassButtonStyle](https://developer.apple.com/documentation/SwiftUI/GlassButtonStyle)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)