Axiom Liquid Glass

Liquid Glass — Apple's New Material Design System

When to Use This Skill

Use when:

• Implementing Liquid Glass effects in your app
• Reviewing existing UI for Liquid Glass adoption opportunities
• Debugging visual artifacts with Liquid Glass materials
• Optimizing Liquid Glass performance
• Requesting expert review of Liquid Glass implementation
• Understanding when to use Regular vs Clear variants
• Troubleshooting tinting, legibility, or adaptive behavior issues

Related Skills

• Use axiom-liquid-glass-ref for comprehensive app-wide adoption guidance (app icons, controls, navigation, menus, windows, platform considerations)

Example Prompts

These are real questions developers ask that this skill is designed to answer:

1. "I just saw Liquid Glass in WWDC videos. How is it different from blur effects I've used before? Should I adopt it?"

→ The skill explains Liquid Glass as a lensing-based material (not blur), shows design philosophy, and when adoption makes sense

2. "I'm implementing Liquid Glass in my app but the lensing effect doesn't look quite right. It looks like a regular blur. What am I missing?"

→ The skill covers the visual properties (lensing vs motion vs environment), Regular vs Clear variants, and debugging visual artifacts

3. "Liquid Glass works great on iPhone but looks odd on iPad. Should I adjust the implementation differently for different screen sizes?"

→ The skill demonstrates adaptive Liquid Glass patterns and platform-specific guidance (iOS 26+, macOS Tahoe+, axiom-visionOS 3+)

4. "I need to use Liquid Glass but still need legible text on top. How do I ensure text contrast while using Liquid Glass?"

→ The skill covers tinting strategies, adaptive color choices, and opacity patterns for maintaining readability across light/dark modes

5. "We want to do a design review of our Liquid Glass implementation. What are the expert criteria for a good Liquid Glass implementation?"

→ The skill provides the comprehensive review checklist and professional push-back frameworks for design review meetings

What is Liquid Glass?

Liquid Glass is Apple's next-generation material design system introduced at WWDC 2025. It represents a significant evolution from previous materials (Aqua, iOS 7 blurs, Dynamic Island) by creating a new digital meta-material that:

• Dynamically bends and shapes light (lensing) rather than scattering it
• Moves organically like a lightweight liquid, responding to touch and app dynamism
• Adapts automatically to size, environment, content, and light/dark modes
• Unifies design language across all Apple platforms (iOS, iPadOS, macOS, axiom-visionOS)

Core Philosophy: Liquid Glass complements the evolution of rounded, immersive screens with rounded, floating forms that feel natural to touch interaction while letting content shine through.

Visual Properties

1. Lensing (Primary Visual Characteristic)

Liquid Glass defines itself through lensing — the warping and bending of light that communicates presence, motion, and form.

How it works:

• Dynamically concentrates and shapes light in real-time
• Provides definition against background while feeling visually grounded
• Controls feel ultra-lightweight and transparent while visually distinguishable
• Elements materialize in/out by modulating light bending (not fading)

Design Implication: Unlike previous materials that scattered light, Liquid Glass uses instinctive visual cues from the natural world to provide separation.

2. Motion & Fluidity

Motion and visuals were designed as one unified experience:

• Instant flex and energize — Responds to interaction by flexing with light
• Gel-like flexibility — Communicates transient, malleable nature
• Moves in tandem with interaction — Aligns with dynamism of thinking and movement
• Temporary lift — Elements can lift into Liquid Glass on interaction (great for controls)
• Dynamic morphing — Continuously shape-shifts between app states as a singular floating plane
• Lightweight transitions — Menus pop open in-line, maintaining clear relationship to source

3. Adaptive Behavior

Liquid Glass continuously adapts without fixed light/dark appearance:

Content-aware adaptation:

• Shadows become more prominent when text scrolls underneath
• Tint and dynamic range shift to ensure legibility
• Independently switches light/dark to feel at home in any context
• Larger elements (menus, sidebars) simulate thicker material with deeper shadows and richer lensing

Platform adaptation:

• Nests perfectly into rounded corners of windows
• Forms distinct functional layer for controls/navigation
• Ambient environment (colorful content nearby) subtly spills onto surface
• Light reflects, scatters, and bleeds into shadows

