Tutoriais

Implementando o Modo Escuro: Um Guia Completo para Desenvolvedores

9 min de leitura

O modo escuro passou de uma preferência de nicho para um recurso esperado. Usuários em todas as plataformas — macOS, Windows, Android, iOS — podem definir uma aparência escura em todo o sistema, e esperam que sites e aplicativos a respeitem. Implementar o modo escuro corretamente exige mais do que trocar branco por preto: demanda uma abordagem sistemática de cor, contraste e controle do usuário. Este guia percorre o processo completo, desde a arquitetura CSS até a mecânica de alternância com JavaScript e o teste completo de ambos os temas.

Propriedades Personalizadas CSS para Temas

A maneira mais sustentável de lidar com o modo escuro em CSS é por meio de propriedades personalizadas (também chamadas de variáveis CSS). Em vez de espalhar valores de cor por todas as suas folhas de estilo, você define cada cor como uma variável em :root e, em seguida, redefine essas variáveis para o modo escuro. Os estilos dos componentes fazem referência apenas às variáveis — nunca a códigos hex brutos.

Definindo Suas Paletas Clara e Escura

Comece com uma paleta de modo claro como padrão. Um ponto de partida limpo pode ser assim:

:root {
  /* Planos de fundo */
  --color-bg-base:      #FFFFFF;
  --color-bg-elevated:  #F8F9FA;
  --color-bg-overlay:   #F1F3F5;

  /* Texto */
  --color-text-primary:   #1A1A2E;
  --color-text-secondary: #4A4A6A;
  --color-text-muted:     #6C757D;

  /* Bordas */
  --color-border:         #DEE2E6;
  --color-border-strong:  #ADB5BD;

  /* Marca / acento */
  --color-accent:         #3B82F6;
  --color-accent-hover:   #2563EB;

  /* Feedback */
  --color-success:  #22C55E;
  --color-warning:  #F59E0B;
  --color-danger:   #EF4444;
}

Em seguida, defina substituições para o modo escuro em um bloco separado. A percepção-chave é que você não está apenas invertendo as cores — está escolhendo uma paleta diferente, construída especificamente para uma superfície escura:

[data-theme="dark"] {
  /* Planos de fundo */
  --color-bg-base:      #0F0F17;
  --color-bg-elevated:  #1A1A2E;
  --color-bg-overlay:   #252540;

  /* Texto */
  --color-text-primary:   #E8E8F0;
  --color-text-secondary: #A8A8C0;
  --color-text-muted:     #6A6A88;

  /* Bordas */
  --color-border:         #2E2E4A;
  --color-border-strong:  #4A4A6A;

  /* Marca / acento — muitas vezes ligeiramente mais claro para legibilidade em fundo escuro */
  --color-accent:         #60A5FA;
  --color-accent-hover:   #93C5FD;

  /* Feedback — ligeiramente dessaturado para evitar dureza */
  --color-success:  #4ADE80;
  --color-warning:  #FCD34D;
  --color-danger:   #F87171;
}

Observe que o acento #3B82F6 no modo claro torna-se #60A5FA no modo escuro. O matiz é o mesmo, mas a luminosidade aumenta — isso é necessário porque o contexto de contraste se inverteu. Uma cor que passa no WCAG AA contra um fundo branco quase sempre falhará contra um fundo quase preto, a menos que você a ajuste. O Gerador de Tons permite explorar a faixa completa de 50–950 de qualquer cor, facilitando a escolha do tom adequado para cada tema.

Usando Variáveis em Componentes

Com a paleta estabelecida, cada componente faz referência a variáveis em vez de valores brutos:

.card {
  background-color: var(--color-bg-elevated);
  border: 1px solid var(--color-border);
  color: var(--color-text-primary);
}

.btn-primary {
  background-color: var(--color-accent);
  color: #FFFFFF;
}

.btn-primary:hover {
  background-color: var(--color-accent-hover);
}

