Liquid Glass

Liquid Glass (iOS 26+)

Liquid Glass is Apple's dynamic material for the navigation and control layer (iOS/iPadOS/macOS/watchOS/tvOS/visionOS 26+). It blurs content behind it, reflects surrounding light, reacts to touch, and morphs between shapes. Standard SwiftUI/UIKit/AppKit components adopt it automatically; you apply it explicitly to custom controls. The visual direction is yours — this skill covers what the system provides and how to use it correctly.

This SKILL.md is the dispatcher. Read the reference file named for the task at the point of use.

Reference map

| You need… | Read | |-----------|------| | API signatures, variants, cross-framework equivalents, official links/WWDC/versions | [references/api-core.md](references/api-core.md) | | SwiftUI implementation code (glass, containers, morphing, nav, sheets, SF Symbols, haptics, fallbacks) | [references/swiftui-patterns.md](references/swiftui-patterns.md) | | UIKit (UIGlassEffect) and WidgetKit (accented rendering) code | [references/uikit-widgetkit.md](references/uikit-widgetkit.md) | | Refactoring an existing shipping app to Liquid Glass | [references/adoption-guide.md](references/adoption-guide.md) | | Apple's Landmarks worked examples (background extension, toolbar, badges) | [references/examples-landmarks.md](references/examples-landmarks.md) | | Design principles, best practices, anti-patterns, accessibility | [references/design-principles.md](references/design-principles.md) |

Step 0 — Read first (always, before changing anything)

1. Inventory existing glass usage. Grep the target for glassEffect, GlassEffectContainer, glassEffectID, glassEffectUnion, buttonStyle(.glass, UIGlassEffect, backgroundExtensionEffect, .ultraThinMaterial, visualEffect, custom blur/material backgrounds. Note where glass already exists and where custom materials imitate it.
2. Find the deployment target. Check the iOS deployment target (Xcode project / Package.swift platforms: / @available). Liquid Glass is iOS 26+. If the target is below 26, every glass site needs an #available(iOS 26, *) gate with a fallback (see swiftui-patterns.md) — do not silently raise the minimum OS.
3. Confirm the surface is navigation/control, not content. Glass belongs on controls, bars, toolbars, sheets, floating actions — not content backgrounds (design-principles.md explains why: glass cannot sample glass).

Do not edit until steps 1–3 are answered.

Workflow A — Adopt Liquid Glass in new UI

1. Do Step 0.
2. Decide the glass surfaces up front: shape, prominence (.regular vs .clear, tint), grouping, and which elements are interactive.
3. Apply glassEffect(_:in:) after layout/appearance modifiers. Use built-in .buttonStyle(.glass) / .glassProminent for buttons rather than hand-rolling.
4. Wrap every set of sibling glass views in a GlassEffectContainer; tune spacing.
5. Add .interactive() only to touch/focus targets.
6. Add morphing (@Namespace + glassEffectID, state changed inside withAnimation) only where the hierarchy actually changes.
7. Gate with #available(iOS 26, *) + a non-glass fallback (.ultraThinMaterial).
8. Verify in the simulator across light, dark, and tinted/accented appearances (see "Verifying").

Workflow B — Refactor an existing feature to Liquid Glass

1. Do Step 0.
2. Read [references/adoption-guide.md](references/adoption-guide.md).
3. Remove custom backgrounds/blur on bars, sheets, and popovers so the system material shows through; replace imitation materials with real glass (gated).
4. Identify the few most important custom controls for glass — do not glassify everything.
5. Refactor sibling glass into GlassEffectContainers; apply the modifier order and interactive rules from Workflow A.
6. Audit controls for hard-coded layout metrics, color legibility, concentric corners, and toolbar grouping (ToolbarSpacer).
7. Verify across appearances and accessibility settings (Reduce Transparency / Reduce Motion).

Workflow C — Review Liquid Glass usage

1. Do Step 0 to build the inventory.
2. Check each glass site against, in order of severity:

• Availability — #available(iOS 26, *) present with a fallback (crash/blank risk on older OS).
• Container composition — multiple sibling glass views wrapped in GlassEffectContainer (glass cannot sample glass; missing container = wrong rendering + no morphing).
• Surface correctness — glass on controls/navigation, not content backgrounds; not overused.
• Modifier order — glassEffect applied after layout/appearance modifiers.
• Interactivity — .interactive() only where interaction exists.
• Transitions — glassEffectID used with @Namespace inside a container for morphing.
• Consistency — shapes, tint, spacing align across the feature.
• UIKit — clipsToBounds = true with corner radii; widgets — accented rendering mode handled.
• Accessibility — 44×44pt targets, icon labels, contrast on glass.

Review output format

Report findings as a list, most severe first, each as:

path/to/File.swift:line — — —

Group nothing; one finding per line so it is directly actionable. End with a one-line verdict (e.g. "3 blockers, 2 warnings — not ready" or "clean"). State what you actually observed; if you could not build or run, say so.

Verifying

Glass is a rendering effect — "looks right in code" is not proof. Build and run in the simulator and capture screenshots in light, dark, and tinted/accented appearances; for morphing, exercise the state change and confirm the transition. Headless mockup renderers cannot show real glass. Use the simulator lane (route to /ios-simulator for device management and screenshots). Report what you saw, not what you expect.

Does not do

• Mockups, visual direction, design systems, tokens → /ios-design. Note: headless mockup renders cannot show real Liquid Glass — glass needs the simulator lane (see ios-design/RENDERER.md).
• Production SwiftUI craft rules (spacing grid, typography, semantic colors, sizing) and HIG / native-idiom review → /swiftui-craft.
• Widget plumbing (timeline providers, App Groups, entitlements, controls) → /widgetkit. This skill covers only the glass/accented rendering of widgets.
• Simulator device management & screenshots → /ios-simulator.

This skill owns the Liquid Glass material itself: glassEffect, containers, morphing, variants, glass buttons/toolbars/tab bars, adoption, and review of glass usage.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.