Como Adicionar Modo Escuro ao Seu Site ou App (Sem o Flash Branco)

Para adicionar modo escuro, defina as suas cores como tokens nomeados (fundo, texto, superfície, borda, destaque) em vez de valores fixos no código, dê a cada token um valor para o modo claro e outro para o escuro, e alterne entre eles com o recurso de mídia CSS prefers-color-scheme, para que o site siga a configuração do sistema do visitante. Se você também quer um botão manual, guarde a escolha no navegador e aplique-a com um pequeno script inline no head da página, para não haver flash branco ao carregar. Depois, confira o contraste, as imagens e os gráficos nos dois temas. Em um construtor de apps com IA, um prompt claro faz a maior parte disso; a verificação é onde está a qualidade.

Duas abordagens

A maioria dos apps funciona melhor com a segunda: respeitar o sistema por padrão e deixar as pessoas mudarem.

Comece pelos tokens de cor

Modo escuro dá trabalho quando as cores estão espalhadas pelo código como white, #333 e gray-100. Fica fácil quando cada cor vem de um pequeno conjunto de tokens nomeados:

Cada componente usa os nomes dos tokens. Trocar de tema, então, significa trocar um conjunto de valores, e não editar cada componente.

Dicas para a paleta escura:

• Evite preto puro e branco puro em áreas grandes; cinza muito escuro e branco suave são mais fáceis de ler.
• Mostre profundidade com superfícies mais claras, não com sombras — as sombras quase não aparecem em fundos escuros.
• Dessature um pouco as cores de marca vivas; elas podem brilhar de forma incômoda sobre fundos escuros.
• Mantenha o contraste legível. O nível AA do WCAG pede pelo menos 4,5:1 de contraste para texto normal. Textos cinza discretos muitas vezes falham nisso em temas escuros.

Com Tailwind CSS

O Tailwind é a ferramenta de estilo padrão em muitos apps criados com IA. Segundo a documentação de modo escuro do Tailwind, a variante dark: usa prefers-color-scheme por padrão, então classes como bg-white dark:bg-gray-900 seguem a configuração do sistema sem nenhum trabalho extra.

Para um botão manual no Tailwind v4, a documentação mostra como trocar a variante por uma classe em um elemento pai:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

Em seguida, o app adiciona ou remove a classe dark no elemento raiz. A documentação também sugere um script inline no head que aplica a escolha salva (ou a configuração do sistema) antes de a página ser pintada — exatamente como se evita o flash.

Evitando o flash branco

O flash acontece porque a página é pintada no modo claro, depois o JavaScript carrega, lê a escolha salva e muda para o escuro. A correção:

1. Coloque um pequeno script inline no head da página que lê o tema salvo e define a classe no elemento raiz antes de qualquer coisa ser renderizada.
2. Defina a propriedade CSS color-scheme para cada tema, para que os elementos desenhados pelo navegador (barras de rolagem, controles de formulário) combinem.
3. Dê à página uma cor de fundo explícita nos dois temas.
4. Se o app é renderizado no servidor, garanta que o servidor e o navegador concordem com o tema inicial, ou a página pode ser renderizada de novo e piscar.

Prompts de exemplo

Uma configuração completa:

Adicione modo escuro. Primeiro, substitua as cores fixas por tokens de tema (fundo, superfície, texto, texto secundário, borda, destaque), com valores para claro e escuro. Por padrão, siga a configuração de claro/escuro do sistema do visitante. Adicione um seletor de tema no cabeçalho com as opções Claro, Escuro e Sistema, guarde a escolha no localStorage e aplique-a com um script inline no head para não haver flash branco ao carregar. Defina color-scheme para cada tema. Mantenha o design do modo claro exatamente como está.

Corrigindo o que sobrou:

Verifique todas as páginas no modo escuro e corrija: textos com baixo contraste (busque pelo menos 4,5:1), fundos brancos fixos no código, bordas que somem, gráficos com texto escuro sobre fundo escuro e logos que desaparecem. Não altere o tema claro.

Imagens e gráficos:

Use uma versão clara do logo no modo escuro. Faça com que os eixos, as linhas de grade e os rótulos dos gráficos usem os tokens do tema. Dê às capturas de tela uma borda sutil no modo escuro para que não se misturem ao fundo.

Passo a passo

1. Audite as cores. Encontre as cores fixas e troque-as por tokens. Esta é a maior parte do trabalho.
2. Defina os valores escuros de cada token.
3. Siga o sistema com prefers-color-scheme (ou o dark: padrão do Tailwind).
4. Adicione um seletor se quiser um: Claro, Escuro, Sistema. Guarde a escolha no navegador; em apps com login, você também pode salvá-la no perfil do usuário.
5. Evite o flash com o script inline no head e com color-scheme.
6. Confira os pontos delicados: logos, ícones, imagens com fundo branco, gráficos, blocos de código, mapas, embeds, e-mails.
7. Teste os dois temas no desktop e no celular, com o sistema em claro e em escuro, e depois de um recarregamento forçado.

Erros comuns

• Inverter tudo. Um filtro que inverte as cores estraga fotos e cores de marca.
• Cores fixas deixadas para trás. Um card branco em uma página escura se destaca imediatamente.
• Texto cinza de baixo contraste. Fica elegante, mas falha na legibilidade.
• Flash branco ao carregar. Especialmente perceptível em celulares à noite.
• Esquecer embeds de terceiros. Mapas, vídeos e widgets podem continuar claros; verifique se têm uma opção escura.
• Botão com só dois estados. Depois que alguém clica, não consegue voltar a seguir o sistema.
• Quebrar o tema claro. Diga explicitamente no prompt que o design claro deve permanecer.

Checklist

• Todas as cores vêm de tokens de tema
• Segue a configuração do sistema por padrão
• Botão opcional com Claro, Escuro e Sistema, lembrado
• Sem flash branco ao carregar ou recarregar
• color-scheme definido para que controles de formulário e barras de rolagem combinem
• Contraste de texto de pelo menos 4,5:1 nos dois temas
• Logos, imagens, gráficos e embeds conferidos no modo escuro
• Tema claro sem alterações
• Testado no desktop e no celular

Modo escuro com o Mythex

Apps criados no Mythex usam Vite, React, TypeScript e Tailwind por padrão, então a abordagem com Tailwind acima se aplica diretamente: cole o prompt de configuração completa no chat e depois verifique o Preview nos dois temas e em tamanho de celular. A orientação do Mythex para prompts de design é nomear o que mudar e o que manter, e isso importa aqui — diga que o tema claro deve continuar como está. Veja Prompts de design e UI e, se uma alteração der errado, volte com um checkpoint.

Para mais sobre como acertar a aparência, veja como criar um app bonito com IA e como escrever prompts para construtores de apps com IA.

Perguntas