Liquid Glass Adoption — Reference Guide

When to Use This Skill

• 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

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

Test with Accessibility Settings

Settings That Affect Liquid Glass

• Reduce Transparency (makes glass frostier)
• Increase Contrast (makes elements predominantly black/white)
• Reduce Motion (decreases animation intensity)

Testing Checklist

• Enable Reduce Transparency → verify frosted appearance works
• Enable Increase Contrast → verify contrasting borders appear
• Enable Reduce Motion → verify elastic properties disabled
• All settings → verify legibility maintained
• Standard components adapt automatically
• Custom elements provide fallback experience

How to Test

// Launch arguments for accessibility testing
app.launchArguments += [
    "-UIAccessibilityIsReduceTransparencyEnabled", "1",
    "-UIAccessibilityButtonShapesEnabled", "1",
    "-UIAccessibilityIsReduceMotionEnabled", "1"
]

Avoid Overusing Liquid Glass

❌ DON'T: Apply to Every Custom Control

✅ DO: Limit to Important Functional Elements

// ✅ Selective application to navigation layer
struct ContentView: View {
    var body: some View {
        ZStack {
            // Content layer - no glass
            ScrollView {
                ForEach(articles) { article in
                    ArticleCard(article) // No glass
                }
            }

            // Navigation layer — Liquid Glass
            VStack {
                Spacer()
                HStack {
                    Button("Filter") { }
                        .glassEffect() // ✅ Important functional element
                    Spacer()
                    Button("Sort") { }
                        .glassEffect() // ✅ Important functional element
                }
                .padding()
            }
        }
    }
}

App Icons

Platform Support

Layered Icons

• iOS 26+
• iPadOS 26+
• macOS Tahoe+
• watchOS (rounded rectangle → circular mask)

Appearance Variants

• Default (light)
• Dark
• Clear
• Tinted (Home Screen personalization)

Design Principles

Key Principles

1. Visually consistent across platforms
2. Optically balanced design
3. Simplified design with solid, filled, overlapping semi-transparent shapes
4. Let system handle effects (masking, blurring, reflection, refraction)

❌ DON'T: Include System Effects in Design

❌ Design includes:
   - Pre-applied blur
   - Manual shadows
   - Hardcoded highlights
   - Fixed masking

✅ DO: Design Clean Layers

✅ Design includes:
   - Clean vector shapes
   - Solid fills
   - Semi-transparent overlays
   - Foreground/middle/background separation

   System automatically adds:
   - Reflection, refraction
   - Shadow, blur, axiom-highlights
   - Masking to final shape

Design Using Layers

Layer Structure

• Foreground Layer: Primary visual elements
• Middle Layer: Supporting elements
• Background Layer: Foundation elements

Export from Design App

Export settings:
- Format: PNG or vector (SVG recommended)
- Resolution: @1x, @2x, @3x
- Transparency: Preserved
- One file per layer

System-Applied Effects

• Reflection (light bouncing off surface)
• Refraction (light bending through material)
• Shadow (depth and elevation)
• Blur (atmospheric depth)
• Highlights (light sources)

Icon Composer

Compose and Preview

1. Drag and drop exported layers
2. Add background (optional - system provides default for irregular shapes)
3. Create layer groupings
4. Adjust layer attributes (opacity, position, scale)
5. Preview with system effects and appearance variants

Download Icon Composer

• Included in Xcode 26+
• Standalone: https://developer.apple.com/design/resources/

Capabilities

• Real-time preview with system effects
• Light/dark/clear/tinted appearance previews
• Layer management (order, opacity, grouping)
• Export asset catalog directly

Preview Against Updated Grids

Grid Updates

• iOS/iPadOS/macOS: Rounded rectangle mask
• watchOS: Circular mask

What to Check

• Keep elements centered to avoid clipping
• Irregular shapes receive system-provided background
• Test at all sizes (small, medium, large)

