Skip to main content
skill CX Codex

axiom-liquid-glass — Claude Code skill: Apple Liquid Glass for iOS 26+

axiom-liquid-glass — a Claude skill for Apple's Liquid Glass: picking the material variant, wiring SwiftUI glass effects and reviewing a UI before it ships on iOS 26.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill axiom-liquid-glass -a claude-code
Open on GitHub

What axiom-liquid-glass does

The skill covers the glass material Apple showed at WWDC 2025. It walks from the first glassEffect modifier in SwiftUI through a review of a finished screen: where glass earns its place, where it blocks the content underneath, and why a panel suddenly looks muddy.

Inside are the three weights of material (ultra-thin, regular, thick) and one firm rule: glass belongs to the navigation layer, not to content. Stacking it on more glass breaks the hierarchy too. Regular is the safe default for almost everything; Clear is kept for a control over media, with a dimming layer below and bright bold content above. Tint goes on the primary action only.

Targets are iOS 26+, iPadOS 26+, macOS Tahoe+ and visionOS 3+. Standard controls pick up the new look once you build with Xcode 26. Drop the dimming layer under Clear and labels stop being readable.

What it helps with

  • Move an existing screen onto Liquid Glass without a rewrite
  • Decide between Regular and Clear for a given panel
  • Track down artifacts under a translucent toolbar
  • Check a layout against iOS 26 before release
  • Set a tint that holds up over a busy background

Example prompts for the agent

  • Apply Liquid Glass to the tab bar in ContentView.swift, Regular variant, and show me the diff
  • Review SettingsView — where am I stacking glass on glass?
  • Text under my toolbar disappears into the background; is a dimming layer the right fix?

How to install axiom-liquid-glass

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill axiom-liquid-glass -a claude-code

2Manually: put the files in place

~/.claude/skills/axiom-liquid-glass/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/axiom-liquid-glass/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about axiom-liquid-glass

How do I install axiom-liquid-glass in Claude Code?

Run npx skills add coco-research/coco --skill axiom-liquid-glass -a claude-code. The skill file lands at ~/.claude/skills/axiom-liquid-glass/SKILL.md.

What does axiom-liquid-glass do?

It is a discipline skill for Apple Liquid Glass: adding the material, telling Regular from Clear, tinting, scroll edge effects, and reviewing a UI for a native iOS feel.

Which Apple platforms does it target?

iOS 26+, iPadOS 26+, macOS Tahoe+ and visionOS 3+. Standard controls switch to the new material once the app is built with Xcode 26.

Source text

SKILL.md · MIT
---
name: axiom-liquid-glass
description: "Use when implementing, reviewing, or debugging Apple Liquid Glass: iOS 26+ adoption, Regular vs Clear variants, tinting, scroll edge effects, or an iOS-native redesign review."
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

```swift
// 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

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

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

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

### Design Principles & Best Practices

#### Reserve Glass for Navigation Layer

```
[Content Layer — No Glass]
    |
[Navigation Layer — Liquid Glass]
    - Tab bars, Navigation bars, Toolbars, Floating controls
```

#### DO NOT Use on Content Layer

```swift
// WRONG
List(items) { item in
    Text(item.name)
}
.glassEffect() // Competes with navigation, muddy hierarchy
```

#### DO NOT Stack Glass on Glass

```swift
// WRONG
ZStack {
    NavigationBar().glassEffect()
    FloatingButton().glassEffect() // Glass on glass
}

// CORRECT
ZStack {
    NavigationBar().glassEffect()
    FloatingButton()
        .foregroundStyle(.primary) // Use fills, transparency, vibrancy
}
```

#### Avoid Content Intersections in Steady State

Reposition or scale content to maintain separation. Intersections are acceptable during scrolling/transitions.

---

## Part 4: Tinting & Color

### Adaptive Tinting System

1. Selecting color generates range of tones
2. Tones mapped to content brightness underneath
3. Changes hue, brightness, saturation based on background
4. Doesn't deviate too much from intended color

```swift
Button("Primary Action") { }
    .tint(.red)
    .glassEffect()