Quando o atributo [data-theme="dark"] está presente no elemento <html>, todas as variáveis são atualizadas simultaneamente, e cada componente que as referencia muda de aparência — sem CSS adicional necessário.

A Media Query prefers-color-scheme

Antes que o usuário interaja com uma alternância, você pode respeitar a preferência do sistema operacional usando a media query prefers-color-scheme. Essa media query é disparada quando o SO está configurado para aparência escura.

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg-base:      #0F0F17;
    --color-bg-elevated:  #1A1A2E;
    --color-bg-overlay:   #252540;
    --color-text-primary:   #E8E8F0;
    --color-text-secondary: #A8A8C0;
    --color-text-muted:     #6A6A88;
    --color-border:         #2E2E4A;
    --color-border-strong:  #4A4A6A;
    --color-accent:         #60A5FA;
    --color-accent-hover:   #93C5FD;
    --color-success:  #4ADE80;
    --color-warning:  #FCD34D;
    --color-danger:   #F87171;
  }
}

Essa abordagem funciona sem nenhum JavaScript, tem zero deslocamento de layout e respeita a preferência declarada do usuário imediatamente no carregamento da página. É a base correta. A limitação é que os usuários não podem substituí-la no seu aplicativo — se o SO está escuro, o site fica escuro, sem escapatória. É por isso que a maioria das implementações em produção adiciona uma alternância JavaScript sobre a media query.

Combinando Ambas as Abordagens

O padrão recomendado usa a media query como padrão e o atributo data-theme como uma substituição explícita. Você pode lidar com isso com um truque de especificidade CSS ou ordenando suas regras corretamente:

/* 1. Padrão de modo claro */
:root {
  --color-bg-base: #FFFFFF;
  /* ... */
}

/* 2. Substituição de modo escuro pelo SO (quando nenhuma preferência explícita está definida) */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg-base: #0F0F17;
    /* ... */
  }
}

/* 3. Modo escuro explícito (usuário alternado via JS) */
[data-theme="dark"] {
  --color-bg-base: #0F0F17;
  /* ... */
}

O seletor :not([data-theme="light"]) na media query significa que a preferência escura do SO só se aplica quando o usuário não escolheu explicitamente o modo claro. Uma vez que ele alterne, sua escolha explícita prevalece.

Mecanismo de Alternância com JavaScript

Uma alternância bem implementada faz três coisas: muda a aparência atual imediatamente, persiste a preferência no localStorage e lê a preferência salva no carregamento da página antes da primeira renderização.

Lendo a Preferência no Carregamento

Este script deve ser executado no <head> — antes que a página seja renderizada — para evitar um flash do tema errado:

<head>
  <script>
    (function() {
      const stored = localStorage.getItem('theme');
      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      const theme = stored ?? (prefersDark ? 'dark' : 'light');
      document.documentElement.setAttribute('data-theme', theme);
    })();
  </script>
</head>

Isso define imediatamente data-theme no <html> antes de qualquer estilo ser aplicado. O navegador calcula os valores corretos de propriedade personalizada desde a primeira renderização — sem flash.

A Função de Alternância

function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  const next = current === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', next);
  localStorage.setItem('theme', next);
}

// Conecte a um botão
document.getElementById('theme-toggle').addEventListener('click', toggleTheme);

Sincronizando o Estado do Botão de Alternância

O botão de alternância deve refletir visualmente o modo atual. Uma abordagem simples usa ícones:

<button id="theme-toggle" aria-label="Alternar modo escuro">
  <span class="icon-light">☀️</span>
  <span class="icon-dark">🌙</span>
</button>

[data-theme="dark"] .icon-light { display: none; }
[data-theme="dark"] .icon-dark  { display: inline; }
[data-theme="light"] .icon-light { display: inline; }
[data-theme="light"] .icon-dark  { display: none; }

Como a visibilidade do ícone é controlada por variáveis CSS vinculadas ao data-theme, o estado do botão é atualizado automaticamente sempre que o atributo muda — sem JavaScript adicional necessário.

Estratégias de Adaptação de Cores

