# Use Fixed Z-Index Scale

**MUST** · **ID:** `layout-ibelick-z-index-scale` · **Category:** layout
**Source:** [@Ibelick](https://www.ui-skills.com/)
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/layout-ibelick-z-index-scale

> MUST: Use a fixed z-index scale (z-10, z-20, z-30) not arbitrary values. Document the scale. Arbitrary z-index values lead to escalating z-index wars.

Use a defined z-index scale instead of arbitrary values like z-[999]

Arbitrary values are an escalation game: z-[999] wins today, so the next thing that must sit above it becomes z-[9999], and nobody can answer "should a tooltip be above a modal?" by reading the code. A fixed, named scale (base, dropdown, sticky, modal, popover, tooltip) turns stacking into a decision made once. The semantic layer names are our elaboration, not upstream's words — upstream only forbids the arbitrary values.

## Bad — do not do this

`layout-ibelick-zindex-scale-bad`

```tsx
export function IbelickZIndexScaleBad() {
  return (
    <div className="relative h-48 w-full bg-muted/50 rounded-lg overflow-hidden">
      {/* Arbitrary z-index values - z-index wars! */}
      <div className="absolute inset-x-4 top-4 p-3 bg-card rounded-lg shadow-md z-[10]">
        <span className="text-sm">Card (z-[10])</span>
      </div>
      <div className="absolute left-8 top-12 p-2 bg-primary text-primary-foreground rounded z-[100]">
        <span className="text-xs">Dropdown (z-[100])</span>
      </div>
      <div className="absolute right-8 top-8 p-2 bg-destructive text-white rounded z-[999]">
        <span className="text-xs">Modal (z-[999])</span>
      </div>
      <div className="absolute right-4 bottom-4 p-2 bg-muted-foreground text-background rounded z-[9999]">
        <span className="text-xs">Tooltip (z-[9999])</span>
      </div>
      <p className="absolute bottom-2 left-4 text-xs text-destructive">
        Arbitrary z-indexes lead to unpredictable stacking
      </p>
    </div>
  );
}
```

## Good — do this

`layout-ibelick-zindex-scale-good`

```tsx
export function IbelickZIndexScaleGood() {
  // Semantic z-index scale:
  // z-0: base content
  // z-10: dropdowns, floating elements
  // z-20: sticky headers
  // z-30: fixed elements
  // z-40: modals, dialogs
  // z-50: tooltips, popovers

  return (
    <div className="relative h-48 w-full bg-muted/50 rounded-lg overflow-hidden">
      {/* Semantic z-index scale */}
      <div className="absolute inset-x-4 top-4 p-3 bg-card rounded-lg shadow-md z-0">
        <span className="text-sm">Card (z-0 base)</span>
      </div>
      <div className="absolute left-8 top-12 p-2 bg-primary text-primary-foreground rounded z-10">
        <span className="text-xs">Dropdown (z-10)</span>
      </div>
      <div className="absolute right-8 top-8 p-2 bg-destructive text-white rounded z-40">
        <span className="text-xs">Modal (z-40)</span>
      </div>
      <div className="absolute right-4 bottom-4 p-2 bg-muted-foreground text-background rounded z-50">
        <span className="text-xs">Tooltip (z-50)</span>
      </div>
      <p className="absolute bottom-2 left-4 text-xs text-success">
        Semantic scale: base → dropdown → modal → tooltip
      </p>
    </div>
  );
}
```

## References

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Tailwind Z-Index](https://tailwindcss.com/docs/z-index)