Implementation Guide

Basic API Usage

SwiftUI: glassEffect Modifier

// Basic usage - applies glass within capsule shape
Text("Hello")
    .glassEffect()

// Custom shape
Text("Hello")
    .glassEffect(in: RoundedRectangle(cornerRadius: 12))

// Interactive elements (iOS - for controls/containers)
Button("Tap Me") {
    // action
}
.glassEffect()
.interactive() // Add for custom controls on iOS

Automatic Adoption: Simply recompiling with Xcode 26 brings Liquid Glass to standard controls automatically.

Variants: Regular vs Clear

CRITICAL DECISION: Never mix Regular and Clear in the same interface.

Regular Variant (Default — Use Most Often)

Characteristics:

• Most versatile, use in 95% of cases
• Full visual and adaptive effects
• Provides legibility regardless of context
• Works in any size, over any content
• Anything can be placed on top

When to use: Navigation bars, tab bars, toolbars, buttons, menus, sidebars

// Regular is the default
NavigationView {
    // Content
}
.glassEffect() // Uses Regular variant

Clear Variant (Special Cases Only)

Characteristics:

• Permanently more transparent
• No adaptive behaviors
• Allows content richness to interact with glass
• Requires dimming layer for legibility

Use ONLY when ALL three conditions are met:

1. ✅ Element is over media-rich content
2. ✅ Content layer won't be negatively affected by dimming layer
3. ✅ Content above glass is bold and bright

// Clear variant with localized dimming for small footprints
ZStack {
    MediaRichBackground()
        .overlay(.black.opacity(0.3)) // Dimming layer

    BoldBrightControl()
        .glassEffect(.clear)
}

⚠️ WARNING: Using Clear without meeting all three conditions results in poor legibility.

Layered System Architecture

Liquid Glass is composed of multiple layers working together:

1. Highlights Layer

• Light sources shine on material, producing highlights responding to geometry
• Lights move during interactions (lock/unlock), defining silhouette
• Some cases respond to device motion (feels aware of position in real world)

2. Shadows Layer

• Aware of background content
• Increases shadow opacity over text for separation
• Lowers shadow opacity over solid light backgrounds
• Ensures elements are always easy to spot

3. Internal Glow (Interaction Feedback)

• Material illuminates from within on interaction
• Glow starts under fingertips, spreads throughout element
• Spreads to nearby Liquid Glass elements
• Interacts with flexible properties - feels natural and fluid
• Makes interface feel alive and connected to physical world

4. Adaptive Tinting Layer

• Multiple layers adapt together to maintain hierarchy
• Windows losing focus visually recede (Mac/iPad)
• All behaviors come built-in automatically

Design Principles & Best Practices

✅ DO: Reserve for Navigation Layer

Correct Usage:

[Content Layer — No Glass]
    ↓
[Navigation Layer — Liquid Glass]
    • Tab bars
    • Navigation bars
    • Toolbars
    • Floating controls

Why: Liquid Glass floats above content, creating clear hierarchy.

❌ DON'T: Use on Content Layer

Wrong:

// DON'T apply to table views, lists, or content
List(items) { item in
    Text(item.name)
}
.glassEffect() // ❌ Competes with navigation, muddy hierarchy

Why: Makes elements compete, creates visual confusion.

❌ DON'T: Stack Glass on Glass

Wrong:

ZStack {
    NavigationBar()
        .glassEffect() // ❌

    FloatingButton()
        .glassEffect() // ❌ Glass on glass
}

Correct:

ZStack {
    NavigationBar()
        .glassEffect()

    FloatingButton()
        .foregroundStyle(.primary) // Use fills, transparency, vibrancy
        // Feels like thin overlay part of the material
}

✅ DO: Avoid Content Intersections in Steady State

Wrong: Content intersects with Liquid Glass when app launches

Correct: Reposition or scale content to maintain separation in steady states

Why: Prevents unwanted visual noise; intersections acceptable during scrolling/transitions.

Scroll Edge Effects

Work in concert with Liquid Glass to maintain separation and legibility with scrolling content.

How they work:

• Content begins scrolling → effect gently dissolves content into background
• Lifts glass visually above moving content
• Floating elements (titles) remain clear
• Darker content triggers dark style → subtle dimming for contrast

