/axiom-liquid-glass

name: axiom-liquid-glass
description: Apple Liquid Glass design system — comprehensive design philosophy, implementation guide, and technical API reference from WWDC 2025. Covers design principles (iOS-native glass hierarchy, restraint over spectacle), implementation patterns (Regular vs Clear variants, SwiftUI glassEffect API, scroll edge effects, tinting), platform adaptation (iOS 26+, iPadOS 26+, macOS Tahoe+, visionOS 3+), accessibility, performance, testing, design review frameworks, and iOS-native UI redesign guidance.
user-invocable: true
skill_type: discipline
version: 1.2.0
apple_platforms: iOS 26+, iPadOS 26+, macOS Tahoe+, visionOS 3+
domain: design

Liquid Glass — Apple's Design System

When to Use This Skill

• 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
• Redesigning a mobile app UI to feel iOS-native with glass materials
• Understanding Regular vs Clear variants, tinting, legibility
• Conducting design reviews with professional push-back frameworks

---

Part 1: Design Philosophy

Core Principles

• **Native over custom** — Use system components and patterns first
• **Restraint over spectacle** — Glass is a tool for hierarchy, not decoration
• **Material is functional, not decorative** — Improves clarity and depth
• **"Feels obvious" rather than "looks fancy"** — Calm, confident, inevitable
• **Glass complements content** — Lets content shine through

Avoid trendy glassmorphism gimmicks. Glass effects should appear only where they improve clarity and depth. Every screen should feel like it belongs in a first-party Apple app.

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 Material Hierarchy

Use glass materials to express depth and context:

| Material | Use For | Visual Weight | |----------|---------|---------------| | Ultra-thin | Subtle overlays, toolbars, floating controls | Lightest | | Regular | Cards needing gentle separation | Medium | | Thick | Bottom sheets, modals, areas requiring strong readability | Heaviest |

**Rules:**

• Background must remain legible through blur (never "muddy")
• Material opacity and blur should scale with background complexity
• Prefer fewer, larger glass surfaces over many small glass chips

---

Part 2: Visual Properties

1. Lensing (Primary Characteristic)

Liquid Glass defines itself through **lensing** — the warping and bending of light that communicates presence, motion, and form. Unlike previous materials that scattered light, Liquid Glass uses instinctive visual cues from the natural world.

• Dynamically concentrates and shapes light in real-time
• Provides definition against background while feeling visually grounded
• Controls feel ultra-lightweight and transparent while visually distinguishable
• Elements materialize in/out by modulating light bending (not fading)

2. Motion & Fluidity

• **Instant flex and energize** — Responds to interaction by flexing with light
• **Gel-like flexibility** — Communicates transient, malleable nature
• **Temporary lift** — Elements can lift into Liquid Glass on interaction
• **Dynamic morphing** — Continuously shape-shifts between app states
• **Lightweight transitions** — Menus pop open in-line, maintaining relationship to source
• Smooth, natural easing (no playful bounce unless system-like)
• Motion explains hierarchy, not decoration

3. Adaptive Behavior

Liquid Glass **continuously adapts** without fixed light/dark appearance:

• Shadows become more prominent when text scrolls underneath
• Tint and dynamic range shift to ensure legibility
• Independently switches light/dark to feel at home in any context
• Larger elements (menus, sidebars) simulate thicker material
• Ambient environment subtly spills onto surface

---

Part 3: 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)
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 — Use 95% of the Time)

• Most versatile, full visual and adaptive effects
• Provides legibility regardless of context
• Works in any size, over any content

**When to use**: Navigation bars, tab bars, toolbars, buttons, menus, sidebars

NavigationView {
    // Content
}
.glassEffect() // Uses Regular variant by default

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**

ZStack {
    MediaRichBackground()
        .overlay(.black.opacity(0.3)) // Dimming layer
    BoldBrightControl()
        .glassEffect(.clear)
}

**WARNING**: Using Clear without meeting all three conditions results in poor legi