Adicionando Dark Mode ao Seu Site com Tailwind

Sep 23, 2025 · 4 min read

Adicionando Dark Mode ao Seu Site com Tailwind

O dark mode não é apenas uma tendência—é uma expectativa dos usuários. No entanto, muitos desenvolvedores complicam demais sua implementação. Com o Tailwind CSS, adicionar dark mode ao seu site requer apenas algumas linhas de código e zero dependências de framework.

Este tutorial aborda tanto o dark mode automático (respeitando as preferências do sistema) quanto a alternância manual com persistência de preferência do usuário. Você aprenderá a implementar qualquer uma das abordagens em minutos usando a variante dark integrada do Tailwind.

Principais Pontos

A variante dark: do Tailwind habilita o dark mode com configuração mínima
O dark mode baseado no sistema funciona automaticamente com zero JavaScript
Alternadores manuais dão aos usuários controle sobre sua preferência de visualização
localStorage previne o flash de tema no carregamento das páginas

Como o Dark Mode Funciona no Tailwind CSS

A Variante dark: Explicada

O Tailwind CSS fornece uma variante dark: que aplica estilos condicionalmente quando o dark mode está ativo. Simplesmente prefixe qualquer classe utilitária com dark: para definir sua aparência no dark mode:

<div class="bg-white dark:bg-gray-900">
  <h1 class="text-gray-900 dark:text-white">Hello World</h1>
  <p class="text-gray-600 dark:text-gray-400">
    Este texto se adapta à sua preferência de tema
  </p>
</div>

Por padrão, o Tailwind usa a media query CSS prefers-color-scheme para detectar a preferência do sistema do usuário. Nenhuma configuração necessária—simplesmente funciona.

Dark Mode Baseado no Sistema (Automático)

Usando prefers-color-scheme

A implementação mais simples de dark mode requer zero JavaScript. O Tailwind aplica automaticamente os utilitários de dark mode quando o sistema operacional do usuário está configurado para dark mode:

<!-- Este card será branco no modo claro, cinza escuro no dark mode -->
<article class="bg-white dark:bg-gray-800 rounded-lg p-6 shadow-lg">
  <h2 class="text-xl font-bold text-gray-900 dark:text-white">
    Dark Mode Automático
  </h2>
  <p class="mt-2 text-gray-600 dark:text-gray-300">
    Este componente respeita sua preferência de tema do sistema
  </p>
</article>

Esta abordagem funciona imediatamente, mas tem uma limitação: os usuários não podem sobrescrever sua preferência do sistema especificamente no seu site.

Alternador Manual de Dark Mode

Implementação Baseada em Classe

Para dar controle aos usuários, configure o Tailwind para usar uma classe .dark em um elemento pai. Para Tailwind CSS v3.4 e posteriores, adicione isto ao seu CSS:

@import "tailwindcss";

/* Para Tailwind CSS v4+ */
@custom-variant dark (&:where(.dark, .dark *));

Para versões anteriores do Tailwind (v3.x), configure-o no seu tailwind.config.js:

module.exports = {
  darkMode: 'class',
  // ... resto da sua configuração
}

Agora o dark mode é ativado quando a classe dark está presente em um elemento pai:

<html class="dark">
  <body>
    <div class="bg-white dark:bg-black">
      <!-- Dark mode está ativo -->
    </div>
  </body>
</html>

Alterne o dark mode com este JavaScript:

// Alternar dark mode
document.documentElement.classList.toggle('dark');

Método de Atributo de Dados

Alguns desenvolvedores preferem atributos de dados para gerenciamento de tema. Configure o Tailwind para usar data-theme:

@import "tailwindcss";

/* Para Tailwind CSS v4+ */
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

Então controle o dark mode via atributo:

<html data-theme="dark">
  <body>
    <div class="bg-white dark:bg-black">
      <!-- Dark mode ativo quando data-theme="dark" -->
    </div>
  </body>
</html>

Persistindo a Preferência do Usuário

Implementação com localStorage

Os usuários esperam que sua escolha de tema persista. Aqui está uma solução completa que lembra as preferências enquanto respeita os padrões do sistema:

// Verificar preferência salva ou usar padrão do sistema
function getThemePreference() {
  const savedTheme = localStorage.getItem('theme');
  if (savedTheme) {
    return savedTheme;
  }
  return window.matchMedia('(prefers-color-scheme: dark)').matches 
    ? 'dark' 
    : 'light';
}

// Aplicar tema no carregamento
function applyTheme(theme) {
  if (theme === 'dark') {
    document.documentElement.classList.add('dark');
  } else {
    document.documentElement.classList.remove('dark');
  }
}

// Inicializar tema
applyTheme(getThemePreference());

// Função de alternância de tema
function toggleTheme() {
  const currentTheme = document.documentElement.classList.contains('dark') 
    ? 'dark' 
    : 'light';
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
  
  applyTheme(newTheme);
  localStorage.setItem('theme', newTheme);
}

Para prevenir um flash de tema incorreto no carregamento da página, adicione este script inline ao seu <head>:

<script>
  // Prevenir FOUC (Flash of Unstyled Content)
  if (localStorage.theme === 'dark' || 
      (!localStorage.theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark');
  }
</script>

Melhores Práticas para Dark Mode com Tailwind

Performance: Coloque scripts de detecção de tema no <head> para prevenir mudanças de layout. O script inline acima executa antes da página renderizar.

Acessibilidade: Garanta contraste de cor suficiente em ambos os temas. Dark mode não é apenas sobre inverter cores—mantenha a legibilidade com taxas de contraste adequadas (o padrão WCAG AA recomenda 4.5:1 para texto normal).

Testes: Sempre teste ambos os temas durante o desenvolvimento. Use as DevTools do navegador para alternar rapidamente prefers-color-scheme sem mudar as configurações do sistema.

Consistência de Cores: Use a paleta de cores do Tailwind sistematicamente. Por exemplo, se você usa gray-100 para fundos claros, considere gray-800 ou gray-900 para equivalentes no dark mode.

Conclusão

Implementar dark mode com Tailwind CSS requer código mínimo e nenhuma dependência externa. Seja escolhendo dark mode baseado no sistema ou alternância manual, a variante dark torna o estilo consciente de tema direto. Comece com dark mode automático para simplicidade, depois adicione controles manuais quando os usuários precisarem de mais controle sobre sua experiência de visualização.

Perguntas Frequentes

Sim, você pode implementar uma alternância de três vias que oferece opções claro, escuro e sistema. Armazene a escolha do usuário no localStorage e verifique se eles selecionaram o modo sistema para respeitar as preferências do SO.

Use filtros CSS para ajustes simples ou forneça fontes de imagem alternativas. Para ícones, considere usar currentColor em SVGs para que herdem a cor do texto, ou aplique ajustes de opacidade com utilitários do Tailwind.

Absolutamente. A variante dark funciona com qualquer utilitário do Tailwind, incluindo cores personalizadas definidas na sua configuração. Apenas prefixe qualquer classe com dark: para aplicá-la condicionalmente no dark mode.

Mínimo. A variante dark apenas adiciona regras CSS, não sobrecarga de JavaScript. A principal consideração é prevenir o flash de conteúdo sem estilo carregando scripts de detecção de tema cedo no head do documento.

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.