| name | apple-liquid-glass |
|---|---|
| description | Apple's Liquid Glass design language (iOS 26 / macOS 26 HIG) made buildable on any platform: the content/chrome two-layer model, regular vs clear glass, real refraction (content bending at the rim), the rim light, type scales, system colours, component shapes, and Reduce Motion/Transparency/Increase Contrast fallbacks. Ships a CSS token file and a refraction script for the web, plus routes for SwiftUI/UIKit, Android Compose (Haze), Flutter, Electron, Tauri, Windows and Linux. Use when building or reviewing any UI that should look Apple-made or "liquid glass": "iOS style", "macOS style", "Liquid Glass", "glassmorphism", "frosted glass", "refraction", SF Pro typography, "Apple gibi görünsün", "cam efekti", "buzlu cam", "kırılma efekti", or when an Apple-style UI looks fake. Not for app flows, navigation or screen specs (use `mobile-ux-designer`). |
Apple Liquid Glass — the design language, on any platform
Scope: any interface that should carry Apple's Liquid Glass look — a web page, a web app, an Electron or Tauri desktop app, an Android or Flutter app, or a native Apple app. The design rules below are the same everywhere; only the way you get the backdrop, the blur and the bend differs. Pick the route first:
| Building for | Route |
|---|---|
| Web, Electron, Tauri, WebView | assets/tokens.css + assets/refraction.js (this file and the references) |
| iOS, iPadOS, macOS 26+ native | the system material: SwiftUI glassEffect, UIKit UIGlassEffect — never a fake |
| Android (Compose) | Haze haze-glass recipe |
| Flutter | BackdropFilter + ImageFilter.shader |
| Windows / Linux native | draw it in-app; window materials (Mica, Acrylic) are not Liquid Glass |
Per-platform code, version limits and fallbacks: references/platforms.md.
For app flows, navigation and screen specs use mobile-ux-designer.
This skill exists so you never have to re-derive Apple's design language from scratch. Everything here was read off Apple's own Human Interface Guidelines and its figures, not from memory or from blog posts about Apple. Where Apple does not actually state something, this skill says so rather than inventing a rule — that honesty is the point, because most "Apple-style" work fails by confidently applying invented rules.
The one idea everything else follows from
Apple's interface is two layers, and the entire language is about keeping them distinct:
- The content layer — what the app is actually about. Opaque. Solid surfaces, real shadows, no glass. Text lives here and must never sit on a moving background.
- The functional layer — toolbars, sidebars, tab bars, popovers, menus, floating controls. This is where Liquid Glass lives. It floats above the content, refracts it, and never competes with it.
Apple states this directly: "Don't use Liquid Glass in the content layer… including it in the content layer can result in unnecessary complexity and a confusing visual hierarchy."
If you take one thing: glass on chrome, never on cards. The single most common failure of "Apple-style" work is frosting everything, which destroys the hierarchy the material exists to create.
Output
Give the user what they asked for — a fixed page, a diagnosis, a component — at the length and in the format they asked for. Don't pad a fix with an unrequested design-philosophy writeup, and don't skip real requirements to stay brief: verify contrast, tap-target size, and the fallbacks below even when not asked, because a result that looks right but fails them is exactly the "fake Apple" outcome this skill exists to prevent.
The 2026 refinement matters too. Apple's macOS 27 Golden Gate page (apple.com/os/macos, checked 2026-09-27): "Updates to Liquid Glass ensure exceptional readability with more uniform refraction and improved contrast." It also lists uniform toolbars, edge-to-edge sidebars, and updated window shapes. So: heavier tint, visible refraction rim, one continuous bar rather than floating islands. If you build the thin, barely-there glass of the first release, you are building the version Apple already corrected.
Start from the tokens (web)
assets/tokens.css is a working token layer — light and dark palettes, the
glass primitive with its refraction rim, the scroll edge effect, and fallbacks
for reduced transparency, reduced motion, and no backdrop-filter support at
all. Start from it instead of hand-rolling values, but verify it against the
actual brief rather than pasting it in unread: check it still meets the
contrast and tap-target rules below in your context, and adapt values (colours
especially — Apple restates it may change them release to release) rather than
citing the file as unquestionable ground truth.
Two things in it are worth understanding rather than just using:
The glass primitive is a tinted translucent background + backdrop-filter: saturate(180%) blur(28px) + an inset top highlight. The highlight is what reads
as bent light; without it the surface looks like plain transparency, which is
the tell of glassmorphism-by-imitation. Apple's own material figures show a
distinct bright rim tracing the edge.
The rim (.glass::before) is a 1px gradient ring, brightest upper-left,
faint along the sides, brighter again lower-right. A uniform white border reads
as a sticker; the uneven rim reads as a thick bevel catching light.
The ambient ground. Glass needs something behind it to refract or it renders as flat grey. A subtle multi-stop gradient on the page background gives the material something to do. Apple gets this free from wallpapers and photos; on the web you have to supply it.
Refraction: the part blur cannot fake
Apple: "This translucent material reflects and refracts its surroundings." Zoom into any of Apple's own images and the text or shapes that reach the edge of a glass control bend and stretch along its outline, while the middle stays clear. This is what separates Liquid Glass from 2020-era glassmorphism, and it is the first thing users miss when it is absent. Build it in by default for glass controls; don't wait to be asked.
- Mechanism (all platforms): inside a rim band, show the content from further inward, strongest at the outline, following the real shape (capsule ends, rounded corners).
- Web: add
data-refractto a glass element and loadassets/refraction.js. In Chromium engines (Chrome, Edge, Android WebView, Electron, Tauri on Windows) it bends the live backdrop. Safari and Firefox can't runurl()filters inbackdrop-filter, so for glass over a known area adddata-refract-source="#id": the script bends a copy of that area instead, in every browser. Glass with neither keeps plain blur. Always give hero and demo glass a source, or most visitors (Safari, Firefox) see no bend at all. - Clear glass is where text visibly curves (little blur); on regular glass the bend shows in the blurred picture's shapes and colour edges.
- Bending glass gets a lighter tint (
--glass-refract) so the bend shows. Glass that carries words — menus, popovers, sheets, sidebars — adds.glass-textto keep the full tint; otherwise its labels can drop below contrast over bright content. - Off under Reduce Transparency, never animated under Reduce Motion.
- Check it: put the control over a line of text and screenshot. Letters at the rim curve and stretch; the middle stays readable.
Values, tuning table and the test method: references/materials.md
("Refraction and the rim"). Android, Flutter and native routes:
references/platforms.md.
Non-negotiables
These are the rules that, when broken, make the result read as not-Apple.
- Glass only in the functional layer. Content cards get opaque surfaces and shadows.
- Colour is rationed. Apple: "Apply color sparingly to the Liquid Glass material… reserve it for elements that truly benefit from emphasis, such as status indicators or primary actions." Their figure shows a toolbar with three tinted buttons marked incorrect, and the same toolbar with only the primary action tinted marked correct. One coloured thing per bar.
- Emphasis goes on the background, not the glyph. "To emphasize primary actions, apply color to the background rather than to symbols or text." The exception is a selected tab: there Apple colours the icon and label and leaves the bar neutral.
- Hairlines, not borders. Separators are 0.5px at ~12% opacity, and in lists they inset past the leading icon. A 1px solid grey border is a web idiom, not an Apple one.
- No light font weights. Apple: "prefer Regular, Medium, Semibold, or Bold font weights, and avoid Ultralight, Thin, and Light."
- Sentence case, not uppercase-with-tracking. Uppercase micro-labels with wide letter-spacing are a dashboard/editorial idiom. Apple's section headers are sentence case and rely on weight and colour.
- Hierarchy from size, weight and colour — never from rules and boxes. Headings are not underlined and sections are not fenced. Apple's own Mail figure builds four levels purely from those three variables.
- Icons are all-or-nothing within a group. Apple's menu rule: "either every item in a group has an icon, or none do." Half-iconed lists look unfinished.
- Every custom control needs a press state. Apple calls this out explicitly — without it a control "can feel unresponsive."
- Content extends under the chrome. Use the scroll edge effect so content dissolves as it passes beneath a bar, and extend the background beneath sidebars (see below). Content that stops dead at a sidebar edge is the thing Apple's own incorrect/correct figure pair is about.
- Every
backdrop-filteruse needs an@supports not (...)opaque fallback, separate from the reduced-transparency media query — one handles missing browser support, the other a user setting. Skipping it is a common, easy-to-miss bug: the bar silently renders too-transparent with no blur. - Glass bends and has a rim. A glass control with a uniform 1px white border and no refraction is glassmorphism, not Liquid Glass. Use the rim gradient and refraction wherever the platform allows, and a clean blur fallback where it doesn't.
- Hit targets are at least 44×44pt on iOS (macOS is denser but still needs a comfortable click target). Destructive actions (delete, remove account) get the destructive/red role, never a neutral one.
Type
Apple's scale is not decorative — it is a fixed ladder, and staying on it is most of what makes typography feel native. The iOS default (Large) styles:
| Style | Weight | Size | Leading |
|---|---|---|---|
| Large Title | Regular | 34 | 41 |
| Title 1 | Regular | 28 | 34 |
| Title 2 | Regular | 22 | 28 |
| Title 3 | Regular | 20 | 25 |
| Headline | Semibold | 17 | 22 |
| Body | Regular | 17 | 22 |
| Callout | Regular | 16 | 21 |
| Subhead | Regular | 15 | 20 |
| Footnote | Regular | 13 | 18 |
| Caption 1 | Regular | 12 | 16 |
| Caption 2 | Regular | 11 | 13 |
macOS runs a tighter ladder (Body 13/16, Large Title 26/32) and its Headline is Bold rather than Semibold. A desktop-first web layout usually wants something between the two: iOS sizes for headings and reading text, macOS density for sidebars and metadata.
Minimums are real: iOS 11pt, macOS 10pt. Below that Apple considers text illegible, and web pixels are smaller than points, so treat ~11px as your floor.
Font stack: -apple-system, BlinkMacSystemFont, 'SF Pro Text', … gives real SF
on Apple hardware. Everywhere else you need a fallback — Inter is the closest
widely available substitute. Never link SF from a CDN; it is not licensed for
that.
Apple's tracking is optically compensated per size: loose below 12pt, zero at
exactly 12pt, tightest around 19–20pt (≈ −0.45pt), then positive from about
24pt (+0.40pt at 29–34pt) before decaying to zero at display sizes. The system
font applies this itself on Apple hardware. The web values in the token file
(-0.022em headings, -0.012em body, 0 captions) are a web convention that
keeps fallback fonts such as Inter from looking loose — not a conversion of
Apple's table, so don't cite them as Apple's.
Full tables, the tracking curve, and SF Symbols weight/scale pairing:
references/typography.md.
Colour
Apple ships exact values, but also says "Avoid hard-coding system color values… The actual color values may fluctuate from release to release." So use them as anchors, not gospel.
The semantic set is more useful than the palette: label /secondaryLabel /
tertiaryLabel / quaternaryLabel for text, separator for hairlines, and two
background families — system and grouped — each with primary / secondary /
tertiary. Grouped is the one to reach for when content sits in cards: the page
takes the grouped background (a light grey) and the cards take white. That
inversion of the web default — grey page, white cards — is a large part of why
Apple layouts read as Apple.
Dark mode is not an inversion. Apple uses base and elevated surfaces: near-black for the receding backmost layer, a distinctly lighter charcoal for anything that should read as raised. Painting everything pure black is wrong, and Apple's own figure pair demonstrates it.
Contrast minimums, stated by Apple: 4.5:1 up to 17pt, 3:1 at 18pt and above, 3:1 for bold at any size.
Exact RGB values for every system colour across light, dark, and both
increased-contrast variants, plus the full semantic list for iOS and macOS:
references/color.md.
Material
Two variants, and choosing wrong is visible:
- Regular — blurs and adjusts the luminosity of what is behind it. Almost everything uses this. In Apple's figures it is close to opaque; the background reads as soft colour, not as a picture.
- Clear — highly translucent, for controls floating over photos and video where the media must stay prominent. If the content behind is bright, Apple specifies a dark dimming layer at 35% opacity underneath so the labels survive.
The material also adapts: on light content the glass and its symbols go dark, on dark content they go light. On the web that means your glass tokens need genuinely different values per theme, not one value with a different opacity.
Recipes, the four standard materials, and vibrancy levels:
references/materials.md.
Components
Component shapes carry a lot of the signal. The short version:
- Toolbar — one uniform bar, monochromatic, actions as circular or capsule chips, related actions grouped into a shared capsule. Title (and optional subtitle) can live in it.
- Sidebar — edge-to-edge, glass, SF-Symbol icons tinted with the accent, rounded selection fill on the active row, no chevrons. Extend the content's background beneath it (blurred and mirrored) instead of drawing a border.
- Tab bar — floating capsule; only the selected item is tinted, and the tint goes on its icon and label, not on the bar.
- Lists — inset grouped: a rounded container, rows inside it, hairlines inset past the leading thumbnail, a chevron only when the row navigates.
- Segmented control — equal-width segments in a filled track, the selected segment a raised light thumb. Five to seven segments maximum, about five on phone widths.
- Popover — an outer glass card containing nested opaque groups, with a pointer aimed at whatever opened it. One popover at a time, never stacked.
Every component's rules, limits, and what its figures show:
references/components.md.
Motion and accessibility
Apple names no universal easing curve in the HIG, so don't claim one. What it
does say: motion must be purposeful, brief, precise, cancellable, and it should
track the user's gesture. In practice cubic-bezier(0.22, 1, 0.36, 1) around
200–320ms reads correctly for interface movement, and a slightly springier
cubic-bezier(0.32, 0.72, 0, 1) suits a segmented-control thumb — but present
those as sensible choices, not as Apple's specification.
Three system settings change what you render, and honouring them is part of the language rather than an extra:
- Reduce Motion — tighten springs, replace axis transitions with fades, don't animate z-depth, and don't animate into or out of blurs. That last one directly constrains glass transitions.
- Reduce Transparency — swap the material for an opaque fill. Apple doesn't
spell this out for Liquid Glass specifically, but every translucent surface
needs the fallback;
@media (prefers-reduced-transparency: reduce)is in the token file. - Increase Contrast — Apple ships genuinely different colour values, and flips glyph colours where needed. Not a filter.
Details and the full rule lists: references/motion-accessibility.md.
Before you call it done
Run through this. Each item is a mistake that has actually shipped in work claiming to be Apple-style:
- Is anything in the content layer frosted? Un-frost it.
- Count the coloured elements in each bar. More than one? Cut back.
- Any uppercase letter-spaced micro-labels? Convert to sentence case.
- Any 1px solid borders where a 0.5px hairline belongs?
- Any font weight below Regular?
- Does the smallest text clear ~11px?
- Does content pass under the toolbar with a scroll edge effect, or stop at it?
- Does the sidebar have a hard edge instead of an extended background?
- Do rows in one group disagree about having icons?
- Does every control have a press state?
- In dark mode, is everything pure black, or are base and elevated distinct?
- Does text passing under a glass control bend at the rim in Chrome and in
Firefox or Safari (needs
data-refract-sourcethere), on Android 13+ and native Apple? Does the rim have its upper-left highlight? - Where bending is unavailable (Safari, Firefox, old Android), does the glass still look finished as plain blur glass?
- Does the page still work with reduced transparency and reduced motion, and
with no
backdrop-filtersupport at all (@supportsfallback)? - Is every tap target at least 44×44pt, and is every destructive action styled as destructive?
Provenance and honest gaps
Sourced from developer.apple.com/design/human-interface-guidelines (Materials, Color, Typography, Layout, Toolbars, Sidebars, Tab bars, Lists and tables, Buttons, Popovers, Menus, Sheets, Motion, Accessibility, Feedback, Dark Mode) and the Adopting Liquid Glass technology overview, including the figures on those pages. Change-log dates seen: Color December 2025, Materials September 2025, Sidebars June 2026, Typography December 2025. Type ladders, tracking, system/gray colour values, the 35% dimming layer, and the contrast table were re-checked against the HIG data on 2026-09-27.
Refraction and platform material: Apple newsroom, June 2025 ("reflects and
refracts its surroundings"); SwiftUI glassEffect/Glass and UIKit
UIGlassEffect documentation; Haze 2.0.1 as used in a shipped Android app;
Flutter ImageFilter.shader API docs; Electron BrowserWindow docs; the
tauri-apps/window-vibrancy README. Browser behaviour of refraction.js
checked in Chromium and Firefox on 2026-10-12. Reference implementations:
examples/.
Known gaps — do not fill these with invention:
- There is no published arithmetic formula for concentric corner radii.
Apple says the hardware's shape informs the curvature of nested elements and
ships
ConcentricRectangleandcornerConfiguration, but states no inner-equals-outer-minus-padding rule. Nesting radii so the gap stays visually even is a sound derived convention; present it as your own reasoning. - Apple publishes no pixel spec for press states, no toolbar height, and no standard spacing scale — only "prefer standard spacing metrics."
- No named easing preset appears in the HIG text.
- Apple publishes no refraction numbers (rim width, displacement, index). The values in this skill are tuned by eye against Apple's images and a shipped app; present them as such.