stormaref Liquid Glass
Glass is two layers, and the CSS one is not the interesting one.
- CSS paints the tint and the rim — a near-transparent white→gray gradient plus three inset highlights that read as a polished edge. This is what most "glassmorphism" snippets stop at.
- Refraction bends the backdrop through the panel's edge, the way real glass does: a displacement map baked per element and consumed as
backdrop-filter: url(#filter). This is what makes it liquid rather than a blurred rectangle.
They ship as a pair — a class and a directive on the same element:
<div class="liquid-glass" appLiquidGlass>…</div>
assets/liquid-glass.css is the CSS layer, self-contained (its own tokens, light and dark).
assets/liquid-glass.directive.ts is the refraction layer for Angular. Any other framework: port it, see references/refraction.md — the port is transcription, not design.
The four rules
Each of these has one failure mode, and in every case the browser shows you something plausible instead of an error.
1. Glass needs a backdrop. Build it first.
Glass shows what is behind it. Behind a flat background there is nothing to show, so the panel renders as a faintly outlined gray box and the effect reads as broken — which sends people reaching for more blur and more opacity, the exact move that kills it.
So the ambient mesh is part of the recipe, not decoration: off-screen radial glows in a few hues (violet / pink / cyan), fixed to the viewport behind the content. Colour that the glass can pick up.
<body class="liquid-glass-backdrop">
Verify this before styling a single panel: the page must look subtly uneven with no glass on it at all.
2. The glass is colorless — the colour arrives from behind.
The tint is white→70%-gray at 6% alpha in both themes. That is deliberate: hue in the tint fights the hue coming through the panel and the surface turns muddy. If a surface must be branded (a primary CTA, a FAB), override the tint locally and leave the rim, the border and the refraction alone:
.my-fab {
/* refraction still comes from the directive */
background: linear-gradient(155deg, rgba(79, 70, 229, 0.55), rgba(67, 56, 202, 0.42));
border: 1px solid rgba(79, 70, 229, 0.5);
}
3. A child of a glass panel paints no surface of its own.
No background, no border, no second radius — the panel already supplies all three. An opaque fill paints over the refracted backdrop, which is the whole effect; a nested border draws a hard edge across the rim. Panels inside a glass dock, rows inside a glass card, a header band inside a glass section: all transparent, separated by spacing and type weight instead.
The cost of getting this wrong is a surface that reads darker and deader than its neighbours, and nothing points at the cause.
4. Refraction is progressive enhancement, and you cannot feature-query it.
backdrop-filter referencing an SVG filter renders in Chromium only. Safari parses it and paints nothing — so @supports reports success and the panel goes blank. Gate on engine (navigator.userAgentData.brands, Chrome/ in the UA), and let everything else keep the stylesheet's plain backdrop-filter: blur(3px) saturate(125%) fallback. The directive already does this; keep it if you port.
Pick the tier
Refraction bakes a canvas displacement map per element size, so it is priced per surface. Match the tier to the element:
| Tier | What it is | Use for |
|---|---|---|
liquid-glass-chip |
tokens + blur(6px), no directive |
chips, pills, badges, anything small or repeated in bulk |
liquid-glass + directive |
the full effect | cards, panels, topbars, circular controls, FABs |
liquid-glass-menu |
blur(22px) + a 55% wash of the overlay surface, no directive |
dropdowns, popovers, context menus |
liquid-glass liquid-glass--modal + directive |
glass with an opaque frost layer over the tint | dialogs |
The menu and modal tiers exist for the same reason: text has to stay readable. A dropdown floats over arbitrary page content and a dialog over a scrim, so both trade some transparency for a wash — a menu through heavy blur, a modal through a theme-flipping frost (white in light, dark in dark). Do not "fix" either back to plain .liquid-glass.
Adding glass to a project
- Copy
assets/liquid-glass.cssin and link it. Confirm the app setsdata-theme="light|dark"on<html>before first paint — the CSS keys both themes off that attribute; the file header carries the boot snippet. - Put
liquid-glass-backdropon the page shell. Stop and look: uneven, colored, no panels yet. - Apply a tier per element. Radius stays on the element (the directive reads the computed
border-radiusto shape the map). - Non-Angular: port the directive per
references/refraction.md. - Walk the checklist below. Every line is a bug someone shipped.
Checklist
- The backdrop is visible with all glass removed.
- No child of a glass panel sets
backgroundorborder. - Both themes valued for every token you added, and both eyeballed — a rim tuned for dark disappears on white.
- Text on glass stays legible over the busiest part of the backdrop, not the calm part you happened to screenshot.
- Non-Chromium (or directive removed): still a decent frosted panel, nothing blank.
- Chips and repeated elements are on the CSS-only tier, not the directive.
- Nothing hardcodes a hex where a token exists.
More variants, hover, and the pitfalls behind each rule: references/recipes.md.