Hard Style Effect

Use when pinned accessory views exist (e.g., column headers):

ScrollView {
    // Content
}
.scrollEdgeEffect(.hard) // Uniform across toolbar + pinned accessories

When to use: Extra visual separation between floating elements in accessory view and scrolling content.

Tinting & Color

New Tinting System

Liquid Glass introduces adaptive tinting that respects material principles and maximizes legibility.

How it works:

1. Selecting color generates range of tones
2. Tones mapped to content brightness underneath element
3. Inspired by colored glass in reality
4. Changes hue, brightness, saturation based on background
5. Doesn't deviate too much from intended color

Compatible with all glass behaviors (morphing, adaptation, interaction).

Button("Primary Action") {
    // action
}
.tint(.red) // Adaptive tinting automatically applied
.glassEffect()

Tinting Best Practices

✅ DO: Use for Primary Actions

// Good — Emphasizes primary action
Button("View Bag") {
    // action
}
.tint(.red)
.glassEffect()

❌ DON'T: Tint Everything

// Wrong — When everything is tinted, nothing stands out
VStack {
    Button("Action 1").tint(.blue).glassEffect()
    Button("Action 2").tint(.green).glassEffect()
    Button("Action 3").tint(.purple).glassEffect()
} // ❌ Confusing, no hierarchy

Solution: Use color in content layer instead, reserve tinting for primary UI actions.

Solid Fills vs Tinting

Solid fills break Liquid Glass character:

// ❌ Opaque, breaks visual character
Button("Action") {}
    .background(.red) // Solid, opaque

// ✅ Transparent, grounded in environment
Button("Action") {}
    .tint(.red)
    .glassEffect()

Legibility & Contrast

Vibrant Text and Tint Colors

SwiftUI automatically uses a vibrant text color within glass effects that adapts to maintain legibility against colorful backgrounds. Tints applied to glass elements also use vibrant color that adapts to the content behind them. You do not need to manually adjust text or tint colors — the system handles this.

Automatic Legibility Features

Small elements (navbars, tabbars):

• Constantly adapt appearance based on background
• Flip light/dark for discernibility

Large elements (menus, sidebars):

• Adapt based on context
• Don't flip light/dark (too distracting for large surface area)

Symbols/glyphs:

• Mirror glass behavior (flip light/dark)
• Maximize contrast automatically
• All content on Regular variant receives this treatment

Custom Colors

Use selectively for distinct functional purpose:

// Selective tinting for emphasis
NavigationView {
    List {
        // Content
    }
    .toolbar {
        ToolbarItem {
            Button("Important") {}
                .tint(.orange) // Brings attention
        }
    }
}

Applies to: Labels, text, fully tinted buttons, time on lock screen, etc.

Accessibility

Liquid Glass offers several accessibility features that modify material without sacrificing its magic:

Reduced Transparency

• Makes Liquid Glass frostier
• Obscures more content behind it
• Applied automatically when system setting enabled

Increased Contrast

• Makes elements predominantly black or white
• Highlights with contrasting border
• Applied automatically when system setting enabled

Reduced Motion

• Decreases intensity of effects
• Disables elastic properties
• Applied automatically when system setting enabled

Developer Action Required: None - all features available automatically when using Liquid Glass.

Performance Considerations

View Hierarchy Impact

Concern: Liquid Glass rendering cost in complex view hierarchies

Guidance:

• Regular variant optimized for performance
• Larger elements (menus, sidebars) use more pronounced effects but managed by system
• Avoid excessive nesting of glass elements

Optimization:

// ❌ Avoid deep nesting
ZStack {
    GlassContainer1()
        .glassEffect()
    ZStack {
        GlassContainer2()
            .glassEffect()
        // More nesting...
    }
}

// ✅ Flatten hierarchy
VStack {
    GlassContainer1()
        .glassEffect()

    GlassContainer2()
        .glassEffect()
}

Rendering Costs

Adaptive behaviors have computational cost:

• Light/dark switching
• Shadow adjustments
• Tint calculations
• Lensing effects

System handles optimization, but be mindful:

