Foundation

Z-index and stacking

Every surface sits on one of seven named rungs, from the draft at base to the blocking dialog on top. Elevation describes a crossing surface with shadow; this ladder decides which surface paints over the other.

The ladder

Seven tokens in steps of ten, top wins. The gaps belong to future system rungs, never to feature values.

  • 60z.dialog Blocking dialogs, the top of the product stack Rerun feedback?
  • 50z.backdrop The single ink scrim Scrim
  • Blocking above this line
  • 40z.toast Toasts in the bottom right corner Your draft is saved
  • 30z.overlay Menus, popovers, autocomplete, tooltips Export menu
  • 20z.sticky The app navigation bar and sticky toolbars App navigation
  • 10z.raised Sticky table headers and in-page raised surfaces Sticky table header
  • 0z.base All in-flow content: the draft, cards, controls The draft
The stacking ladderEach plane steps right as its token rises; the top rung paints over everything beneath it
Miniature radiischematic surfaces scale down, 4px at most on a mini plane, 0 where the surface it depicts is square
--inline-z-base: 0;
--inline-z-raised: 10;
--inline-z-sticky: 20;
--inline-z-overlay: 30;
--inline-z-toast: 40;
--inline-z-backdrop: 50;
--inline-z-dialog: 60;

What sits where

Every product surface names its rung. Elevation owns how these shadows look; this table only orders them.

Product surfaceTokenValuePaired elevation
The draft, question cards, controlsz.base0shadow.none
Sticky table headerz.raised10shadow.raised while content passes beneath
App navigation barz.sticky20shadow.raised after overlap
Export menuz.overlay30shadow.overlay
Dimensions legend popoverz.overlay30shadow.overlay
Your draft is saved toastz.toast40shadow.overlay
Dialog scrimz.backdrop50bg.overlay fill
Rerun feedback confirmationz.dialog60shadow.dialog
Only tokens reach feature code.

A raw z-index number in a component is a defect: if a surface has no rung, it belongs on z.base.

Blocking and non-blocking

The ladder splits at the scrim. Below z.backdrop the page stays live; above it the page waits.

Non-blocking

z.overlay 30 · z.toast 40
Rerun feedback Copy or export draft Start Brainstorming overlay 30
Your draft is savedtoast 40
  • Nothing dims; the page underneath stays live.
  • Menus and popovers close on outside click or Escape and never trap focus.
  • A toast waits in the bottom right corner and dismisses itself; it never takes focus.

Blocking

z.backdrop 50 · z.dialog 60
Rerun feedback?

This replaces the current questions on your draft.

  • One blocking surface at a time; a dialog never opens a second dialog above itself.
  • The single ink scrim sits at z.backdrop and dims everything below it.
  • The dialog traps focus and restores it on close; deeper keyboard detail belongs to the accessibility page.
A toast never covers an open dialog.

z.toast 40 sits below z.backdrop 50 by design, so the toast waits its turn behind the scrim.

Stacking contexts

transform, filter, and position: sticky each start a new stacking context, and a token wins only against siblings in the same one. Whatever the ancestor sits on caps everything inside it.

App navigationsticky 20
Rerun feedback?dialog 60
Do portal blocking surfaces to the document body, where only the ladder decides what paints on top.
transform
Export menuoverlay 30
App navigationsticky 20
Don't mount one inside a transformed, filtered, or sticky ancestor; its token competes only inside that context, so the navigation still paints over it.

Rules

Seven checks keep stacking boring, which is the goal.

  1. Name every rung. A raw z-index number in feature code is a defect; use the seven tokens and nothing between them.
  2. Keep one blocking surface. A dialog never opens a second dialog above itself; replace the decision or finish it first.
  3. Let toasts wait. z.toast 40 sits below z.backdrop 50 by design, so a toast never covers an open dialog.
  4. Pair order with elevation. z.overlay carries shadow.overlay; z.dialog carries shadow.dialog plus the single bg.overlay scrim.
  5. Match interaction mode. Non-blocking layers close on outside click or Escape and never trap focus; blocking layers trap focus and restore it on close.
  6. Portal blocking surfaces. Render the backdrop and dialog at the document body so no ancestor stacking context can cap them.
  7. Never dim below the scrim. Menus, popovers, autocomplete, and tooltips never darken the page; the one scrim belongs to the dialog alone.