Download Grids

Testing Checklist

• Icon centered within grid
• No critical elements clipped by mask
• Looks good at all sizes
• Appears balanced with system-provided background (if irregular)
• All appearance variants (light/dark/clear/tinted) look intentional

Example Issue

❌ Problem: Logo text clipped at edges
✅ Solution: Center design, reduce size to fit safe area

Controls

Updated Appearance

What Changed

• Bordered buttons default to capsule shape (mini/small/medium on macOS retain rounded-rectangle for density)
• Rounder forms (inspired by hardware curvature)
• Knobs transform into Liquid Glass during interaction
• Buttons morph into menus/popovers
• Extra-large size option for labels and accents (

  controlSize(.extraLarge)

  )
• Control heights slightly taller on macOS (more breathing room, larger click targets)
• Use

  controlSize(.small)

  for backward compatibility in high-density layouts (inspectors, popovers)

Automatic Adoption

// ✅ Standard controls adopt changes automatically
Slider(value: $volume)
Toggle("Enabled", isOn: $isEnabled)
Button("Action") { }

If you hard-coded layout metrics

// ❌ Hard-coded dimensions may break
Slider(value: $volume)
    .frame(width: 250, height: 44) // May not match new dimensions

// ✅ Use automatic sizing
Slider(value: $volume)

Review Updated Controls

Controls to Audit

• Sliders (knob transforms to glass)
• Toggles (knob transforms to glass)
• Buttons (morph into menus/popovers)
• Steppers
• Pickers
• Segmented controls
• Progress indicators

What to Check

• Appearance matches rest of interface
• Spacing around controls looks natural
• Controls not cropped by containers
• Interaction feedback feels responsive

Color in Controls

✅ DO: Use System Colors

// ✅ System colors adapt to light/dark contexts
Button("Primary") { }
    .tint(.accentColor)

Toggle("Feature", isOn: $enabled)
    .tint(.blue) // System blue adapts

❌ DON'T: Hard-code Custom Colors

// ❌ May not adapt to context
Button("Primary") { }
    .foregroundColor(Color(red: 0.2, green: 0.4, blue: 0.8))

Legibility Guidelines

• Be judicious with color in controls and navigation
• Leverage system colors for automatic adaptation
• Test in light and dark modes
• Verify contrast ratios (WCAG AA minimum)

Check for Crowding or Overlapping

❌ AVOID: Crowding Controls

// ❌ Controls too close together
HStack(spacing: 4) { // Too tight
    Button("Action 1") { }.glassEffect()
    Button("Action 2") { }.glassEffect()
    Button("Action 3") { }.glassEffect()
}

✅ DO: Use Standard Spacing

// ✅ System spacing feels natural
HStack {
    Button("Action 1") { }.glassEffect()
    Button("Action 2") { }.glassEffect()
    Button("Action 3") { }.glassEffect()
}

Optimize for Legibility with Scroll Edge Effects

scrollEdgeEffectStyle(_:for:)

// ✅ Obscure content scrolling beneath controls
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item)
        }
    }
}
.scrollEdgeEffectStyle(.hard, for: .top) // Maintain legibility at top edge

System bars adopt this automatically

• Toolbars
• Navigation bars
• Tab bars

Custom bars need registration

// Custom bar with controls/text/icons
CustomToolbar()
    .scrollEdgeEffectStyle(.hard, for: .top)

Align Control Shapes with Containers

Use

containerRelativeShape()

// ✅ Control shape aligns with container curvature
Button("Action") { }
    .containerRelativeShape(.roundedRectangle)

Creates visual continuity

• Controls → concentric to sheets
• Sheets → concentric to windows
• Windows → concentric to display

New Button Styles

Instead of custom Liquid Glass effects, use built-in styles

.borderedProminent

Button("Primary Action") { }
    .buttonStyle(.borderedProminent)
    .tint(.blue)