• Don't animate Liquid Glass elements unnecessarily
• Use Clear variant sparingly (requires dimming layer computation)
• Profile with Instruments if experiencing performance issues

Testing Liquid Glass

Visual Regression Testing

Capture screenshots in multiple states:

func testLiquidGlassAppearance() {
    let app = XCUIApplication()
    app.launch()

    // Test light mode
    XCTContext.runActivity(named: "Light Mode Glass") { _ in
        let screenshot = app.screenshot()
        // Compare with baseline
    }

    // Test dark mode
    app.launchArguments = ["-UIUserInterfaceStyle", "dark"]
    app.launch()

    XCTContext.runActivity(named: "Dark Mode Glass") { _ in
        let screenshot = app.screenshot()
        // Compare with baseline
    }
}

Test Across Configurations

Critical test cases:

• ✅ Light mode vs dark mode
• ✅ Different color schemes (environment)
• ✅ Reduced Transparency enabled
• ✅ Increased Contrast enabled
• ✅ Reduced Motion enabled
• ✅ Dynamic Type (larger text sizes)
• ✅ Content scrolling (verify scroll edge effects)
• ✅ Right-to-left languages

Accessibility Testing

func testLiquidGlassAccessibility() {
    // Enable accessibility features via launch arguments
    app.launchArguments += [
        "-UIAccessibilityIsReduceTransparencyEnabled", "1",
        "-UIAccessibilityButtonShapesEnabled", "1",
        "-UIAccessibilityIsReduceMotionEnabled", "1"
    ]

    // Verify glass still functional and legible
    XCTAssertTrue(glassElement.exists)
    XCTAssertTrue(glassElement.isHittable)
}

Design Review Pressure: Defending Your Implementation

The Problem

Under design review pressure, you'll face requests to:

• "Use Clear variant everywhere — Regular is too opaque"
• "Glass on all controls for visual cohesion"
• "More transparency to let content shine through"

These sound reasonable. But they violate the framework. Your job: defend using evidence, not opinion.

Red Flags — Designer Requests That Violate Skill Guidelines

If you hear ANY of these, STOP and reference the skill:

• ❌ "Use Clear everywhere" – Clear requires three specific conditions, not design preference
• ❌ "Glass looks better than fills" – Correct layer (navigation vs content) trumps aesthetics
• ❌ "Users won't notice the difference" – Clear variant fails legibility tests in low-contrast scenarios
• ❌ "Stack glass on glass for consistency" – Explicitly prohibited; use fills instead
• ❌ "Apply glass to Lists for sophistication" – Lists are content layer; causes visual confusion

How to Push Back Professionally

Step 1: Show the Framework

"I want to make this change, but let me show you Apple's guidance on Clear variant.
It requires THREE conditions:

1. Media-rich content background
2. Dimming layer for legibility
3. Bold, bright controls on top

Let me show which screens meet all three..."

Step 2: Demonstrate the Risk

Open the app on a device. Show:

• Clear variant in low-contrast scenario (unreadable)
• Regular variant in same scenario (legible)

Step 3: Offer Compromise

"Clear can work beautifully in these 6 hero sections where all three conditions apply.
Regular handles everything else with automatic legibility. Best of both worlds."

Step 4: Document the Decision

If overruled (designer insists on Clear everywhere):

Slack message to PM + designer:

"Design review decided to use Clear variant across all controls.
Important: Clear variant requires legibility testing in low-contrast scenarios
(bright sunlight, dark content). If we see accessibility issues after launch,
we'll need an expedited follow-up. I'm flagging this proactively."

Why this works

• You're not questioning their taste (you like Clear too)
• You're raising accessibility/legibility risk
• You're offering a solution that preserves their vision in hero sections
• You're documenting the decision (protects you post-launch)

Real-World Example: App Store Launch Blocker (36-Hour Deadline)

Scenario

• 36 hours to launch
• Chief designer says: "Clear variant everywhere"
• Client watching the review meeting
• You already implemented Regular per the skill

What to do

// In the meeting, demo side-by-side:

// Regular variant (current implementation)
NavigationBar()
    .glassEffect() // Automatic legibility

// Clear variant (requested)
NavigationBar()
    .glassEffect(.clear) // Requires dimming layer below

