Choosing a layer

Overview

Six rungs is a small enough set that the choice should never take long, and this page exists to make sure it does not. It is a lookup table and five rules, followed by the reasoning for the cases people argue about.

The failure this prevents is not an ugly screen. It is a screen that has drifted into five subtly different translucencies over eighteen months, at which point nobody can say what any of them means, the compositing budget is blown, and the contrast of half the surfaces depends on content the design team has never seen.

How it works

Three questions, in order

1. Does content scroll under it? If yes, it is overlay. This is the only question whose answer is a single rung, and it is first because it is the question people most often skip.

2. Does it cover the page, so that what is behind it is no longer usable? If yes, it is sheet, and it needs a scrim beneath it. Both, or neither.

3. Otherwise: is it temporarily above the page, or part of it? A surface that appears, is dismissed and leaves nothing behind, such as a menu, a popover or a dragged card, is raised. A bounded piece of content that belongs to the page is card. If it is neither, it is canvas and it needs no material at all.

overlay and sheet are the pair people get backwards, because two retired vocabularies used those words the other way round. Chrome that content scrolls beneath is overlay; the panel that covers the page is sheet. See ADR 0014.

The decision table

The five nesting rules

N1. A translucent rung may never contain another translucent rung. A card inside a sheet is card or raised, never overlay. Two stacked blurs cost twice as much, and the composite of a translucent surface over a translucent surface has no bounded worst case, so the contrast floor cannot be computed for it.

N2. A scrim is a sibling of the rung it serves, never its child. It sits between the sheet and everything below, in the stacking order, not inside the sheet's box.

N3. At most one sheet at a time. A dialog opened from a dialog is a bug in the flow, not a stack to be styled. If a decision genuinely requires two steps, it requires two steps inside one sheet.

N4. When a sheet is open, the chrome on the overlay rung goes under the scrim. A nav bar that stays bright and crisp above a scrim looks interactive and is not. Dim it with everything else.

N5. raised's shadow is the only shadow you may add. canvas and card have none, sheet and overlay carry their own, and scrim has none. "A small shadow to make it pop" on a card is how a system acquires nine elevations, none of which mean anything.

The one conditional case

A sticky summary bar that shows a health value, such as today's blood pressure or the latest glucose reading, is the only place a number a person may act on is allowed on a translucent rung, and it is allowed only when the same value also appears on an opaque surface on the same screen. The bar is then a convenience and not the record. If the bar is the only place the value appears, it is not chrome: make it a card pinned to the top, opaque, and accept that content no longer scrolls under it.

The reasoning is on The contrast floor: a translucent rung's contrast is bounded and measured, so it is not unsafe, but "bounded worst case" is a weaker guarantee than "known background", and the element carrying the number should have the stronger one.

Using it

Start at the lowest rung that works. The ladder is not a scale of quality. Most surfaces on a well-designed health screen are canvas and card, a few are raised, and one is an overlay. A screen where most things are raised has no hierarchy, because everything is equally lifted.

Do not use a rung to communicate importance. Importance is type size, position and space. Material is depth. A more translucent card is not a more important card, and a reader will not read it as one.

Do not use a rung to communicate status. That is the colour axis's job, and mixing the two produces a screen where urgency is encoded in blur radius. See Two colour axes.

When you cannot decide, the surface is doing two jobs. The recurring example is a header that is both page chrome and a content card. Split it: the chrome is overlay, the card is a card inside the scroll area, and the screen immediately becomes easier to describe.

Tokens

Accessibility impact

The rules on this page are mostly aesthetic hygiene, but three of them are accessibility controls wearing plain clothes:

• N1 exists so that contrast remains computable. A nested translucent surface has no bounded worst case, so no floor can be guaranteed for text on it. This is the reason the rule is absolute rather than a preference.
• N4 exists so that modality is honest. A reader using a screen reader is told the overlay is modal and everything else is inert; a reader using their eyes should be told the same thing, and a bright, crisp nav bar above a scrim says the opposite. The visual and the programmatic state have to agree.
• The conditional case exists so that no health value depends on a backdrop. Bounded is not the same as known, and the number somebody acts on gets the stronger guarantee.

One more, which belongs to the components rather than to the tokens: sheet surfaces are modal, and modality is a focus contract. Focus moves in, is trapped, and returns to the trigger on dismissal. The material says nothing about that, and choosing sheet does not implement it. Keyboard and focus is the contract.

Related

• The ladder says what each rung is made of, and the boundary between opaque and translucent.
• Performance budget explains why "at most three composited surfaces" is a real number and how to check you are under it.
• Layering and elevation has the z-index contract that decides what is in front of what.