// Filled button with Liquid Glass adaptation

.bordered

Button("Secondary Action") { }
    .buttonStyle(.bordered)
// Bordered button with Liquid Glass effects

.plain

with Liquid Glass

Button("Tertiary") { }
    .buttonStyle(.plain)
    .glassEffect()
// Custom glass application for specific needs

.borderedProminent

.bordered

.plain

Navigation

Clear Navigation Hierarchy

✅ DO: Separate Content from Navigation

┌─────────────────────────────────┐
│  Navigation Layer (Liquid Glass)│  ← Tab bar, sidebar, toolbar
│  • Clear functional layer       │
│  • Floats above content         │
├─────────────────────────────────┤
│  Content Layer (No Glass)       │  ← Articles, photos, data
│  • Underlying content           │
│  • Focus of user attention      │
└─────────────────────────────────┘

❌ DON'T: Blur the Boundary

// ❌ Content and navigation compete
List(items) { item in
    ItemRow(item)
        .glassEffect() // ❌ Content layer shouldn't have glass
}

Tab Bar Adapting to Sidebar

Automatic Adaptation

// ✅ Tab bar adapts to sidebar depending on context
TabView {
    ContentView()
        .tabItem { Label("Home", systemImage: "house") }

    SearchView()
        .tabItem { Label("Search", systemImage: "magnifyingglass") }
}
.tabViewStyle(.sidebarAdaptable) // NEW in iOS 26

When it adapts

• iPad: Can switch to sidebar for better space usage
• iPhone: Remains tab bar
• macOS: Sidebar preferred
• Adaptive window sizes: Transitions fluidly

Benefits

• Consistent experience across platforms
• Better space usage on larger screens
• Automatic with minimal code

Split Views for Sidebar + Inspector Layouts

Use split views for consistent layouts

// ✅ Split view with sidebar + content + inspector
NavigationSplitView {
    // Sidebar
    List(folders, selection: $selectedFolder) { folder in
        Label(folder.name, systemImage: folder.icon)
    }
    .navigationTitle("Folders")
} content: {
    // Main content
    List(items, selection: $selectedItem) { item in
        ItemRow(item)
    }
} detail: {
    // Inspector
    InspectorView(item: selectedItem)
}

Platform Optimization

• iOS: Adaptive column visibility
• iPadOS: All columns visible on large screens
• macOS: Sidebar + content + inspector layout
• Liquid Glass applied automatically to sidebars/inspectors

Check Content Safe Areas

Solution: Audit Safe Areas

// ✅ Respect safe areas for proper content peeking
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item)
        }
    }
    .safeAreaInset(edge: .leading) {
        // Sidebar occupies this space
        Color.clear.frame(width: 0)
    }
}

Padding with Liquid Glass Materials

.safeAreaPadding()

.padding()

// ❌ WRONG - Content hits notch/home indicator with Liquid Glass background
ZStack {
    // Liquid Glass background extends edge-to-edge
    RoundedRectangle(cornerRadius: 12)
        .fill(.thinMaterial)
        .ignoresSafeArea()

    VStack {
        content
    }
    .padding(.horizontal, 20)  // Doesn't account for safe areas!
}

// ✅ CORRECT - Content properly inset from safe areas + custom margin
ZStack {
    RoundedRectangle(cornerRadius: 12)
        .fill(.thinMaterial)
        .ignoresSafeArea()

    VStack {
        content
    }
    .safeAreaPadding(.horizontal, 20)  // 20pt beyond safe areas
}

.ignoresSafeArea()

.safeAreaPadding()

.safeAreaPadding()

• Full-screen sheets with

  .ultraThinMaterial

  backgrounds
• Edge-to-edge toolbars with glass effects
• Floating panels that extend to screen edges
• Custom navigation bars with Liquid Glass styling

.safeAreaPadding()

.safeAreaInset()

axiom-swiftui-layout-ref