// Show the three-condition checklist
// Demonstrate which screens pass/fail
// Offer: Clear in hero sections, Regular elsewhere

Result

• 30-minute compromise demo
• 90 minutes to implement changes
• Launch on schedule with optimal legibility
• No post-launch accessibility complaints

When to Accept the Design Decision (Even If You Disagree)

Sometimes designers have valid reasons to override the skill. Accept if:

• They understand the three-condition framework
• They're willing to accept legibility risks
• You document the decision in writing
• They commit to monitoring post-launch feedback

Document in Slack

"Design review decided to use Clear variant [in these locations].
We understand this requires:
- All three conditions met: [list them]
- Potential legibility issues in low-contrast scenarios
- Accessibility testing across brightness levels

Monitoring plan:
- Gather user feedback first 48 hours
- Run accessibility audit
- Have fallback to Regular variant ready for push if needed"

This protects both of you and shows you're not blocking - just de-risking.

Expert Review Checklist

When reviewing Liquid Glass implementation (your code or others'), check:

1. Material Appropriateness

• Is Liquid Glass used only on navigation layer (not content)?
• Are standard controls getting glass automatically via Xcode 26 recompile?
• Is glass avoided on glass situations?

2. Variant Selection

• Is Regular variant used for most cases?
• If Clear variant used, do all three conditions apply?
  • Over media-rich content?
  • Dimming layer acceptable?
  • Content above is bold and bright?
• Are Regular and Clear never mixed in same interface?

3. Legibility & Contrast

• Are primary actions selectively tinted (not everything)?
• Is color used in content layer for overall app color scheme?
• Are solid fills avoided on glass elements?
• Do elements maintain legibility on various backgrounds?

4. Layering & Hierarchy

• Are content intersections avoided in steady states?
• Are elements on top of glass using fills/transparency (not glass)?
• Is visual hierarchy clear (navigation layer vs content layer)?

5. Scroll Edge Effects

• Are scroll edge effects applied where Liquid Glass meets scrolling content?
• Is hard style used for pinned accessory views?

6. Accessibility

• Does implementation work with Reduced Transparency?
• Does implementation work with Increased Contrast?
• Does implementation work with Reduced Motion?
• Are interactive elements hittable in all configurations?

7. Performance

• Is view hierarchy reasonably flat?
• Are glass elements animated only when necessary?
• Is Clear variant used sparingly?

Common Mistakes & Solutions

Mistake 1: Using Glass Everywhere

Wrong:

List(landmarks) { landmark in
    LandmarkRow(landmark)
        .glassEffect() // ❌
}
.glassEffect() // ❌

Correct:

NavigationView {
    List(landmarks) { landmark in
        LandmarkRow(landmark) // No glass
    }
}
.toolbar {
    ToolbarItem {
        Button("Add") {}
            .glassEffect() // ✅ Navigation layer only
    }
}

Why: Content layer should defer to Liquid Glass navigation layer.

Mistake 2: Clear Variant Without Dimming

Wrong:

ZStack {
    VideoPlayer(player: player)

    PlayButton()
        .glassEffect(.clear) // ❌ No dimming, poor legibility
}

Correct:

ZStack {
    VideoPlayer(player: player)
        .overlay(.black.opacity(0.4)) // Dimming layer

    PlayButton()
        .glassEffect(.clear) // ✅
}

Mistake 3: Over-Tinting

Wrong: All buttons tinted different colors

Correct: Primary action tinted, others use standard appearance

Mistake 4: Static Material Expectations

Wrong: Assuming glass always looks the same (e.g., hardcoded shadows, fixed opacity)

Correct: Embrace adaptive behavior, test across light/dark modes and backgrounds

Troubleshooting

Visual Artifacts

Issue: Glass appears too transparent or invisible

Check:

1. Are you using Clear variant? (Switch to Regular if inappropriate)
2. Is background content extremely light or dark? (Glass adapts - this may be correct behavior)
3. Is Reduced Transparency enabled? (Check accessibility settings)

Issue: Glass appears opaque or has harsh edges

Check:

1. Are you using solid fills on glass? (Remove, use tinting)
2. Is Increased Contrast enabled? (Expected behavior)
3. Is custom shape too complex? (Simplify geometry)

Dark Mode Issues

Issue: Glass doesn't flip to dark style on dark backgrounds

Check:

1. Is element large (menu, sidebar)? (Large elements don't flip - by design)
2. Is background actually dark? (Use Color Picker to verify)
3. Are you overriding appearance? (Remove .preferredColorScheme() if unintended)

Issue: Content on glass not legible in dark mode

Fix:

// Let SwiftUI handle contrast automatically
Text("Label")
    .foregroundStyle(.primary) // ✅ Adapts automatically

// Don't hardcode colors
Text("Label")
    .foregroundColor(.black) // ❌ Won't adapt to dark mode

Performance Issues

Issue: Scrolling feels janky with Liquid Glass

Debug:

1. Profile with Instruments (see axiom-swiftui-performance skill)
2. Check for excessive view body updates
3. Simplify view hierarchy under glass
4. Verify not applying glass to content layer (major performance hit)

Issue: Animations stuttering

Check:

1. Are you animating glass shape changes? (Expensive)
2. Profile with SwiftUI Instrument for long view updates
3. Consider reducing glass usage if critical path

Migration from Previous Materials

From UIBlurEffect / NSVisualEffectView

Before (UIKit):

let blurEffect = UIBlurEffect(style: .systemMaterial)
let blurView = UIVisualEffectView(effect: blurEffect)
view.addSubview(blurView)

After (SwiftUI with Liquid Glass):

ZStack {
    // Content
}
.glassEffect()

Benefits:

• Automatic adaptation (no manual style switching)
• Built-in interaction feedback
• Platform-appropriate appearance
• Accessibility features included

From Custom Materials

If you've built custom translucent effects:

1. Try Liquid Glass first — may provide desired effect automatically
2. Evaluate Regular vs Clear — Clear may match custom transparency needs
3. Test across configurations — Liquid Glass adapts automatically
4. Measure performance — Likely improvement over custom implementations

When to keep custom materials:

• Specific artistic effect not achievable with Liquid Glass
• Backward compatibility with iOS < 26 required
• Non-standard UI paradigm incompatible with Liquid Glass principles

API Reference

SwiftUI Modifiers

glassEffect(in:isInteractive:)

Applies Liquid Glass effect to view.

func glassEffect<S: Shape>(
    in shape: S = Capsule(),
    isInteractive: Bool = false
) -> some View

Parameters:

• shape: Shape defining glass bounds (default: Capsule())
• isInteractive: On iOS, enables interactive mode for custom controls (default: false)

Returns: View with Liquid Glass effect applied

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+, axiom-visionOS 3+

Example:

// Default capsule shape
Text("Hello").glassEffect()

// Custom shape
Text("Hello").glassEffect(in: RoundedRectangle(cornerRadius: 16))

// Interactive (iOS)
Button("Tap") {}.glassEffect(isInteractive: true)

glassEffect(_:in:isInteractive:)

Applies specific Liquid Glass variant.

func glassEffect<S: Shape>(
    _ variant: GlassVariant,
    in shape: S = Capsule(),
    isInteractive: Bool = false
) -> some View

Parameters:

• variant: .regular or .clear
• shape: Shape defining glass bounds
• isInteractive: Interactive mode for custom controls (iOS)

Example:

Text("Hello").glassEffect(.clear, in: Circle())

scrollEdgeEffect(_:)

Configures scroll edge appearance with Liquid Glass.

func scrollEdgeEffect(_ style: ScrollEdgeStyle) -> some View

Parameters:

• style: .automatic, .soft, or .hard

Example:

ScrollView {
    // Content
}
.scrollEdgeEffect(.hard) // For pinned accessories

scrollEdgeEffectStyle(_:for:) NEW in iOS 26

Optimizes legibility for controls when content scrolls beneath them.

func scrollEdgeEffectStyle(_ style: ScrollEdgeStyle, for edges: Edge.Set) -> some View

Parameters:

• style: .hard, .soft, or .automatic
• edges: Which edges to apply effect (.top, .bottom, .leading, .trailing)

Use case: Custom bars with controls, text, or icons that have content scrolling beneath them. System bars (toolbars, navigation bars) adopt this automatically.

Example:

// Custom toolbar with controls
CustomToolbar()
    .scrollEdgeEffectStyle(.hard, for: .top) // Maintain legibility

ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item)
        }
    }
}

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+

