ios-liquid-glass-swiftui

name	ios-liquid-glass-swiftui
description	iOS 26/27 Liquid Glass design language + the SwiftUI APIs that implement it, sourced from Apple's WWDC25 sessions 219/323, the WWDC26 Liquid Glass v2 refinements, and developer.apple.com. Covers the functional-layer-over-content mental model, regular vs clear variants, glass-on-glass/over-tint don'ts, the floating tab bar, scroll edge effects, concentric corners, the user transparency slider, the appearsActive inactive-window dimming, accessibility behavior, and a verified-vs-community API table. Use when building or reviewing any iOS 26/27 native screen's chrome, materials, or glass effects.
tags	["ios","ios26","ios27","liquid-glass","swiftui","materials","apple","hig"]

iOS 26/27 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) and refined as Liquid Glass v2 at WWDC26 (June 8–12 2026) shipping in iOS/iPadOS/macOS 27. iOS 26 is the now-shipping baseline; iOS 27 (the WWDC26 cycle) is the current announced iteration — Liquid Glass v2 is the latest material, not the original WWDC25 one. 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", plus the WWDC26 keynote + "What's new in SwiftUI" coverage — 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/27 SDK before relying on it). Do not treat ⚠️ items as canonical. (Stamp: June 2026.)

Source: WWDC25 sessions 219 + 323; WWDC26 keynote (June 8 2026) "Liquid Glass improvements"; WWDC26 "What's new in SwiftUI"; developer.apple.com/documentation. WWDC26 specifics cross-checked against MacRumors (2026-06-08) + DEV/arshtechpro WWDC26 SwiftUI breakdown — Apple dev pages render in JS, so secondary tech sources used to confirm.

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.

3. Regular vs Clear

	Regular — use ~always	Clear — specialized
Adaptive behaviors	Full	None (permanently more transparent)
Legibility	Guaranteed in any context	Needs a dimming layer beneath it
Where	Any size, over any content	Media-rich content only

Clear requires all three to be true (219): the element is over media-rich content, the content layer tolerates a dimming layer, and the content on top is bold/bright. SwiftUI: Glass.regular ✅; Glass.clear ⚠️ (community).

iOS 27 / v2 note: the fixed regular-vs-clear split is now bracketed by the user's transparency slider (see §9) — at runtime a user can dial all glass from fully tinted toward fully clear. Don't hard-code legibility assuming the regular default; the user may have already pushed your chrome toward clear. v2 also "diffuses complex content behind it much more effectively" (Apple, WWDC26), so the regular variant is more legible over busy backgrounds than the WWDC25 version was — but verify, don't assume.

4. Accessibility — automatic, but verify the safety-critical surfaces

When you use the standard material, glass responds to system settings automatically (219):

• Reduce Transparency → glass becomes frostier, obscures more behind it.
• Increase Contrast → elements go predominantly black/white with a contrasting border.
• Reduce Motion → reduces effect intensity, disables elastic properties.

For Greg specifically: keep safety-critical text in the solid content layer (allergy hard-stops, macro/calorie numbers) — never floating on clear glass. Test every glass screen with all three settings ON. Branch in code via the existing \.accessibilityReduceTransparency / \.accessibilityReduceMotion environment keys.

