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
Text("Hello")
.glassEffect()
Text("Hello")
.glassEffect(in: RoundedRectangle(cornerRadius: 12))
Button("Tap Me") {
}
.glassEffect()
.interactive()
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:
- Element is over media-rich content
- Content layer won't be negatively affected by dimming layer
- 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:
- Highlights — Light sources produce highlights responding to geometry; some respond to device motion
- Shadows — Content-aware: stronger over text, weaker over light backgrounds
- Internal Glow — Material illuminates from within on interaction; spreads to nearby glass elements
- 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
Button("View Bag") { }.tint(.red).glassEffect()
VStack {
Button("Action 1").tint(.blue).glassEffect()
Button("Action 2").tint(.green).glassEffect()
}
Button("Action") { }.background(.red)
Button("Action") { }.tint(.red).glassEffect()
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:
ZStack {
GlassContainer1()
.glassEffect()
ZStack {
GlassContainer2()
.glassEffect()
}
}
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
NavigationBar()
.glassEffect()
NavigationBar()
.glassEffect(.clear)
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:
