Lição 20 de 30

Dark Mode no Tailwind: Estratégia por Classe — Web Academy

O suporte a Modo Escuro (Dark Mode) deixou de ser um recurso supérfluo para se consolidar como um requisito indispensável de acessibilidade, conforto visual e economia de bateria em dispositivos OLED. No CSS tradicional, implementar temas alternados exige duplicar dezenas de seletores dentro de media queries @media (prefers-color-scheme: dark) ou injetar dezenas de variáveis CSS dinâmicas. No Tailwind CSS, o Dark Mode é tratado como um cidadão de primeira classe: com o modificador de variante dark:, você projeta temas claros e escuros de forma declarativa e atômica diretamente na marcação do seu componente.

📑 Índice do Conteúdo

1. A Filosofia do Modificador dark:

A mecânica do Tailwind é elegante: você define as cores e aparências do Modo Claro como padrão base e adiciona as variações escuras utilizando o prefixo dark:.

HTML5 7 linhas

<!-- Fundo branco no tema claro, ardósia escuro no tema dark -->
<div class="bg-white dark:bg-slate-900 text-slate-900 dark:text-slate-100 p-6 rounded-2xl border border-slate-200 dark:border-slate-800 transition-colors duration-200">
    <h3 class="font-bold text-lg">Ambiente de Desenvolvimento</h3>
    <p class="text-sm text-slate-600 dark:text-slate-400 mt-1">
        As cores se adaptam instantaneamente ao tema selecionado.
    </p>
</div>

<!-- Fundo branco no tema claro, ardósia escuro no tema dark -->
<div class="bg-white dark:bg-slate-900 text-slate-900 dark:text-slate-100 p-6 rounded-2xl border border-slate-200 dark:border-slate-800 transition-colors duration-200">
<h3 class="font-bold text-lg">Ambiente de Desenvolvimento</h3>
<p class="text-sm text-slate-600 dark:text-slate-400 mt-1">
As cores se adaptam instantaneamente ao tema selecionado.
</p>
</div>

🧪 Quer testar o toggle de Modo Escuro no Playground IDE?
Abrir no Playground IDE →

2. O Grande Duelo: Estratégia media vs. Estratégia class

Por padrão, o Tailwind CSS opera na estratégia media. Contudo, em aplicações de produção, você pode escolher como o tema deve ser acionado através da propriedade darkMode no seu tailwind.config.js:

1. Estratégia “media” (Predefinição Passiva)

O framework monitora a preferência do sistema operacional do visitante via prefers-color-scheme. Se o usuário estiver com o Windows, macOS ou Android em modo noturno, o site fica escuro automaticamente. Desvantagem: o usuário não tem como escolher um tema diferente para o seu site se o sistema operacional dele estiver configurado no modo claro.

2. Estratégia “class” / “selector” (Recomendada pela Indústria)

Os estilos dark: só são ativados quando a classe .dark estiver presente no elemento raiz <html>. Essa abordagem confere controle manual total: você pode fornecer um botão seletor de tema (toggle), salvar a escolha do usuário no localStorage e sincronizar com as preferências do sistema operacional de forma híbrida.

3. Configuração no tailwind.config.js e Script Anti-FOUC

Para ativar a estratégia manual por classe, declare a flag no arquivo de configuração do seu projeto:

JavaScript 9 linhas

// tailwind.config.js
module.exports = {
  darkMode: 'class', // Ou ___WZW_STR_1___ nas versões mais recentes
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {},
  },
  plugins: [],
}

// tailwind.config.js
module.exports = {
darkMode: 'class', // Ou 'selector' nas versões mais recentes
content: ['./src/**/*.{html,js}'],
theme: {
extend: {},
},
plugins: [],
}

Para evitar o terrível FOUC (Flash of Unstyled Content) — aquele incômodo clarão branco que pisca na tela antes de a página carregar —, adicione este pequeno script em linha diretamente no <head> do seu documento HTML, antes de qualquer folha de estilo:

HTML5 8 linhas

<!-- Script inline anti-flash inserido diretamente no <head> -->
<script>
    if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
        document.documentElement.classList.add('dark');
    } else {
        document.documentElement.classList.remove('dark');
    }
</script>