.safeAreaPadding()

.padding()

What to Check

• Content visible beneath sidebar/inspector
• Content not cropped inappropriately
• Background peek-through looks intentional
• Scrolling content visible through Liquid Glass
• Content properly inset from notch, Dynamic Island, home indicator (use

  .safeAreaPadding()

  with edge-to-edge Liquid Glass)

Background Extension Effect

What It Is

Perfect For

• Hero images on product pages
• Full-bleed photo galleries
• Edge-to-edge content experiences
• Apps using split views

How It Works

// ✅ Background extends under sidebar
NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .backgroundExtensionEffect()  // Mirrors and blurs content outside safe area
}

Visual Effect

1. Content appears to extend beneath sidebar
2. Mirrored content subtly visible
3. Blur maintains sidebar legibility
4. Creates immersive, edge-to-edge feel

When to Use

• Split view layouts
• Sidebar/inspector UIs
• Media-rich content
• Product/photo detail views

Automatically Minimize Tab Bar (iOS)

New Behavior

How to Configure

TabView {
    ContentView()
        .tabItem { Label("Home", systemImage: "house") }
}
.tabBarMinimizeBehavior(.onScrollDown) // NEW in iOS 26

Options

• .onScrollDown

  - Minimize when scrolling down

• .onScrollUp

  - Minimize when scrolling up

• .automatic

  - System determines

• .never

  - Always visible

When minimized

• Tab bar recedes (smaller visual footprint)
• Expands when scrolling in opposite direction
• Content gains more screen space

.onScrollDown

Menus and Toolbars

Cross-Platform Menu Consistency

Label

Menu Icons for Standard Actions

Automatic Icon Adoption

// ✅ Standard selectors get icons automatically
Menu("Actions") {
    Button(action: cut) {
        Text("Cut")
    }
    Button(action: copy) {
        Text("Copy")
    }
    Button(action: paste) {
        Text("Paste")
    }
}
// System uses selector to determine icon
// cut() → scissors icon
// copy() → documents icon
// paste() → clipboard icon

Standard Selectors

• cut()

  → ✂️ scissors

• copy()

  → 📄 documents

• paste()

  → 📋 clipboard

• delete()

  → 🗑️ trash

• share()

  → ↗️ share arrow
• Many more...

Custom Actions

// ✅ Provide icon for custom actions
Button {
    customAction()
} label: {
    Label("Custom Action", systemImage: "star.fill")
}

Match Top Menu Actions to Swipe Actions

For consistency and predictability

// ✅ Swipe actions match contextual menu
List(emails) { email in
    EmailRow(email)
        .swipeActions(edge: .leading) {
            Button("Archive", systemImage: "archivebox") {
                archive(email)
            }
        }
        .swipeActions(edge: .trailing) {
            Button("Delete", systemImage: "trash", role: .destructive) {
                delete(email)
            }
        }
        .contextMenu {
            // ✅ Same actions appear at top
            Button("Archive", systemImage: "archivebox") {
                archive(email)
            }
            Button("Delete", systemImage: "trash", role: .destructive) {
                delete(email)
            }

            Divider()

            // Additional actions below
            Button("Mark Unread") { }
        }
}

Toolbar Item Grouping

Group items that share a background

// ✅ Fixed spacer separates groups
.toolbar {
    ToolbarItemGroup(placement: .topBarTrailing) {
        // Navigation group
        Button("Up") { }
        Button("Down") { }

        ToolbarSpacer(.fixed) // NEW in iOS 26 - separates groups

        // Action group
        Button("Settings") { }
    }
}

Visual Effect

• Items within group share Liquid Glass background

• .fixed

  spacer creates visual separation
• Clear grouping of related actions

Best Practices

• Group similar actions (navigation, formatting, settings)
• Maintain consistent groupings across platforms
• Use

  .fixed

  for logical separation

Monochrome Icon Rendering

.tint()

