@theme no Tailwind v4: cores, fontes e escalas da sua marca

@theme registra tokens que participam da API de utilitários do Tailwind v4. Uma variável --color-marca-500 cria classes como bg-marca-500 e text-marca-500; uma variável comum em :root não cria essas classes. Essa é a diferença entre configuração de compilador e valor CSS comum.

O tema da clínica terá cor, fonte e breakpoint. Você vai compilar cada token e ver o que nasce, sem depender de um tailwind.config.js da versão anterior.

Configuração CSS-first mora junto do CSS

O arquivo de entrada importa o framework e declara tokens no nível superior:

@import "tailwindcss";

@theme {
  --color-marca-500: oklch(68% 0.14 210);
  --color-marca-700: oklch(48% 0.12 210);
  --font-display: "Archivo", sans-serif;
}

Não coloque @theme dentro de .clinica ou media query. Theme variables definem quais utilidades existem durante a compilação e precisam estar no topo.

Namespace decide qual família nasce

O nome antes do asterisco é contrato. --color-* alimenta cor; --font-* alimenta font-family; --breakpoint-* cria variantes; --radius-* cria raios.

<h1 class="font-display text-marca-700">Patinha Feliz</h1>
<button class="bg-marca-500 hover:bg-marca-700">Agendar</button>

O CSS compilado confirmou a ligação:

Se você escrever --cor-marca-500, a variável pode existir como CSS, mas não gera bg-marca-500. O prefixo errado não é traduzido.

Um token cria várias utilidades relacionadas

Cor não pertence ao fundo. A mesma variável serve a texto, borda, preenchimento SVG e outras propriedades compatíveis.

<article class="border border-marca-500/30 bg-marca-500/10 text-marca-700">
  Consulta confirmada
</article>

Isso torna o token reutilizável sem acoplar “cor da marca” a um componente. Ainda assim, prefira nomes semânticos quando o produto cresce: acao, erro e surface comunicam função melhor que nome de matiz.

inline muda onde a referência é resolvida

Quando um token aponta para outra variável que muda num seletor, use @theme inline para a utilidade referenciar o valor final diretamente.

:root { --fonte-produto: "Archivo", sans-serif; }

@theme inline {
  --font-sans: var(--fonte-produto);
}

Sem inline, a utilidade pode apontar para var(--font-sans), e a resolução em outro nível da árvore surpreende quando a variável referenciada só existe num filho. No modo escuro, essa distinção é útil para tokens que mudam por classe.

Apagar a paleta padrão transforma escolha em regra

Você pode zerar um namespace e devolver apenas valores aprovados:

@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-marca-500: oklch(68% 0.14 210);
  --color-marca-700: oklch(48% 0.12 210);
}

Agora bg-sky-500 deixa de existir. Isso é útil em produto que precisa impedir cores fora do sistema, mas torna snippets de biblioteca incompatíveis. Faça a restrição depois de mapear necessidades de sucesso, aviso, erro, texto e superfície.

A régua global tem alcance grande

Redefinir --spacing altera padding, margin, gap, dimensões e algumas alturas de linha baseadas na mesma variável.

@theme {
  --spacing: 0.2rem;
}

<div class="gap-4 p-4 size-10">...</div>

Não use isso para corrigir um cartão apertado. Ajuste a classe do cartão. Uma mudança global precisa de inventário e revisão visual de todo o produto. Veja a régua de espaçamento antes de alterá-la.

Breakpoint customizado também é token

Um namespace de breakpoint cria variante:

@theme {
  --breakpoint-3xl: 120rem;
}

<section class="grid grid-cols-2 3xl:grid-cols-6">...</section>

O valor deve nascer do conteúdo, não de uma lista de aparelhos. Mantenha todos os breakpoints na mesma unidade para preservar a ordenação das media queries.

Migração da v3 é tradução por responsabilidade

Na v3, theme.extend.colors, fontFamily e screens eram objetos JavaScript. Na v4, os equivalentes comuns viram namespaces CSS.

export default {
  theme: {
    extend: {
      colors: { marca: '#0891b2' },
      fontFamily: { display: ['Archivo', 'sans-serif'] },
    },
  },
};

- colors: { marca: '#0891b2' }
- fontFamily: { display: ['Archivo', 'sans-serif'] }
+ --color-marca: #0891b2;
+ --font-display: "Archivo", sans-serif;

Plugins, presets e lógica JavaScript não são traduzidos linha a linha para tokens. Primeiro atualize usando a ferramenta oficial de upgrade e depois trate casos que realmente precisam de compatibilidade.

Tema compartilhado é um arquivo importável

Como a configuração é CSS, um monorepo pode publicar theme.css e importá-lo nos produtos:

@import "tailwindcss";
@import "@grupo-club/theme.css";

Mantenha no pacote apenas decisões comuns. Um token específico da tela de agenda não pertence à marca inteira. A lição de cores mostra como medir contraste antes de promover uma cor a token global.

Erro reproduzido: token usado antes de existir

Uma utility semântica só nasce quando o namespace do tema contém o token. Sem --color-acao, o CLI 4.3.3 recusou bg-acao:

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

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

O comando terminou com código 1. Declare --color-acao em @theme ou use um token já publicado; uma referência no componente não cria a API do tema.

Missão de contrato compilável

Crie --color-marca-500, --color-marca-700 e --font-display; use fundo, texto e font-family no HTML; compile e procure as três regras. Depois erre o prefixo de uma cor de propósito e confirme que a utilidade some. A missão termina quando você explica por que :root guarda um valor comum e @theme também altera a API de classes. O próximo passo é decidir se um padrão deve ser componente ou @apply.

Governe tokens como uma API

Um token publicado passa a ser dependência. Renomear --color-acao afeta HTML, componentes, documentação e talvez outros pacotes. Trate a mudança como migração: procure usos, ofereça período de transição quando há consumidores externos e remova o nome antigo só depois da atualização.

Documente intenção e contraste, não apenas valor. “Cyan 600” descreve aparência; “ação primária sobre superfície clara, aprovado para texto branco” descreve uso. Quando a marca muda, o nome semântico pode permanecer e o valor evolui sem rebatizar centenas de classes.

Evite tokens que copiam todo valor único de uma tela. Um sistema com 90 cores quase iguais não restringe decisão; apenas move os números para outro arquivo. Promova o que se repete com a mesma função e mantenha exceções locais, com justificativa. Faça revisão periódica de tokens sem uso e de valores arbitrários recorrentes.

No build, isole uma página sentinela que usa cada família aprovada e compare a saída ao mudar o tema. Esse teste não substitui revisão visual, mas acusa token que parou de gerar utility por prefixo incorreto. Combine-o com os pares medidos na lição de cores e com a arquitetura do guia completo. Um tema sólido é pequeno o bastante para ensinar e explícito o bastante para revisar.

Compile também uma fonte sem uso dos tokens e confira o que permanece. Essa observação separa variável sempre emitida de decisão gerada apenas quando alguma utility a consome.