O Valor de z-index: Como evitar números mágicos e organizar suas camadas

O Problema dos Números Mágicos

A propriedade z-index é uma das ferramentas mais importantes para qualquer desenvolvedor de interface, pois permite controlar a ordem de sobreposição dos elementos. Modais, notificações (toasts), popups e menus dependem dela para garantir que apareçam acima do conteúdo.

No entanto, muitos recursos focam nos detalhes técnicos ou nas armadilhas do Stacking Context, mas ignoram um aspecto crucial: o valor em si. Em projetos maiores, os valores de z-index tornam-se uma bagunça de “números mágicos”, onde cada equipe tenta superar a outra com números mais altos.

“Eu vi isso em um pull request há alguns anos. O autor escolheu um número altíssimo apenas para garantir que ficasse acima de tudo. Eu me perguntei: por que esse valor específico?”

A Falta de Visibilidade

O problema central não é técnico, mas de visibilidade. Em projetos grandes com múltiplas equipes, você nem sempre sabe o que está flutuando na tela. Pode haver uma notificação do time A, um banner de cookies do time B ou um modal do SDK de marketing.

A lógica do desenvolvedor era simples: “Se eu usar um número muito alto, certamente ficará no topo.” É assim que chegamos a esses valores arbitrários desconectados da aplicação.

O Conceito Fundamental

Elementos com valor de z-index maior serão exibidos na frente dos menores, desde que estejam no mesmo Stacking Context. Se não estiverem, elementos em um “stack” superior permanecerão acima, independentemente do valor baixo que tenham.

Dica: O valor máximo para z-index é 2147483647. Trata-se do limite de um inteiro sinalizado de 32 bits. Tentar valores superiores fará com que os navegadores simplesmente o clampe nesse limite.

A Solução: Tokenização

O uso de valores arbitrários pode levar a problemas. A solução é simples: tokenização de z-index. Sistemas de design bem projetados incluem tokens para z-index por um motivo: eles funcionam.

Implementação Prática com CSS Variables

Criamos uma configuração centralizada em :root. Isso torna a adição de novos popups ou toasts previsível. Se precisar alterar a ordem, basta mudar os valores na raiz e tudo se atualiza em um só lugar.

A verdadeira força desse sistema aparece quando os requisitos mudam. Suponha que precise adicionar uma barra lateral entre o conteúdo base e os toasts. Com tokens, inserimos apenas um novo token e ajustamos a escala, sem precisar tocar em componentes existentes.

Tokens Locais para Elementos Internos

Hasta agora, focamos nas camadas globais. Mas e dentro dessas camadas? Os tokens principais (como 100 ou 200) não são ideais para elementos internos, pois a maioria cria seu próprio Stacking Context.

Nota: Para que esses tokens locais funcionem corretamente, certifique-se de que o container crie um Stacking Context usando isolation: isolate.

Para resolver isso, introduzimos pares de “tokens locais” para uso interno. Isso permite gerenciar a posição interna com precisão. Se precisar de um botão flutuante dentro de um popup para ficar no topo, ou um ícone decorativo em um toast atrás do conteúdo principal, usamos esses âncoras locais.

Elementos Flutuantes e Valores Negativos

Um dos maiores desafios é gerenciar componentes que podem aparecer em qualquer lugar, como tooltips. Tradicionalmente, damos a eles z-index massivos (como 9999), mas se o tooltip estiver fisicamente dentro da estrutura DOM do modal, seu z-index é relativo apenas ao modal.

Usando nossos tokens locais, paramos de chutar: um tooltip sempre aparecerá acima do conteúdo ao qual está anexado. Ele não precisa saber sobre a “corrida armamentista” global porque já está em pé no “chão estável” fornecido pelo token da camada pai.

Regras de Ouro

Negativos muitas vezes assustam desenvolvedores, mas dentro dessa abordagem sistemática, valores negativos são ferramentas poderosas para decorações internas. Quando um componente cria seu próprio Stacking Context, o z-index está confinado a ele.

• Mantenha uma visibilidade clara sobre as camadas.
• Use tokens globais apenas para a estrutura principal da aplicação.
• Utilize tokens locais ou cálculos (calc()) para posicionamento interno.
• Nunca chute valores de z-index sem um sistema definido.

Seguindo essas regras, transformamos o z-index em uma parte previsível do seu design system. O valor de z-index não está no quão alto é o número, mas no sistema que o define.

Por Maya Pixel

Responsável editorial por UI.

Especialista em UI/UX e Web Design Minimalista.

Por Maya Pixel

Responsável editorial por UI.

Especialista em UI/UX e Web Design Minimalista.