All articles
Design & UXNovember 5, 2026 6 min read

Z-Index Is a Design System Problem, Not a CSS Bug

Every z-index war starts the same way: someone writes z-index: 9999 to fix a modal, and six months later your tooltip renders behind the cookie banner. Here's how to fix it with tokens.

Every z-index war starts the same way. Someone writes z-index: 9999 to force a modal above a sticky header, ships it, and six months later the tooltip inside that modal renders behind the cookie banner that a third-party script injected at 2147483647. The fix isn't more numbers. It's treating layering as a design system concern with its own tokens, rules, and ownership.

Why z-index goes feral

Z-index feels like a simple integer, which is exactly why it rots. Three forces conspire against you:

  1. Stacking contexts are invisible. Any element with position: relative and a z-index, opacity < 1, transform, filter, will-change, or a handful of other properties creates a new stacking context. Children can't escape it. Your z-index: 9999 inside a transformed parent still loses to a sibling of that parent with z-index: 2.
  2. Numbers invite inflation. Nobody writes z-index: 10 anymore because they got burned once. So they write 9999. Then the next dev writes 10000. Eventually someone ships 99999999 and a Slack message asking why it still doesn't work.
  3. Third-party scripts don't ask. Intercom, Drift, cookie banners, and preview toolbars all stake out the top of the stack. If you don't plan for them, they'll beat you.

The root cause is that z-index is usually written at the component level by whoever is debugging a specific bug, with no shared map of what should sit above what.

Design the layer cake before you write CSS

Before touching code, agree on the vertical order of UI surfaces in your product. This is a design decision, not an engineering one, and it belongs in the design system doc next to your color ramp.

A reasonable default, bottom to top:

  • Base — page content, cards, default flow
  • Raised — sticky elements that scroll with intent (sticky table headers, sticky CTAs)
  • Dropdown — menus, selects, autocomplete panels
  • Sticky nav — the app header or sidebar
  • Overlay — backdrops behind modals and drawers
  • Modal — dialogs, drawers, sheets
  • Popover — tooltips, hover cards, context menus triggered from inside modals
  • Toast — transient notifications
  • Debug — dev-only overlays, grid guides, feature flags UI

The trick is that popover sits above modal on purpose. A tooltip inside a modal has to render above the modal's own content. If you reverse these, you'll spend a quarter fighting it.

What about third parties?

Reserve a band at the top of your scale that you promise never to use. Intercom defaults around 2147483000. Cookie consent tools often sit around 99999. Pick a cap — say, 1000 — for your own app, and leave everything above that for vendors. When something must beat a vendor (rare, usually a legal notice), you make a deliberate exception, not a reflex.

Encode the scale as tokens

Once the order is agreed, name each layer and give it a number with gaps. Gaps matter: you will discover a missing layer, and you want room to slot it in without renumbering everything.

// tokens/z-index.ts
export const zIndex = {
  hide: -1,
  base: 0,
  raised: 10,
  dropdown: 20,
  stickyNav: 30,
  overlay: 40,
  modal: 50,
  popover: 60,
  toast: 70,
  debug: 80,
} as const;

export type ZIndexToken = keyof typeof zIndex;

The entire app uses these names. Not integers. If you see a raw z-index number in a PR, it's either a token file edit or a bug.

Wiring it into Tailwind

If you're on Tailwind, extend the theme so z-modal and z-popover are first-class utilities:

// tailwind.config.js
import { zIndex } from './tokens/z-index';

export default {
  theme: {
    extend: {
      zIndex: Object.fromEntries(
        Object.entries(zIndex).map(([k, v]) => [k, String(v)])
      ),
    },
  },
};

Now a modal is z-modal, a tooltip is z-popover, and the cookie banner has nothing to argue with. Bonus: you can lint against raw z-\[\d+\] arbitrary values in CI.

The stacking context trap

Tokens won't save you from stacking contexts. This is the part most teams miss.

Consider a card component with transform: translateZ(0) applied for GPU compositing. Inside the card, you render a dropdown with z-dropdown (20). Elsewhere on the page, your sticky nav uses z-stickyNav (30). The dropdown renders behind the nav, as expected. But a modal triggered from inside the card, using z-modal (50), also renders behind the nav. Because the modal is trapped inside the card's stacking context, and the card itself has an effective z-index of auto relative to the nav.

Fixes, in order of preference:

  1. Portal overlays to the body. Modals, drawers, toasts, and popovers should render in a sibling of your app root, not inline. Every modern framework supports this — React portals, Vue <Teleport>, Svelte <svelte:component> into a mount node. This is the single highest-leverage change you can make.
  2. Don't create stacking contexts you don't need. Audit transform, filter, will-change, and opacity < 1 on layout wrappers. These are often copy-pasted from a Stack Overflow answer about blurry text.
  3. If you must stack in place, make sure the ancestor's z-index is at least as high as anything it needs to appear above.

A quick detection trick

Drop this into the console on any page to find every stacking context:

[...document.querySelectorAll('*')].filter((el) => {
  const s = getComputedStyle(el);
  return (
    (s.position !== 'static' && s.zIndex !== 'auto') ||
    s.transform !== 'none' ||
    s.filter !== 'none' ||
    parseFloat(s.opacity) < 1 ||
    s.willChange !== 'auto' ||
    s.isolation === 'isolate'
  );
}).forEach((el) => el.style.outline = '2px solid magenta');

You will be horrified. That's the point.

Portals are not optional

If there is one takeaway, it's this: every surface in your top four layers (overlay, modal, popover, toast) should render in a portal. Not because it looks nicer, but because it removes stacking context from the equation entirely. A toast rendered next to <body> doesn't care what transforms your layout uses.

The cost is real — focus management, aria wiring, click-outside detection, and scroll locking all get trickier when a component isn't where it looks like it is. This is why you lean on a headless library (Radix, Ark, Headless UI, React Aria) instead of hand-rolling. They've already solved the portal + focus trap + inert background combo, and they do it accessibly.

Governance: the boring part that actually works

Tokens and portals are the mechanism. Governance is why they survive contact with a growing team.

  • One owner for the z-index token file. Any PR that edits it needs their review. This forces conversations instead of silent inflation.
  • Lint for raw z-index values. A simple stylelint rule or ESLint rule on arbitrary Tailwind values (z-[9999]) catches 90% of regressions.
  • Document third-party bands. Keep a short page listing every vendor script that participates in the stack and its known z-index. When a new vendor shows up, update the doc before you ship.
  • Visual regression on modal + popover combos. The classic bug — tooltip inside modal — is the kind of thing a Chromatic or Percy diff will catch, but only if you write the story.

If you want a broader take on how we structure design tokens across color, spacing, and motion, our design systems work has a few patterns worth stealing.

Where we'd start

If your codebase already has a z-index: 9999 problem, don't try to boil the ocean. In order:

  1. Grep for every z-index in your repo. Count them. Shock yourself.
  2. Define the token scale above (or adapt it). Commit it even if nothing uses it yet.
  3. Portal your modals and toasts. This alone will fix most reported bugs.
  4. Migrate components one at a time, starting with the ones that trigger support tickets.
  5. Add the lint rule last, once the cleanup is done, so it protects the new world instead of blocking the old one.

Z-index isn't a CSS bug. It's a system you either design or inherit by accident. Design it.

#design systems#css#tailwind#tokens#frontend

Want a team like ours?

72Technologies builds production software for the kind of teams who actually read this blog.

Start a project