axiom-liquid-glass-ref

Liquid Glass Adoption — Reference Guide

When to Use This Skill

Use when:

• Planning comprehensive Liquid Glass adoption across your entire app
• Auditing existing interfaces for Liquid Glass compatibility
• Implementing app icon updates with Icon Composer
• Understanding platform-specific Liquid Glass behavior (iOS, iPadOS, macOS, tvOS, watchOS)
• Migrating from previous materials (blur effects, custom translucency)
• Ensuring accessibility compliance with Liquid Glass interfaces
• Reviewing search, navigation, or organizational component updates

Related Skills

• Use axiom-liquid-glass for implementing the Liquid Glass material itself and design review pressure scenarios
• Use axiom-swiftui-performance for profiling Liquid Glass rendering performance
• Use axiom-accessibility-diag for accessibility testing

---

Overview

Adopting Liquid Glass doesn't mean reinventing your app from the ground up. Start by building your app in the latest version of Xcode to see the changes. If your app uses standard components from SwiftUI, UIKit, or AppKit, your interface picks up the latest look and feel automatically on the latest platform releases.

Key Adoption Strategy

1. Build with latest Xcode SDKs
2. Run on latest platform releases
3. Review changes using this reference
4. Adopt best practices incrementally

---

Visual Refresh

What Changes Automatically

Standard Components Get Liquid Glass

• Navigation bars, tab bars, toolbars
• Sheets, popovers, action sheets
• Buttons, sliders, toggles, and controls
• Sidebars, split views, menus

How It Works

• Liquid Glass combines optical properties of glass with fluidity
• Forms distinct functional layer for controls and navigation
• Adapts in response to overlap, focus state, and environment
• Helps bring focus to underlying content

Leverage System Frameworks

✅ DO: Use Standard Components

Standard components from SwiftUI, UIKit, and AppKit automatically adopt Liquid Glass with minimal code changes.

// ✅ Standard components get Liquid Glass automatically
NavigationView {
    List(items) { item in
        Text(item.name)
    }
    .toolbar {
        ToolbarItem {
            Button("Add") { }
        }
    }
}
// Recompile with Xcode 26 → Liquid Glass applied

❌ DON'T: Override with Custom Backgrounds

// ❌ Custom backgrounds interfere with Liquid Glass
NavigationView { }
    .background(Color.blue.opacity(0.5)) // Breaks Liquid Glass effects
    .toolbar {
        ToolbarItem { }
            .background(LinearGradient(...)) // Overlays system effects
    }

What to Audit

• Split views
• Tab bars
• Toolbars
• Navigation bars
• Any component with custom background/appearance

Solution Remove custom effects and let the system determine background appearance.

Test with Accessibility Settings

Liquid Glass adapts to: Reduce Transparency (frostier), Increase Contrast (black/white borders), Reduce Motion (no elastic animations). Verify legibility maintained under each setting and that custom elements provide fallback experiences. For detailed accessibility testing workflows, see axiom-liquid-glass discipline skill.

app.launchArguments += ["-UIAccessibilityIsReduceTransparencyEnabled", "1",
    "-UIAccessibilityButtonShapesEnabled", "1", "-UIAccessibilityIsReduceMotionEnabled", "1"]

Avoid Overusing Liquid Glass

Liquid Glass brings attention to underlying content. Overusing it on multiple custom controls distracts from content. Apply .glassEffect() only to important functional elements (navigation, primary actions) — not content cards, list rows, or decorative elements.

// ✅ Content layer: no glass. Navigation layer: glass on functional buttons only.
ZStack {
    ScrollView { ForEach(articles) { ArticleCard($0) } }
    VStack {
        Spacer()
        HStack {
            Button("Filter") { }.glassEffect()
            Spacer()
            Button("Sort") { }.glassEffect()
        }.padding()
    }
}

---

App Icons

App icons now take on a design that's dynamic and expressive. Updates to the icon grid result in standardized iconography that's visually consistent across devices. App icons contain layers that dynamically respond to lighting and visual effects.

Platform Support

Layered icons: iOS/iPadOS 26+, macOS Tahoe+, watchOS (circular mask). Appearance variants: default (light), dark, clear, tinted (Home Screen personalization).

Design Principles

Design clean, simplified layers with solid fills and semi-transparent overlays. Let the system handle effects (reflection, refraction, shadow, blur, masking). Do NOT bake in pre-applied blur, manual shadows, hardcoded highlights, or fixed masking.

Design Using Layers

Three layers: foreground (primary elements), middle (supporting), background (foundation). Export each layer as PNG or SVG at @1x/@2x/@3x with transparency preserved.

Icon Composer

