Adopt Liquid Glass

Apple's Liquid Glass design language for SwiftUI, UIKit, and AppKit apps.

Language

Match user's language.

When to Use

• User is migrating an existing app to Liquid Glass
• User is building new UI and wants Liquid Glass best practices
• User asks about specific Liquid Glass APIs (glassEffect, GlassEffectContainer, etc.)
• User needs to redesign app icons for the layered system
• User asks about platform-specific considerations (watchOS, tvOS)

Workflow

Step 1: Assess the user's situation

Determine what the user needs:

Step 2: Adoption Checklist

For migration, work through these areas in order. Read references/liquid-glass-guide.md for detailed guidance on each.

1. Build & Review — Build with latest Xcode SDK, run on latest platform releases. Standard SwiftUI/UIKit/AppKit components auto-adopt Liquid Glass.

1. Visual Refresh — Remove custom backgrounds from navigation elements (NavigationStack, NavigationSplitView, titleBar, toolbars). Test with accessibility settings (Reduce Transparency, Reduce Motion).

1. App Icons — Redesign with layers (foreground/middle/background). Use Icon Composer. Simple, filled, semi-transparent shapes. Test against updated grids.

1. Controls — Don't hard-code layout metrics. Review color usage (use system colors). Adopt new button styles (.glass, .glassProminent). Use safeAreaBar for scroll edge effects. Use ConcentricRectangle for concentric shapes.

1. Navigation — Establish clear hierarchy. Consider sidebarAdaptable for tab→sidebar. Use NavigationSplitView for split layouts. Apply backgroundExtensionEffect() for edge-to-edge content.

1. Menus & Toolbars — Use standard selectors for icon auto-assignment. Group related toolbar items. Use icons over text. Hide entire toolbar items (not inner views).

1. Windows & Modals — Support arbitrary window sizes. Use split views for fluid resizing. Check sheet corner content. Set action sheet source anchor with confirmationDialog.

1. Layout — Title-style capitalization for section headers. Adopt grouped form style.

1. Search — Use Tab(role: .search) for semantic search tabs. Test keyboard layout.

1. Platform Testing — Test across iOS, iPadOS, macOS, tvOS, watchOS. Use GlassEffectContainer for performance. Profile with Instruments.

Step 3: Custom Glass Effects

When the user needs to apply Liquid Glass to custom views, guide them through:

1. Basic: glassEffect() / glassEffect(in: .rect(cornerRadius:)) / .tint() / .interactive()
2. Containers: GlassEffectContainer(spacing:) for multiple effects — controls blending behavior
3. Unions: glassEffectUnion(id:namespace:) for unified shapes across dynamic views
4. Morphing: glassEffectID(_:in:) + @Namespace for transition coordination
5. Transitions: matchedGeometry (within spacing) vs materialize (farther apart)

Always read references/liquid-glass-guide.md Section 10 for complete code examples before answering custom glass effect questions.

Step 4: Opt-out Path

If the user needs to ship with latest SDKs but keep previous appearance:

• Add UIDesignRequiresCompatibility key to Info.plist

Key Principles

• Don't overuse Liquid Glass — Limit to the most important functional elements
• Let the system decide — Remove custom backgrounds, trust system framework defaults
• Test accessibility — Reduce Transparency, Reduce Motion, increased contrast
• Performance matters — Use GlassEffectContainer, limit onscreen effects, profile regularly
• Apply glass effect last — After other appearance modifiers

Reference

Detailed guide with all code examples and complete API reference: → Read references/liquid-glass-guide.md

<!-- Keep under 200 lines. Detailed docs in references/. -->