Tailwind não está aplicando as classes: as 6 causas

Quando uma classe Tailwind não aparece, descubra primeiro se a regra foi gerada. Se ela não está no CSS, investigue fonte e build; se está, investigue cascata e estado. Essa divisão reduz seis causas a duas famílias e evita editar configuração no escuro.

Todos os erros abaixo foram reproduzidos com o CLI 4.3.3 no Node 26.3.0. O caso de painel Styles foi adaptado para uma inspeção textual, porque não há screenshot confiável neste ambiente.

O teste de trinta segundos

Procure o seletor escapado no arquivo final. Para uma classe simples, grep -F é suficiente:

grep -F '.bg-emerald-500' saida.css

Se não houver saída, o navegador não tem regra para aplicar. Se houver, abra Computed e Styles e procure propriedade riscada, media query inativa ou seletor que não corresponde ao estado atual.

Causa 1: classe montada em runtime

O scanner não executa JSX. Este código não contém bg-emerald-500 como texto:

export function Etiqueta({ cor }) {
  return <span className={`bg-${cor}-500 rounded px-2`}>Status</span>;
}

Compilei essa fonte isoladamente e contei a regra esperada:

npx @tailwindcss/cli -i dynamic.css -o dynamic.out.css --minify
grep -c 'bg-emerald-500' dynamic.out.css

Mapeie entradas para strings completas. Isso também impede que uma cor externa vire uma classe arbitrária:

const estilos = {
  sucesso: 'bg-emerald-500 text-white',
  alerta: 'bg-amber-300 text-slate-950',
};
return <span className={estilos[tom]}>{children}</span>;

Causa 2: arquivo fora das fontes

Dependências, binários, arquivos ignorados e alguns caminhos de monorepo podem ficar fora da detecção automática. Registre a origem relativa ao CSS:

@import "tailwindcss" source("../src");
@source "../node_modules/@empresa/ui";

Para confirmar o diagnóstico, coloque temporariamente uma classe exclusiva no arquivo e procure a regra. Não adicione uma lista gigante de safelist antes de corrigir o caminho; isso mascara a causa.

Causa 3: build ou watch não entrega o arquivo certo

Confirme processo, horário e tamanho do artefato:

npx @tailwindcss/cli -i input.css -o public/app.css --watch
stat public/app.css

Depois confira o href ou import da aplicação. É comum recompilar dist/app.css e o HTML continuar carregando public/app.css. A instalação do Tailwind v4 separa os fluxos CLI, Vite e PostCSS para não manter dois builds concorrentes.

Causa 4: @apply recebeu utilidade desconhecida

Reproduzi um token inexistente:

.cartao {
  @apply bg-clinica-500;
}

npx @tailwindcss/cli -i unknown.css -o unknown-output.css

Declare --color-clinica-500 em @theme ou corrija o nome. A lição de @theme mostra o contrato dos namespaces.

Causa 5: a regra existe, mas perdeu na cascata

Este HTML pode receber CSS legado mais específico:

<button id="salvar" class="bg-cyan-600">Salvar</button>

#salvar { background: #334155; }
.bg-cyan-600 { background-color: var(--color-cyan-600); }

O id vence por especificidade, independentemente da intenção. No DevTools, background-color da utility aparece riscado. Corrija o seletor legado, a camada ou a responsabilidade; não comece espalhando !important.

Causa 6: tutorial da v3 num projeto v4

Se o tutorial pede tailwindcss init, content num config obrigatório ou bg-opacity-*, confira a versão. Na v4, o fluxo inicial é CSS-first:

@import "tailwindcss";

npx @tailwindcss/cli -i input.css -o output.css

Misturar gera arquivos que não participam da pipeline. Consulte a documentação da versão instalada e migre deliberadamente em vez de copiar mais configuração.

A árvore na ordem em que eu uso

1. A regra existe no CSS? Se não, verifique nome completo, fonte e build.
2. O arquivo certo chegou ao navegador? Confira URL e horário.
3. A variante está ativa? Teste largura, hover, foco, dark e atributo.
4. A declaração perdeu na cascata? Leia Styles e Computed.
5. O nome pertence à versão instalada? Consulte a referência oficial.

Depois da correção, remova safelists e testes temporários. Reproduza o caso numa fonte mínima e adicione uma verificação ao componente. Se o problema veio de classes dinâmicas em React, aplique o mapa de strings da lição de componentes. Volte ao guia da trilha quando o erro revelar uma lacuna de base, não apenas um typo.

Guarde uma reprodução mínima do incidente

Copie para uma pasta temporária apenas CSS de entrada, uma fonte com a classe e o comando exato. Use source(none) para impedir que arquivos vizinhos escondam o problema. Se o caso desaparece, a diferença entre o projeto e a reprodução é evidência: caminho de fonte, plugin, ordem de import ou regra legada.

Registre versão do Node, CLI e integração. “Tailwind 4” não basta quando um patch altera comportamento ou mensagem. Guarde o trecho do erro literal, mas remova caminhos pessoais e dados do produto antes de compartilhar. Uma reprodução boa permite que outra pessoa execute e obtenha o mesmo resultado.

Depois acrescente as partes uma por vez. Primeiro tema, depois plugins, depois CSS legado e por fim framework hospedeiro. O passo que reintroduz a falha identifica a fronteira. Essa técnica é mais rápida que alternar seis classes na tela completa sem saber qual camada respondeu.

Quando corrigir, escreva uma prevenção proporcional. Classe dinâmica pede mapa estático e teste; fonte ausente pede configuração explícita; watch morto pede script e monitoramento; cascata pede reduzir seletor ou organizar layer. Não adicione safelist global para todo incidente. Ela aumenta bundle e conserva o erro de arquitetura.

Por fim, ensine o sinal à equipe: regra ausente é build, regra riscada é cascata, variante fora da condição é estado. Essa frase reduz o tempo da próxima análise e conecta o erro à instalação CSS-first, em vez de transformar cada ocorrência num ritual de reinstalação.

Repita o comando depois da correção e guarde o resultado ao lado da reprodução. Uma explicação sem evidência fecha o chamado, mas não prova que a regra voltou ao artefato que chega ao navegador.