iOS 26 Liquid Glass — design rules + the SwiftUI APIs that ship it

Liquid Glass is the unified material introduced across iOS/iPadOS/macOS Tahoe/watchOS/tvOS 26 (WWDC June 2025). Sources below are anchored to Apple primary material — WWDC25 session 219 "Meet Liquid Glass" and session 323 "Build a SwiftUI app with the new design" — and confirmed developer.apple.com/documentation symbol pages. API symbols are marked ✅ (shown in an Apple source) or ⚠️ (community-reported only — verify in the Xcode 26 SDK before relying on it). Do not treat ⚠️ items as canonical.

1. The one mental model that prevents 90% of mistakes

Glass is the functional/navigation layer that floats above the content layer. Content scrolls underneath it.

• Apple, verbatim: "Liquid Glass is best reserved for the navigation layer that floats above the content of your app." (219)
• "making [a tableview] Liquid Glass would make it compete with other elements and muddy the hierarchy. So keep it in the content layer instead." (219)
• It is a light-bending meta-material, not a blur — its signature cue is lensing (it bends/concentrates light so content shows through while staying separated). It materializes in/out (modulating lensing), it doesn't fade. (219)
• It is continuously adaptive: each layer adapts to what's behind it. Small chrome (nav/tab bars) flips light↔dark with the background; large elements (sidebars, menus) adapt tint but do not flip (flipping would distract). (219)

2. Hard don'ts (all Apple-stated, 219/323)

• No glass on glass. "Stacking Liquid Glass elements on top of each other can quickly make the interface feel cluttered… use fills, transparency, and vibrancy for the top elements." Also enforced technically: "Glass cannot sample other glass."
• Don't overuse it. "You may be tempted to use Liquid Glass everywhere but it is best reserved for the navigation layer."
• Don't put color/tint on everything. "When every element is tinted, nothing stands out… imbue color into your app… in the content layer instead." Tint only to convey meaning (one call-to-action / next step).
• Don't let chrome intersect content at rest. "In steady states… avoid intersections between content and Liquid Glass. Instead, reposition or scale the content to maintain separation."
• Never mix the two variants (regular + clear) in one element.
• Don't reintroduce redundant chrome once on glass: remove extra sheet backgrounds, darkening behind toolbar items, custom .presentationBackground.