```

### Tinting Rules

- **DO**: Use tinting for primary actions only
- **DON'T**: Tint everything (when everything is tinted, nothing stands out)
- **DON'T**: Use solid fills on glass elements (breaks visual character)
- Use color in content layer instead, reserve tinting for primary UI actions

```swift
// WRONG - Solid fill breaks glass character
Button("Action") {}
    .background(.red) // Opaque

// CORRECT - Transparent, grounded
Button("Action") {}
    .tint(.red)
    .glassEffect()
```

---

## Part 5: Scroll Edge Effects

Work in concert with Liquid Glass to maintain separation with scrolling content.

- Content scrolling -> effect gently dissolves content into background
- Lifts glass visually above moving content
- Darker content triggers dark style for contrast

### Hard Style Effect

Use when pinned accessory views exist:

```swift
ScrollView { }
    .scrollEdgeEffect(.hard)
```

---

## Part 6: Layout & Component Patterns

### Typography
- System-first typography (SF Pro style)
- Clear hierarchy using size & weight, not color
- Prefer semantic text styles (Title / Headline / Body / Caption)

### Color
- Neutral palette by default (white, off-white, system grays)
- Accent colors used sparingly (1 primary accent max)
- Avoid neon, high saturation blocks, heavy gradients

### Buttons
- Prefer system button semantics
- Glass button usage: only for floating contexts (toolbar, overlay)
- Press state: slight opacity down + subtle scale, never flashy

### Lists
- iOS list rhythm (consistent row height, predictable spacing)
- Glass behind lists: only if list is within a sheet/overlay
- Ensure text contrast and scannability remain high

### Navigation
- Standard navigation bars with large titles when appropriate
- Translucent nav bar when content scrolls under it
- Preserve clear title hierarchy and scroll behavior

### Modals & Sheets
- Bottom sheets preferred, respect drag-to-dismiss
- Regular/Thick material based on background complexity
- Avoid full-screen modal unless task truly demands it

### Layout Principles
- iOS-native layout patterns, safe-area aware
- Comfortable touch targets (44pt+)
- Use whitespace and grouping as main separators
- Cards should feel light and system-like

---

## Part 7: Layered System Architecture

### 1. Highlights Layer
- Light sources produce highlights responding to geometry
- Lights move during interactions, defining silhouette
- Some respond to device motion

### 2. Shadows Layer
- Aware of background content
- Increases shadow opacity over text for separation
- Lowers shadow opacity over solid light backgrounds

### 3. Internal Glow (Interaction Feedback)
- Illuminates from within on interaction
- Glow starts under fingertips, spreads throughout
- Spreads to nearby Liquid Glass elements

### 4. Adaptive Tinting Layer
- Multiple layers adapt together
- Windows losing focus visually recede (Mac/iPad)

---

## Part 8: Accessibility

Liquid Glass offers accessibility features that modify material **without sacrificing its magic**:

| Feature | Effect | Developer Action |
|---------|--------|-----------------|
| Reduced Transparency | Makes glass frostier, obscures more | Automatic |
| Increased Contrast | Elements predominantly black/white with contrasting border | Automatic |
| Reduced Motion | Decreases intensity, disables elastic properties | Automatic |

**No developer action required** — all features apply automatically when using Liquid Glass.

---

## Part 9: Performance Considerations

### View Hierarchy
- Regular variant optimized for performance
- Avoid excessive nesting of glass elements
- Flatten hierarchy when possible

```swift
// WRONG - Deep nesting
ZStack {
    GlassContainer1().glassEffect()
    ZStack {
        GlassContainer2().glassEffect()
    }
}

