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

• "How is Liquid Glass different from blur effects? Should I adopt it?"
• "My lensing effect looks like a regular blur. What am I missing?"
• "Liquid Glass looks odd on iPad vs iPhone. How do I adjust?"
• "How do I ensure text contrast on top of Liquid Glass?"
• "What are the expert criteria for reviewing a Liquid Glass implementation?"

---

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 — warping and bending light to communicate presence, motion, and form. Elements materialize in/out by modulating light bending (not fading). Controls feel ultra-lightweight yet visually distinguishable.

2. Motion & Fluidity

• Responds to interaction by flexing with light
• Gel-like flexibility communicates transient, malleable nature
• Elements lift into Liquid Glass on interaction (controls)
• Dynamic morphing between app states as a singular floating plane

3. Adaptive Behavior

Liquid Glass continuously adapts without fixed light/dark appearance:

• Shadows intensify when text scrolls underneath; tint shifts for legibility
• Small elements (navbars) independently flip light/dark; large elements (menus, sidebars) don't flip but adapt depth
• Ambient environment subtly spills onto surface

---

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 — 95% of Cases)

Most versatile. Full adaptive effects, automatic legibility, works in any size over any content. Use for navigation bars, tab bars, toolbars, buttons, menus, sidebars.

Clear Variant (Special Cases Only)

Permanently more transparent, no adaptive behaviors. 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

Using Clear without meeting all three conditions results in poor legibility. See axiom-liquid-glass-ref for implementation examples.

---

Layered System Architecture

Liquid Glass is composed of four layers working together:

1. Highlights — Light sources produce highlights responding to geometry; some respond to device motion
2. Shadows — Content-aware: stronger over text, weaker over light backgrounds
3. Internal Glow — Material illuminates from within on interaction; spreads to nearby glass elements
4. Adaptive Tinting — Multiple layers adapt together to maintain hierarchy; all built-in automatically

---

Scroll Edge Effects

Scroll edge effects dissolve content into background as it scrolls, lifting glass above moving content. Use .scrollEdgeEffect(.hard) when pinned accessory views exist (e.g., column headers) for extra visual separation. See axiom-liquid-glass-ref for full API details.

---

Tinting & Color

Liquid Glass introduces adaptive tinting — selecting a color generates tones mapped to content brightness underneath, inspired by colored glass in reality. Compatible with all glass behaviors (morphing, adaptation, interaction).

Tinting Rules

// ✅ Tint primary actions only
Button("View Bag") { }.tint(.red).glassEffect()

// ❌ Don't tint everything — when everything is tinted, nothing stands out
VStack {
    Button("Action 1").tint(.blue).glassEffect()
    Button("Action 2").tint(.green).glassEffect()  // No hierarchy
}

// ❌ Solid fills break Liquid Glass character
Button("Action") { }.background(.red)  // Opaque, wrong

// ✅ Use .tint() instead of solid fills
Button("Action") { }.tint(.red).glassEffect()  // Grounded in environment

Reserve tinting for primary UI actions. Use color in the content layer for overall app color scheme.

---

Legibility & Contrast

SwiftUI automatically uses vibrant text and tint colors within glass effects — no manual adjustment needed. Small elements (navbars, tabbars) flip light/dark for discernibility. Large elements (menus, sidebars) adapt but don't flip (too distracting for large surface area). Symbols/glyphs mirror glass behavior and maximize contrast automatically.

Use custom tint colors selectively for distinct functional purpose (e.g., .tint(.orange) on a single toolbar button for emphasis).

---

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

Test across these configurations:

• Light/dark modes
• Reduced Transparency enabled
• Increased Contrast enabled
• Reduced Motion enabled
• Dynamic Type (larger text sizes)
• Content scrolling (verify scroll edge effects)
• Right-to-left languages

See axiom-ui-testing for comprehensive UI testing patterns including visual regression and accessibility testing.

---

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 feedbac