{
  "esquema": "design-guia-para-agentes/v1",
  "guia": "tailwind",
  "nome": "Tailwind e tokens",
  "titulo": "Tailwind CSS v4: @theme, design tokens e CSS moderno",
  "descricao": "Tailwind CSS v4 na prática: configuração no @theme, design tokens em OKLCH, a versão 4.3 estável e os erros de classe que a IA comete na landing.",
  "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/",
  "arquivos": {
    "markdown": "https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md",
    "json": "https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.json",
    "indice": "https://brasilgeo.ai/leadlovers2026/design/llms.txt"
  },
  "revisadoEm": "2026-11-16",
  "idioma": "pt-BR",
  "resumo": "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.",
  "quandoUsar": [
    "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": [
    {
      "id": "TWD-01",
      "nivel": "obrigatória",
      "regra": "Declare os tokens antes da primeira tela, na ordem cor, espaçamento, tipografia, no bloco @theme do CSS principal.",
      "porque": "Sem tokens prévios a máquina adivinha e a consistência some na segunda ou terceira tela."
    },
    {
      "id": "TWD-02",
      "nivel": "obrigatória",
      "regra": "Dê aos tokens nome de papel (--color-text-secondary, --color-action), nunca nome de tom (--color-slate-700).",
      "porque": "O papel diz onde o valor é usado e se adapta ao tema escuro."
    },
    {
      "id": "TWD-03",
      "nivel": "obrigatória",
      "regra": "Proíba hexadecimal e cor arbitrária (bg-[#8A2D10], color: #1a1a1a) em componente; varra por hex cru antes de entregar. Meta: zero.",
      "porque": "Hex fixo é o erro de contraste número um em código gerado: preto sobre preto no tema escuro."
    },
    {
      "id": "TWD-04",
      "nivel": "obrigatória",
      "regra": "Escreva nomes completos de classe. Nunca monte classe por concatenação (bg-${cor}-500); use mapa estático com as strings inteiras.",
      "porque": "O compilador lê texto puro; a classe montada não gera CSS e falha em silêncio."
    },
    {
      "id": "TWD-05",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "A divisão em três lugares corta bug visual em dia de lançamento."
    },
    {
      "id": "TWD-06",
      "nivel": "obrigatória",
      "regra": "Declare a ordem das camadas na primeira linha do CSS global (@layer theme, base, components, utilities), com utilities por último, e evite !important.",
      "porque": "Entre declarações normais, a última camada vence; o utilitário supera o componente sem exclamação."
    },
    {
      "id": "TWD-07",
      "nivel": "obrigatória",
      "regra": "Não deixe regra normal de CSS próprio fora de camada; coloque-a em @layer components.",
      "porque": "Regra normal sem camada vence todas as camadas, mesmo com 1 px contra 6 px, e apaga estilos do portal."
    },
    {
      "id": "TWD-08",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "Piso da WCAG 2.2 (1.4.3); 95,9% das home pages falham em WCAG (WebAIM Million 2026)."
    },
    {
      "id": "TWD-09",
      "nivel": "obrigatória",
      "regra": "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).",
      "porque": "24 px é o mínimo AA (2.5.8); 44 px é o confortável, AAA (2.5.5)."
    },
    {
      "id": "TWD-10",
      "nivel": "obrigatória",
      "regra": "Gere cores em OKLCH e derive estados com color-mix(in oklch, var(--marca) 88%, white), sem criar hex novo.",
      "porque": "OKLCH e color-mix são Widely Available desde 09/11/2025; in oklch evita o cinza da mistura em sRGB."
    },
    {
      "id": "TWD-11",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "O Chrome passa a ciclos de duas semanas na versão 153 (08/09/2026); política escrita virou manutenção básica."
    },
    {
      "id": "TWD-12",
      "nivel": "obrigatória",
      "regra": "Teste no @supports a propriedade exata usada no código e confirme o selo no webstatus.dev ou caniuse antes de afirmá-lo.",
      "porque": "Testar outra propriedade da família dá falsa segurança; o agente desconhece o que veio após o treinamento."
    },
    {
      "id": "TWD-13",
      "nivel": "recomendada",
      "regra": "Use espaçamento em base 4 px, tipografia em poucos tamanhos e um único regime de raio (pílula, médio ou reto).",
      "porque": "A auditoria de 26 sites de alto padrão converge para base 4 px e três regimes de raio."
    },
    {
      "id": "TWD-14",
      "nivel": "recomendada",
      "regra": "Em componente reutilizável, use container query (@container, @sm:, @md:) com contêiner declarado no elemento que o envolve, no lugar de media query.",
      "porque": "O mesmo componente entra em colunas de 280 e 520 px sem a janela mudar."
    },
    {
      "id": "TWD-15",
      "nivel": "recomendada",
      "regra": "Resolva estado por prefixo antes de criar useState: focus-visible:, group-hover:, peer-checked:, disabled:, motion-safe:, dark:, data-*, aria-*, has-*.",
      "porque": "O CSS resolve o que seria mais um estado em JavaScript."
    },
    {
      "id": "TWD-16",
      "nivel": "recomendada",
      "regra": "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.",
      "porque": "Corrigir só o arquivo derivado deixa a origem divergente."
    },
    {
      "id": "TWD-17",
      "nivel": "recomendada",
      "regra": "Cole a política Baseline no arquivo de instruções do agente, com data de revisão, em menos de 200 linhas.",
      "porque": "Instrução é contexto; bloqueio garantido exige hook (documentação do Claude Code)."
    }
  ],
  "decisoes": [
    {
      "situacao": "A regra descreve a aparência de uma tela",
      "escolha": "Classe do Tailwind ao lado do elemento",
      "evitar": "CSS-in-JS salvo necessidade explícita"
    },
    {
      "situacao": "A regra descreve comportamento do sistema (cascata, herança, grade do componente)",
      "escolha": "Arquivo de CSS em @layer components, usando tokens por var()",
      "evitar": "Regra normal fora de camada"
    },
    {
      "situacao": "A decisão se repete em toda parte (cor, espaço, fonte, raio)",
      "escolha": "Token no @theme com nome de papel",
      "evitar": "Valor solto ou bg-[#hex]"
    },
    {
      "situacao": "Widely Available: container queries, OKLCH, color-mix, subgrid, :has()",
      "escolha": "Usar livre, sem @supports",
      "evitar": "Biblioteca para o que o CSS já faz"
    },
    {
      "situacao": "Newly Available: light-dark, contrast-color, @scope, popover, anchor positioning, style queries, field-sizing, view transitions no mesmo documento",
      "escolha": "@supports com fallback funcional na linha anterior",
      "evitar": "Usar sem retaguarda"
    },
    {
      "situacao": "Fora do Baseline: carrossel CSS, @function, if(), masonry (grid-lanes), corner-shape, view transitions entre documentos",
      "escolha": "Só sob pedido, como melhoria que degrada limpa",
      "evitar": "Depender em produção"
    },
    {
      "situacao": "Tema claro e escuro por botão",
      "escolha": "color-scheme em [data-theme] e tokens que mudam por tema",
      "evitar": "Hex fixo em componente"
    },
    {
      "situacao": "Hover, ativo ou borda da cor de marca",
      "escolha": "color-mix(in oklch, var(--marca) 88%, white)",
      "evitar": "Manter 32 valores à mão (8 matizes por 4 estados)"
    },
    {
      "situacao": "Classe depende de variável em execução",
      "escolha": "Mapa estático de strings completas, ou @source inline()",
      "evitar": "Template string bg-${cor}"
    }
  ],
  "numeros": [
    {
      "valor": "4.3.3 (16/07/2026)",
      "uso": "Versão estável do Tailwind no npm em 02/10/2026; confira o package.json do código gerado",
      "fonte": "registro npm, citado no guia"
    },
    {
      "valor": "3,78x (378 para 100 ms); 8,8x; 182x",
      "uso": "Ganho de build completo, rebuild incremental e rebuild sem CSS novo da v4.0 (22/01/2025)",
      "fonte": "anúncio oficial do Tailwind v4.0"
    },
    {
      "valor": "4,5:1 e 3:1",
      "uso": "Contraste AA em texto normal e texto grande",
      "fonte": "WCAG 2.2, critério 1.4.3"
    },
    {
      "valor": "24 px (AA) e 44 px (AAA)",
      "uso": "Alvo de toque mínimo e confortável",
      "fonte": "WCAG 2.2, critérios 2.5.8 e 2.5.5"
    },
    {
      "valor": "95,9% e 83,9%",
      "uso": "Home pages com falha de WCAG e com contraste baixo (34 instâncias por página)",
      "fonte": "WebAIM Million, 2026"
    },
    {
      "valor": "1200 px em 25 de 26 sites",
      "uso": "Largura máxima do contêiner de conteúdo",
      "fonte": "auditoria de 26 sites de alto padrão"
    },
    {
      "valor": "base 4 px; 80 px entre seções",
      "uso": "Escala de espaçamento e respiro vertical",
      "fonte": "auditoria de 26 sites"
    },
    {
      "valor": "raio: pílula, médio (8 a 16 px no pedido pronto) e reto (0 a 4 px)",
      "uso": "Três regimes de canto; escolha um",
      "fonte": "auditoria de 26 sites"
    },
    {
      "valor": "09/11/2025",
      "uso": "OKLCH e color-mix(): Widely Available (container queries desde 14/08/2025, subgrid desde 15/03/2026)",
      "fonte": "Baseline, web-features, 18/08/2026"
    },
    {
      "valor": "light-dark(): Newly desde 13/05/2024; contrast-color(): Newly desde 10/04/2026",
      "uso": "Exigem @supports; contrast-color devolve só preto ou branco e, segundo a MDN, comumente garante AA",
      "fonte": "Baseline, MDN"
    }
  ],
  "evitar": [
    {
      "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."
    }
  ],
  "padroes": [
    {
      "nome": "Bloco @theme com tokens de papel",
      "quando": "Primeira sessão do projeto, antes da primeira tela",
      "linguagem": "css",
      "codigo": "@import \"tailwindcss\";\n\n@theme {\n  /* cor: papéis, não tons */\n  --color-surface: oklch(0.99 0.005 80);\n  --color-ink: oklch(0.2 0.02 60);\n  --color-action: oklch(0.45 0.13 40);\n  --color-on-action: oklch(0.99 0.005 80);\n  /* espaçamento em base 4 px */\n  --spacing-xs: 4px;\n  --spacing-md: 16px;\n  --spacing-lg: 24px;\n  --spacing-section: 80px;\n  /* tipografia e forma */\n  --font-body: system-ui, sans-serif;\n  --text-body: 1rem;\n  --text-body--line-height: 1.6;\n  --radius-md: 8px;\n}"
    },
    {
      "nome": "Cor derivada com color-mix",
      "quando": "Hover, active e borda a partir de uma cor de marca",
      "linguagem": "css",
      "codigo": ".botao {\n  background: var(--color-action);\n  color: var(--color-on-action);\n}\n.botao:hover {\n  /* in oklch evita o cinza da mistura em sRGB; meça o contraste do resultado */\n  background: color-mix(in oklch, var(--color-action) 88%, white);\n}\n.cartao {\n  border: 1px solid color-mix(in oklch, var(--color-ink) 15%, transparent);\n}"
    },
    {
      "nome": "Tema claro e escuro por tokens",
      "quando": "Tema por botão com data-theme, sem mudar nenhuma classe",
      "linguagem": "css",
      "codigo": "@import \"tailwindcss\";\n@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));\n\n:root { --app-surface: #ffffff; --app-ink: #172238; --app-action: #185c96; --app-on-action: #ffffff; }\n:root[data-theme=\"dark\"] { --app-surface: #101827; --app-ink: #f0f4ff; --app-action: #91cbff; --app-on-action: #101827; }\n\n/* ponte única, no nível superior; inline mantém var() vivo na troca de tema */\n@theme inline {\n  --color-surface: var(--app-surface);\n  --color-ink: var(--app-ink);\n  --color-action: var(--app-action);\n  --color-on-action: var(--app-on-action);\n}"
    },
    {
      "nome": "Política de adoção Baseline",
      "quando": "Colar no CLAUDE.md ou AGENTS.md do repositório",
      "linguagem": "markdown",
      "codigo": "## Política de CSS de plataforma (Baseline), revisada em AAAA-MM-DD\n- Widely Available: use livremente, sem @supports.\n- Newly Available: SEMPRE atrás de @supports com fallback funcional.\n- Fora do Baseline: só se eu pedir, como melhoria que degrada.\n- Antes de afirmar o selo de um recurso, confirme no webstatus.dev ou caniuse;\n  não presuma pelo treinamento.\n- Prefira o nativo do navegador a uma dependência nova quando cobrir o requisito.\n- Cor só por token; nunca hex em componente. Nomes de classe sempre completos."
    }
  ],
  "checklist": [
    "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": [
    {
      "nome": "Tailwind CSS 4.3.3",
      "uso": "Utilitários com configuração em @theme"
    },
    {
      "nome": "@tailwindcss/upgrade (Node 20+)",
      "uso": "Migração da v3 para a v4, com revisão do diff"
    },
    {
      "nome": "Lightning CSS",
      "uso": "Minificação e prefixo do CSS fora do Tailwind"
    },
    {
      "nome": "Style Dictionary, Tokens Studio, Terrazzo",
      "uso": "Implementações de referência do DTCG 2025.10"
    },
    {
      "nome": "@google/design.md (lint, diff, export)",
      "uso": "Conferir o DESIGN.md (alfa) e gerar o tema do Tailwind"
    }
  ],
  "ondeAprofundar": [
    {
      "tema": "Tokens antes da primeira tela, DTCG e OKLCH",
      "ancora": "#tokens",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#tokens"
    },
    {
      "tema": "Tailwind v4: diretivas, motor e container queries",
      "ancora": "#tailwind",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#tailwind"
    },
    {
      "tema": "Onde cada regra mora: camadas, @scope, Lightning CSS",
      "ancora": "#divisao",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#divisao"
    },
    {
      "tema": "Armadilhas de código gerado por IA e prefixos de estado",
      "ancora": "#armadilhas",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#armadilhas"
    },
    {
      "tema": "Cor derivada, light-dark() e contrast-color()",
      "ancora": "#cor-derivada",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#cor-derivada"
    },
    {
      "tema": "Política Baseline, masonry e calc-size()",
      "ancora": "#plataforma",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#plataforma"
    },
    {
      "tema": "Medidas dos 26 sites de alto padrão",
      "ancora": "#medidas",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/#medidas"
    }
  ],
  "relacionados": [
    {
      "guia": "design",
      "motivo": "Menu geral do Design e decisões de identidade antes de fechar os tokens.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/agentes.md"
    },
    {
      "guia": "react",
      "motivo": "Estrutura de componentes e estado em React.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/react/agentes.md"
    },
    {
      "guia": "navegacao",
      "motivo": "Menus, abas, sumário e paleta de comandos nativos.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/navegacao/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/navegacao/agentes.md"
    },
    {
      "guia": "botoes",
      "motivo": "Estados, foco e alvo de toque dos botões sobre os tokens.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/botoes/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/botoes/agentes.md"
    },
    {
      "guia": "frontend2027",
      "motivo": "Paleta vibrante, escala display e movimento além da base.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/frontend2027/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/frontend2027/agentes.md"
    }
  ],
  "fontes": [
    {
      "titulo": "Definição de Baseline (Newly e Widely Available)",
      "url": "https://web.dev/baseline"
    },
    {
      "titulo": "webstatus.dev, base do pacote web-features",
      "url": "https://webstatus.dev"
    }
  ]
}