glassBackgroundEffect() NEW in iOS 26

Applies glass effect to custom views for reflecting surrounding content.

func glassBackgroundEffect() -> some View

Use case: Apply Liquid Glass appearance to custom views (not buttons/controls) that should beautifully reflect surrounding content like photos.

Example:

struct PhotoGalleryView: View {
    var body: some View {
        CustomPhotoGrid()
            .glassBackgroundEffect() // Reflects surrounding photos
    }
}

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+, axiom-visionOS 3+

Toolbar Modifiers NEW in iOS 26

.toolbar with ToolbarSpacer(.fixed)

Separates toolbar button groups with fixed spacing.

.toolbar {
    ToolbarItemGroup(placement: .topBarTrailing) {
        Button("Up") { }
        Button("Down") { }

        ToolbarSpacer(.fixed) // Fixed spacer separates groups

        Button("Settings") { }
    }
}

Why use .fixed: Creates logical visual separation between button groups. Default Spacer() is flexible and adjusts based on available space; .fixed maintains consistent separation.

Common pattern: Separate navigation buttons from action buttons, or primary actions from secondary actions.

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+

.buttonStyle(.borderedProminent) + .tint() in Toolbars

Makes toolbar items more prominent with Liquid Glass tinting.

.toolbar {
    ToolbarItem(placement: .topBarTrailing) {
        Button("Add Trip") {
            addTrip()
        }
        .buttonStyle(.borderedProminent)
        .tint(.blue) // Liquid Glass toolbars support tinting
    }
}