// CORRECT - Flat hierarchy
VStack {
    GlassContainer1().glassEffect()
    GlassContainer2().glassEffect()
}
```

### Rendering Costs
- Don't animate Liquid Glass elements unnecessarily
- Use Clear variant sparingly (requires dimming layer computation)
- Profile with Instruments if experiencing performance issues

---

## Part 10: Testing

### Visual Regression Testing

```swift
func testLiquidGlassAppearance() {
    let app = XCUIApplication()
    app.launch()

    // Test light mode
    XCTContext.runActivity(named: "Light Mode Glass") { _ in
        let screenshot = app.screenshot()
    }

    // Test dark mode
    app.launchArguments = ["-UIUserInterfaceStyle", "dark"]
    app.launch()
    XCTContext.runActivity(named: "Dark Mode Glass") { _ in
        let screenshot = app.screenshot()
    }
}
```

### Critical Test Cases
- Light mode vs dark mode
- Reduced Transparency / Increased Contrast / Reduced Motion enabled
- Dynamic Type (larger text sizes)
- Content scrolling (verify scroll edge effects)
- Right-to-left languages

### Accessibility Testing

```swift
func testLiquidGlassAccessibility() {
    app.launchArguments += [
        "-UIAccessibilityIsReduceTransparencyEnabled", "1",
        "-UIAccessibilityButtonShapesEnabled", "1",
        "-UIAccessibilityIsReduceMotionEnabled", "1"
    ]
    XCTAssertTrue(glassElement.exists)
    XCTAssertTrue(glassElement.isHittable)
}
```

---

## Part 11: Design Review & Push-Back Framework

### Red Flags — Requests That Violate Guidelines

If you hear ANY of these, **STOP and reference the skill**:

- "Use Clear everywhere" — Clear requires three specific conditions
- "Glass looks better than fills" — Correct layer trumps aesthetics
- "Stack glass on glass for consistency" — Explicitly prohibited
- "Apply glass to Lists for sophistication" — Lists are content layer

### How to Push Back Professionally

**Step 1: Show the Framework**
```
"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) vs Regular (legible).

**Step 3: Offer Compromise**
```
"Clear works beautifully in these 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, send written documentation of the decision and monitoring plan.

---

## Part 12: Expert Review Checklist

### 1. Material Appropriateness
- [ ] Glass used only on navigation layer (not content)?
- [ ] Standard controls get glass automatically via Xcode 26 recompile?
- [ ] No glass-on-glass situations?

### 2. Variant Selection
- [ ] Regular variant used for most cases?
- [ ] Clear variant meets all three conditions where used?
- [ ] Regular and Clear never mixed in same interface?

### 3. Legibility & Contrast
- [ ] Primary actions selectively tinted (not everything)?
- [ ] Solid fills avoided on glass elements?
- [ ] Elements maintain legibility on various backgrounds?

### 4. Layering & Hierarchy
- [ ] Content intersections avoided in steady states?
- [ ] Elements on top of glass use fills/transparency (not glass)?
- [ ] Visual hierarchy clear (navigation vs content layer)?

### 5. Scroll Edge Effects
- [ ] Applied where glass meets scrolling content?
- [ ] Hard style used for pinned accessory views?

### 6. Accessibility
- [ ] Works with Reduced Transparency, Increased Contrast, Reduced Motion?
- [ ] Interactive elements hittable in all configurations?

### 7. Performance
- [ ] View hierarchy reasonably flat?
- [ ] Glass elements animated only when necessary?
- [ ] Clear variant used sparingly?

---

## Part 13: API Reference

### SwiftUI Modifiers

#### `glassEffect(in:isInteractive:)`

```swift
func glassEffect<S: Shape>(
    in shape: S = Capsule(),
    isInteractive: Bool = false
) -> some View
```

#### `glassEffect(_:in:isInteractive:)`

```swift
func glassEffect<S: Shape>(
    _ variant: GlassVariant,  // .regular or .clear
    in shape: S = Capsule(),
    isInteractive: Bool = false
) -> some View
```

#### `scrollEdgeEffect(_:)`

```swift
func scrollEdgeEffect(_ style: ScrollEdgeStyle) -> some View
// styles: .automatic, .soft, .hard
```

#### `scrollEdgeEffectStyle(_:for:)` (NEW in iOS 26)

```swift
func scrollEdgeEffectStyle(_ style: ScrollEdgeStyle, for edges: Edge.Set) -> some View
```

#### `glassBackgroundEffect()` (NEW in iOS 26)

Apply glass effect to custom views for reflecting surrounding content.

```swift
CustomPhotoGrid()
    .glassBackgroundEffect()