Escolher as cores do modo escuro não é tão simples quanto inverter sua paleta clara. Vários princípios orientam boas escolhas de cores para o escuro.

Reduza o Contraste, Não Apenas o Inverta

Texto branco puro sobre fundo preto puro (#FFFFFF sobre #000000) é tecnicamente o contraste máximo — 21:1 — mas é cognitivamente cansativo para leitura prolongada. Reduza ambos os extremos: use um off-white como #E8E8F0 para o texto do corpo e um azul-marinho muito escuro como #0F0F17 para o plano de fundo da página. Isso preserva contraste amplo (ainda acima de 15:1) enquanto reduz a fadiga visual.

Use o Verificador de Contraste para verificar se cada combinação texto/plano de fundo no seu tema escuro atende pelo menos ao WCAG AA (4,5:1 para texto normal, 3:1 para texto grande). Pontos comuns de falha incluem:

  • Texto de espaço reservado em campos de formulário
  • Rótulos de botões desabilitados
  • Texto de metadados secundários (carimbos de data/hora, sublinhas)
  • Botões somente com ícone sem rótulos visíveis

Elevação em Camadas com Superfícies Escuras

No modo claro, a elevação é tipicamente expressa por sombras projetadas. No modo escuro, as sombras ficam invisíveis contra fundos escuros. A especificação Material Design 3 introduziu uma abordagem mais eficaz: superfícies mais claras parecem mais altas. Use planos de fundo sutilmente mais claros para componentes elevados:

/* Escala de elevação do modo escuro */
--color-bg-base:     #0F0F17;  /* Plano de fundo da página */
--color-bg-elevated: #1A1A2E;  /* Cartões, barras laterais */
--color-bg-overlay:  #252540;  /* Modais, menus suspensos */
--color-bg-tooltip:  #2E2E4A;  /* Dicas de ferramenta */

#0F0F17 como base, #1A1A2E para cartões, #252540 para modais — cada etapa é aproximadamente 8–10% mais clara em termos de luminosidade HSL. Isso cria uma hierarquia visual clara sem depender de sombras.

Dessature Levemente as Cores do Modo Escuro

Cores altamente saturadas parecem duras e neon em fundos escuros. Ao adaptar as cores da sua marca para o modo escuro, reduza a saturação em 10–20% juntamente com o aumento da luminosidade. Em vez de um verde de sucesso vívido #22C55E, prefira #4ADE80 — mais claro e ligeiramente menos saturado, o que é lido como sucesso sem causar fadiga ocular.

O Gerador de Tons é ideal aqui: insira o verde ou azul primário da sua marca e explore a faixa 300–400 para usos de texto e ícone no modo escuro, versus a faixa 500–600 para elementos interativos.

Imagens e Mídia

Imagens com fundos brancos parecem chocantes no modo escuro. O CSS pode ajudar:

/* Reduza a dureza das imagens no modo escuro */
[data-theme="dark"] img:not([src*=".svg"]) {
  filter: brightness(0.9) contrast(1.05);
}

/* Ou permita que as imagens se misturem levemente com o fundo */
[data-theme="dark"] img {
  mix-blend-mode: luminosity;
  opacity: 0.9;
}

Para ícones SVG que precisam se adaptar, usar currentColor como valor de preenchimento significa que eles adotam automaticamente a cor de texto atual:

.icon { color: var(--color-text-secondary); }

<svg fill="currentColor" viewBox="0 0 24 24">...</svg>

Testando Ambos os Modos

Testes completos evitam que regressões do modo escuro cheguem à produção.

Emulação nas DevTools do Navegador

Chrome e Firefox oferecem emulação do modo escuro nas DevTools sem alterar a configuração do SO. No Chrome: abra o DevTools, clique no menu de três pontos, vá em Mais ferramentas → Renderização e defina "Emular recurso de mídia CSS prefers-color-scheme" como "dark". Isso permite comparar ambos os modos lado a lado.

Testes de Contraste Automatizados

A verificação manual por amostragem é propensa a erros. Integre auditorias de contraste automatizadas ao seu fluxo de trabalho de desenvolvimento. Use ferramentas como Axe ou Lighthouse em CI para detectar novas adições de cores que falham nos limites do WCAG. O Verificador de Contraste permite verificar rapidamente um par de primeiro plano/plano de fundo em todos os níveis WCAG — cole qualquer par hex e veja a proporção instantaneamente.

Teste com Conteúdo Real

Bugs no modo escuro frequentemente aparecem em páginas com conteúdo dinâmico: imagens enviadas por usuários, incorporações de terceiros, gráficos e mapas. Teste com uma amostra realista de conteúdo, não apenas com a biblioteca de componentes do seu sistema de design isoladamente.

Testes no Nível do SO

Após verificar via emulação DevTools, teste com o SO realmente configurado para o modo escuro. A media query prefers-color-scheme dispara com base na configuração do SO, e alguns navegadores se comportam ligeiramente diferente dependendo de a configuração ser real ou emulada. Teste também a transição: alterne os modos enquanto uma página está aberta e confirme que não ocorrem deslocamentos de layout ou artefatos de renderização.

Lista de Verificação de Armadilhas Comuns

  • Valores hex codificados diretamente no CSS do componente em vez de variáveis — procure nos estilos por códigos hex brutos e substitua por variáveis
  • Ícones SVG com fill="#000000" codificado — altere para fill="currentColor"
  • Componentes de terceiros que não respeitam data-theme — envolva-os em uma camada CSS com escopo
  • Propriedade color-scheme não definida — adicione color-scheme: light dark ao :root para que o chrome do navegador (barras de rolagem, controles de formulário) também se adapte
  • <meta name="color-scheme"> ausente do <head> — adicione para que o navegador possa aplicar a cor de fundo correta antes do CSS ser carregado
<meta name="color-scheme" content="light dark">

:root {
  color-scheme: light dark;
}

Essa pequena adição faz com que barras de rolagem nativas, seletores de data e outros controles de formulário renderizados pelo SO mudem automaticamente para suas variantes escuras — um detalhe que muitas implementações ignoram.

Principais Conclusões

  • Defina todas as cores como propriedades personalizadas CSS no :root e as substitua para o modo escuro usando [data-theme="dark"]. Os estilos dos componentes fazem referência apenas a variáveis, tornando a troca de tema sem esforço assim que a paleta estiver estabelecida.
  • Use prefers-color-scheme: dark como padrão automático para usuários que configuraram seu SO com aparência escura. Adicione uma alternância JavaScript com persistência em localStorage para usuários que desejam substituir.
  • Execute o script anti-flash no <head> antes do CSS ser carregado para evitar o flash da primeira renderização com o tema errado.
  • As cores do modo escuro não são o inverso das cores claras — reduza o contraste extremo, use fundos mais claros para transmitir elevação e dessature levemente os acentos de marca para evitar a dureza neon.
  • Verifique cada par texto/plano de fundo com o Verificador de Contraste e use o Gerador de Tons para encontrar o tom certo de cada cor de marca para ambos os temas.
  • Adicione color-scheme: light dark e a tag <meta> correspondente para que os elementos de UI nativos do navegador (barras de rolagem, entradas) também mudem automaticamente.

Cores relacionadas

black

#000000

blue

#0000FF

green

#008000

navy

#000080

white

#FFFFFF

Marcas relacionadas

Meta

Helping people connect

1 cor

Drop

3 cores

Hex

8 cores

Must

2 cores

Open

2 cores

Reflect

2 cores

Ferramentas relacionadas

Verificador de contraste

Verifique as proporções de contraste de cores de acordo com as diretrizes WCAG 2.1. Teste a conformidade AA e AAA para texto normal e grande.

Abrir ferramenta

Gerador de tons

Gere escalas de tons estilo Tailwind CSS (50–950) a partir de qualquer cor base para sistemas de design.

Abrir ferramenta