Visual effect: Button appears with bordered prominent style and custom tint color, making it stand out against Liquid Glass toolbar background.

Best practice: Use for primary actions in toolbars. Don't over-tint - use for prominence, not decoration.

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+

Navigation & Search NEW in iOS 26

Bottom-Aligned Search

Search automatically appears bottom-aligned on iPhone (more ergonomic), top-trailing on iPad.

NavigationSplitView {
    List { }
        .searchable(text: $searchText)
}
// Placement on NavigationSplitView automatically:
// - Bottom-aligned on iPhone
// - Top trailing corner on iPad

No code changes required — existing .searchable() modifier automatically adopts platform-specific placement.

Why bottom-aligned: More ergonomic to reach on iPhone with thumb-based interaction.

Availability: iOS 26+, iPadOS 26+

Search Tab Role

Separates search tab from other tabs in tab bar, morphs into search field.

TabView {
    SearchView()
        .tabItem { Label("Search", systemImage: "magnifyingglass") }
        .tabRole(.search) // Separated from other tabs, morphs into search

    TripsView()
        .tabItem { Label("Trips", systemImage: "map") }
}

Visual effect: Search tab appears separated from other tabs in the tab bar. When tapped, morphs into the search field.

Use case: Tab-based apps where search is a primary destination.

Availability: iOS 26+

Controls and Layout NEW in iOS 26

containerRelativeShape()

Aligns control shapes with container curvature for visual continuity.

func containerRelativeShape(_ shape: ContainerRelativeShape) -> some View

Parameters:

• shape: Shape that aligns with container (e.g., .roundedRectangle)

Use case: Create visual harmony by making controls concentric to their containers (sheets concentric to windows, controls concentric to sheets).

Example:

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

Visual Effect Nested elements feel visually harmonious, with curvature matching container shape.

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+

tabBarMinimizeBehavior(_:) NEW in iOS 26

Configures tab bar to minimize when scrolling to elevate underlying content.

func tabBarMinimizeBehavior(_ behavior: TabBarMinimizeBehavior) -> some View

Parameters:

• behavior: .onScrollDown, .onScrollUp, .automatic, or .never

Use case: Content-focused apps (reading, media) where tab bar should recede during scrolling.

Example:

TabView {
    ContentView()
        .tabItem { Label("Home", systemImage: "house") }
}
.tabBarMinimizeBehavior(.onScrollDown) // Minimize when scrolling down

Visual Effect Tab bar recedes when scrolling down, expands when scrolling up. Content gains more screen space.

