adopt-liquid-glass

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:

Situation	Action
Migrating existing app	Walk through the adoption checklist (Step 2)
Building new custom glass UI	Jump to custom glass effects guidance
Specific API question	Read reference, give targeted answer with code
App icon redesign	Guide through layered icon design
Platform-specific question	Give platform-targeted advice

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.

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

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

4. 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.

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

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

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

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

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

10. 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