Indice Z

L'echelle d'indices Z qui maintient les elements superposes previsibles.

L'échelle z-index assigne un rôle à chaque couche. Les composants choisissent le jeton qui correspond à leur rôle — un dropdown ne devine jamais z-index: 9999 pour gagner une guerre d'empilement.

Les composants choisissent le jeton qui correspond à leur rôle — un dropdown ne devine jamais z-index: 9999 pour gagner une guerre d'empilement.

L'échelle d'empilement

--ep-z-base

Contenu de page, éléments statiques, empilement par défaut.

--ep-z-dropdown

Menus déroulables, popovers de select, résultats d'autocomplétion.

--ep-z-sticky

Headers sticky, sidebars sticky, barres d'outils persistantes.

--ep-z-overlay

Arrières-plans plein écran, overlays assombris.

--ep-z-modal

Dialogues modaux, tiroirs, palettes de commandes.

--ep-z-popover

Infobulles, popovers contextuels, notifications flottantes. Les composants portalés vers document.body (createPortal) DOIVENT utiliser ce niveau (65) — le niveau dropdown (30) perd face au sticky (40) dans le contexte d'empilement racine.

--ep-z-toast

Notifications toast — au-dessus des popovers pour rester visible pendant les menus contextuels.

100

--ep-z-skip-link

Bypass skip-link pour utilisateurs clavier — doit surplomber chaque couche.

Règles de l'échelle

N'utilisez jamais de valeurs arbitraires comme z-9999.
Les skip-links passent au-dessus de tout (100) — l'accessibilité gagne sur les guerres d'empilement.
Les toasts passent au-dessus des popovers (70 vs 65) — les notifications bannière restent visibles pendant que les menus contextuels sont ouverts.
Les modales passent au-dessus des overlays (60 vs 50).
Les headers sticky passent au-dessus des dropdowns inline (40 vs 30). Un dropdown qui s'ouvre dans un header sticky hérite du contexte d'empilement du header — SAUF s'il est portalé, auquel cas il devient une couche flottante et perd face au sticky.
Patron Portal : tout ReactDOM.createPortal(..., document.body) doit utiliser le niveau popover (65). Le niveau dropdown (30) n'est valide que pour les dropdowns non-portalés ancrés dans le contexte de leur hôte. (Source : foundation-integrity Phase 1, 2026-08-24 — le menu Sign-out était coupé derrière la topbar du dashboard au niveau 30.)

Contextes d'empilement

Un jeton z-index ne fonctionne qu'à l'intérieur du bon contexte d'empilement. Créer un nouveau contexte (via transform, opacity, filter, ou will-change) piège les descendants — leurs valeurs z-index sont relatives au contexte, pas à la page.

Ce qu'il faut éviter

Escalader les valeurs z-index pour « gagner » l'empilement.
Utiliser z-index: -1 pour pousser le contenu derrière la page.
Définir z-index sur des éléments qui sont l'unique enfant de leur parent.