Removing Items from Group Background

.toolbar {
    ToolbarItem(placement: .topBarTrailing) {
        Image(systemName: "person.crop.circle")
            .sharedBackgroundVisibility(.hidden)
            // Item appears without glass background pill
    }
}

Icons vs Text in Toolbars

✅ DO: Use Icons for Common Actions

// ✅ Icons declutter interface
.toolbar {
    ToolbarItem(placement: .topBarTrailing) {
        Button {
            share()
        } label: {
            Label("Share", systemImage: "square.and.arrow.up")
        }
    }
}

❌ DON'T: Mix Icons and Text in Same Group

// ❌ Inconsistent visual style
.toolbar {
    ToolbarItemGroup {
        Button("Save") { } // Text
        Button {
            share()
        } label: {
            Image(systemName: "square.and.arrow.up") // Icon
        }
    }
}

Backward-Compatible Toolbar Labels (iOS 18+26)

LabelStyle

struct ToolbarLabelStyle: LabelStyle {
    func makeBody(configuration: Configuration) -> some View {
        if #available(iOS 26, *) {
            Label(configuration)  // Icon + text (system shows icon)
        } else {
            Label(configuration)
                .labelStyle(.titleOnly)  // Text-only on older OS
        }
    }
}

@available(iOS, introduced: 18, obsoleted: 26,
           message: "Remove — iOS 26 uses icon-based toolbars natively")
extension LabelStyle where Self == ToolbarLabelStyle {
    static var toolbar: Self { .init() }
}

ToolbarItem(placement: .confirmationAction) {
    Button("Done", systemImage: "checkmark") { }
        .labelStyle(.toolbar)
}

obsoleted: 26

Floating Glass Buttons

.glassEffect(.regular.interactive())

ZStack(alignment: .bottomTrailing) {
    List { /* content */ }

    Button(action: { }) {
        Label("Add", systemImage: "plus")
            .bold()
            .labelStyle(.iconOnly)
            .padding()
    }
    .glassEffect(.regular.interactive())
    .padding([.bottom, .trailing], 12)
}

Provide Accessibility Labels for Icons

Always specify accessibility label

