Incident Report
A minor UI polish PR added opacity: 0.99 and transform: translateZ(0) to the data-grid wrapper to smooth out horizontal scroll jitter. Storybook visual snapshots passed cleanly.
Within two hours of release, customer support reported unusable row-action menus clipped beneath the position: sticky; z-index: 10 page header, while Android RUM telemetry flagged severe scroll-time INP spikes.
- T+00:00: Grid wrapper GPU promotion ships to production.
- T+22:00: Users report row action menus (
z-index: 9999) rendering behind thez-index: 10sticky header. - T+55:00: Team ships a JS
document.bodyportal withscrolllisteners to escape clipping; Android p75 INP jumps from 140 ms to 480 ms. - T+90:00: Performance traces show synchronous
getBoundingClientRect()reflows on every scroll tick.
The Red Herring
The first Slack reflex was to bump the menu's stylesheet from z-index: 9999 to z-index: 2147483647 and add will-change: transform to the table wrapper to "fix scroll jank." Both changes passed local visual checks on an un-scrolled viewport.
In production, z-index: 2147483647 remained trapped beneath the z-index: 10 sticky header. z-index only orders siblings inside the same stacking context, and will-change: transform sealed a new stacking context around the table wrapper.
Causal Chain
This failure combines CSS paint-order isolation with main-thread layout thrashing caused by JavaScript workarounds.
- A parent card sets
opacity: 0.99ortransform, forming a local stacking context. - GPU layer promotion via
transformorwill-changeseals that stacking boundary. - Portaling the element to
document.bodyescapes the trap, but forces synchronous JSgetBoundingClientRect()reads on scroll. - Moving the overlay into the browser Top Layer eliminates
z-indexcompetition entirely. - CSS Anchor Positioning replaces the JS positioning loop with native layout-engine constraint resolution.
Failure Simulator
Layer Dissection
01 → 02: Stacking Contexts Meet GPU Layer Promotion
Under CSS Stacking Context rules, z-index is never global. It only compares siblings that share the same parent stacking context. When a parent container has z-index: 1 and forms a stacking context, a child with z-index: 9999 still paints behind a sibling header at z-index: 10.
Under GPU Compositor Layers, adding transform: translateZ(0) or will-change: transform instructs Blink to promote the element into its own compositor texture. The CSS specification mandates that any element with a non-none transform, filter, or opacity < 1 establishes a new stacking context so the GPU can composite it atomically.
02 → 03: Why React Portals Escalate to Main-Thread Freeze
To escape the parent's stacking context, teams reach for React Portal Z-Index Legacy patterns that render the tooltip directly under document.body. Detaching the overlay from its trigger DOM subtree breaks CSS layout inheritance and forces a JS positioning library to:
- Attach
scrollandresizelisteners across all scrollable ancestors. - Call
getBoundingClientRect()on every scroll tick, forcing synchronous style recalculation and layout reflow. - Maintain a global
z-indextoken registry (z-modal: 1000,z-popover: 1100) that still collides with third-party widgets.
03 → 04: Escaping Document Z-Index via the Top Layer
The Browser Top Layer is a dedicated rendering stratum managed by the user agent outside the document root stacking context.
Elements promoted via dialog.showModal() or the HTML popover attribute (popover="auto" or popover="manual") paint in the Top Layer in last-in-first-out (LIFO) order. No z-index, opacity, overflow: hidden, or transform anywhere in the ancestor tree can clip or occlude a Top Layer element.
04 → 05: Replacing JS Positioning Loops with CSS Anchor Positioning
Placing a tooltip in the Top Layer solves occlusion, while CSS Anchor Positioning eliminates JavaScript coordinate tracking.
Declaring anchor-name: --trigger on the button and position-anchor: --trigger on the popover lets the layout engine compute anchor(bottom) and flip via @position-try inside the standard layout phase, running zero scroll listeners on the main thread.
Architectural Fix & Invariants
<button popovertarget="row-menu" style="anchor-name: --row-btn;">Actions</button> <div id="row-menu" popover="auto" class="anchored-menu"> <button type="button">Edit Record</button> </div> <style> .anchored-menu { position: fixed; position-anchor: --row-btn; top: anchor(bottom); left: anchor(left); position-try-fallbacks: flip-block, flip-inline; margin: 0; } </style> Architectural Invariants:
- Zero
z-indexescalation for overlays: Render modals and popovers withdialog.showModal()orpopoverso they paint in the Top Layer rather than competing in document stacking contexts. - No
getBoundingClientRect()on scroll: Position anchor-relative overlays withanchor-nameandposition-anchorinstead of main-thread scroll listeners. - Explicit layer-promotion audits: Never apply
will-change: transformoropacity < 1to layout wrappers without verifying that no non-Top-Layer positioned descendants expect globalz-index.
Golden Rule: Adding nines to z-index is shouting inside a soundproof room; promote overlays to the Top Layer with popover and anchor them in CSS.