iOS 27 / v2 — the transparency slider is NOT an accessibility toggle (it's a default for everyone). Separate from Reduce Transparency, iOS 27 adds a user-facing Liquid Glass transparency slider (in Settings, also offered on the iPhone setup screen) that dials all glass from fully tinted toward fully clear — Apple's direct response to iOS 26 readability complaints. SwiftUI glass tint responds to it automatically with no code. Consequence: you can no longer assume the regular-variant default translucency — a mainstream (not just low-vision) user may have already pushed your chrome toward clear, so legibility of anything over glass must hold across the slider's range, not just at the default.

5. The floating tab bar + content flow (323)

• Tab bar + toolbars float as glass chrome; content scrolls under, with the scroll edge effect handling the transition (no hard bar background).
• Minimize on scroll ✅: .tabBarMinimizeBehavior(.onScrollDown) — re-expands on scroll up, keeps content the focus.
• Persistent accessory above the bar ✅: .tabViewBottomAccessory { … }, lay out via @Environment(\.tabViewBottomAccessoryPlacement).
• Dedicated search tab ✅: Tab(role: .search) { … }.
• ⚠️ Full enum case lists for tabBarMinimizeBehavior (.automatic/.never) and placement (.inline/.expanded) are community-reported; only .onScrollDown + placement == .inline are confirmed.

6. Verified SwiftUI API reference (iOS 26.0+, Xcode 26+; iOS 27 / v2 notes inline)

Standard controls auto-adopt glass when built with Xcode 26 — reach for .glassEffect() only to highlight what's unique to your app. (323)

iOS 27 / v2 — automatic appearance adoption: apps built with SwiftUI automatically pick up the updated Liquid Glass v2 appearance on the iOS/iPadOS/macOS 27 build with no code change, and glass tint follows the user transparency slider automatically (WWDC26). No glassEffect rename — the same modifiers render the v2 material. So an app already on the API gets v2 "for free"; the work is re-verifying legibility, not re-coding.

appearsActive — inactive-window dimming (mainly iPad/Mac, WWDC26): read the \.appearsActive environment value to reduce opacity on your CUSTOM glass elements when the window is inactive; iPad windows now auto-dim when inactive and Apple's standard chrome handles this for you. Only custom glass needs the manual branch.

@Environment(\.appearsActive) private var appearsActive   // ✅ WWDC26 "What's new in SwiftUI"
// e.g. custom floating-glass accessory:
.opacity(appearsActive ? 1.0 : 0.5)   // reduce custom-element opacity when window inactive

// Apply glass to a CUSTOM view
.glassEffect()                        // ✅ defaults to Glass.regular, capsule-ish
.glassEffect(in: .rect(cornerRadius: 16))   // ✅ custom shape
.glassEffect(.regular.tint(.green))         // ✅ tint ONLY to convey meaning
.glassEffect(.regular.interactive())        // ✅ scale/bounce/shimmer on touch

// Group + morph (share sampling region, batch render)
@Namespace var ns
GlassEffectContainer {                       // ✅ symbol page confirmed
    BadgeLabel().glassEffect().glassEffectID(badge.id, in: ns)  // ✅ glassEffectID(_:in:)
    BadgeToggle().buttonStyle(.glass).glassEffectID("toggle", in: ns)
}

// Button styles
Button("Learn More") {}.buttonStyle(.glass)           // ✅ secondary
Button("Get Started") {}.buttonStyle(.glassProminent) // ✅ prominent

// Toolbars
.toolbar {
    ToolbarItem { ShareLink() }
    ToolbarSpacer(.fixed)                              // ✅ group separation
    ToolbarItem { FavoriteButton() }
    DefaultToolbarItem(kind: .search, placement: .bottomBar)   // ✅
    ToolbarItem { ProfileButton() }.sharedBackgroundVisibility(.hidden) // ✅ detach from shared glass
}

// Search
.searchable(text: $q)
.searchToolbarBehavior(.minimize)   // ✅ NOTE: .minimize, NOT .minimized (community ref is wrong)

// Scroll edge effect — content-under-chrome legibility
.scrollEdgeEffectStyle(.hard, for: .top)   // ✅ tune sharpness for dense UIs
.scrollEdgeEffectHidden(true, for: .top)   // ✅ hide it
// ⚠️ full ScrollEdgeEffectStyle case list beyond .hard not confirmed

// Background extension — artwork fills under chrome / into safe area
Image("hero").resizable().scaledToFill().backgroundExtensionEffect()  // ✅

Concentric corners (Harmony principle — nested shapes share a curve center so corners align across devices):

.background(.tint, in: .rect(corner: .containerConcentric))  // ✅ form shown in 323
// ⚠️ community forms — verify spelling in SDK before use:
//   ConcentricRectangle(corners: .concentric, isUniform: true)
//   .containerShape(.rect(cornerRadius: 24))

⚠️ Unresolved naming: Apple's transcript shows corner: .containerConcentric (singular); community shows corners: .concentric. Likely beta API churn — confirm in your Xcode 26 SDK.

Community-only (⚠️ verify before use): Glass.clear/.identity, glassEffectUnion, glassEffectTransition/GlassEffectTransition, GlassEffectContainer(spacing:), matchedTransitionSource/.navigationTransition(.zoom(...)), UIDesignRequiresCompatibility opt-out, and all battery/performance figures.

7. Glass vs solid — quick decision

Use glass	Use solid / content fills
Tab bars, toolbars, nav bars (floating chrome)	Lists, cards, media, data rows
Standalone floating action buttons	Anything carrying brand color or meaning-tint
Sheets (system applies inset glass automatically)	Safety-critical / dense legibility text
One element over media (Clear, 3 conditions)	The second layer when something sits on glass

8. What changed in Liquid Glass v2 (iOS 27 / WWDC26) — the delta to know

Don't rebuild — most of this is automatic on the iOS 27 build. The net for design/review:

• Material retuned for legibility. v2 "diffuses complex content behind it much more effectively, while also creating more depth and separation" (Apple keynote). The original WWDC25 glass over busy content was the chief complaint; v2 is the fix. Re-check any screen you previously hacked for contrast — the hack may now be redundant.
• User transparency slider (Settings + setup screen) → glass spans fully-tinted ↔ fully-clear for everyone. Auto-honored in SwiftUI. See §3/§4: design legibility across the range, not at one default.
• appearsActive inactive-window dimming (§6) — iPad windows dim when inactive; custom glass opts in manually.
• Sidebars now extend to the window edge, with refraction continuing beneath them rather than stopping at the boundary; sidebar icons keep their color (was a v1 complaint). (Relevant to iPad/Mac, not Greg's iPhone tab UI.)
• App icons gain dimensional Liquid Glass layers baked into the artwork itself (building on the WWDC25 first-party icon redesign). ⚠️ Verify-at-source: exact Icon Composer / asset-format requirements for shipping a v2-layered icon are not pinned here — confirm in Xcode 27 / HIG before producing Greg's AppIcon.
• Tab/navigation bars refreshed under v2; tab-bar search re-integration is called out for iOS 27. ⚠️ Verify-at-source: no confirmed new tab/search API symbol beyond the §5 set (Tab(role:.search), .searchToolbarBehavior(.minimize), .tabBarMinimizeBehavior) — treat v2 tab/search changes as appearance + behavior until an SDK symbol is confirmed.
• No renamed glass APIs. glassEffect / GlassEffectContainer / glassEffectID / .interactive() were not announced as changed at WWDC26 — same symbols, v2 material. ⚠️ Verify-at-source if you see beta release-note churn.

9. Greg application

• Let the system render chrome glass; theme only .tint(tangerine) + your own content surfaces. Never force the tab bar opaque (that's the "white bar" bug — reserves a dead inset, kills content-scrolls-under).
• Put the tangerine accent in the content layer (primary button fill, key numbers), not on the bars.
• Keep GregCard and data rows solid (standard materials/fills), not glass — they're content.
• If adopting .tabViewBottomAccessory, use it for a persistent "log food" affordance, not decoration.
• iOS 27 / v2: Greg gets the v2 material free on the iOS 27 build — but the transparency slider means a user can push chrome toward clear, so re-verify that allergy hard-stops, macro/calorie numbers, and any text near the bars stay legible at the clear end, not just the default. The solid-content-layer rule for safety-critical text matters more now, not less.

Pairs with: ios-color-and-materials (material levels + semantic color), ios-components (bar behavior), ios26-hig-patterns (field manual).