Tailwind CSS: o que é e como a primeira classe vira CSS

Tailwind CSS é um compilador que transforma classes pequenas, como p-4 e bg-cyan-600, nas declarações CSS de que a página realmente precisa. Você continua escrevendo CSS, só escolhe as declarações por uma API de classes em vez de inventar um seletor para cada caixa.

O exemplo desta lição é a agenda de uma clínica. O objetivo é construir um botão visível, compilá-lo e enxergar a ligação entre o nome escrito no HTML e a regra que o navegador recebe. Se você ainda não tem o CLI, siga a instalação do Tailwind v4 antes de executar.

O botão antes e depois da linguagem utilitária

Em CSS comum, você dá um nome ao componente e concentra várias declarações nesse seletor. É um modelo válido e continua disponível num projeto Tailwind.

<button class="acao">Abrir agenda</button>

.acao {
  border-radius: 0.5rem;
  background: #0891b2;
  padding: 0.5rem 1rem;
  color: white;
  font-weight: 700;
}

No modelo utility-first, cada decisão recebe uma classe reconhecível. O elemento fica assim:

<button class="rounded-lg bg-cyan-600 px-4 py-2 font-bold text-white">
  Abrir agenda
</button>

Pense numa bancada com ferramentas identificadas. Você pega a chave para arredondar, a chave para pintar e a chave para espaçar. A analogia ajuda a entender a composição; o limite é que o compilador pode gerar regras com variáveis, estados e media queries, não apenas copiar uma declaração fixa.

A classe bg-cyan-600 vira uma regra verificável

O arquivo de entrada da versão 4 pode ter somente um import. Não é preciso criar tailwind.config.js para começar.

@import "tailwindcss";

O CLI lê os arquivos de origem como texto, reconhece os nomes completos e emite o CSS. Este foi o comando executado no diretório temporário da medição:

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

Dentro de pretty.css, as classes do botão apareceram desta forma:

.bg-cyan-600 {
  background-color: var(--color-cyan-600);
}
.px-4 {
  padding-inline: calc(var(--spacing) * 4);
}
.py-2 {
  padding-block: calc(var(--spacing) * 2);
}

O navegador nunca interpreta “Tailwind”. Ele recebe CSS normal. Essa distinção explica por que a aplicação continua funcionando depois do build sem carregar um runtime do framework no cliente.

Uma classe por decisão muda a manutenção

Uma classe utilitária costuma representar uma decisão pequena. font-bold escolhe peso; text-white escolhe cor; rounded-lg escolhe raio. Quando você abre o componente, enxerga o conjunto sem procurar um seletor em outro arquivo.

<article class="flex flex-col gap-4 rounded-xl bg-white p-6 shadow-lg">
  <h2 class="text-3xl font-bold text-slate-900">Consultas de hoje</h2>
  <p class="text-slate-600">Três horários confirmados.</p>
</article>

Isso não elimina a cascata. Se duas classes escrevem a mesma propriedade, a ordem das regras geradas decide o resultado. Também não transforma uma tela sem hierarquia numa boa interface. Você ainda precisa entender box model, contraste, Flexbox e Grid. A trilha de CSS é o lugar para fortalecer essa base.

O HTML comprido é um custo real

O atributo pode ficar grande. Esconder esse custo seria vender ferramenta em vez de ensinar. Num trecho repetido, extraia um componente de template ou React; num estilo raro, mantenha as classes perto do elemento. O ponto de corte não é um número mágico de caracteres, mas repetição com responsabilidade própria.

export function Botao({ children }) {
  return (
    <button className="rounded-lg bg-cyan-600 px-4 py-2 font-bold text-white">
      {children}
    </button>
  );
}

Não troque automaticamente esse componente por uma classe gigante com @apply. A lição sobre quando usar @apply mostra por que componente e CSS resolvem problemas diferentes.

O compilador lê texto, não executa o seu programa

Como a detecção é textual, uma classe montada em partes não existe durante o build. Este JSX parece razoável, mas não oferece bg-cyan-600 como sequência completa para o scanner.

const cor = 'cyan';
return <span className={`bg-${cor}-600 text-white`}>Confirmada</span>;

O resultado medido continha text-white, mas nenhuma regra bg-cyan-600 vinda dessa interpolação. A solução é mapear valores para strings completas:

const estilos = {
  confirmada: 'bg-cyan-600 text-white',
  cancelada: 'bg-rose-600 text-white',
};
return <span className={estilos[status]}>{texto}</span>;

Esse padrão também limita quais estilos um dado externo pode escolher. O guia classe Tailwind não funciona traz a árvore de diagnóstico quando uma regra some.

Erro reproduzido: uma utility que não existe

Inventar bg-marca sem declarar esse token não cria uma cor. Enviei este CSS pela entrada padrão do CLI 4.3.3:

@import "tailwindcss";
.qa { @apply bg-marca; }

printf '@import "tailwindcss"; .qa { @apply bg-marca; }\n' | npx @tailwindcss/cli@4.3.3 -i - -o /dev/null

O processo encerrou com código 1. Use uma utility existente ou publique o token no tema; trocar o nome apenas no HTML não ensina o compilador sobre a marca.

O que o Tailwind não decide por você

O framework não escolhe semântica HTML, ordem de foco, contraste, conteúdo nem arquitetura. text-slate-400 existe, mas pode reprovar contraste. order-first existe, mas pode separar a ordem visual da leitura por teclado. Uma classe disponível não é uma recomendação universal.

Também não é biblioteca de componentes. Ele fornece primitivas. O botão desta lição só vira componente quando você define estados, rótulo, comportamento e contrato de uso. É justamente essa liberdade que torna Tailwind útil em produtos com identidade própria e inadequado quando você procura uma interface pronta sem tomar decisões de design.

Primeiro teste com critério de sucesso

Crie um HTML com um cartão da clínica. Use p-6, rounded-xl, bg-white, text-slate-900 e um botão bg-cyan-600. Compile, abra o CSS gerado e procure .bg-cyan-600. A missão termina quando você aponta a classe no HTML, a regra no CSS e a mudança visual correspondente. Depois avance para espaçamento no Tailwind, onde essa mesma relação vira uma régua de layout.

Como revisar uma utility antes de adotá-la

Não avalie uma classe só pelo resultado visual imediato. Leia o CSS emitido, identifique a propriedade e teste o mesmo elemento com conteúdo maior. Um botão que funciona com “Salvar” pode quebrar com “Confirmar reagendamento”. Uma caixa que cabe no desktop pode impor largura mínima no mobile. A utility é correta quando expressa uma decisão adequada ao conteúdo, não apenas quando existe no catálogo.

Também confira a condição em volta da regra. Variantes podem produzir media query, pseudo-classe ou seletor de atributo. Se a regra está presente e não ativa, trocar a cor não corrige o estado. Use o painel Styles para ver o seletor e o painel Computed para ver o valor vencedor.

Por fim, observe remoção. Apague a única ocorrência de uma classe, compile de novo e confirme que a regra deixa a saída. Esse exercício mostra por que a detecção baseada nas fontes ajuda a manter o bundle ligado ao produto real. O guia completo de Tailwind coloca esse mecanismo dentro da ordem de estudo e dos critérios de adoção.