The modal is under the sticky header again. The agent “fixes” it with z-index: 9999 on the dialog, 10000 on the toast, and 1 on a tooltip that now punches through a drawer. The visual bug is gone in that one storybook story. The stacking scale is not.
I’ve started treating a magic z-index in an agent UI patch as a review comment, not a mergeable polish. If the repo already has --z-dropdown, --z-modal, and --z-toast, the model should pick one of those — or propose a new token in the same file — not invent 9999.
Why 9999 is a trap
A z-index scale is a contract. Once three components pick random four-digit numbers, every later overlay has to guess higher. Portals, sticky headers, and third-party widgets make the guessing worse. The next agent session cannot see the implicit “we already used 10000,” so it uses 10001.
The number also hides the real bug. A popover under a header is often a stacking context problem (isolation, transform, filter, or a parent z-index), not a missing 9999. A huge literal lets the PR look finished without asking which context actually won.
A simple scale policy
- Tokens only —
var(--z-modal)or the Sass/JS equivalent already in the theme - One scale file — new layers are added there, with a one-line comment for what sits above and below
- No +1 arms races — do not “beat” a sibling by adding one to its computed value
- Name the layer —
modal,popover,toast,nav, notzIndex={50}next to an unexplainedzIndex={40}
If the design system uses Tailwind, pin the agent to the configured z- utilities (z-modal, z-10 only if that is the scale). A raw z-[9999] is the same offense as a raw 9999 in CSS.
What to put in the prompt
Give the agent the scale, not a vibe:
Use only the z-index tokens in src/theme/z-index.css. Do not invent a new numeric z-index. If a new layer is required, add a named token in that file and say what it sits above. If the bug is a stacking context, fix the context — don’t raise the number. Paste the token file, or a 10-line excerpt, into the prompt. A screenshot of the broken overlay is not a substitute for the scale.
In the PR, ask for a one-line note: which token was used, or why a new token was added. If the diff contains a raw integer, send it back.
The same rule applies when the agent “fixes” a popover by adding z-index to a parent that already creates a stacking context. Raising the child does nothing useful, and raising the parent can lift a whole column of the page over the nav. Ask what element actually forms the context. A one-line DevTools note in the PR (“header is transform: translateZ(0), so the popover must portal to document.body”) is worth more than a new integer.
If the design system documents a portal target for overlays, use that. A modal that stays in the article flow and then tries to win with z-index is the usual source of these patches.
Reject / send back
Reject
-
z-index: 9999,z-[9999], orstyle={{ zIndex: 10000 }}in a repo that has a scale - A toast, modal, and popover each inventing their own number in the same PR
- “I set it high so it always wins” as the only justification
- Fixing an overlay by raising z-index when a parent
transformcreated a new context
Accept
- An existing token, correctly chosen for the layer
- A new named token in the scale file, with a short comment
- A stacking-context fix that leaves the scale alone

