# Adopt Liquid Glass

> Guide for adopting Apple's Liquid Glass design language in SwiftUI/UIKit/AppKit apps. Covers visual refresh, app icons, controls, navigation, menus, toolbars, windows, modals, layout, search, platform considerations, and custom glass effects. Triggers: 'liquid glass', 'adopt liquid glass', 'glass effect', 'glassEffect', 'Liquid Glass migration', 'Liquid Glass adoption', 'iOS 26 UI update', 'macOS 26 design', 'new Apple design language', '适配 Liquid Glass', '毛玻璃效果'

- Skill: `psylch/adopt-liquid-glass` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add psylch/adopt-liquid-glass`
- Raw SKILL.md: https://api.skillmd.com/api/skills/psylch/adopt-liquid-glass/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: psylch (https://skillmd.com/u/psylch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/psylch/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`

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