Variáveis CSS para alternância de temas

As propriedades personalizadas do CSS (variáveis) definidas em :root ficam disponíveis globalmente em toda a folha de estilos. Defina uma paleta de cores completa uma única vez — planos de fundo, cores de texto, superfícies e bordas — e faça referência a ela em todos os lugares. Essa única fonte de verdade torna trivial alternar o tema.

Quando um atributo data-theme="dark" é definido em document.documentElement, um seletor CSS como [data-theme='dark'] substitui as variáveis da raiz por valores escuros. Os componentes fazem referência a var(--color-bg) e passam automaticamente a usar os novos valores, sem nenhuma alteração no código.

No mínimo, defina: --color-bg (plano de fundo da página), --color-text (texto principal), --color-primary (cor da marca), --color-surface (plano de fundo de cartões e painéis) e --color-border (divisórias). Um conjunto consistente de tokens impede o surgimento de valores de cor improvisados nos componentes.

No CSS do componente, faça referência a variáveis como background: var(--color-bg) e color: var(--color-text). Você também pode fornecer um valor alternativo: var(--color-bg, #ffffff). O navegador resolve a variável no momento da renderização, portanto uma única classe funciona para os temas claro e escuro.

Adicione transition: background-color 200ms, color 200ms ao seletor :root. Quando o atributo data-theme muda, todos os elementos que usam variáveis CSS animam simultaneamente até seus novos valores. Isso cria uma experiência refinada sem qualquer código de animação em JS.

Gerenciar o tema por meio de variáveis CSS é superior a definir estilos embutidos a partir de JavaScript. O navegador gerencia nativamente todos os recálculos de estilo, não há novas renderizações do React acionadas para cada componente filho tematizado e a cascata do CSS gerencia a herança automaticamente. O JS só precisa alternar um atributo no elemento raiz.

Você pode combinar variáveis CSS com a consulta @media (prefers-color-scheme: dark) como alternativa exclusiva de CSS. Defina as substituições escuras dentro da consulta de mídia além do seletor data-theme (ou em vez dele). Isso garante que o modo escuro funcione mesmo que o JavaScript ainda não tenha sido executado.

A abordagem mais robusta combina os dois mecanismos: a consulta @media fornece o padrão do OS, enquanto um atributo data-theme permite a substituição do usuário por meio de JavaScript. Quando o atributo está presente, ele prevalece por causa da especificidade; quando está ausente, a consulta de mídia entra em ação.

Para imagens que ficam ruins em planos de fundo escuros, use o elemento HTML picture com um elemento filho source media="(prefers-color-scheme: dark)". O navegador seleciona automaticamente a variante escura. Para ícones SVG no CSS, você pode usar filter: invert(1) como uma aproximação rápida.

As variáveis CSS também podem ter escopo limitado a componentes individuais, sendo definidas no elemento raiz de um componente em vez de :root. Isso permite a tematização por componente, como uma barra lateral com seu próprio token de plano de fundo, diferente do plano de fundo da página, e que ainda alterna corretamente com a alternância de tema global.

O Chrome DevTools mostra os valores resolvidos das variáveis CSS no painel Estilos. Clique na referência da variável para ir até sua definição. Isso facilita verificar se o token claro ou escuro correto está sendo aplicado a qualquer elemento. Você também pode editar os valores das variáveis diretamente no painel.

As propriedades personalizadas do CSS em :root fornecem um sistema centralizado de tokens para os temas. Alterne um atributo data-theme no elemento HTML para mudar de tema instantaneamente. Adicione transições CSS para uma animação suave, use a consulta de mídia prefers-color-scheme como alternativa exclusiva de CSS e evite substituições de estilos em JS por componente.