---
name: liquid_glass_ui
description: Designs and builds Apple-style Liquid Glass UI: the material spec (layer stack, Regular vs Clear variants), layering rules (navigation layer only, never glass on glass), and CSS/SwiftUI recipes for frosted nav bars, floating controls, and press glow. Use when someone asks for Liquid Glass, glassmorphism with real Apple semantics, glass nav bars or controls, or wants to convert a card-everywhere blur design into correct Liquid Glass usage.
---

# Liquid Glass UI

## Purpose

Turn a Liquid Glass design request into something that would survive Apple's Human Interface Guidelines and still read as glass on the web. Apple's material is a native, GPU-rendered lens: it bends light, carries specular highlights, and adapts to what sits behind it. On the web we reproduce it as a baseline frosted material plus progressive enhancements, and we never let the fancy layers carry legibility.

## Workflow

1. **Decide if glass applies.** Read `references/material-specs.md` first. Glass is for the navigation/control layer only: tab bars, toolbars, floating action clusters, sheets' action bars, controls. If the request is "glass cards in the content area", that is glassmorphism, not Liquid Glass. Say so, then either convert it (move glass to controls) or fall back to the static frosted-pane variant and record the override.
2. **Pick the variant.** Regular unless all three hold: media-rich content underneath, a dimming layer is acceptable, and bold bright content sits above. Only then Clear. Never mix both in one interface.
3. **Apply the layer stack.** Build in this order: blur + luminosity adaptation, optional tint (primary actions only), specular rim light from one consistent light angle, adaptive shadow, interactive press glow. Refraction is a Chromium-only enhancement on web (SVG filters in `backdrop-filter` don't work in Safari/Firefox), never load-bearing.
4. **Check the rules before shipping.** Never glass on glass (items on glass get fills/vibrancy, toolbar items share one glass background). Use sparingly. Strip custom backgrounds/borders/darkening overlays from under bars. One scroll edge effect per view edge, only where floating UI exists. Radius: capsule for phone-scale controls (half the element height), parent-radius-minus-padding for nested containers.
5. **Verify contrast.** Run the tint check: `python3 bin/glass-contrast.py --fill "#RRGGBBAA" --text "#RRGGBB" --backdrop "#F4F6FA"`. Target 4.5:1 or better for text over glass. The recipe file documents one measured-passing fill (#0A3FC9 at 84%, 5.87:1 with white text over pale backdrop); anything you substitute gets measured, never eyeballed.
6. **Test in two engines.** The design baseline is what Safari/Firefox render (frost + rim + fill, no refraction). Chromium gets refraction on top. Check both before claiming it works. Add the Reduce Transparency / Increase Contrast fallback: drop to an opaque fill.
7. **QA the render.** Open a fixture page with real content behind the glass (text, images, saturated color), screenshot it, and read it: legible text, no content half-trapped under glass in the resting layout, press glow emanating from the touch point, nothing flickering or stacking into a grey box.

## Output Contract

- A `material-specs.md` summary of which rules were applied and where each glass element sits (layer + variant).
- Production CSS (or SwiftUI) implementing exactly the layer stack, with the Chromium-only refraction isolated behind a feature check so Safari/Firefox get the designed baseline.
- A contrast report: measured ratio for each glass-plus-text pairing.
- Screenshots from two rendering engines showing the resting state and the pressed state.
- Plain-language note of what is native-accurate, what is approximated, and what falls back.

## Operating Rules

1. Glass lives in the navigation layer, never the content layer. Transient in-content controls (slider knobs, toggle knobs) go glassy only while being manipulated.
2. No glass on glass, ever. Items placed on a glass surface use fills, transparency, and vibrancy. Grouped toolbar items share one glass background.
3. Regular and Clear variants never appear in the same interface. Tint only to emphasize primary actions: when every element is tinted, nothing stands out.
4. Sparingly means sparingly: limit custom glass to the most important functional elements. The system picks up its own.
5. Refraction, morphing, and press glow are progressive enhancement. Legibility and brand must survive with only the frost layer.
6. Every number, radius, and ratio in the skill is measured or sourced, never invented. If a claim can't be verified against Apple's docs or a real render, cut it or label it as approximation.
7. Accessibility: honor Reduce Transparency (opaque fill) and Increase Contrast. Keep tap targets at 44pt/44px minimum on touch; don't shrink controls to chase the look.
8. Respect the trademark: "Liquid Glass" is Apple's term. Use it descriptively in prose, never in identifiers, class names, or package names.