DEV Community

Sherotree
Sherotree

Posted on

Make the agent keep the existing z-index scale — no magic z-index values

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, not zIndex={50} next to an unexplained zIndex={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.
Enter fullscreen mode Exit fullscreen mode

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], or style={{ 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 transform created 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

Top comments (0)