Elevation and surfaces

Contract

Depth is carried by the surface. A shadow means "it floats above and is about to disappear" and belongs to three components.

.my-panel {
  background: var(--surface-raised);
  border: var(--hairline) solid var(--border);
}

Accessibility

Anatomy

Declared in one place so that it does not drift across components.

A popover and a modal built on the Popover API and <dialog> live in the browser's top layer, where z-index no longer decides. The tokens stay for what does not get the top layer — and for an application that needs to fit into the same order.

Scale

They read as a stack from the bottom up. A step is chosen by the role of the region rather than by a wanted brightness.

The fifth role stands outside the stack, because it is not about depth but about input:

Containment

A region inside a region recedes by one film, at any depth. The film is --surface-recessed — the same one a control recesses by — and it is counted from whatever lies underneath rather than being a step of the ramp, which is what makes it work at the second nesting and the third.

An absolute step cannot: it knows one depth and runs out. Measured before the rule was general, a card inside a card and a panel inside a panel both sat at a step of exactly 0.000, with one hairline to tell them apart. Films composite in paint, so three of them on white measure 232 · 218 · 206 and the depth of a nesting shows through the stack of elements rather than through the strength of one fill.

A region takes at most one film. A support region asks for the same film, and one that is already nested still paints one — so rank's ground lever bites at depth 0 only, and a support region deeper in shows its rank in its title and its missing edge. See rank.

The inset steps with the ground too. A nested region insets one rung tighter than a free-standing one, which also settles a figure that was always slightly wrong: a card inside a panel used to inset 16 where the panel inset 12, so the child was roomier than its parent. Nested content recedes, and an inset that grew on the way in was the one place the kit said otherwise.

The corner steps with the ground. A nested region takes --radius-md where a free-standing one takes --radius-lg, because nested radii have to decrease or the inner shape reads as bulging out of the outer one. One rung and not one per level: at a third nesting the next step down would be a control's corner on a full-width block. After the first step the ground carries depth on its own.

The corner belongs to depth and not to rank, and that is a collision rather than a preference. Rank is a screen-level choice, so a lead card can sit inside a support panel — and were the corner rank's to set, that card would carry the larger radius inside a container carrying the smaller one and bulge out of it. Depth cannot collide with itself: a nested region is inside its container by definition, so a step down is always available and always right.

In a dark theme the distance between neighbouring steps is wider than in a light one: the dark end of the ramp is harder to tell apart, and a mirrored light arrangement would give four identical black rectangles. In the dark-soft theme the whole stack rises by one step of the ramp — four surfaces are overridden, and the rest of the semantics does not know the theme has changed. There is no room above that: the next step of the ramp no longer holds text. The light end behaves in exactly the same way, where raised and overlay both sit on --n-0.

States over a surface

Hover and selection are alpha. An opaque fill would keep them from adding up: a hover over a selected row would disappear.

Variants

Both are functional. Both are declared entire in the tokens — a component substitutes a ready value and does not assemble a shadow itself.

Every shadow has two layers: the far one gives the distance to the background, the near one the contact of the edge. In one layer it looks either glued down or floating with no support.

The colour of a shadow is kept separate, because light-dark() accepts only a <color> and a whole shadow value does not pass through it:

In a dark theme a shadow is denser. A weak shadow on a dark background is invisible, and a light shadow is a glow already, and glows are forbidden.

The rule

A shadow is given only to what appeared on an action and will disappear on Escape. Everything that stands on the screen permanently is parted by a surface and a border. A card gets no shadow — it gets a surface.

The ground

In a dark theme the ground is denser: on a light page a dimming creates contrast by itself, on a dark one it has to be added. This is a dimming, not a blur — gradients, glows and blurs are forbidden entirely.

The ground is put on the ::backdrop of a native <dialog>, so the top layer, the focus trap and closing on Escape come from the platform rather than from the library.

Rules

What to take and what not to

API

Related

Colour Motion Panel Card Popover Modal