```

#### `GlassEffectContainer` (NEW in iOS 26)

Container for combining multiple Liquid Glass effects with optimized rendering.

```swift
GlassEffectContainer {
    HStack {
        Button("Action 1") { }.glassEffect()
        Button("Action 2") { }.glassEffect()
    }
}
```

Benefits: Optimizes rendering, fluid morphing between glass shapes, reduced compositor overhead.

### Toolbar Modifiers (NEW in iOS 26)

#### `Spacer(.fixed)` in Toolbars

Separates toolbar button groups with fixed spacing.

#### `.buttonStyle(.borderedProminent)` + `.tint()` in Toolbars

Makes toolbar items prominent with Liquid Glass tinting.

### Navigation & Search (NEW in iOS 26)

- **Bottom-aligned search** on iPhone (automatic with `.searchable()`)
- **Search tab role** with `.tabRole(.search)` — morphs into search field
- **Tab bar minimization** with `.tabBarMinimizationBehavior(.onScrollDown)`

### Types

```swift
enum GlassVariant {
    case regular  // Default - full adaptive behavior
    case clear    // More transparent, no adaptation
}

enum ScrollEdgeStyle {
    case automatic  // System determines
    case soft       // Gradual fade
    case hard       // Uniform across toolbar height
}
```

---

## Part 14: Backward Compatibility

### UIDesignRequiresCompatibility Key (NEW in iOS 26)

Add to Info.plist to maintain iOS 18 appearance while building with iOS 26 SDK:

```xml
<key>UIDesignRequiresCompatibility</key>
<true/>
```

**Migration strategy:**
1. Ship with key enabled
2. Audit interface changes in separate build
3. Update interface incrementally
4. Remove key when ready for Liquid Glass

---

## Output Requirements (For UI Redesigns)

For each redesigned screen, provide:

1. **Design intent** — What feels more iOS-native and why
2. **Layout structure** — Regions, spacing, safe-area decisions
3. **Material map** — Where glass is used, which thickness, and why
4. **Typography map** — Text styles and hierarchy rationale
5. **Interaction & motion notes** — Scroll, transitions, gestures
6. **iOS-native justification** — System defaults, familiarity, clarity

---

## Absolute Avoid List

- Over-designed custom components
- Glass everywhere (blanket translucency)
- Trendy gimmicks (neon, glow, heavy gradients, fake reflections)
- Harsh borders or outlines
- Dense, cluttered information layouts
- Non-standard navigation patterns
- Solid opaque fills on glass elements

---

## Resources

**WWDC**: 2025-219, 2025-323, 2025-256
**Docs**: /technologyoverviews/adopting-liquid-glass, /swiftui/landmarks-building-an-app-with-liquid-glass, /swiftui/applying-liquid-glass-to-custom-views
**Related Skills**: axiom-liquid-glass-ref, swiftui-liquid-glass
**Platforms:** iOS 26+, iPadOS 26+, macOS Tahoe, visionOS 3
**Xcode:** 26+

© coco-research · MIT · coco-research/coco

Similar skills

All skills for Design →

From the same set82

The whole set →
figma Imports Figma assets, brand tokens, and components into HyperFrames compositions, freezing media locally for deterministic rendering. CX Codex +1 ★ 328repo stars 3d-camera-flight The 3d-camera-flight rule describes a perspective camera moving through a 3D scene, from a dive into a grid to a focused landing. Use it for interfaces built around depth, parallax, and camera travel. CX Codex +1 ★ 328repo stars ai-product ai-product guides building production AI features: structured schema validation, streaming UI patterns, prompt regression testing, and RAG pipelines. CX Codex +1 ★ 328repo stars OpenAI Apps MCP OpenAI Apps MCP is a Claude Code skill for building ChatGPT apps with MCP servers on Cloudflare Workers, tools, and HTML widgets. It covers CORS and widget-loading issues. CX Codex +1 ★ 328repo stars general-video general-video — a skill for authoring and editing video through HyperFrames compositions: multi-scene pieces, promos, montages, static loops, and footage remixes. CX Codex +1 ★ 328repo stars _index _index routes /team calls across a four-layer cross-functional workflow covering research, coding, testing, verification, and shipping. CX Codex +1 ★ 328repo stars officecli Creates, inspects, and modifies .docx, .xlsx, and .pptx documents via the officecli binary without requiring an installed Office suite. CX Codex +1 ★ 328repo stars faceless-explainer Turns an article, notes, or a topic brief into a faceless explainer video project with a script, storyboard, and scene visuals. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open