Apple's Liquid Glass: what the Human Interface Guidelines require from those designing for iOS, iPadOS, and macOS

- Reading
- 5 min
- Tables
- 1
Apple's official materials documentation details when to use Liquid Glass, how it responds to accessibility settings, and which standard materials remain valid per platform. For those maintaining a design system, it's time to revalidate component by component.
Apple introduced Liquid Glass as a unified visual language in 2025, bringing a translucent, dynamic layer to controls and navigation across iOS, iPadOS, macOS, tvOS, and visionOS. More than a year later, the Materials page of the Human Interface Guidelines (HIG) continues to be updated as a living reference for what is allowed, recommended, and prohibited in this material. It's not a new announcement: it's the document that product and design system teams need to read line by line before validating any screen that uses transparency, blur, or depth.
The problem Apple is solving isn't aesthetic, it's about visual hierarchy. When a control floats over content that scrolls behind it, the user still needs to read the button's text even as a colorful photo passes behind it. Getting this wrong creates the same old problem in UI with transparency: low contrast, illegible text, and users with low vision or high contrast enabled simply not being able to see the control.
Two materials, two different functions
The HIG splits the system into two categories that aren't interchangeable. Liquid Glass forms the functional layer: tab bars, sidebars, and navigation controls that sit above content and depend on constant contrast. Standard materials serve to differentiate within the content layer itself, such as app backgrounds or sections of a screen.
The most straightforward rule in the documentation is also the easiest to break without noticing: don't use Liquid Glass in the content layer. Apple argues that this creates confusing visual hierarchy, because the material was designed to signal "this is a control, that is content." The explicit exception is transient interactive elements, such as sliders and toggles, which take on a Liquid Glass appearance only during activation to reinforce that something is being manipulated.
The second rule is about usage discipline: applying the effect to multiple custom controls "distracts from the underlying content" instead of helping. Apple's recommendation is to limit Liquid Glass to the interface's most important functional elements, not spread the effect across the entire screen just because it exists.
Regular or clear: the choice changes with the background, not with taste
For those building custom components or styling system components, the HIG defines two variants of Liquid Glass with distinct uses, not interchangeable based on aesthetic preference:
regular: blurs and adjusts the luminosity of the background content to preserve legibility. It's the default variant for most system components, recommended for text-heavy screens, such as alerts, sidebars, and popovers.clear: highly translucent, designed to prioritize the visibility of what's behind it, such as photos and videos. It's the choice for components floating over media in immersive experiences.
Using clear over a very light background requires extra attention: Apple recommends adding a dimming layer with 35% opacity when the background content is light, in order to maintain contrast and legibility. If the background is already dark, or if the app uses AVKit's standard media playback controls (which already include their own dimming layer), this extra layer isn't necessary.
The detail that trips up anyone who copies color instead of token
The documentation provides a direct visual example to illustrate a common mistake: a share button with its symbol in systemGray3 color over a translucent material ends up with poor contrast and is nearly illegible. The same button using the system's vibrant color solves the problem without extra effort from the design team.
In summary: Apple recommends choosing material and effect based on semantic meaning and use case, never based on the color it appears to produce at a given moment, because system settings change that appearance later. This includes using the vibrant colors defined by the system instead of hardcoding gray or black values directly over any material.
Accessibility is part of the material's definition, not an afterthought
This is the point that matters most to those validating accessibility before approving a screen. The appearance of the regular and clear variants of Liquid Glass changes according to user settings: material appearance preference in the device's settings, and the accessibility modes that reduce transparency or increase contrast.
This means that a custom component tested only in the default mode can render completely differently, and potentially with contrast issues, when the user turns on "Reduce Transparency" or "Increase Contrast." Teams building custom Liquid Glass need to include these two settings in the visual QA test matrix, not just in the generic accessibility checklist.
What changes by platform
Beyond Liquid Glass, each platform maintains its own set of standard materials, with specific names and vibrancies that don't automatically carry over between systems:
| Platform | Standard materials | Accessibility note |
|---|---|---|
| iOS, iPadOS | ultraThin, thin, regular (default), thick | Avoid quaternaryLabel vibrancy over thin/ultraThin: insufficient contrast |
| macOS | NSVisualEffectView materials, with "behind window" or "within window" blending | Test vibrancy across varied contexts before locking in a mode |
| tvOS | Same four levels (ultraThin to thick), used based on color scheme recommendation (light/dark) | Liquid Glass appears on focus for elements such as buttons and image views |
| visionOS | Single adaptive, non-modifiable "glass" material for windows; thin, regular, thick for internal components | Prioritize translucency over opaque color; vibrancy limited to label, secondaryLabel, tertiaryLabel |
For multiplatform design systems, this table is practically a revalidation checklist: a material token designed for iOS doesn't carry the same semantics in visionOS, where Apple goes as far as prohibiting opaque backgrounds in windows because they "block the person's view and reduce awareness of the surrounding physical and virtual environment."
What to revalidate before the next cycle
For those maintaining a component library shared across apps, the HIG suggests a practical checklist:
- No use of Liquid Glass in the content layer, except
slidersandtogglesduring active interaction. - Custom components using
clearover a light background have a 35% dimming layer applied. - Every label, fill, or separator color over material uses the system's vibrant values, never hardcoded gray.
- Visual tests cover "Reduce Transparency" and "Increase Contrast" enabled, not just the default state.
- Material tokens are mapped per platform (iOS/iPadOS, macOS, tvOS, visionOS), without assuming direct equivalence between them.
None of these points require rewriting the interface from scratch, but all of them require revisiting decisions that were likely made while looking only at the screen under ideal lighting and standard contrast conditions. The complete reference, with visual examples of correct and incorrect contrast, is published in the Materials documentation on Apple's developer site.
Translated from the Brazilian Portuguese original · Read the original
Figma's Dev Mode MCP Server brings the design file straight into the IDE
The Dev Mode MCP Server connects agents like those in Cursor, Copilot, and Claude Code directly to Figma files, trading manual exports and screenshots for automatic reading of components, variables, and Auto Layout, but it only works well if the design library is organized the right way.





