liquid-glass

name	liquid-glass
description	Build and reuse the "liquid glass" refraction UI in components/grid-wallet-demo (the LiquidGlass / Glass / GlassOver components). Use this skill when the user asks for a glass / liquid-glass / frosted / refraction / squircle UI element — e.g. "make a glass button", "glass tab bar", "glass card", "glass panel", "glass nav", "make this glass", "glass border that expands on hover", "frosted surface", or to tune the glass effect (refraction, chroma, specular, blur, corner smoothing, shadow).
allowed-tools	["Read","Glob","Grep"]

Liquid Glass

Reusable refraction glass for components/grid-wallet-demo. Full docs: components/grid-wallet-demo/src/components/liquid-glass/README.md — read it before implementing anything non-trivial.

The rule that prevents 90% of the pain

The glass refracts its own CHILDREN, not the page behind it. There is no "frost whatever is behind me" mode (backdrop-filter can't refract portably). To bend a background you put a copy of it inside the glass. So:

• Glass over a known backdrop (color / gradient / image / pattern) → use GlassOver, which makes the copy for you.
• Glass over live UI behind a small surface (over a static screen) → achievable: feed the glass a positioned copy of that UI. See "Refract live UI behind a small surface" in the gotchas / README.
• Glass over arbitrary scrolling/animating DOM → not achievable. Tell the user.

Exception: a big frosted surface (sheet/modal) should NOT refract — the per-frame SVG filter tanks Safari. Use FrostPanel (GPU backdrop-filter + a specular edge). Refraction is for the small, tactile elements.

Skipping this gives a flat panel that doesn't lens (the classic failure).

Pick the right entry point

Need	Use
Glass button / tab bar / card / chip over a known bg	GlassOver (easiest)
Refract content you already render, or custom backdrop wiring	Glass (= LiquidGlass)
A big frosted sheet/modal (no refraction — fast on Safari)	FrostPanel (BottomSheet uses it)
A small surface that refracts the (static) screen behind it	GlassOver's backdropNode
A lens over the LIVE aurora that must work on Safari	WebGL: AuroraLensButton (circle) / AuroraLensPanel (rect squircle)
The phone preview's WebGL stage	glass-gl/StageGL — bespoke, don't reuse

SVG vs shader (which renderer): default to the SVG path (Glass / GlassOver) for anything made of live DOM — buttons, tab bars, cards, text, layouts (keeps content selectable/clickable). The shader / WebGL path is only needed when you're refracting content that is not live DOM — a <canvas> drawing (e.g. a generated QR) or a <video> (Safari won't SVG-filter those). There is no auto-switching and no general "glass over a canvas/video" yet: the only WebGL renderer (StageGL) is bespoke to the phone and re-derives the math in GLSL. If a canvas/video glass actually comes up, generalize StageGL (or build a map-fed WebGL glass) on demand — don't assume a drop-in exists.

Minimal usage

import { GlassOver } from '@/components/liquid-glass';

const BG = 'linear-gradient(135deg, #5b9dff, #b07cff)';

<div style={{ background: BG }}>
  <GlassOver backdrop={BG} radius={16} depth={10} scale={18} cornerSmoothing={0.6}>
    <span style={{ display: 'block', padding: '12px 22px', color: '#fff', fontWeight: 600 }}>
      Settings
    </span>
  </GlassOver>
</div>

backdrop = the same CSS background the surface sits on (gets refracted). children = content on top (not refracted). Any GlassConfig field is a prop. Start from a preset (DEFAULT_GLASS, PHONE_SHELL_GLASS) and override. Frosted surfaces (FrostPanel) use the slimmer FrostConfig, not GlassConfig.

Must-know gotchas (details in the README)

• Hover/resize: animate transform: scale(), never width/height/radius — the displacement map re-bakes on shape change (jank).
• Refraction needs texture: over a flat color you only see specular/edge rim.
• Tiny elements: lower depth/scale or they over-distort.
• specularRotation is directional (45° puts a bright highlight on the top-left/bottom-right corners) — rotate or lower edgeStrength to move it.
• corner-shape: squircle is Chromium-only (graceful circular fallback).
• Outer drop shadow → round the wrapper. A glass surface clips itself with overflow: hidden, so an outer box-shadow has to live on a wrapper around the glass (inside, the clip eats it). box-shadow traces that wrapper's own border-radius/corner-shape, not the glass child's — so an unrounded wrapper gives a square halo around round glass. Give the shadow wrapper the same border-radius + corner-shape as the glass (see GlassSymbolButton / GlassWindowButtonGroup .root). Same rule for any border/background painted on a wrapper. Debug heuristic: a square around glass = a rounding-unaware layer.
• Tiled backgrounds: pass GlassOver's backdropOffset={{x,y}} to align.
• Circles & pills auto-lens radially (Aave's production circle/pill model, detected from the geometry — no flag). splay doesn't apply to them; the dome applies to circles only. Don't fight it with per-axis expectations.
• Live/changing content inside a lens is a Safari minefield — stale filter-output caching, composited descendants escaping the lens unfiltered (translateZ(0)/will-change/motion's filter: blur(0px) leftovers), canvas/video killing the filter, and a LAYOUT-bounds source-size ceiling. Read "Safari field notes" in the README before attempting; the full experiment is parked on pat/scroll-refraction-experiment.
• WebKit renders SVG displacement over a copied subtree as EMPTY output at notification size (confirmed June 2026 — see the README's "Confirmed dead end" postmortem). Don't retry it: use the WebGL lenses for Safari refraction and gate the SVG path to Chromium. Squircle-rect corner rules for Safari (map smoothing with cornerRadii, overlay border-radius intersection, one-element frost, no drop-shadow wrappers) are in the same section.
• Verifying a bend over a soft backdrop: displacement is invisible without texture — draw a sharp debug grid through the bent coordinates to check.
• Big sheets/modals don't refract — they frost. A large displacement lens re-runs its whole SVG filter every frame while the surface animates, which tanks Safari (CPU feDisplacementMap). Use FrostPanel (GPU backdrop-filter + a static specular edge); keep refractive Glass/GlassOver for the small buttons on top. Example: apps/shared/BottomSheet (FrostPanel) → aurora/PasskeySheet.
• Refract live UI behind a small surface: pass a copy of the behind-UI as GlassOver's backdropNode, anchored to align, and counter-animate it against any slide so it stays put while the glass slides over it. Behind-UI must be static while open. (Not for big sheets — see above.)

When tuning

There's a live tuning panel: run the demo (npm run dev, port 4000), open the App panel, switch it to swag mode. Sliders map 1:1 to GlassConfig.