Z-index Management

Introduction

This standard defines how z-index values MUST be managed to prevent stacking context conflicts and ensure predictable layering of UI elements.

Centralized Z-index Variables

Z-index values MUST be defined as centralized variables in _variable.scss:

$z-index__dropdown:    100;
$z-index__sticky:      200;
$z-index__overlay:     300;
$z-index__modal:       400;
$z-index__popover:     500;
$z-index__toast:       600;
$z-index__cookies:     700;

Rules

• New z-index values MUST NOT be added directly into component files as magic numbers.

• Z-index values MUST be assigned within a reasonable range (1–1000). Extreme values like 9999999999 MUST NOT be used.

• When a new stacking layer is needed, a new variable MUST be created in _variable.scss with a value that fits within the existing scale.

• Negative z-index values (z-index: -1) MAY be used for decorative pseudo-elements positioned behind their parent.

Existing Scale Reference

The z-index scale is divided into tiers of 100 to leave room for intermediate values if needed. Components within the same tier SHOULD share the same z-index variable.