Layers
Sets the stacking order of app chrome, dialogs, popups, and tooltips.
Principles
- Use a named layer, never a raw z-index. The
--surf-layer-*scale keeps app chrome, dialogs, popups, and tooltips in one order. - Portal anything that floats. A child's z-index can't escape its parent's stacking context or overflow clip.
- Close overlays from the inside out. Escape closes the innermost layer first and returns focus to its trigger.
- Diagnose before raising a number. A higher number rarely fixes an overlay, because the cause is usually the portal target, an ancestor context, or clipping.
Layer scale
Layers set paint order only. How a raised surface looks, its shadow and edge, is part of Visual hierarchy.
Sheet and Drawer keep their backdrop at 0 and content at 1 inside one isolated positioner. Menus and toasts share the popup layer, so when numbers tie, DOM order decides.
Stacking contexts
A child's z-index can't leave its parent's stacking context. transform, opacity below 1, isolation, and some contain values each create one, so don't put a transform on a whole content area.
Local: the child stays in its parent's context, so 9999 can't outrank a sibling context at 2.
Clipping and paint order are separate: turning off the clip doesn't change the order. The values 1, 2, and 9999 show the rule and aren't product layers.
Nested overlays
Base UI handles initial focus, the Tab range, the inert background, Escape order, and focus return. Keep selection state and task data in the calling screen.
Diagnosis
- Find the real portal target and ancestor contexts in the DOM. The React tree can differ.
- Tell clipping by overflow, mask, or clip-path apart from paint order.
- Set the layer token on the outermost positioned element, such as a popup's positioner, not on content inside it.
- Look for the browser's top layer: showModal() dialogs, the popover attribute, and fullscreen sit above every z-index. Surflane's Dialog is a portal, not showModal().
References: W3C stacking order, React createPortal, W3C positioned layout / top layer, Base UI Dialog