swiftui-liquid-glass git:20261019.6c21074A

Immutable. This exact content never changes and is served at /api/v1/blob/1a2d9906efc0f351.

---
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 SwiftUI UI, refactor to Liquid Glass, or review Liquid Glass usage.
---

# SwiftUI Liquid Glass

## Overview

Liquid Glass is a dynamic material in iOS 26+ that combines optical glass properties with fluidity. It blurs content, reflects surrounding color and light, and reacts to touch interactions in real time.

## The `UIDesignRequiresCompatibility` opt-out ends with the iOS 27 SDK

The `UIDesignRequiresCompatibility` Info.plist key lets an app built with the iOS 26 SDK keep its pre-iOS 26 look. Apple's reference page for the key says: "The system ignores this key when you build for iOS 27 or later, iPadOS 27 or later, Mac Catalyst 27 or later, macOS 27 or later, or tvOS 27 or later." (https://developer.apple.com/documentation/bundleresources/information-property-list/uidesignrequirescompatibility)

Before moving a project to Xcode 27, audit its UI under the current design with the key removed or set to `NO`, and fix what changes. Do not rely on the key to postpone that work.

## Workflow Decision Tree

### 1) Review an existing feature
- Inspect where Liquid Glass should/shouldn't be used
- Verify correct modifier order, shape usage, container placement
- Check for iOS 26+ availability handling and fallbacks

### 2) Improve a feature using Liquid Glass
- Identify target components (surfaces, chips, buttons, cards)
- Refactor to use `GlassEffectContainer` for multiple glass elements
- Add interactive glass only for tappable/focusable elements

### 3) Implement a new feature using Liquid Glass
- Design glass surfaces and interactions first (shape, prominence, grouping)
- Add glass modifiers after layout/appearance modifiers
- Add morphing transitions only when 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
- Gate with `#available(iOS 26, *)` and provide 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 feature

## Implementation Checklist

- [ ] Define target elements and desired glass prominence
- [ ] Wrap grouped glass elements in `GlassEffectContainer` with 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 for earlier iOS versions

## Quick Snippets

### Basic Glass Effect with Fallback
```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))
}
```

### Multiple Glass Elements
```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()
    }
}
```

### Glass Buttons
```swift
Button("Confirm") { }
    .buttonStyle(.glassProminent)

Button("Cancel") { }
    .buttonStyle(.glass)
```

### Morphing Transitions
```swift
@State private var isExpanded = false
@Namespace private var namespace

GlassEffectContainer(spacing: 40) {
    HStack(spacing: 40) {
        Image(systemName: "pencil")
            .frame(width: 80, height: 80)
            .glassEffect()
            .glassEffectID("pencil", in: namespace)

        if isExpanded {
            Image(systemName: "eraser")
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectID("eraser", in: namespace)
        }
    }
}

Button("Toggle") {
    withAnimation {
        isExpanded.toggle()
    }
}
.buttonStyle(.glass)
```

### Customizing Glass
```swift
Text("Tinted Glass")
    .padding()
    .glassEffect(.regular.tint(.orange).interactive(), in: .capsule)
```

### Uniting Glass Effects
```swift
@Namespace private var namespace

GlassEffectContainer(spacing: 20) {
    HStack(spacing: 20) {
        ForEach(items.indices, id: \.self) { index in
            ItemView(item: items[index])
                .glassEffect()
                .glassEffectUnion(id: index < 2 ? "group1" : "group2", namespace: namespace)
        }
    }
}
```

## Shape Options

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

## Fallback Materials

When gating with `#available(iOS 26, *)`, fall back to a `Material`, ordered from closest to glass appearance to most opaque:

- `.ultraThinMaterial` -- closest to glass appearance
- `.thinMaterial` -- slightly more opaque
- `.regularMaterial` -- standard blur
- `.thickMaterial` -- more opaque
- `.ultraThickMaterial` -- most opaque

## System Design Notes

- **Toolbar icons** render monochrome by default in the new design. The monochrome palette reduces visual noise and maintains legibility -- use `tint(_:)` only to convey meaning (e.g. a call to action), not for visual effect.
- **Partial-height sheets** use a Liquid Glass background by default. If a custom `presentationBackground(_:)` was previously applied, consider removing it to let the new material shine. Sheets can morph out of the glass controls that present them using `navigationZoomTransition`.
- **Scroll edge effects** automatically blur and fade content under system toolbars to keep controls legible. Remove any custom background-darkening effects behind bar items -- they interfere with the automatic effect.

> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)

## Best Practices

1. **Container Usage**: Always use `GlassEffectContainer` for multiple glass views
2. **Modifier Order**: Apply `.glassEffect()` after appearance modifiers
3. **Spacing**: Choose spacing values carefully to control effect merging
4. **Animation**: Use animations when changing view hierarchies for smooth morphing
5. **Interactivity**: Add `.interactive()` only to touchable elements
6. **Consistency**: Maintain consistent shapes and styles across your app

Source: split from [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill)'s reference material; also cites Apple's WWDC25 session 323 for one design note.