Foundations

Materials

Materials are translucent layers that blur what's behind them. They keep people oriented: a menu or toolbar reads as floating above the content, and the content's color still shows through.

UltrathinOver media you want to keep seeing

ThinSmall floating controls

RegularMenus, popovers, the default

ThickBusy content, long text

ChromeToolbars and title bars

SidebarSource lists

LibraryFor YouBrowseSearch

The materials

A material is the mb-material class with a data-material thickness. It sets a translucent background, the shared blur and saturation filter, a bright rim along the top edge and a hairline border:

<div className="mb-material" data-material="thick">…</div>

`data-material`	Background	Use it for
`ultrathin`	Elevated background at 38%	Controls over photos and video, where the content should stay visible
`thin`	54%	Small floating controls
`regular` (default)	70%	Menus, popovers, context menus
`thick`	84%	Surfaces with lots of text, or over busy content
`chrome`	Page background at 76%	Toolbars, title bars and navigation bars
`sidebar`	Sidebar background at 78%	Sidebars and source lists

Each value is also a token, --mb-material-ultrathin through --mb-material-sidebar, for components that compose their own surface. They pair with --mb-material-filter (a 28px blur at 180% saturation), --mb-glass-rim for the top-edge highlight and --mb-shadow-menu for elevation:

.inspector-popover {
  background: var(--mb-material-regular);
  backdrop-filter: var(--mb-material-filter);
  box-shadow: var(--mb-glass-rim), var(--mb-shadow-menu);
}

macbetter's menus, dialogs, alerts, bars, windows and sidebars use these tokens, so they follow the theme and the accessibility settings below.

Choosing a thickness

Thicker materials are more legible and less contextual. Start from the surface's job:

Text-heavy surfaces get thicker materials. A long menu or a popover with paragraphs needs regular or thick.
Small controls over media get thinner ones. A play button over a video can be ultrathin because it has one glyph and a large hit area.
Chrome stays consistent. Use chrome for every bar in a window, so toolbars and title bars read as one layer.
Busy backgrounds need more. If text over a material is hard to read in a screenshot of your real content, go one step thicker instead of adding a shadow to the text.

Glass

mb-glass is a clearer, lensing surface for floating controls such as tab bars and toolbar capsules. It has a brighter top edge, a soft inner glow and a lighter blur than the materials. The Glass component page covers its API and variants. The glass variant of Button uses the same look.

Don't stack materials

Never put one material on another. Blurring a surface that's already blurred produces a flat, muddy layer, and the contrast of text on it becomes unpredictable. Inside a material, use fills (--mb-fill-tertiary) or separators to group content, not a second material. If a popover opens from a toolbar, it floats over content beside the toolbar; it doesn't need to look like part of it.

Reduced transparency and increased contrast

When someone turns on Reduce Transparency (prefers-reduced-transparency: reduce), every material token resolves to its opaque background and --mb-material-filter becomes none. Increase Contrast (prefers-contrast: more) makes the materials opaque too, and strengthens the glass border. mb-glass becomes opaque under either setting.

This happens in the tokens, so a component built on them needs no extra CSS. If you write your own translucent surface, build it from --mb-material-* and --mb-material-filter rather than raw rgba() and blur(), or it won't respond.

Edit this page on GitHub View source