<!-- Script inline anti-flash inserido diretamente no <head> -->
<script>
if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
document.documentElement.classList.add('dark');
} else {
document.documentElement.classList.remove('dark');
}
</script>

4. Matriz Comparativa: Media Query vs. Alternância por Classe

Analise as diferenças estruturais antes de definir a arquitetura de temas da sua aplicação:

Critério	Estratégia media	Estratégia class
Gatilho de Ativação	Sistema Operacional (SO)	Classe `.dark` na tag `<html>`
Chave Seletora (Toggle)	Inviável sem alterar o tema do computador	100% suportada com botão interativo
Persistência no Navegador	Automática pelo sistema	Salva no `localStorage` do usuário
Controle pelo Usuário	Passivo	Ativo e Personalizado

5. Exemplo Prático: Card de Perfil com Alternador Funcional de Tema

O exemplo a seguir demonstra a alternância de temas na prática: um cartão elegante que adapta suas cores, bordas e sombras com base no estado da classe dark no documento, acompanhado por um botão de toggle com ícones dinâmicos de Sol e Lua:

HTML5 47 linhas

<div class="max-w-md mx-auto p-6">
 
    <!-- BOTÃO DE TOGGLE DE TEMA -->
    <div class="flex justify-end mb-4">
        <button 
            id="theme-toggle" 
            onclick="document.documentElement.classList.toggle('dark');"
            class="flex items-center gap-2 px-3 py-1.5 text-xs font-semibold rounded-lg border border-slate-300 dark:border-slate-700 bg-slate-100 dark:bg-slate-800 text-slate-700 dark:text-slate-300 hover:bg-slate-200 dark:hover:bg-slate-700 transition-colors">
            <span class="dark:hidden">🌙 Modo Escuro</span>
            <span class="hidden dark:inline">☀️ Modo Claro</span>
        </button>
    </div>
 
    <!-- CARD ADAPTÁVEL: MODO CLARO VS MODO ESCURO -->
    <div class="bg-white dark:bg-slate-900 border border-slate-200 dark:border-slate-800 rounded-3xl p-6 shadow-xl dark:shadow-black/60 transition-colors duration-300">
        
        <div class="flex items-center gap-4">
            <div class="size-14 rounded-2xl bg-emerald-100 dark:bg-emerald-950/80 border border-emerald-300 dark:border-emerald-700/50 flex items-center justify-center text-emerald-600 dark:text-emerald-400 font-bold text-xl">
                FE
            </div>
            <div>
                <h3 class="text-lg font-bold text-slate-900 dark:text-white transition-colors">
                    Flávio Estaiano
                </h3>
                <p class="text-xs text-slate-500 dark:text-slate-400 transition-colors">
                    Arquiteto de Software & Autor E-E-A-T
                </p>
            </div>
        </div>
 
        <div class="mt-6 pt-6 border-t border-slate-100 dark:border-slate-800/80 grid grid-cols-2 gap-4 text-center">
            <div class="bg-slate-50 dark:bg-slate-950/60 p-3 rounded-xl border border-slate-200/60 dark:border-slate-800">
                <span class="block text-xl font-extrabold text-slate-900 dark:text-white">144+</span>
                <span class="text-[11px] text-slate-500 dark:text-slate-400 uppercase tracking-wider font-medium">Ferramentas</span>
            </div>
            <div class="bg-slate-50 dark:bg-slate-950/60 p-3 rounded-xl border border-slate-200/60 dark:border-slate-800">
                <span class="block text-xl font-extrabold text-emerald-600 dark:text-emerald-400">100%</span>
                <span class="text-[11px] text-slate-500 dark:text-slate-400 uppercase tracking-wider font-medium">Autorais</span>
            </div>
        </div>
 
        <button class="w-full mt-6 py-2.5 bg-emerald-600 hover:bg-emerald-500 text-white font-semibold text-xs rounded-xl shadow-md transition-all active:scale-95">
            Acessar Perfil Completo
        </button>
    </div>
 
</div>

