Apple Liquid Glass

---
name: apple-liquid-glass
description: Apply the Apple Liquid Glass visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Apple Liquid Glass, mentions Liquid Glass, iOS 26 glass, macOS Tahoe material, or describes refractive lensing (not flat blur), specular edge highlights, adaptive wallpaper-derived tint — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Apple Liquid Glass Design System

Apple's 2025 translucent 'meta-material': controls behave like lenses that refract and reflect the content beneath them rather than merely blurring it. Concentric continuous-curvature capsules float above the canvas, tint themselves from the wallpaper, and flip between light and dark ink based on backdrop luminance.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values are representative interpretations of the aesthetic, not an official spec. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Apple Liquid Glass.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (Liquid Glass, iOS 26 glass, macOS Tahoe material, adaptive glass UI, lensing UI), or describes its traits: refractive lensing (not flat blur); specular edge highlights; adaptive wallpaper-derived tint; continuous-curvature capsules; concentric corner nesting; floating control layer.

## Design tokens

### Color palette

- Neutral wallpaper-derived light base: `#f5f5f7` (--color-bg)
- Glass control fill, 60% white before blur/refraction: `#ffffff99` (--color-surface)
- Glass fill over bright content, 40% ink: `#1d1d1f66` (--color-surface-dark)
- Primary ink on light backdrops: `#1d1d1f` (--color-text)
- Ink when luminance flips dark: `#f5f5f7` (--color-text-inverse)
- Secondary labels: `#6e6e73` (--color-text-muted)
- System-blue tint for active controls; adapts toward wallpaper hue: `#0071e3` (--color-accent)
- Specular light-catching edge, 35% white: `#ffffff59` (--color-border)

### Typography

- Display / headings: Inter (fallback: -apple-system, Helvetica Neue, sans-serif) (ideal: SF Pro Display, premium — use Inter as the free substitute)
- Body: Inter (fallback: -apple-system, Helvetica Neue, sans-serif) (ideal: SF Pro Text, premium — use Inter as the free substitute)
- Type scale: 1.2 ratio, base 17px — computed steps: 17px / 20px / 24px / 29px / 35px / 42px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 700, line-height 1.1, letter-spacing -0.015em
- Body: line-height 1.45, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 20, 28, 44, 64 — Controls are compact capsules, but they float with clear margin from screen edges; padding nests concentrically so inner radii track outer window corners.
- Border radius: control 12px, card 20px, sheet 28px, capsule 999px — Continuous-curvature (squircle) corners throughout; inner radius = outer radius minus inset, keeping every nesting concentric.
- Border treatment: 1px solid rgba(255,255,255,0.35) — Reads as a specular rim, brighter on the light-facing edge; on dark backdrops it drops to ~15% white.

### Shadows

- float: `0 8px 24px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)` — Floating glass controls above content
- sheet: `0 24px 60px rgba(0,0,0,0.2)` — Modal sheets and windows
- specular: `inset 0 1px 0 rgba(255,255,255,0.5)` — Top-edge highlight selling the lens material

### Layout

- Max content width: 1200px
- Two strict layers: content canvas below, floating glass control layer above
- Controls cluster into capsule groups near screen edges
- Corners nest concentrically into the rounded display/window
- Content scrolls edge-to-edge underneath the controls, never around them

### Effects

- backdrop-filter: blur(20px) saturate(180%) as the web approximation of lensing
- SVG displacement or subtle edge distortion to fake refraction
- Specular highlight that shifts with scroll or pointer position
- Adaptive tint sampled from the dominant backdrop color
- Luminance-triggered light/dark ink flip on controls

### Motion

- Easing: cubic-bezier(0.32, 0.72, 0, 1); durations 150ms / 350ms / 550ms
- Controls morph fluidly — capsules stretch and merge rather than crossfade
- Specular highlights track scroll velocity like light on real glass
- Sheets spring up with slight overshoot, settling softly
- All translucency effects collapse to solid fills under Reduce Transparency

## CSS variables (drop-in)

```css
:root {
  --color-bg: #f5f5f7;
  --color-surface: #ffffff99;
  --color-surface-dark: #1d1d1f66;
  --color-text: #1d1d1f;
  --color-text-inverse: #f5f5f7;
  --color-text-muted: #6e6e73;
  --color-accent: #0071e3;
  --color-border: #ffffff59;
  --radius-control: 12px;
  --radius-card: 20px;
  --radius-sheet: 28px;
  --radius-capsule: 999px;
  --shadow-float: 0 8px 24px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08);
  --shadow-sheet: 0 24px 60px rgba(0,0,0,0.2);
  --shadow-specular: inset 0 1px 0 rgba(255,255,255,0.5);
  --border-default: 1px solid rgba(255,255,255,0.35);
  --font-display: Inter, -apple-system, "Helvetica Neue", sans-serif;
  --font-body: Inter, -apple-system, "Helvetica Neue", sans-serif;
  --text-base: 17px;
  --leading-heading: 1.1;
  --leading-body: 1.45;
  --tracking-heading: -0.015em;
  --tracking-body: 0;
  --ease: cubic-bezier(0.32, 0.72, 0, 1);
  --duration-fast: 150ms;
  --duration-base: 350ms;
  --duration-slow: 550ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Floating capsule tab bar detached from the screen edge; glass fill, specular rim, active tab tinted with the adaptive accent; shrinks on scroll
- **Hero:** Full-bleed photographic or gradient canvas with a single glass panel holding the headline; SF-style tight bold type flipping light/dark with the backdrop
- **Card:** 20px squircle glass card, specular top edge, float shadow; content stays high-contrast while decoration lives in the material
- **Button (primary):** Capsule filled with the adaptive accent at full opacity, white 600-weight label — solid on purpose so it reads against any backdrop
- **Button (secondary):** Clear glass capsule, specular rim, adaptive ink label; brightens and slightly swells on press
- **Form fields:** Inset glass well with darker inner fill, capsule or 12px squircle; focus rings with the adaptive accent at 60%

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

A capsule control that visibly bends the content scrolling beneath it — edge distortion plus a moving specular highlight — while its ink color adapts in real time to the luminance of whatever passes behind. Spend boldness here; keep everything else quiet.

## Do

- Keep exactly two planes: canvas below, glass controls above — never stack glass on glass on glass
- Pair every translucent fill with a specular edge and a real shadow; blur alone reads as fog
- Let backdrop luminance drive ink color switching automatically
- Provide a Reduced-Transparency fallback of solid neutral fills from day one

## Don't

- Don't tint the glass with heavy brand color — the material stays neutral and borrows hue from content
- No opaque hairline-border cards mixed into the floating layer; they break the material illusion
- Don't put long-form reading text on translucent surfaces
- Avoid static glass — without motion-reactive highlights it degrades into 2020 glassmorphism

## Accessibility notes

- Accent #0071e3 on the #f5f5f7 base measures ~4.3:1 — below AA for small text; use it for large labels and icons, or darken to #0066cc for fine print
- Contrast over glass is backdrop-dependent by design: every text-on-glass pairing must be tested against worst-case content behind it, and the luminance flip must have hysteresis to avoid flicker
- Honor prefers-reduced-transparency and prefers-reduced-motion with solid fills and static highlights; refraction effects can trigger vestibular discomfort

## Reference sites

- Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines
- Apple Newsroom — Liquid Glass announcement: https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/
- iOS: https://www.apple.com/ios/

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip apple-liquid-glass.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/apple-liquid-glass.json

Settings → Capabilities → Skills → Upload skill → apple-liquid-glass.zip