/liquid-glass

name: liquid-glass
description: Implement Liquid Glass design using .glassEffect() API for iOS/macOS 26+. Covers SwiftUI, AppKit, UIKit, and WidgetKit. Use when creating modern glass-based UI effects.
allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Liquid Glass Design

Implement Apple's Liquid Glass design language across all Apple UI frameworks. Covers SwiftUI (`.glassEffect()`), AppKit (`NSGlassEffectView`), UIKit (`UIGlassEffect` + `UIVisualEffectView`), and WidgetKit (rendering modes, accented content, glass elements in widgets).

When This Skill Activates

• User wants glass/blur effects on views
• User asks about Liquid Glass or modern Apple design
• User needs transparent, interactive UI elements
• User wants morphing transitions between views
• User is implementing glass effects in UIKit with `UIVisualEffectView`
• User needs `UIGlassEffect` or `UIGlassContainerEffect`
• User asks about scroll view edge effects in UIKit
• User wants Liquid Glass in widgets (WidgetKit)
• User needs to support accented rendering mode in widgets
• User asks about widget textures or mounting styles on visionOS

Design Rules (WWDC25)

Liquid Glass is the material of the **navigation layer** — bars, toolbars, floating controls — never the content layer (tables, lists, rows in a scroll view).

| Rule | Detail | |------|--------| | **Never glass on glass** | Don't stack glass. Elements sitting ON glass don't get the material again — style them with fills and vibrancy. | | **Two variants — never mix them** | **Regular** (default): works at any size, over anything, with adaptive legibility. **Clear**: only when ALL three hold — media-rich content underneath, a dimming layer is acceptable, and bold bright content sits above. Clear has no adaptive behaviors. One variant per interface. | | **Tint only primary actions** | "When every element is tinted, nothing stands out." | | **No steady-state intersections** | In resting layouts, content shouldn't sit half-under a glass element — reposition or scale the content instead. | | **Strip decorated bars** | Remove customized bar backgrounds and borders; build hierarchy through layout and grouping, not decoration. Never group a symbol with a text label in one toolbar group. Action sheets spring from their source element. |

**Scroll edge effects** keep floating elements separated from scrolling content: soft (gradual fade — the iOS default) vs hard (denser, with a dividing line — mostly macOS). One per view edge, and they're not decorative — don't add one where no floating UI elements exist.

**Shape system** — let containers do the math:

| Shape | Radius | Use | |-------|--------|-----| | Fixed | Constant | Standalone elements | | Capsule | Half the element height | Phone-scale controls — add extra margin from the screen edge | | Concentric | Parent radius minus padding | Nested containers (inner radii auto-calculate); iPad/Mac elements concentric with the window edge |

**Accessibility comes free at the system level**: Reduced Motion decreases lensing and elastic effects; Increased Contrast renders glass elements black/white with a contrasting border. (Lensing is how glass appears — it materializes by modulating how it bends light, and adaptive shadows flip small elements light/dark for legibility over any content.)

Quick Start (SwiftUI)

Basic Glass Effect

import SwiftUI

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect()  // Capsule shape by default

Custom Shape

Text("Hello")
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16))

// Available shapes:
// .capsule (default)
// .rect(cornerRadius: CGFloat)
// .rect(corner: .containerConcentric) — radius derived from the container, keeps nested shapes concentric
// .circle

Interactive Glass

Button("Tap Me") {
    // action
}
.padding()
.glassEffect(.regular.interactive())

Tinted Glass

Text("Important")
    .padding()
    .glassEffect(.regular.tint(.blue))

Glass Configuration Options

| Option | Description | Example | |--------|-------------|---------| | `.regular` | Standard glass effect | `.glassEffect(.regular)` | | `.tint(Color)` | Add color tint | `.glassEffect(.regular.tint(.orange))` | | `.interactive()` | Scale, bounce, and shimmer on touch/hover | `.glassEffect(.regular.interactive())` |

Multiple Glass Effects

GlassEffectContainer

When using multiple glass elements, wrap them in `GlassEffectContainer` for:

• Better rendering performance
• Proper blending between effects
• Morphing transitions

This is correctness, not just performance: glass can not sample other glass, so nearby glass elements must share ONE container to render and blend correctly.

GlassEffectContainer(spacing: 40.0) {
    HStack(spacing: 40.0) {
        Image(systemName: "star.fill")
            .frame(width: 80, height: 80)
            .font(.system(size: 36))
            .glassEffect()

        Image(systemName: "heart.fill")
            .frame(width: 80, height: 80)
            .font(.system(size: 36))
            .glassEffect()
    }
}

**Spacing Parameter:**

• Controls when effects merge
• Smaller spacing = views must be closer to merge
• Larger spacing = effects merge at greater distances

Uniting Glass Effects

Combine views into a single glass effect using `glassEffectUnion`:

@Namespace private var namespace

GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(items.indices, id: \.self) { index in
            Image(systemName: items[index])
                .frame(width: 60, height: 60)
                .glassEffect()
                .glassEffectUnion(
                    id: index < 2 ? "group1" : "group2",
                    namespace: namespace
                )
        }
    }
}

Morphing Transitions

Create fluid morphing effects whe