Gotcha: Tab bar blur only activates when the tab bar overlays scrollable content. If non-scrollable views (buttons, fixed VStacks) sit between your list and the tab bar, you get a solid background instead of blur. Ensure your primary scrollable view is the outermost content layer.

// ❌ Solid background — Button breaks scrollable overlay
VStack {
    List { /* items */ }
    Button("Add") { }  // Sits between list and tab bar
}

// ✅ Blurred background — List extends under tab bar
ZStack(alignment: .bottomTrailing) {
    List { /* items */ }  // Scrollable content under tab bar
    Button(action: { }) {
        Label("Add", systemImage: "plus")
            .labelStyle(.iconOnly).padding()
    }
    .glassEffect(.regular.interactive())
    .padding([.bottom, .trailing], 12)
}

Availability: iOS 26+

Floating Glass Buttons

Liquid Glass replaces bottom-anchored action buttons with floating glass buttons. Use .glassEffect(.regular.interactive()) on a ZStack-overlaid button:

ZStack(alignment: .bottomTrailing) {
    ScrollView {
        // Main content
    }

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

When to use: Replace pre-iOS 26 bottom-bar action buttons that no longer fit the layered Liquid Glass design.

Availability: iOS 26+

Types

GlassVariant

enum GlassVariant {
    case regular  // Default - full adaptive behavior
    case clear    // More transparent, no adaptation
}

ScrollEdgeStyle

enum ScrollEdgeStyle {
    case automatic  // System determines style
    case soft       // Gradual fade
    case hard       // Uniform effect across toolbar height
}

GlassEffectContainer NEW in iOS 26

Container for combining multiple Liquid Glass effects with correct visual behavior.

struct GlassEffectContainer<Content: View>: View {
    init(@ViewBuilder content: () -> Content)
}

Why this is essential: Glass samples content from an area larger than itself to produce its reflections and refractions. However, glass cannot sample other glass — nearby glass elements in different containers will produce inconsistent visual behavior. Using a GlassEffectContainer allows elements to share their sampling region, providing a consistent visual result.

Example

// ✅ Shared sampling region — consistent visual result
GlassEffectContainer {
    HStack {
        Button("Action 1") { }
            .glassEffect()

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

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

// ❌ Separate containers — inconsistent glass behavior
HStack {
    Button("Action 1") { }.glassEffect()  // Samples independently
    Button("Action 2") { }.glassEffect()  // Can't sample neighbor's glass
}

Benefits

• Correct visual behavior (shared sampling region)
• Fluidly morphs Liquid Glass shapes into each other
• Optimizes rendering performance
• Reduces compositor overhead

When to use

• Multiple custom Liquid Glass elements near each other
• Morphing animations between glass shapes
• Any time glass elements are visually adjacent

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+, axiom-visionOS 3+

glassEffectID NEW in iOS 26

Enables fluid morphing transitions between glass elements using a namespace. When elements share a namespace and transition between states, glass morphs fluidly between shapes.

@Namespace private var glassNamespace

// Associate glass elements with IDs in the namespace
ForEach(badges) { badge in
    BadgeView(badge: badge)
        .glassEffect()
        .glassEffectID(badge.id, in: glassNamespace)
}

// A toolbar button with the same namespace absorbs/expands badges
Button("Awards", systemImage: "star.fill") {
    toggleBadges()
}
.glassEffect()
.glassEffectID("awards", in: glassNamespace)

Use case: Award badges expanding from a toolbar button, controls morphing between states, expanding/collapsing glass elements.

Availability: iOS 26+, iPadOS 26+, macOS Tahoe+

Backward Compatibility

UIDesignRequiresCompatibility Key NEW in iOS 26

To ship with latest SDKs while maintaining previous appearance:

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

Availability: iOS 26+, iPadOS 26+

Resources

WWDC: 2025-219, 2025-256, 2025-323 (Build a SwiftUI app with the new design)

Docs: /technologyoverviews/adopting-liquid-glass, /swiftui/landmarks-building-an-app-with-liquid-glass, /swiftui/applying-liquid-glass-to-custom-views

Skills: axiom-liquid-glass-ref

Platforms: iOS 26+, iPadOS 26+, macOS Tahoe, axiom-visionOS 3 Xcode: 26+ History: See git log for changes