Liquid Glass Framework

A GlassEffectContainer is used to group multiple Liquid Glass shapes into a unified composition. It improves rendering performance by sharing a sampling region and is required for morphing transitions between glass elements.

Critical Rule: Glass cannot sample other glass; the GlassEffectContainer provides the shared sampling region necessary for multiple elements to interact visually.

Use the spacing parameter to control the morphing threshold. Elements within this distance will visually blend and morph together during transitions.

GlassEffectContainer(spacing: 40.0) {
    ForEach(icons) { icon in
        IconView(icon)
            .glassEffect()
    }
}

When to use Liquid Glass

• Use for: Navigation bars, toolbars, tab bars, floating action buttons, sheets, popovers, menus, and system-level alerts.
• Avoid for: Content layers (lists, tables, media), full-screen backgrounds, scrollable content, or stacking multiple glass layers.

Design Guidelines

• Hierarchy: Content is Primary $\rightarrow$ Glass controls are Secondary $\rightarrow$ Overlay fills/vibrancy are Tertiary.
• Contrast: Maintain a minimum 4.5:1 contrast ratio. Use vibrant text on glass and subtle borders for definition.
• Tinting: Use selectively for primary actions to convey meaning, not just decoration.

Glass effects automatically adapt their appearance based on the background color scheme:

• Light/Dark Switching: Glass automatically flips between light and dark modes based on the background (e.g., a black background triggers light glass).
• Element Size Logic:
  • Small elements (nav bars, tab bars): Flip between light/dark.
  • Large elements (sidebars, menus): Adapt appearance without flipping to avoid jarring visual shifts.
• Visual Adjustments: Shadows adjust opacity based on text/background contrast, and tints adjust hue, brightness, and saturation for legibility.

To maintain a clear visual hierarchy, avoid 'Glass-on-Glass' stacking. Instead, follow this layering philosophy:

1. Content layer (bottom): The primary content (lists, tables, media). Do not apply glass here.
2. Navigation layer (middle): Floating elements like tab bars, toolbars, or sidebars. Apply Liquid Glass here.
3. Overlay layer (top): Elements like vibrancy fills or popovers that sit on top of the glass.

Correct Pattern: Use a ZStack to place a single glass layer (like a Header) over a non-glass content layer.

// ✅ GOOD - Clear separation
ZStack {
    ContentView()  // No glass
    HeaderView().glassEffect()  // Single floating layer
}

Follow these best practices to ensure smooth performance and avoid GPU lag or thermal issues:

1. Use GlassEffectContainer: Always wrap multiple glass elements in a single GlassEffectContainer for efficient rendering. Avoid applying .glassEffect() to multiple individual elements in a list or stack without a container.
2. Use .identity for toggling: When conditionally showing glass, use .glassEffect(shouldShowGlass ? .regular : .identity) to avoid layout recalculations.
3. Limit continuous animations: Avoid continuous rotations or infinite linear animations on glass elements; let them rest in steady states.
4. Hardware testing: Monitor performance on older devices (iPhone 11-13) using Instruments to check GPU usage and thermal impact.

Liquid Glass includes automatic system adaptations for accessibility settings. It is recommended to let the system handle these automatically rather than overriding them manually.

Automatic Adaptations

• Reduced Transparency: Increases frosting for better clarity.
• Increased Contrast: Applies starker colors and borders.
• Reduced Motion: Tones down animations and elastic effects.
• iOS 26.1+ Tinted Mode: Respects user-controlled opacity settings.

Manual Control (If necessary)

If you must manually adjust the effect based on accessibility environments, use the following environment values:

@Environment(\.accessibilityReduceTransparency) var reduceTransparency
@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    Text("Accessible")
        .padding()
        .glassEffect(reduceTransparency ? .identity : .regular)
}

To use the Liquid Glass features, ensure your development environment meets the following minimum requirements:

• iOS Version: 26.0+
• Xcode Version: 26.0+

When implementing iOS 26 Liquid Glass, follow these architectural and design principles to ensure usability and performance:

• Layering: Reserve Liquid Glass effects for the navigation layer only.
• Composition: Always use GlassEffectContainer when managing multiple glass elements to ensure proper rendering and coordination.
• Transitions: Use morphing transitions for smooth state changes between different glass configurations.
• Legibility: Prioritize content legibility over visual effects; do not let glass effects obscure text or interactive elements.
• Accessibility: Test extensively with accessibility settings enabled and respect user preferences and system settings.
• Performance: Monitor performance closely, especially on older devices, as glass effects can be resource-intensive.