Z-Index Strategy

Semantic z-index tokens, single-source-of-truth codegen, global vs local tiers, and a forbid-raw-z-index lint rule.

The Problem

A site grows past five overlay types — modal, drawer, popover, toolbar, tooltip — and z-index becomes a hand-rolled lottery. Every new overlay nudges a value up: 10, 20, 99, 100, 9999. Within a year the codebase contains z-index: 1, z-index: 21, z-index: 100, z-index: 99999, and a comment that reads /* must be above modal */ with no way to verify the claim.

The standard symptoms:

• Magic numbers everywhere. A grep for z-index: returns dozens of unique integers with no shared scale.
• The 99999 reflex. When a layer renders behind another, the fix is “make my number bigger” — no investigation of the actual stacking context.
• Renumbering paralysis. Adding a new tier between 100 (modal) and 200 (toast) means picking 150 and praying nothing in the codebase already uses it.
• Tailwind’s z-10 / z-20 / z-30 scale. This was a workaround for the renumbering pain — leave gaps so you can squeeze new layers between old ones. It traded one numeric scale for another and demanded that every developer memorise which class corresponds to which overlay role.

The renumbering pain and the memorisation tax both dissolve in the AI-era refactor: a model can rename --z-200 → --z-toast across hundreds of files in seconds. The cost that drove numeric scales no longer exists.

The Solution

Define z-index tiers as semantic, single-namespace tokens generated from a single TypeScript source of truth.

:root {
  /* Generated from z-index-tokens.ts — do not hand-edit */
  --z-content:           0;
  --z-toolbar:          10;
  --z-dropdown:         20;
  --z-popover:          30;
  --z-popover-portaled: 40;
  --z-modal-backdrop:   50;
  --z-modal:            60;
  --z-toast:            70;
  --z-tooltip:          80;
}

Every component CSS file uses the named token, never a raw integer:

.modal {
  position: fixed;
  z-index: var(--z-modal);
}

.toast {
  position: fixed;
  z-index: var(--z-toast);
}

Three properties make this work:

1. Semantic names — --z-modal tells you what layer it is. --z-200 does not.
2. Single namespace — one flat list of tiers, not split by feature or context. (Z-index is fundamentally one ordering problem, unlike density tokens which split per design context.)
3. Codegen from a TS source of truth — the CSS block, the styleguide table, and any TypeScript constants all derive from one file. Drift is structurally impossible.

Why not Tailwind-numeric?

Tailwind’s default z-0 / z-10 / z-20 / z-30 / z-40 / z-50 scale exists for one reason: in pre-AI CSS work, renumbering tokens across a codebase was painful. Leaving gaps (10, 20, 30…) let you squeeze new tiers between old ones without touching existing code.

Both costs that drove numeric scales — refactor pain and memorisation tax — collapse once a model can confidently rename across the whole codebase. Semantic names win on every other axis: readability, grepability, code review, onboarding.

Single-namespace vs multi-namespace

For density tokens (spacing, font sizes), splitting into multiple namespaces — --spacing-myweb-* and --spacing-myadmin-* — is the right call. Article pages and admin dashboards genuinely need different scales. See Multi Namespace Token Strategy.

Z-index does not follow that rule. There is exactly one viewport, one stacking universe, and one ordering question: “is this above or below that?”. A modal in the article context still needs to render above a tooltip in the admin context if both happen to be on screen during a flow.

Keep z-index in a single namespace. Resist the urge to define --z-myweb-modal separate from --z-myadmin-modal — they would always need to be kept in sync, which is exactly what a single token already does.

Source of truth: TS → codegen → CSS

Define tiers in TypeScript. Generate the CSS block. Have the styleguide read the TS file directly.

// src/styles/z-index-tokens.ts
export type ZIndexTier = {
  name: string;       // CSS var name without --z- prefix
  value: number;      // numeric z-index
  purpose: string;    // human-readable role
  kind: "global" | "local";
};

export const Z_INDEX_TIERS: ZIndexTier[] = [
  { name: "content",          value:  0, purpose: "Default in-flow content",         kind: "global" },
  { name: "toolbar",          value: 10, purpose: "Sticky toolbars and headers",     kind: "global" },
  { name: "dropdown",         value: 20, purpose: "In-flow dropdown menus",          kind: "global" },
  { name: "popover",          value: 30, purpose: "Inline popovers (not portaled)",  kind: "global" },
  { name: "popover-portaled", value: 40, purpose: "Popovers rendered via portal",    kind: "global" },
  { name: "modal-backdrop",   value: 50, purpose: "Modal/drawer backdrop",           kind: "global" },
  { name: "modal",            value: 60, purpose: "Modal/drawer foreground",         kind: "global" },
  { name: "toast",            value: 70, purpose: "Transient notifications",         kind: "global" },
  { name: "tooltip",          value: 80, purpose: "Tooltips (highest UI layer)",     kind: "global" },
  { name: "local-1",          value:  1, purpose: "Child promotion within parent",   kind: "local"  },
  { name: "local-2",          value:  2, purpose: "Child promotion within parent",   kind: "local"  },
  { name: "local-3",          value:  3, purpose: "Child promotion within parent",   kind: "local"  },
];

The codegen rewrites a marker block inside the main CSS file:

