z-index-scale

Z-Index Scale

Overview

Generate a systematic z-index token scale that eliminates arbitrary values and z-index conflicts. Creates predictable layering for dropdowns, modals, tooltips, and overlays.

When to Use

• Setting up z-index tokens for a new design system
• Fixing z-index conflicts and "wars" in existing code
• Creating consistent layering for overlays, modals, tooltips
• Documenting stacking context expectations

Quick Reference: Layering Levels

Level	Purpose	Typical Range
Base	Default content flow	0
Raised	Cards, subtle elevation	1-10
Dropdown	Menus, selects, popovers	100-199
Sticky	Sticky headers, sidebars	200-299
Fixed	Fixed navigation, FABs	300-399
Overlay	Backdrop, dimmer	400-499
Modal	Dialogs, sheets	500-599
Toast	Notifications, snackbars	600-699
Tooltip	Tooltips, hovers	700-799
Maximum	Debug overlays, dev tools	9999

The Process

1. Understand stacking needs: Identify all layered components in the system
2. Ask output format: CSS custom properties, Tailwind config, or JSON tokens
3. Generate scale: Create tokens with semantic naming
4. Document usage: Explain which token for which use case

Output Formats

CSS Custom Properties

:root {
  /* Base - default document flow */
  --z-index-base: 0;
  --z-index-below: -1;

  /* Raised - subtle elevation within content */
  --z-index-raised: 1;
  --z-index-raised-2: 2;
  --z-index-raised-3: 3;

  /* Dropdown - menus, selects, comboboxes, popovers */
  --z-index-dropdown: 100;

  /* Sticky - sticky positioned elements */
  --z-index-sticky: 200;

  /* Fixed - fixed navigation, floating action buttons */
  --z-index-fixed: 300;
  --z-index-header: 310;
  --z-index-sidebar: 320;

  /* Overlay - backdrop behind modals */
  --z-index-overlay: 400;

  /* Modal - dialogs, sheets, drawers */
  --z-index-modal: 500;
  --z-index-modal-content: 510;

  /* Toast - notifications, snackbars */
  --z-index-toast: 600;

  /* Tooltip - tooltips, title attributes */
  --z-index-tooltip: 700;

  /* Maximum - debug, dev tools (avoid in production) */
  --z-index-max: 9999;
}