# Tailwind e tokens: instruções para agentes de IA

- Página: Tailwind CSS v4: @theme, design tokens e CSS moderno (https://brasilgeo.ai/leadlovers2026/design/tailwind/)
- Revisado em: 2026-11-16
- JSON com o mesmo conteúdo: https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.json
- Índice dos guias de Design para agentes: https://brasilgeo.ai/leadlovers2026/design/llms.txt
- Esquema: design-guia-para-agentes/v1

Cor, espaçamento e tipografia entram como tokens num bloco @theme antes da primeira tela, e todas as telas leem dali. Aparência vira classe do Tailwind v4, comportamento vira CSS em camadas, e recurso novo de CSS entra pela faixa do Baseline. Resultado: base visual consistente, contraste AA nos dois temas e zero hexadecimal solto nos componentes.

## Quando consultar

- Iniciar projeto ou landing page com Tailwind v4 e definir a base visual.
- Converter paleta, DESIGN.md ou JSON de tokens (DTCG) em @theme.
- Revisar código gerado por IA com cor fixa, classe concatenada ou CSS fora de camadas.
- Implementar tema claro e escuro, ou várias marcas no mesmo componente.
- Derivar hover, borda e véu de uma cor de marca.
- Decidir se um recurso novo de CSS (light-dark, anchor positioning, @scope) vai para produção.
- Escrever a política de CSS no arquivo de instruções do repositório (CLAUDE.md, AGENTS.md).

## Regras

- **TWD-01** (obrigatória). Declare os tokens antes da primeira tela, na ordem cor, espaçamento, tipografia, no bloco @theme do CSS principal. Por quê: Sem tokens prévios a máquina adivinha e a consistência some na segunda ou terceira tela.
- **TWD-02** (obrigatória). Dê aos tokens nome de papel (--color-text-secondary, --color-action), nunca nome de tom (--color-slate-700). Por quê: O papel diz onde o valor é usado e se adapta ao tema escuro.
- **TWD-03** (obrigatória). Proíba hexadecimal e cor arbitrária (bg-[#8A2D10], color: #1a1a1a) em componente; varra por hex cru antes de entregar. Meta: zero. Por quê: Hex fixo é o erro de contraste número um em código gerado: preto sobre preto no tema escuro.
- **TWD-04** (obrigatória). Escreva nomes completos de classe. Nunca monte classe por concatenação (bg-${cor}-500); use mapa estático com as strings inteiras. Por quê: O compilador lê texto puro; a classe montada não gera CSS e falha em silêncio.
- **TWD-05** (obrigatória). Decida o destino pelo que a regra descreve: aparência de tela vira classe no JSX, comportamento do sistema vira CSS em arquivo, o que se repete vira token. Por quê: A divisão em três lugares corta bug visual em dia de lançamento.
- **TWD-06** (obrigatória). Declare a ordem das camadas na primeira linha do CSS global (@layer theme, base, components, utilities), com utilities por último, e evite !important. Por quê: Entre declarações normais, a última camada vence; o utilitário supera o componente sem exclamação.
- **TWD-07** (obrigatória). Não deixe regra normal de CSS próprio fora de camada; coloque-a em @layer components. Por quê: Regra normal sem camada vence todas as camadas, mesmo com 1 px contra 6 px, e apaga estilos do portal.
- **TWD-08** (obrigatória). Meça contraste AA de cada par nos dois temas: 4,5:1 em texto normal, 3:1 em texto grande. Meça de novo cada tom derivado por cálculo. Por quê: Piso da WCAG 2.2 (1.4.3); 95,9% das home pages falham em WCAG (WebAIM Million 2026).
- **TWD-09** (obrigatória). Dê a alvos de toque no mínimo 24 por 24 px CSS; nas ações principais use 44 por 44 px (min-h-11). Por quê: 24 px é o mínimo AA (2.5.8); 44 px é o confortável, AAA (2.5.5).
- **TWD-10** (obrigatória). Gere cores em OKLCH e derive estados com color-mix(in oklch, var(--marca) 88%, white), sem criar hex novo. Por quê: OKLCH e color-mix são Widely Available desde 09/11/2025; in oklch evita o cinza da mistura em sRGB.
- **TWD-11** (obrigatória). Adote por faixa do Baseline: Widely Available entra livre; Newly Available só atrás de @supports com fallback funcional; fora do Baseline só sob pedido, como melhoria que degrada limpa. Por quê: O Chrome passa a ciclos de duas semanas na versão 153 (08/09/2026); política escrita virou manutenção básica.
- **TWD-12** (obrigatória). Teste no @supports a propriedade exata usada no código e confirme o selo no webstatus.dev ou caniuse antes de afirmá-lo. Por quê: Testar outra propriedade da família dá falsa segurança; o agente desconhece o que veio após o treinamento.
- **TWD-13** (recomendada). Use espaçamento em base 4 px, tipografia em poucos tamanhos e um único regime de raio (pílula, médio ou reto). Por quê: A auditoria de 26 sites de alto padrão converge para base 4 px e três regimes de raio.
- **TWD-14** (recomendada). Em componente reutilizável, use container query (@container, @sm:, @md:) com contêiner declarado no elemento que o envolve, no lugar de media query. Por quê: O mesmo componente entra em colunas de 280 e 520 px sem a janela mudar.
- **TWD-15** (recomendada). Resolva estado por prefixo antes de criar useState: focus-visible:, group-hover:, peer-checked:, disabled:, motion-safe:, dark:, data-*, aria-*, has-*. Por quê: O CSS resolve o que seria mais um estado em JavaScript.
- **TWD-16** (recomendada). Gere o CSS dos tokens da origem (JSON DTCG ou DESIGN.md), versione a origem e falhe o build com alias quebrado ou contraste abaixo de 4,5:1. Por quê: Corrigir só o arquivo derivado deixa a origem divergente.
- **TWD-17** (recomendada). Cole a política Baseline no arquivo de instruções do agente, com data de revisão, em menos de 200 linhas. Por quê: Instrução é contexto; bloqueio garantido exige hook (documentação do Claude Code).

## Decisões rápidas

| Situação | Escolha | Evite |
| --- | --- | --- |
| A regra descreve a aparência de uma tela | Classe do Tailwind ao lado do elemento | CSS-in-JS salvo necessidade explícita |
| A regra descreve comportamento do sistema (cascata, herança, grade do componente) | Arquivo de CSS em @layer components, usando tokens por var() | Regra normal fora de camada |
| A decisão se repete em toda parte (cor, espaço, fonte, raio) | Token no @theme com nome de papel | Valor solto ou bg-[#hex] |
| Widely Available: container queries, OKLCH, color-mix, subgrid, :has() | Usar livre, sem @supports | Biblioteca para o que o CSS já faz |
| Newly Available: light-dark, contrast-color, @scope, popover, anchor positioning, style queries, field-sizing, view transitions no mesmo documento | @supports com fallback funcional na linha anterior | Usar sem retaguarda |
| Fora do Baseline: carrossel CSS, @function, if(), masonry (grid-lanes), corner-shape, view transitions entre documentos | Só sob pedido, como melhoria que degrada limpa | Depender em produção |
| Tema claro e escuro por botão | color-scheme em [data-theme] e tokens que mudam por tema | Hex fixo em componente |
| Hover, ativo ou borda da cor de marca | color-mix(in oklch, var(--marca) 88%, white) | Manter 32 valores à mão (8 matizes por 4 estados) |
| Classe depende de variável em execução | Mapa estático de strings completas, ou @source inline() | Template string bg-${cor} |

## Números de referência

| Valor | Para quê | Fonte |
| --- | --- | --- |
| 4.3.3 (16/07/2026) | Versão estável do Tailwind no npm em 02/10/2026; confira o package.json do código gerado | registro npm, citado no guia |
| 3,78x (378 para 100 ms); 8,8x; 182x | Ganho de build completo, rebuild incremental e rebuild sem CSS novo da v4.0 (22/01/2025) | anúncio oficial do Tailwind v4.0 |
| 4,5:1 e 3:1 | Contraste AA em texto normal e texto grande | WCAG 2.2, critério 1.4.3 |
| 24 px (AA) e 44 px (AAA) | Alvo de toque mínimo e confortável | WCAG 2.2, critérios 2.5.8 e 2.5.5 |
| 95,9% e 83,9% | Home pages com falha de WCAG e com contraste baixo (34 instâncias por página) | WebAIM Million, 2026 |
| 1200 px em 25 de 26 sites | Largura máxima do contêiner de conteúdo | auditoria de 26 sites de alto padrão |
| base 4 px; 80 px entre seções | Escala de espaçamento e respiro vertical | auditoria de 26 sites |
| raio: pílula, médio (8 a 16 px no pedido pronto) e reto (0 a 4 px) | Três regimes de canto; escolha um | auditoria de 26 sites |
| 09/11/2025 | OKLCH e color-mix(): Widely Available (container queries desde 14/08/2025, subgrid desde 15/03/2026) | Baseline, web-features, 18/08/2026 |
| light-dark(): Newly desde 13/05/2024; contrast-color(): Newly desde 10/04/2026 | Exigem @supports; contrast-color devolve só preto ou branco e, segundo a MDN, comumente garante AA | Baseline, MDN |

## Erros comuns e a correção

- Erro: Hexadecimal fixo ou bg-[#hex] no componente. Corrija: Use token de papel (bg-action, text-ink) e rode varredura por hex cru.
- Erro: Classe montada por concatenação (bg-${cor}-500) Corrija: Use mapa estático { azul: "bg-action" } com strings completas.
- Erro: tailwind.config.js e Sass em projeto v4. Corrija: Mova os tokens para @theme, use aninhamento nativo e migre com npx @tailwindcss/upgrade em branch novo.
- Erro: Regra de CSS próprio fora de @layer vencendo os utilitários. Corrija: Coloque em @layer components e declare utilities por último.
- Erro: @media (min-width) em componente reutilizável. Corrija: Declare container no pai e use @container.
- Erro: Animar height, padding ou margem; animação infinita. Corrija: Anime opacity e transform, finitas, com reduce-motion.
- Erro: Cor de DESIGN.md sem aspas no YAML. Corrija: Escreva "#9C3D1E" entre aspas; sem elas o # abre comentário e a cor some sem erro.

## Padrões de código

### Bloco @theme com tokens de papel

Primeira sessão do projeto, antes da primeira tela.

```css
@import "tailwindcss";

@theme {
  /* cor: papéis, não tons */
  --color-surface: oklch(0.99 0.005 80);
  --color-ink: oklch(0.2 0.02 60);
  --color-action: oklch(0.45 0.13 40);
  --color-on-action: oklch(0.99 0.005 80);
  /* espaçamento em base 4 px */
  --spacing-xs: 4px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-section: 80px;
  /* tipografia e forma */
  --font-body: system-ui, sans-serif;
  --text-body: 1rem;
  --text-body--line-height: 1.6;
  --radius-md: 8px;
}
```

### Cor derivada com color-mix

Hover, active e borda a partir de uma cor de marca.

```css
.botao {
  background: var(--color-action);
  color: var(--color-on-action);
}
.botao:hover {
  /* in oklch evita o cinza da mistura em sRGB; meça o contraste do resultado */
  background: color-mix(in oklch, var(--color-action) 88%, white);
}
.cartao {
  border: 1px solid color-mix(in oklch, var(--color-ink) 15%, transparent);
}
```

### Tema claro e escuro por tokens

Tema por botão com data-theme, sem mudar nenhuma classe.

```css
@import "tailwindcss";
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

:root { --app-surface: #ffffff; --app-ink: #172238; --app-action: #185c96; --app-on-action: #ffffff; }
:root[data-theme="dark"] { --app-surface: #101827; --app-ink: #f0f4ff; --app-action: #91cbff; --app-on-action: #101827; }

/* ponte única, no nível superior; inline mantém var() vivo na troca de tema */
@theme inline {
  --color-surface: var(--app-surface);
  --color-ink: var(--app-ink);
  --color-action: var(--app-action);
  --color-on-action: var(--app-on-action);
}
```

### Política de adoção Baseline

Colar no CLAUDE.md ou AGENTS.md do repositório.

```markdown
## Política de CSS de plataforma (Baseline), revisada em AAAA-MM-DD
- Widely Available: use livremente, sem @supports.
- Newly Available: SEMPRE atrás de @supports com fallback funcional.
- Fora do Baseline: só se eu pedir, como melhoria que degrada.
- Antes de afirmar o selo de um recurso, confirme no webstatus.dev ou caniuse;
  não presuma pelo treinamento.
- Prefira o nativo do navegador a uma dependência nova quando cobrir o requisito.
- Cor só por token; nunca hex em componente. Nomes de classe sempre completos.
```

## Checklist antes de entregar

- [ ] Cor, espaçamento e tipografia estão no @theme, com nomes de papel.
- [ ] Varredura por hexadecimal e bg-[#hex] fora do @theme retorna zero.
- [ ] Nenhuma classe montada por concatenação; mapas de variantes com strings completas.
- [ ] Ordem de camadas declarada no topo, utilities por último, sem regra normal fora de camada nem !important.
- [ ] Contraste de cada par conferido nos dois temas, inclusive tons derivados.
- [ ] Tema troca por data-theme sem mudar classe no DOM.
- [ ] Todo recurso Newly Available está atrás de @supports com a propriedade exata e fallback testado.
- [ ] Componentes reutilizáveis medem o contêiner (@container), não a janela.
- [ ] Política de adoção colada no arquivo de instruções do agente, com data de revisão.

## Ferramentas citadas

- **Tailwind CSS 4.3.3**: Utilitários com configuração em @theme.
- **@tailwindcss/upgrade (Node 20+)**: Migração da v3 para a v4, com revisão do diff.
- **Lightning CSS**: Minificação e prefixo do CSS fora do Tailwind.
- **Style Dictionary, Tokens Studio, Terrazzo**: Implementações de referência do DTCG 2025.10.
- **@google/design.md (lint, diff, export)**: Conferir o DESIGN.md (alfa) e gerar o tema do Tailwind.

## Onde aprofundar na página

- [Tokens antes da primeira tela, DTCG e OKLCH](https://brasilgeo.ai/leadlovers2026/design/tailwind/#tokens)
- [Tailwind v4: diretivas, motor e container queries](https://brasilgeo.ai/leadlovers2026/design/tailwind/#tailwind)
- [Onde cada regra mora: camadas, @scope, Lightning CSS](https://brasilgeo.ai/leadlovers2026/design/tailwind/#divisao)
- [Armadilhas de código gerado por IA e prefixos de estado](https://brasilgeo.ai/leadlovers2026/design/tailwind/#armadilhas)
- [Cor derivada, light-dark() e contrast-color()](https://brasilgeo.ai/leadlovers2026/design/tailwind/#cor-derivada)
- [Política Baseline, masonry e calc-size()](https://brasilgeo.ai/leadlovers2026/design/tailwind/#plataforma)
- [Medidas dos 26 sites de alto padrão](https://brasilgeo.ai/leadlovers2026/design/tailwind/#medidas)

## Guias relacionados

- [Design (entrada da pasta)](https://brasilgeo.ai/leadlovers2026/design/): Menu geral do Design e decisões de identidade antes de fechar os tokens. Instruções: https://brasilgeo.ai/leadlovers2026/design/agentes.md
- [React](https://brasilgeo.ai/leadlovers2026/design/react/): Estrutura de componentes e estado em React. Instruções: https://brasilgeo.ai/leadlovers2026/design/react/agentes.md
- [Navegação](https://brasilgeo.ai/leadlovers2026/design/navegacao/): Menus, abas, sumário e paleta de comandos nativos. Instruções: https://brasilgeo.ai/leadlovers2026/design/navegacao/agentes.md
- [Botões](https://brasilgeo.ai/leadlovers2026/design/botoes/): Estados, foco e alvo de toque dos botões sobre os tokens. Instruções: https://brasilgeo.ai/leadlovers2026/design/botoes/agentes.md
- [frontend-2027](https://brasilgeo.ai/leadlovers2026/design/frontend2027/): Paleta vibrante, escala display e movimento além da base. Instruções: https://brasilgeo.ai/leadlovers2026/design/frontend2027/agentes.md

## Fontes primárias

- [Definição de Baseline (Newly e Widely Available)](https://web.dev/baseline)
- [webstatus.dev, base do pacote web-features](https://webstatus.dev)
