# liquid-glass-design

> A Claude Code skill from Affaan M's everything-claude-code repo for implementing Apple's iOS 26 Liquid Glass material in SwiftUI, UIKit, and WidgetKit — covering glassEffect modifiers, GlassEffectContainer for morphing, UIGlassEffect / UIGlassContainerEffect, scroll edge effects, widget accent groups, and the rendering-mode detection for tinted Home Screen.

**Use case**: Apply Liquid Glass material correctly across SwiftUI views, UIKit controls, and widgets without breaking morphing or tinted modes

**Canonical URL**: https://agentcookbooks.com/skills/liquid-glass-design/

**Topics**: claude-code, skills, ios, design

**Trigger phrases**: "iOS 26 Liquid Glass button", "add glass effect to my SwiftUI view", "Liquid Glass widget that handles tinted mode"

**Source**: [Affaan M](https://github.com/affaan-m/everything-claude-code/tree/main/skills/liquid-glass-design)

**License**: MIT

---

## What it does

`liquid-glass-design` is the iOS 26 material skill in [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code) — see [skills/liquid-glass-design](https://github.com/affaan-m/everything-claude-code/tree/main/skills/liquid-glass-design). It covers Apple's Liquid Glass — a dynamic material that blurs content behind it, reflects color from surroundings, and reacts to touch — across SwiftUI, UIKit, and WidgetKit with the modifiers and container types each platform exposes.

The SwiftUI surface is `.glassEffect()` with variants (`.regular`, `.tint(Color)`, `.interactive()`) and shapes (`.capsule`, `.rect(cornerRadius:)`, `.circle`), plus dedicated button styles `.glass` and `.glassProminent`. The skill is explicit that multiple sibling glass views must be wrapped in `GlassEffectContainer(spacing:)` — both for rendering performance and to enable the morphing transitions between glass shapes via `@Namespace` + `glassEffectID(_:in:)`. The `spacing` parameter controls merge distance, so closer elements blend their shapes; `glassEffectUnion(id:namespace:)` combines multiple views into a single glass shape.

UIKit gets the parallel API: `UIGlassEffect` (with `tintColor` and `isInteractive`) wrapped in `UIVisualEffectView`, plus `UIGlassContainerEffect` for the container pattern. Scroll edge effects (`scrollView.topEdgeEffect.style`), toolbar integration (`hidesSharedBackground`), and widget-specific rendering-mode detection (`@Environment(\.widgetRenderingMode)` switches between `.accented` and full color) cover the platform-specific seams. The skill ships explicit anti-patterns: don't use standalone `.glassEffect()` without a container, don't nest glass effects, don't forget `clipsToBounds = true` in UIKit when using corner radii.

## When to use it

- Updating an app for iOS 26+ with toolbars, tab bars, floating buttons, or cards that should adopt Liquid Glass
- Implementing morphing transitions between related UI states (expanding card, toolbar reveal)
- Adding interactive controls that need visual depth — buttons or toggles that should respond to touch with the glass treatment
- Building widgets that need to integrate with the tinted Home Screen appearance (the `.accented` rendering mode case)
- Migrating existing `.ultraThinMaterial` / `UIVisualEffectView(effect: UIBlurEffect)` views to the new API

When *not* to reach for it:

- Pre-iOS-26 deployment targets — the APIs are gated to iOS 26
- Non-Apple platforms (this is Liquid Glass specifically, not a cross-platform glass shader)
- Design systems where you'd rather build a custom material from `Material` + custom blur — the skill is about the system primitive, not bespoke effects

## Install

From [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) at `skills/liquid-glass-design/`. Drop the folder into `~/.claude/skills/liquid-glass-design/`. The skill is markdown; the runtime requires Xcode 26+ and an iOS 26+ deployment target for the Liquid Glass APIs to be available.

## What a session looks like

1. **State the surface.** "Add Liquid Glass to my toolbar with a heart button that highlights when tapped, plus a card sheet that morphs in from the bottom."
2. **Skill picks the right modifier set.** Toolbar uses `.glass` button style + `hidesSharedBackground` opt-out logic; card sheet uses `GlassEffectContainer` + `glassEffectID` + `withAnimation` for the morph.
3. **Wrap siblings in a container.** The skill is explicit that multiple `.glassEffect()` views without a container both degrade rendering and break morphing. The container's `spacing` value gets tuned to control how much the glass shapes blend.
4. **Add the `@Namespace` and `glassEffectID`.** For the morph transition, the from-state and to-state share an ID inside the namespace so the system animates between shapes.
5. **Handle widget rendering mode.** If the surface includes a widget, the `@Environment(\.widgetRenderingMode)` branch covers `.accented` (tinted Home Screen) separately from full color.
6. **Test across appearances.** Light mode, dark mode, accented mode — the skill flags that ignoring the tinted mode is the most common widget bug.

The discipline that makes it work: container-before-modifier. Apple's docs technically allow standalone `.glassEffect()`, but the morphing and rendering-performance benefits only show up inside `GlassEffectContainer` — the skill enforces that as a default rather than an option.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been used in a real iOS 26 app, this section will capture: whether the `GlassEffectContainer` `spacing` value needed tuning to get the desired merge behavior or whether the default landed correctly, the actual frame cost of a 5-view container vs. 5 standalone glass views, how the widget's `.accented` mode reads on a tinted Home Screen vs. the developer's expectation, and whether `clipsToBounds = true` was the bug that broke the UIKit variant on first run._

## Source and attribution

From [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code/tree/main/skills/liquid-glass-design) — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the container rule verbatim: *"Always wrap multiple glass views in a container for performance and morphing."* The container isn't optional — it's where the morphing namespace lives and where the renderer batches the glass passes; standalone `.glassEffect()` views silently lose both benefits.