1. ¿Qué es z-index?

El atributo z-index determina la posición de un elemento en el eje z (profundidad) dentro de su Stacking Context. Solo funciona cuando el elemento está posicionado (position: relative|absolute|fixed|sticky) o es un flex/grid item con z-index explícito.

• Valor numérico: cuanto mayor sea el número, más arriba estará el elemento.
• Valor auto: hereda el orden de apilamiento natural del documento.
• Negativo: permite enviar elementos detrás del fondo del contenedor.

2. Stacking Context (Contexto de Apilamiento)

Un Stacking Context es una capa aislada que define un nuevo plano de referencia para los z-index. Los elementos dentro de un mismo contexto compiten entre sí, pero nunca pueden sobresalir del contexto padre.

Los contextos se crean de forma implícita o explícita por diversas propiedades:

3. Reglas de ordenamiento dentro de un Stacking Context

1. Elementos con position: static y sin z-index (orden del DOM).
2. Elementos con position: relative y z-index: auto.
3. Elementos con position: relative/absolute/fixed/sticky y z-index negativo.
4. Elementos con z-index positivo (de menor a mayor).

Entender este flujo evita sorpresas al mezclar modales, tooltips y menús desplegables.

4. Ejemplos prácticos

4.1. Superponiendo tarjetas con z-index

<style>
  .card { position: relative; width: 200px; height: 120px; margin: 20px; }
  .card:nth-child(1) { background:#ffdddd; z-index: 10; }
  .card:nth-child(2) { background:#ddffdd; z-index: 5; }
  .card:nth-child(3) { background:#ddddff; z-index: 15; }
</style>
<div class="d-flex">
  <div class="card">Card 1</div>
  <div class="card">Card 2</div>
  <div class="card">Card 3</div>
</div>

El tercer card siempre quedará encima porque su z-index:15 supera a los demás.

4.2. Modal con opacity creando un nuevo contexto

<style>
  .overlay {
    position: fixed; top:0; left:0; width:100%; height:100%;
    background: rgba(0,0,0,0.5); /* opacity < 1 crea nuevo stacking context */
    z-index: 1000;
  }
  .modal {
    position: absolute; top:50%; left:50%; transform:translate(-50%,-50%);
    background:#fff; padding:20px; border-radius:8px; z-index:1010; /* dentro del mismo contexto */
  }
</style>
<div class="overlay">
  <div class="modal">Soy un modal</div>
</div>

Si añadimos otro elemento con z-index:2000 fuera del .overlay, aparecerá encima del modal, porque pertenece a un contexto superior.

4.3. Tooltip sobre elemento transformado

<style>
  .rotated {
    transform: rotate(15deg); /* crea nuevo stacking context */
    position: relative; z-index: 1;
  }
  .tooltip {
    position: absolute; top:-30px; left:0; background:#333; color:#fff;
    padding:5px 10px; border-radius:4px; z-index: 10; /* sigue dentro del mismo contexto */
  }
</style>
<div class="position-relative" style="margin:100px;">
  <div class="rotated">Elemento rotado
    <span class="tooltip">Tooltip</span>
  </div>
</div>

El tooltip se muestra correctamente porque comparte el mismo contexto que el elemento rotado; si el tooltip tuviera z-index mayor pero fuera fuera del contenedor, quedaría oculto.

5. Comparativa rápida: z-index vs. otras técnicas de superposición

6. Buenas prácticas y troubleshooting

6.1. Evita valores arbitrarios

Define una escala de z-index en tu hoja de estilos base (p.ej., 0‑10: UI básica, 100‑200: modales, 1000‑1100: overlays). Así reduces conflictos.

6.2. Inspecciona el árbol de stacking context

En Chrome DevTools, abre la pestaña Layers o usa document.querySelectorAll('*') para buscar elementos con opacity<1, transform, etc., que crean contextos inesperados.

6.3. Rendimiento

Muchos contextos pueden forzar composiciones de GPU en navegadores móviles. Mantén el número bajo y evita animaciones en propiedades que crean nuevos contextos (como opacity constante).

6.4. Accesibilidad

Los elementos superpuestos deben ser navegables con teclado. Usa aria-hidden="true" en capas decorativas y tabindex="-1" en contenedores invisibles.