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

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

Duas abordagens

A maioria das apps funciona melhor com a segunda: respeitar o sistema por defeito e deixar as pessoas mudar.

Começar pelos tokens de cor

O modo escuro torna-se difícil quando as cores estão espalhadas pelo código como white, #333 e gray-100. Fica fácil quando todas as cores vêm de um pequeno conjunto de tokens com nome:

Cada componente usa os nomes dos tokens. Mudar de tema passa então a ser 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; o cinzento muito escuro e o branco não puro são mais fáceis de ler.
• Mostre profundidade com superfícies mais claras, não com sombras — as sombras quase não se veem em fundos escuros.
• Dessature ligeiramente as cores de marca muito vivas; podem brilhar de forma desconfortável sobre fundos escuros.
• Mantenha o contraste legível. O nível AA da WCAG exige pelo menos 4,5:1 de contraste para texto normal. O texto cinzento esbatido costuma falhar isto em temas escuros.

Com Tailwind CSS

O Tailwind é a ferramenta de estilos por defeito em muitas apps criadas com IA. Segundo a documentação de modo escuro do Tailwind, a variante dark: usa prefers-color-scheme por defeito, pelo que classes como bg-white dark:bg-gray-900 seguem a definição do sistema sem trabalho extra.

Para um botão manual no Tailwind v4, a documentação mostra como mudar a variante para uma classe num elemento pai:

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

Depois, a app adiciona ou remove a classe dark no elemento raiz. A documentação também sugere um script inline no cabeçalho que aplica a escolha guardada (ou a definição do sistema) antes de a página ser desenhada — que é exatamente a forma de evitar o flash.

Evitar o flash branco

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

1. Coloque um pequeno script inline no cabeçalho da página que lê o tema guardado 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 as partes desenhadas pelo navegador (barras de deslocação, controlos de formulário) combinem.
3. Dê à página uma cor de fundo explícita em ambos os temas.
4. Se a app for renderizada no servidor, certifique-se de que o servidor e o navegador concordam quanto ao tema inicial, ou a página pode voltar a renderizar 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 esbatido, contorno, destaque) com valores claros e escuros. Por defeito, use a definição do sistema do visitante. Adicione um seletor de tema no cabeçalho com as opções Claro, Escuro e Sistema, memorize a escolha no localStorage e aplique-a com um script inline no cabeçalho para não haver flash branco ao carregar. Defina color-scheme para cada tema. Mantenha exatamente como está o design claro atual.

Corrigir o que sobra:

Verifique todas as páginas em modo escuro e corrija: texto com contraste baixo (procure pelo menos 4,5:1), fundos brancos fixos, contornos que desaparecem, gráficos com texto escuro sobre fundos escuros e logótipos que somem. Não altere o tema claro.

Imagens e gráficos:

Use uma versão clara do logótipo em modo escuro. Faça com que os eixos, as linhas de grelha e as etiquetas dos gráficos usem tokens de tema. Dê às capturas de ecrã um contorno subtil em modo escuro para não se confundirem com o fundo.

Passo a passo

1. Auditar as cores. Encontre as cores fixas e substitua-as por tokens. Esta é a maior parte do trabalho.
2. Defina os valores escuros para cada token.
3. Siga o sistema com prefers-color-scheme (ou o dark: predefinido do Tailwind).
4. Adicione um botão se quiser um: Claro, Escuro, Sistema. Guarde a escolha no navegador; em apps com início de sessão também pode guardá-la no perfil do utilizador.
5. Evite o flash com o script inline no cabeçalho e com color-scheme.
6. Verifique as partes delicadas: logótipos, ícones, imagens com fundo branco, gráficos, blocos de código, mapas, incorporações.
7. Teste os dois temas em computador e telemóvel, com o sistema em claro e em escuro, e após um refresh completo.

Erros comuns

• Inverter tudo. Um filtro que inverte as cores estraga fotografias e cores de marca.
• Cores fixas esquecidas. Um cartão branco numa página escura salta logo à vista.
• Texto cinzento com pouco contraste. Fica elegante, mas é difícil de ler.
• Flash branco ao carregar. Nota-se sobretudo em telemóveis à noite.
• Esquecer incorporações de terceiros. Mapas, vídeos e widgets podem continuar claros; verifique se têm uma opção escura.
• Botão com só dois estados. Quando alguém clica, deixa de conseguir voltar a seguir o sistema.
• Estragar o tema claro. Diga explicitamente no prompt que o design claro deve manter-se.

Lista de verificação

• Todas as cores vêm de tokens de tema
• Segue a definição do sistema por defeito
• Botão opcional com Claro, Escuro e Sistema, memorizado
• Sem flash branco ao carregar ou atualizar
• color-scheme definido para os controlos de formulário e barras de deslocação combinarem
• Contraste do texto de pelo menos 4,5:1 nos dois temas
• Logótipos, imagens, gráficos e incorporações verificados em modo escuro
• Tema claro inalterado
• Testado em computador e telemóvel

Modo escuro com o Mythex

As apps criadas no Mythex usam Vite, React, TypeScript e Tailwind por defeito, pelo que a abordagem Tailwind acima se aplica diretamente: cole o prompt de configuração completa no chat e depois verifique a Pré-visualização nos dois temas e com tamanho de telemóvel. O conselho do Mythex para prompts de design é indicar o que mudar e o que manter, o que importa aqui — diga que o tema claro deve ficar como está. Veja Prompts de design e UI, e reverta com um checkpoint se uma alteração correr mal.

Para mais sobre como acertar no aspeto, veja como criar uma app com bom aspeto usando IA e como escrever prompts para construtores de apps com IA.

Perguntas