Included in Xcode 26+ (also standalone from developer.apple.com/design/resources). Drag and drop layers, add optional background, adjust attributes (opacity, position, scale), preview with system effects and all appearance variants, export directly to asset catalog.

Preview Against Updated Grids

Grids: iOS/iPadOS/macOS use rounded rectangle mask; watchOS uses circular mask. Download from developer.apple.com/design/resources. Keep elements centered to avoid clipping, test at all sizes, verify all appearance variants look intentional.

---

Controls

Controls have refreshed look across platforms and come to life during interaction. Knobs transform into Liquid Glass during interaction, buttons fluidly morph into menus/popovers. Hardware shape informs curvature of controls (rounder forms nestle into corners).

Updated Appearance

Bordered buttons default to capsule shape (mini/small/medium on macOS retain rounded-rectangle). Knobs transform into glass during interaction; buttons morph into menus/popovers. New controlSize(.extraLarge) option; heights slightly taller on macOS. Use controlSize(.small) for backward-compatible high-density layouts. Standard controls adopt automatically — remove hard-coded .frame() dimensions.

Review Updated Controls

Audit sliders, toggles, buttons, steppers, pickers, segmented controls, and progress indicators. Verify appearance matches interface, spacing looks natural, controls aren't cropped, and interaction feedback is responsive.

Color in Controls

Use system colors (.tint(.blue), .accentColor) — they adapt to light/dark contexts automatically. Avoid hard-coded RGB values (Color(red:green:blue:)) which may not adapt. Test in both modes and verify WCAG AA contrast ratios.

Check for Crowding or Overlapping

Liquid Glass elements need breathing room. Use default HStack spacing (not spacing: 4) for glass buttons. Overcrowding or layering glass-on-glass creates visual noise. Use GlassEffectContainer when multiple glass elements must be close together.

Optimize for Legibility with Scroll Edge Effects

Use .scrollEdgeEffectStyle(.hard, for: .top) to obscure content scrolling beneath controls. System bars (toolbars, navigation bars, tab bars) adopt this automatically; custom bars need it explicitly.

Align Control Shapes with Containers

Use containerRelativeShape() to align control curvature with containers — creates concentric visual continuity from controls to sheets to windows to display.

New Button Styles

Use built-in styles instead of custom glass effects: .borderedProminent (primary, with .tint()), .bordered (secondary), .plain + .glassEffect() (tertiary/custom). Each adapts to Liquid Glass automatically.

---

Navigation

Liquid Glass applies to topmost layer where you define navigation. Key navigation elements like tab bars and sidebars float in this Liquid Glass layer to help people focus on underlying content.

Clear Navigation Hierarchy

Maintain two distinct layers: Navigation (tab bar, sidebar, toolbar — Liquid Glass) floats above Content (articles, photos, data — no glass). Do NOT apply .glassEffect() to content items like list rows — glass on the content layer blurs the boundary and competes with navigation.

Tab Bar Adapting to Sidebar

Use .tabViewStyle(.sidebarAdaptable) (iOS 26) to let the tab bar adapt to sidebar on iPad/macOS while remaining a tab bar on iPhone. Transitions fluidly with adaptive window sizes.

TabView {
    ContentView().tabItem { Label("Home", systemImage: "house") }
    SearchView().tabItem { Label("Search", systemImage: "magnifyingglass") }
}
.tabViewStyle(.sidebarAdaptable)

Split Views for Sidebar + Inspector Layouts

Use NavigationSplitView with sidebar, content, and detail columns. Liquid Glass applies automatically to sidebars and inspectors. iOS adapts column visibility; iPadOS/macOS shows all columns on large screens.

NavigationSplitView {
    List(folders, selection: $selectedFolder) { Label($0.name, systemImage: $0.icon) }
        .navigationTitle("Folders")
} content: {
    List(items, selection: $selectedItem) { ItemRow($0) }
} detail: {
    InspectorView(item: selectedItem)
}

Check Content Safe Areas

Verify content peeks through appropriately beneath sidebars/inspectors. Use .safeAreaInset(edge:) when content needs to account for sidebar/inspector space.

Padding with Edge-to-Edge Glass

When glass extends edge-to-edge via .ignoresSafeArea(), use .safeAreaPadding() (not .padding()) on the content layer to respect device safe areas (notch, Dynamic Island, home indicator):

// ❌ .padding(.horizontal, 20) — doesn't account for safe areas
// ✅ .safeAreaPadding(.horizontal, 20) — 20pt beyond safe areas

Applies to: full-screen sheets with materials, edge-to-edge toolbars, floating panels, custom glass navigation bars. Requires iOS 17+. See axiom-swiftui-layout-ref for full .safeAreaPadding() vs `.paddin

---

Content truncated.