<div class="max-w-md mx-auto p-6">
<!-- BOTÃO DE TOGGLE DE TEMA -->
<div class="flex justify-end mb-4">
<button 
id="theme-toggle" 
onclick="document.documentElement.classList.toggle('dark');"
class="flex items-center gap-2 px-3 py-1.5 text-xs font-semibold rounded-lg border border-slate-300 dark:border-slate-700 bg-slate-100 dark:bg-slate-800 text-slate-700 dark:text-slate-300 hover:bg-slate-200 dark:hover:bg-slate-700 transition-colors">
<span class="dark:hidden">🌙 Modo Escuro</span>
<span class="hidden dark:inline">☀️ Modo Claro</span>
</button>
</div>
<!-- CARD ADAPTÁVEL: MODO CLARO VS MODO ESCURO -->
<div class="bg-white dark:bg-slate-900 border border-slate-200 dark:border-slate-800 rounded-3xl p-6 shadow-xl dark:shadow-black/60 transition-colors duration-300">
<div class="flex items-center gap-4">
<div class="size-14 rounded-2xl bg-emerald-100 dark:bg-emerald-950/80 border border-emerald-300 dark:border-emerald-700/50 flex items-center justify-center text-emerald-600 dark:text-emerald-400 font-bold text-xl">
FE
</div>
<div>
<h3 class="text-lg font-bold text-slate-900 dark:text-white transition-colors">
Flávio Estaiano
</h3>
<p class="text-xs text-slate-500 dark:text-slate-400 transition-colors">
Arquiteto de Software & Autor E-E-A-T
</p>
</div>
</div>
<div class="mt-6 pt-6 border-t border-slate-100 dark:border-slate-800/80 grid grid-cols-2 gap-4 text-center">
<div class="bg-slate-50 dark:bg-slate-950/60 p-3 rounded-xl border border-slate-200/60 dark:border-slate-800">
<span class="block text-xl font-extrabold text-slate-900 dark:text-white">144+</span>
<span class="text-[11px] text-slate-500 dark:text-slate-400 uppercase tracking-wider font-medium">Ferramentas</span>
</div>
<div class="bg-slate-50 dark:bg-slate-950/60 p-3 rounded-xl border border-slate-200/60 dark:border-slate-800">
<span class="block text-xl font-extrabold text-emerald-600 dark:text-emerald-400">100%</span>
<span class="text-[11px] text-slate-500 dark:text-slate-400 uppercase tracking-wider font-medium">Autorais</span>
</div>
</div>
<button class="w-full mt-6 py-2.5 bg-emerald-600 hover:bg-emerald-500 text-white font-semibold text-xs rounded-xl shadow-md transition-all active:scale-95">
Acessar Perfil Completo
</button>
</div>
</div>

🎯 Dica Pro: Evite Preto Puro (#000000) e Suavize Contrastes!

Um erro clássico cometido por desenvolvedores ao criar o Modo Escuro é utilizar preto puro (bg-black / #000000) com texto em branco absoluto (text-white / #ffffff). Essa combinação gera um contraste excessivo e agressivo que causa fadiga visual rápida aos olhos do usuário. No padrão de design moderno, prefira fundos em tons profundos de ardósia ou obsidiana como bg-slate-900 ou bg-slate-950 combinados com textos em cinza claro calibrado (text-slate-100 ou text-slate-200). Isso mantém a legibilidade impecável conforme a norma WCAG 2.2 e confere sofisticação à sua interface!

6. Ferramentas Correlatas da Rede Web-ZoneWare

Valide esquemas cromáticos e audite folhas de estilo escuras com utilitários da rede:

Playground Web IDE: Ambiente interativo para compor e simular temas com a classe dark em tempo real.
Central do Desenvolvedor Web: Mais de 144 utilitários práticos para front-ends e engenheiros full-stack.
Lição 06 de Tailwind CSS: Entenda a escala cromática nativa (50 a 950) que abastece o tema escuro.
Lição 45 do Curso de CSS: Veja como o Dark Mode é construído utilizando Variáveis CSS puras.
Limpador e Formatador CSS: Audite a sintaxe e reduza o peso das suas folhas de estilo.

7. Links Oficiais e Documentação de Referência

Consulte a documentação técnica oficial sobre o modificador dark:

🛠️ Laboratório Prático & Prática Imediata

Aplique o que você aprendeu nesta lição

Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online

⚡ Live Code Studio

Playground Web Online

Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.

⚡ Codificar no Playground IDE