// ✅ Icon has accessibility label
Button {
    share()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")

Audit Toolbar Customizations

What to Check

• Custom fixed spacers → verify they work with new Liquid Glass backgrounds
• Custom items → verify appearance consistent with system behavior
• Toolbar visibility → verify hiding/showing works correctly

Common Issue: Empty Toolbar Items

❌ Problem

// ❌ Hiding view instead of item
.toolbar {
    ToolbarItem {
        if showButton {
            Button("Action") { }
        } else {
            EmptyView() // ❌ Creates empty toolbar item
        }
    }
}

✅ Solution

// ✅ Hide entire toolbar item
.toolbar {
    if showButton {
        ToolbarItem {
            Button("Action") { }
        }
    }
}

Windows and Modals

Arbitrary Window Sizes (iPadOS)

Support continuous resizing

// ✅ Content adapts to arbitrary window sizes
WindowGroup {
    ContentView()
}
.defaultSize(width: 600, height: 800)
.windowResizability(.contentSize) // NEW in iPadOS 26

What Changed

• No longer transitions between preset sizes
• Windows resize fluidly down to minimum size
• Content should reflow gracefully

Developer Action

• Remove hard-coded size assumptions
• Use flexible layouts (VStack, HStack, Grid)
• Test at various window sizes

Split Views for Fluid Column Resizing

Use split views for automatic reflow

// ✅ Split view handles continuous resizing
NavigationSplitView(columnVisibility: $columnVisibility) {
    SidebarView()
} detail: {
    DetailView()
}

Benefits

• Automatic content reflow
• Beautiful, fluid transitions
• Minimal code
• System-optimized animations

Without split views

• Manual layout calculations
• Custom animation code
• More complexity

Use Layout Guides and Safe Areas

Specify safe areas for automatic adjustment

// ✅ Content respects safe areas
VStack {
    ContentView()
}
.safeAreaInset(edge: .top) {
    // Window controls and title bar
    Color.clear.frame(height: 0)
}

System Automatically Adjusts

• Window controls position
• Title bar layout
• Content layout relative to chrome

Sheets: Increased Corner Radius

What Changed

• Sheets have increased corner radius
• Half sheets inset from edge (content peeks through)
• Half sheets transitioning to full height become more opaque

Check Content Around Edges

Inside Sheet

• Content too close to rounder corners?
• Controls cropped by corner radius?

Outside Sheet

• Content peeking through between inset sheet and edge looks intentional?
• Background visible around half sheet edges?

Testing

// Test half sheet presentation
.sheet(isPresented: $showSheet) {
    SheetContent()
        .presentationDetents([.medium, .large])
}

Remove presentationBackground

presentationBackground

// ❌ Custom background interferes with new sheet material
.sheet(isPresented: $showDetail) {
    DetailView()
        .presentationBackground(.thinMaterial)  // Remove this
}

// ✅ System applies Liquid Glass sheet material automatically
.sheet(isPresented: $showDetail) {
    DetailView()
}

Audit Sheet/Popover Backgrounds

❌ REMOVE: Custom Background Views

// ❌ Custom visual effect view in popover
.popover(isPresented: $showPopover) {
    ContentView()
        .background(
            VisualEffectView(effect: UIBlurEffect(style: .systemMaterial))
        ) // ❌ Interferes with Liquid Glass
}

✅ DO: Let System Handle Background

// ✅ System applies Liquid Glass automatically
.popover(isPresented: $showPopover) {
    ContentView()
    // No background modifier needed
}

Action Sheets: Inline Appearance

What Changed

Specify Source of Action Sheet

// ✅ Action sheet anchored to source
Button("Options") {
    showActionSheet = true
}
.confirmationDialog("Options", isPresented: $showActionSheet) {
    Button("Option 1") { }
    Button("Option 2") { }
    Button("Cancel", role: .cancel) { }
}
// System positions sheet next to button automatically

Benefits

• Clear relationship to source
• Doesn't block entire interface
• More flexible interaction
• Inline appearance feels lighter

Organization and Layout

Larger Row Height and Padding

What Changed

• Lists: Larger row height
• Tables: More padding
• Forms: Increased spacing
• Sections: Increased corner radius

Automatic Adoption

// ✅ Standard components adopt new metrics
List(items) { item in
    Text(item.name)
}

If you hard-coded metrics

// ❌ May look cramped with new design
List(items) { item in
    Text(item.name)
        .frame(height: 44) // ❌ Hard-coded height
        .padding(.vertical, 4) // ❌ Hard-coded padding
}

// ✅ Use automatic sizing
List(items) { item in
    Text(item.name)
    // System determines row height and padding
}

Section Header Capitalization

What Changed

Before (iOS 18 and earlier)

Section(header: Text("User settings")) {
    // Rendered as "USER SETTINGS"
}

After (iOS 26+)

Section(header: Text("User Settings")) {
    // Rendered as "User Settings" (title-style)
}

Action Required

// ❌ Old style (all lowercase)
Section(header: Text("user settings")) {
    // Renders as "user settings" (looks wrong)
}

// ✅ New style (title-style)
Section(header: Text("User Settings")) {
    // Renders as "User Settings" (correct)
}

Adopt Forms for Platform-Optimized Layouts

Use

.grouped

form style

// ✅ Form adopts platform-optimized layout
Form {
    Section("Personal Information") {
        TextField("Name", text: $name)
        TextField("Email", text: $email)
    }

    Section("Preferences") {
        Toggle("Notifications", isOn: $notificationsEnabled)
        Picker("Theme", selection: $theme) {
            Text("Light").tag(Theme.light)
            Text("Dark").tag(Theme.dark)
            Text("Auto").tag(Theme.auto)
        }
    }
}
.formStyle(.grouped) // Platform-optimized metrics

Benefits

• Automatic row height updates
• Correct padding and spacing
• Section corner radius matches controls
• Consistent across platforms

Search

Keyboard Layout When Activating Search

What Changed (iOS)

Testing

• Tap search field
• Verify smooth upward slide
• Keyboard appears without covering search field
• Consistent with system search experiences (Spotlight, Safari)

No Code Changes Required

// ✅ Existing searchable modifier adopts new behavior
List(items) { item in
    Text(item.name)
}
.searchable(text: $searchText)

Semantic Search Tabs

.tabRole(.search)

Platform Considerations

watchOS

Minimal Changes

To Ensure Proper Adoption

• Adopt standard toolbar APIs
• Use standard button styles from watchOS 10

// ✅ Standard button styles on watchOS
Button("Action") { }
    .buttonStyle(.bordered)

tvOS

Focus-Based Appearance

System Requirements

• Apple TV 4K (2nd generation) and newer: Full Liquid Glass effects
• Older devices: Maintains current appearance

Adopt Standard Focus APIs

// ✅ Standard focus APIs for Liquid Glass on focus
Button("Action") { }
    .focusable()

For Custom Controls

// ✅ Custom control with focus-based glass
struct CustomControl: View {
    @FocusState private var isFocused: Bool

    var body: some View {
        Text("Custom")
            .glassEffect()
            .opacity(isFocused ? 1.0 : 0.5)
            .focused($isFocused)
    }
}

Combining Custom Liquid Glass Effects

Use

GlassEffectContainer

for Performance

// ✅ Combine effects in container for optimization
GlassEffectContainer {
    HStack {
        Button("Action 1") { }
            .glassEffect()

        Button("Action 2") { }
            .glassEffect()

        Button("Action 3") { }
            .glassEffect()
    }
}

Benefits

• Optimizes rendering performance
• Fluidly morphs Liquid Glass shapes into each other
• Better animation performance
• Reduces compositor overhead

When to Use

• Multiple custom Liquid Glass elements
• Morphing animations between glass shapes
• Performance-critical interfaces

Performance Testing

Profile Your App

Use Instruments

• Time Profiler (CPU usage)
• SwiftUI (view updates - see

  axiom-swiftui-performance

  skill)
• Allocations (memory usage)
• Core Animation (rendering performance)

What to Check

• Scrolling performance with Liquid Glass
• Animation smoothness
• Memory usage patterns
• CPU usage during interactions

See Related Skills

• axiom-swiftui-performance

  - SwiftUI Instrument workflows

• axiom-performance-profiling

  - Instruments decision trees

Backward Compatibility

Maintain Previous Appearance

Add

UIDesignRequiresCompatibility

key

<!-- Info.plist -->
<key>UIDesignRequiresCompatibility</key>
<true/>

Effect

• App built with iOS 26 SDK
• Appearance matches iOS 18 and earlier
• Liquid Glass effects disabled
• Previous blur/material styles used

When to Use

• Need time to audit interface changes
• Gradual adoption strategy
• Maintain exact appearance temporarily

Migration Strategy

1. Ship with

   UIDesignRequiresCompatibility

   enabled
2. Audit interface changes in separate build
3. Update interface incrementally
4. Remove key when ready for Liquid Glass

Quick Reference: API Checklist

Core Liquid Glass APIs

• glassEffect()

  - Apply Liquid Glass material

• glassEffect(.clear)

  - Clear variant (requires 3 conditions)

• glassEffect(in: Shape)

  - Custom shape

• glassBackgroundEffect()

  - For custom views reflecting content

Scroll Edge Effects

• scrollEdgeEffectStyle(_:for:)

  - Maintain legibility where glass meets scrolling content

• .hard

  style for pinned accessory views

• .soft

  style for gradual fade

Controls and Shapes

• containerRelativeShape()

  - Align control shapes with containers

• .borderedProminent

  button style

• .bordered

  button style
• System colors with

  .tint()

  for adaptation

Navigation

• .tabViewStyle(.sidebarAdaptable)

  - Tab bar adapts to sidebar

• .tabBarMinimizeBehavior(_:)

  - Minimize on scroll

• .tabRole(.search)

  - Semantic search tabs

• NavigationSplitView

  for sidebar + inspector layouts

Toolbars and Menus

• ToolbarSpacer(.fixed)

  - Separate toolbar groups
• Standard selectors for automatic menu icons
• Match contextual menu actions to swipe actions

Organization and Layout

• .formStyle(.grouped)

  - Platform-optimized form layouts
• Title-style capitalization for section headers
• Respect automatic row height and padding

Performance

• GlassEffectContainer

  - Combine multiple glass effects
• Profile with Instruments
• Test with accessibility settings

Backward Compatibility

• UIDesignRequiresCompatibility

  in Info.plist (if needed)

Audit Checklist

Visual Refresh

• Built with Xcode 26 SDK
• Run on latest platform releases
• Standard components adopt Liquid Glass automatically
• Custom backgrounds in controls/navigation removed
• Tested with Reduce Transparency
• Tested with Increase Contrast
• Tested with Reduce Motion
• Liquid Glass not overused on custom controls

App Icons

• Designed with foreground/middle/background layers
• Exported layers from design app
• Composed in Icon Composer
• Previewed against updated grids
• All appearance variants tested (light/dark/clear/tinted)
• Elements centered to avoid clipping

Controls

• Updated appearance reviewed (capsule default for bordered buttons)
• Hard-coded layout metrics removed (control heights changed)

• controlSize(.small)

  for backward-compatible high-density layouts
• System colors used for adaptation
• Controls not crowded or overlapping
• Scroll edge effects applied where needed
• Control shapes aligned with containers (

  .containerConcentric

  if desired)
• New button styles adopted (

  .borderedProminent

  ,

  .bordered

  )
• Extra large buttons used for prominent actions where appropriate

Navigation

• Clear hierarchy (navigation layer vs content layer)
• Tab bar adapts to sidebar (if appropriate)
• Split views used for sidebar + inspector layouts
• Content safe areas checked
• Background extension effect considered
• Tab bar minimization configured (if desired)

Menus and Toolbars

• Standard selectors used for automatic menu icons
• Top menu actions match swipe actions
• Toolbar items grouped logically with

  ToolbarSpacer(.fixed)

• Icons OR text used per group (not mixed)
• Monochrome icon rendering embraced (tint only for meaning)

• sharedBackgroundVisibility(.hidden)

  for standalone items (avatars, status)
• Accessibility labels provided for all icons
• Custom toolbar items audited for compatibility

Windows and Modals

• Arbitrary window sizes supported (iPadOS)
• Split views used for fluid column resizing
• Layout guides and safe areas specified
• Sheet content checked around rounder corners
• Content peeking through half sheets reviewed

• presentationBackground

  removed from sheets (let Liquid Glass material shine)
• Custom sheet/popover backgrounds removed
• Action sheets specify source element

Organization and Layout

• Hard-coded row heights removed
• Section headers use title-style capitalization

• .formStyle(.grouped)

  adopted for forms
• Automatic row height and padding respected

Search

• Keyboard layout tested when activating search

• .tabRole(.search)

  used for search tabs (if tab-based)
• Search placement appropriate for platform

Platform Considerations

• watchOS: Standard toolbar APIs and button styles adopted
• tvOS: Standard focus APIs adopted for custom controls

• GlassEffectContainer

  used for combining custom effects
• Performance tested with Instruments

• UIDesignRequiresCompatibility

  key considered (if backward compatibility needed)

Resources