/* GENERATED:Z_INDEX_BEGIN — do not hand-edit; run `pnpm gen:z-index` */
:root {
  --z-content:           0;
  --z-toolbar:          10;
  --z-dropdown:         20;
  --z-popover:          30;
  --z-popover-portaled: 40;
  --z-modal-backdrop:   50;
  --z-modal:            60;
  --z-toast:            70;
  --z-tooltip:          80;
  --z-local-1:           1;
  --z-local-2:           2;
  --z-local-3:           3;
}
/* GENERATED:Z_INDEX_END */

Wire two scripts:

The styleguide page imports Z_INDEX_TIERS directly from the TS file and renders a table. The table can never go stale because there is no second copy of the data.

Global vs local tokens

Once the global tier list is in place, a recurring pattern emerges in components: z-index: 1 on a child to lift it above siblings within a stacking-context-creating parent. These values are not independent tiers in the global ordering — they only matter relative to the parent.

For these cases, define a small reserved family: --z-local-1, --z-local-2, --z-local-3.

.card {
  position: relative;
  isolation: isolate;        /* parent creates a stacking context */
}

.card__background {
  position: absolute;
  inset: 0;
  z-index: var(--z-local-1); /* sits above default flow but inside .card */
}

.card__content {
  position: relative;
  z-index: var(--z-local-2); /* sits above .card__background */
}

The rule for using --z-local-N:

Use --z-local-N only when (a) the parent creates a stacking context and (b) the child is being promoted above its siblings, not stacked against other components.

If the child needs to render above unrelated UI (e.g. a popover that must sit above the page toolbar), it is not local — it is a global tier and belongs in the named scale.

Lint enforcement

A token system that is not enforced is a token system that decays. Add a lint rule that forbids raw z-index: <integer> in component CSS.

The escape hatch matters. Some legitimate cases (a one-off third-party widget integration, an experimental layer) need a raw integer with a code comment explaining why — block by default, but do not block forever.

For the full multi-pass linter pattern (raw color literals, zone-aware semantic tokens, and the matching enforcement rules for other token families), see Design Token Lint. Pass 3 covers the raw-z-index rule documented above.

Decision tree: where does my new overlay belong?

Is the new layer a stacking promotion *inside* a parent that has its own
stacking context (isolation: isolate, position+z-index, transform, etc.)?
│
├── YES → use --z-local-1 / --z-local-2 / --z-local-3
│         (No global tier needed. The parent's stacking context contains it.)
│
└── NO  → it is a global UI layer
          │
          ├── Does it already match a tier? (modal, toast, tooltip, popover, ...)
          │   │
          │   ├── YES → use that tier's token
          │   │
          │   └── NO  → add a new tier to z-index-tokens.ts, run pnpm gen:z-index,
          │              then use the new token. Update the styleguide automatically.
          │
          └── If you find yourself adding more than 1-2 tiers per quarter, the tier
              list is probably too granular — review whether existing tiers cover it.

Portal vs inline decision

A popover anchored to a button can render either inline (in the button’s DOM subtree) or portaled (appended to <body>). The choice changes which token applies.

Walk up the DOM from the anchor to the root; if any ancestor creates a stacking context, the inline popover will be trapped inside it. See Stacking Context for the full list of properties that create one.

Common AI Mistakes

• Defining a numeric scale (--z-50, --z-100, --z-200). This recreates the Tailwind-numeric problem with custom property syntax. Names should describe roles, not magnitudes.
• Hardcoding z-index: 100 “because bigger”. The fix to a layering bug is almost never a higher number — it is understanding which stacking context the element lives in. See Stacking Context.
• Using --z-local-N outside a stacking context. Without an isolated parent, --z-local-1 participates in the root stacking context and competes against global tiers. Either add isolation: isolate to the parent, or use a global tier.
• Defining --z-emergency: 99999. The “emergency” tier is the bug, not the fix. If a layer needs to escape its parent, fix the stacking context. If a real new tier is needed, add it to the named scale at the right position.
• Splitting z-index into per-context namespaces (--z-myweb-modal, --z-myadmin-modal). The viewport is one ordering universe. Multi-namespace makes sense for density tokens but not for z-index.
• Hand-editing the generated CSS marker block. Edit z-index-tokens.ts and re-run pnpm gen:z-index. Hand edits are wiped on next codegen and cause pnpm check:z-index to fail in CI.
• Skipping the lint rule. Without enforcement, raw z-index: 100 reappears within a sprint and the system slowly returns to magic-number chaos.

When to Use

Good fit

• Projects with 5+ overlay types — once modal, drawer, popover, tooltip, toast, and a sticky toolbar coexist, ad-hoc numbers stop scaling
• Multi-team codebases — a shared semantic scale prevents one team’s z-index: 100 from colliding with another team’s z-index: 200
• Projects with a styleguide / design system page — the generated table becomes the canonical reference for designers and developers

Not needed

• Prototypes and single-overlay sites — a marketing landing page with one mobile menu does not need a tier system
• Static content sites — blog and documentation sites with no overlays beyond the menu can use z-index: 1 and stop there
• One-off internal tools — if the entire app has three z-index values total, the tier system is overhead

References

• Stacking Context — what creates a stacking context and how to debug layering bugs
• Multi Namespace Token Strategy — companion strategy for density tokens (spacing, font sizes); contrast with z-index’s single-namespace rule
• pgen worked example (zudo-pattern-gen #940) — concrete migration from magic numbers to the tier-token system