Tailwind, tokens e CSS moderno: a base visual num lugar só
Uma tela consistente começa antes da primeira tela: cor, espaçamento e tipografia entram guardados num lugar só, na forma de tokens, e todas as páginas leem dali. Este guia foi verificado em fontes primárias em 18/08/2026 e cobre o caminho inteiro: os tokens com o formato estável do W3C (DTCG 2025.10) e as cores em OKLCH, Widely Available desde novembro de 2025; o Tailwind v4 com as datas e os números do anúncio oficial; a divisão que diz onde cada regra mora; as armadilhas de quem gera código com agentes de IA, na letra da documentação do Tailwind; a cor derivada por color-mix e o estado real de light-dark() e contrast-color(); a política de adoção com as datas oficiais do Baseline em 2026; e as medidas da auditoria de 26 sites de alto padrão. A mesma matéria está em aula de vídeo e podcast logo abaixo.
Guia do menu Design, construído sobre os capítulos de Tailwind do curso Frontends com Vibecoding, de Alexandre Caramaschi, e sobre pesquisa de fontes primárias com verificação adversarial independente (dez de dez itens confirmados em 18/08/2026). Ele compõe o menu com os guias de ícones e imagens, menus e paginação, React e diagramas.
A aula, em vídeo e em podcast
O conteúdo deste guia virou uma aula gerada no NotebookLM a partir do dossiê de pesquisa verificado, servida nos arquivos originais, sem recompressão. O vídeo apresenta o panorama; o podcast aprofunda a conversa para ouvir no deslocamento. Os dois têm transcrição para ler, copiar e baixar.
Ler a transcrição do vídeo
Bom, vamos lá. Bem-vindos, time de marketing da Leadlovers, a esta aula técnica. Hoje a gente tem em mãos o panorama do dossiê briefing.txt, que é literalmente o nosso projeto estrutural de interface para o 2026. Entender essa base técnica é exatamente o que vai permitir que a equipe lance campanhas e páginas de captura com uma velocidade absurda, claro, garantindo acessibilidade e sem jamais quebrar a identidade visual da marca. Ok, vamos direto ao ponto.
A rota de hoje tem seis paradas, um, tokens e a base visual, dois, tailwind versão 4 na prática, três, onde cada regra mora, quatro, armadilhas de agentes de IA, cinco, política baseline de 2026 e por fim, seis, três movimentos práticos. Passo número um, tokens e a base visual, a fundação do nosso design. Imagina o seguinte, centralização total. Para a nossa equipe, Tolkien significa um proteção absoluta da marca.
Quando a gente declara uma variável num único lugar, tipo a nossa cor primária, e a direção de marketing decide ajustar esse tom para uma campanha nova, bom, mudar esse Tolkien central atualiza todas as landing pages da empresa na mesma hora. A fonte da verdade fica intocável e o trabalho braçal despenca, simples assim. E a ordem para adotar isso é super rigorosa. A gente começa pela cor, depois avança para os passamentos usando uma escala de 4 pixels e finaliza com a tipografia, que fica estritamente limitada a três tamanhos. E olha, o pulo do gato aqui é essa escala de 4 pixels.
Ela age quase como mágica, resolvendo a enorme maioria dos problemas de alinhamento visual de cara. Isso tira completamente a divinhação da frente da equipe na hora de montar os ativos de uma campanha. E isso nos leva a um dado que chama muita atenção. Segundo o relatório Web em Million, de fevereiro de 2026, assustadores 95,9% das páginas web falham nos critérios de acessibilidade. Passar nesses critérios sem soar a camisa, apenas usando tokens bem estruturados, previne de imediato aqueles erros chatos de baixo contraste. Para o nosso marketing, isso é sinônimo de conversão.
Nossas companhias chegam a muito mais pessoas sem perder leads valiosos só porque o texto estava difícil de ler. Seguindo em frente, sessão 2, T-Win de venção 4 na prática e a adoção do motor Oxide. Dando uma olhada rápida nessa linha do tempo, a evolução das ferramentas foi impressionante. A gente teve lançamento da versão 4.0 estável em janeiro de 2025, logo depois a 4.1 em abril e agora chegamos na versão 4.3 em maio de 2026. O grande lance hoje é que a configuração inteira rola dentro do próprio CSS, tudo ali usando o bloco Arrobatim. E o ganho de performance com esse motor Oxide?
É bizarro de tão alto. O blog do 3Win já apontou lá em janeiro de 2025 que um build completo ficou 3,78 vezes mais rápido. Agora as coisas terminam na casa dos microsegundos. Falando sério, as reconstruções das nossas páginas rodam mais rápido do que um gestor consegue aprovar uma mudança de copy num botão. O fluxo de trabalho da equipe fica infinitamente mais dinâmico. Parte 3 – Onde cada regra mora Aquela famosa arquitetura em três camadas. Essa é a arquitetura exata que a gente precisa seguir aqui na leadlovers. Sem erro. O React compõe as telas, sem invenções.
O arquivo de CSS real toma conta do comportamento do sistema e o bloco a rouba tem é a casa de todos os nossos tokens, cada pecinha tem o seu lugar. E o motivo disso ser vital para o marketing é que essa previsibilidade gigante corta pela raiz aqueles bugs visuais desesperadores bem no meio de um lançamento importante. Agora a partir 4, armadilhas de agentes de inteligência artificial e como prevenir problemas com o código gerado. A gente sabe que a geração de código com inteligência artificial está com tudo tudo no nosso dia a dia, mas isso pede cuidado redobrado.
Tem uma reagra inegociável na documentação do Tailwind que diz, sempre use nomes completos de classes no código, por que isso? Porque o compilador lê o código como texto puro. Sem inteligência artificial tentar juntar pedaços de palavras para formar uma classe dinamicamente, o compilador simplesmente ignora e a interface quebra silenciosamente. Então, a string inteira é obrigatória sempre. Outro tropeço muito comum dessas ferramentas generativas é cuspicores com o código hexadecimal totalmente travado, chumbado no código.
O jeito seguro de lidar com isso é atribuir nomes de papéis semânticos aos nossos tokens. Ou seja, ao invés de aplicar um cinza claro, a gente dá o nome da função, tipo fundo primário. Isso salva as nossas campanhas do pesadelo de ter textos invisíveis ou caixas esquisitas quando um lead abre a página no celular com o modo escuro ativado. Entrando na sessão 5, a nossa política baseline de 2026, para garantir uma adoção super segura de CSS. O que é super interessante aqui são os dados do programa Web Baseline, que é a nossa bússola.
Recursos como as Container Queries lá de agosto de 2025, a cor OCLCH de novembro do mesmo ano e o SubGrid de março de 2026 já estão com o selo de amplamente disponíveis. O que isso quer dizer? Eles já passaram por um ciclo de maturidade de 30 meses e podem ser usados por todo o time as campanhas com tranquilidade e confiança total. Por outro lado, nós temos os recursos classificados como recém disponíveis. Aqui entram funções maravilhosas como o Light Dark de maio de 2024 e contraste color de abril de 2026. Mas atenção, esses casos exigem obrigatoriamente um plano B.
A gente precisa implementar fallbacks funcionais usando a regra Arroba Supports, e só que garante que a nossa página inovadora converta perfeitamente até no aparelho mais antigo do mercado, sem quebrar o layout. Então o ponto crucial de toda essa conversa é o ritmo absurdo das plataformas. O portal Chrome Developers avisou lá em março de 2026 que a partir da versão 153 o Chrome passaria a ser atualizado a cada duas semanas. Imagina a cada 15 dias ter uma política explícita sobre o que a gente pode usar ou não, parou de ser capricho faz tempo.
É manutenção básica para não ver a aplicação caindo do nada no mercado frenético desses. E para amarrar tudo, sessão 6. Três movimentos práticos de ação imediata. Vão para o que interesse ver como colocar a mão na massa já a partir de amanhã. É um checklist rápido para afinar de vez as operações de marketing e tecnologia. Primeiro movimento, checar rigorosamente se as nossas definições visuais estão morando no bloco correto, a rouba sim. Segundo, varrer o código e trocar qualquer correxa decimal chumbada por Tolkien semânticos.
E terceiro, colar essa política de adoção inteira, direto nas instruções globais que os nossos agentes de inteligência artificial leem, simples, prático e cirúrgico. E a gente encerra nossa análise de hoje com uma pergunta bem provocativa. Como o time vai blindar a qualidade do código enquanto a inteligência artificial evoluir cada vez mais rápido, às vezes até passando por cima das nossas diretrizes? Bom, a resposta é tratar esse dossiê como um projeto vivo orgânico.
Dominando a fundo esses fundamentos visuais, a equipe da Lead Lover se torna absolutamente imparável, ditando as regras para a máquina e não o contrário. Um excelente trabalho a todos nós e vamos em frente!
Ler a transcrição do podcast
Imagina colocar um chefe de cozinha de alto padrão, sabe? Com uma venda nos olhos, para preparar um banquete. Nossa, um desastre na certa. Exato! A pessoa só liga o fogão e torce silenciosamente para o prato da certo. E a real é que isso é exatamente o que acontece quando a gente pede para um agente de inteligência artificial gerar uma interface web moderna sem travar os tokens de design primeiro. Bom, bem-vindos à nossa análise aprofundada de hoje, a gente tem uma missão bem clara aqui. E bem urgente, né?
Sem dúvida, o foco absoluto é munir a equipe de marketing da leadlovers, a galera que já está com a mão na massa, construído páginas com IA, com uma base técnica pesada. E a gente vai usar os dados mais rigorosos verificados até a data de hoje, 18 de agosto de 2026. É, o cenário mudou bastante. Mudou muito, a gente vai conectar os pontos entre os tokens de design, a arquitetura nova do Tailwind de versão 4 e entender como a acessibilidade e a performance abandonaram aqueles status de recomendação e viraram regras implacáveis de engenharia.
Essa imagem do chefe vendado que você trouxe, ela traduz perfeitamente o caos da falta de parâmetros. Tipo, a máquina fica tentando adivinhar, né? Exatamente. Sem uma medição prévia e rigorosa, o resultado perde a consistência logo na segunda ou terceira tela que a IA gera. A organização da base de código funciona como uma receita matemática. Que tira a venda do chefe. Isso, tira a venda e faz a máquina trabalhar de forma previsível.
E para organizar esses ingredientes de forma segura, a Fundação exige centralizar as decisões visuais num vocabulário único antes mesmo de redigir a primeira linha de instrução para a inteligência artificial. O que nos leva ao amadurecimento desse formato? Como a indústria empacota essas decisões hoje em dia? Olha, o Design Tokens Community Group do W3C bateu martelo. Eles anunciaram a primeira versão estável da especificação, a versão 2025.10, lá no dia 28 de outubro de 2025. Ah, então oficializou mesmo? Oficializou.
Um Tolkien adota a estrutura de objeto com a propriedade cifrão velho, armazenando o dado bruto. E o tipo fica formalmente declarado na propriedade cifrão type, utilizando extensões de arquivo como ponto tokens ou ponto tokens.json. A taxonomia do material design 3 organiza isso nas classes reference, system e component. E como uma equipe adota tudo isso sem se perder. Porque parece muita coisa de uma vez. O curso Front Ends com VibeCoding estabelece uma prioridade de adoção muito sistemática. A equipe resolve primeiro a cor, depois o espaçamento e por fim a tipografia.
Com certeza, o campo das cores passou por uma modernização matemática profunda. O espaço OCLCH oferece linearidade e uniformidade de matiz superiores. E já está amplamente disponível, certo? Sim, os dados oficiais do programa Baseline atestam que o OKLCH figura como Baseline Widely Available desde 9 de novembro de 2025. Qual? Então o mercado subiu a barra de exigência. Muito.
A publicação da WCAG 2.2 como recommendation em 5 de outubro de 2023, atualizada em 12 de dezembro de 2024, exige o piso de contraste nível AA de 4,5 para 1, em um texto normal e 3 para um em texto grande e os alvos de toque o mesmo documento técnico impõe alvos de toque mínimos de 24 por 24 pixels css e a punição por igno ebre milhão de fevereiro de 2026 os números são assustadores muito eles detectaram falhas de wcag em 95,9% de 1 milhão de home pages auditadas o dado aponta a texto de baixo contraste em 83,9% delas. Quase a internet inteira.
É, com uma média de 34 instâncias de falha por página. Então a grande questão é como garantir que a IA não quebre essa regra matemática toda vez que gerar um componente novo. A máquina vai inevitavelmente replicar os erros do passado se essas regras não forem blindadas na arquitetura. O agente de IA precisa consumir as restrições diretamente de um motor capaz de aplicar isso em escala. Mas sem estrangular compilação, né? O que nos faz avançar para o T-Wind V4? Porque o problema de impor essas regras todas é que o sistema comece a engasgar se a arquitetura for lenta. Exato.
E o carendário de lançamentos oficiais mostra o ritmo dessa evolução. A versão estável T-Wind CSS V4.0 foi lançada em 22 de janeiro de 2025. E já avançou bastante de lá para cá. Sim, alcançando a versão V4.3.3 em 16 de julho de 2026. A engenharia responsável por suportar alias gerando código em massa depende desse novo motor. Ele foi apresentado inicialmente como Oxide no alfa de março de 2024. Aquele que introduziu o Hust. Isso mesmo. Esse motor possui partes vitais reescritas em Hust integral lightning CSS.
E os números de velocidade documentados no anúncio oficial de 22 de janeiro de 2025 justificam esse esforço. Os builds completos ficaram 3,78 vezes mais rápidos. Eles caíram de 378 milisegundos para 100 milisegundos. É uma diferença brutal. Brutal. Os rebuilds incrementais alcançaram 8,8 vezes mais velocidade, indo de 44 milisegundos para 5 e os rebuilds sem CSS novo despencaram de 35 milisegundos para impressionantes 192 microsegundos. É uma agilidade 182 vezes maior e a conquista dessa velocidade permitiu a grande mudança arquitetônica deles.
A configuração do framework mudou do JavaScript para o CSS, operando a partir do bloco Arroba Thymie. Tá, mas pausa aqui. Eu preciso fazer o papel de advogada do diabo agora manda a gente passou a última década inteira fugindo do css global sabe isolando configuração no javascript mover tudo de volta para o css puro só como um retrocesso aos tempos das folhas de estilo confusas eu entendo o ceticismo qual o ganho arquitetônico real que convenceu engenharia deles o ganho arquitetônico surge com eliminação de intermediários. A ponte em JavaScript gerava um pedágio computacional inviável.
Com a roba team, o compilador nativo processa o design system inteiro numa única leitura de CSS. A documentação oficial até orienta os desenvolvedores a pensarem no teu em CSS como o próprio pré-processador da aplicação, dispensando o SAS. Entendi, faz o compilador respirar melhor, mas assim, isso traz um desafio imediato. Se o CSS volta a ser o centro de comando, a ordem física das regras no arquivo dita quem vence os conflitos. Onde cada camada mora nesse cenário? Tomando como exemplo uma aplicação React operando em 2026, o Teowind fica encarregado de compor as telas.
Um arquivo CSS puro guarda o comportamento do sistema, como cascata e herança de grade, e os tokens residem no Arroba Certo. E como a gente organiza as camadas globais? O arquivo global organiza as camadas estritamente, com as diretivas Arroba Layer Reset, Tokens, Base, Components e Utilities. Exatamente nessa ordem. Sim. E o curso Frontends com VibeCoding ensina a alocar a camada Utilities na última linha disponível. O que faz total sentido lógico. Funciona tipo um plano de zoneamento urbano. As e utílires na última linha são como ambulâncias, veículos de emergência.
Elas precisam ter passagem livre absoluta no fim da via para sobreescrever os estilos básicos. Exato. Garante que as classes utilitárias vençam, o CSS de componente naturalmente. Evita o uso forçado daquelas exclamações de importas. Só que o sistema todo quebra quando a gente de IA entra nessa via expressa dirigindo na contramão. Tipo, inventando classes que o compilador nem consegue ler. O ponto de falha das gerações de código automatizadas se concentra na mecânica de leitura.
Agentes assumem padrões antigos, mas o compilador do Tailwind V4 funciona via leitura de texto puro e ignora código rodando em tempo de execução. Ah, então classes montadas dinamicamente e falham. Falham em silêncio. A documentação oficial estabelece a regra, Always Use Complete Class Names. e tem alguma válvula de escape estrutural na versão 4 para isso. O uso da diretiva Arroba Sourcing Line, com parênteses, serve para forçar o sistema a gerar classes específicas que passariam despercebidas. Mas obstáculo mais letal da IA aparece nas cores.
O erro de contraste número 1 em códigos gerados é o uso de valores hexadecemais fixos. Tipo aplicar um chassis sostenido 1A, 1A, 1A, direto no código. Isso. Aplicação de uma cor explícita assim resulta em texto preto sobre fundo preto no tema escuro. A solução exija do cara-máquina para usar apenas tokens com nomes de papel, como o traço-traço-galler-text-secondary, permitindo adaptação pelo sistema operacional. Mas a gente contém isso pelo arquivo de contexto, né? A documentação do Cloud Code de recomenda a uso de convenções no arquivo cloud.md.
Limitando o conteúdo a menos de 200 linhas de instruções concretas. Sabe. Isso levando uma reflexão econômica pesada. O ecossistema de documentação primária está em risco.
Em 6 de janeiro de 2026, o Adam Weitham, criador do Tailwind, fechou um pedido de um arquivo llms.txt no site dele sem fazer esse episódio foi bem marcante para o setor muito na recusa ele citou a queda de cerca de 40% no tráfico da documentação desde 2023 uma receita perto de 80% menor e o corte de 75% do time de engenharia é o impacto direto da IA no modelo de negócios de quem documenta web o exato o que afeta as documentações consumidas por IAS e aí fica a reflexão como as equipes vão depender de geradores no futuro se a própria fonte de conhecimento secar.
A saída técnica é dominar as funções matemáticas nativas para evitar os erros de código estático. As cores derivadas, por exemplo... A matemática resolve essas falhas. A função color traço mix, passando inoclet var traço traço marca, 88% e white permite derivar estados inteiros. A conta do curso front chains com vibecoding demonstra isso. 8 matizes combinados a 4 estados custam 32 valores feitos à mão num sistema legado. E no modelo moderno, apenas 8 valores base acompanhados dessa função. A Color Mix ostenta o status Widely Available desde 9 de novembro de 2025.
Perfeito, e tem as outras também. A função Light traço Dark detém o status Newly Available desde 13 de maio de 2024. projetada para completar os 30 meses do ciclo e alcançar a maturidade por volta de novembro de 2026. E a contrast traço color atingiu status Newly Available em 10 de abril de 2026 nos navegadores Chrome 147, Firefox 146 e Safari 26. Eu fico meio apreensiva com essa contrast color. Por causa do nível de conformidade? É, a MDN orienta que a função comumente assegura o nível A. Delegar acessibilidade a um recurso que só comumente assegura o limite exige muita cautela.
Tem que usar melhoria progressiva, com arroba suporte, se fazer a auditoria manual, a gente não pode confiar cegamente, ainda mais com o baseline definindo as políticas de adoção. Falando no programa baseline, ele abusula para isso. Ele distingue os status. Newly Available marca quando os navegadores centrais suportam o recurso. Widely Available marca o ponto seguro 30 meses após essa interoperabilidade. E as datas reais para o nosso código hoje. Os dados oficiais até 18 de agosto de 2026 confirmam o status Widely Available para Container Queries desde 14 de agosto de 2025.
Para o OCLC e a Color Mix desde 9 de novembro de 2025, para SubGrid desde 15 de março de 2026 e para o seletor 2.RES a partir de 19 de junho de 2026. E o layout mazory que todo mundo estava esperando? Esse encontrou barreira. O CSS Working Group registrou uma resolução em 13 de novembro de 2025, determinando a sintaxe Display 2.Grid Trasulanes. O Safari 26.4 entregou recurso em 24 de março de 2026. E os outros navegadores? Nenhum outro suporta na data de hoje, o que impede a presença no baseline e torna a aplicação em produção inviável. Olha, o ritmo vai ficar frenético.
O blog Chrome for Developers publicou um anúncio em 3 de março de 2026. Eles revelaram que o Chrome passará a adotar ciclos de atualização de duas semanas a partir do Chrome 153, e isso está agendado para 8 de setembro de 2026. É o mercado acelerando. Total, é como uma esterargométrica que aumentou repentinamente a velocidade. Manteer a política de adoção das 5 regras deixa de ser um luxo e passa-se uma exigência de sobrevivência. A política das 5 regras impõe um escudo. Recursos em faixa ampla, os widely, entram de forma livre. Recursos recentes exigem a rouba, suports, com fallback funcional.
Certo. E os que estão fora? Recursos fora do baseline dependem de pedido formal como melhoria de degradação elegante. A IA é obrigada a conferir o painel de compatibilidade oficial antes de afirmar o status, e em conflitos o suporte nativo vence a dependência de terceiros. Acompanhar os resultados disso no mercado expõe padrões surpreendentes. Quando a gente analisa as medidas dos sites de alto padrão da elite da web, os números são extremamente rígidos. É verdade. Auditoria conduzida pelo curso Front Ends com VibeCoding mensurou o CSS publicado de 26 sites reconhecidos pela excelência.
As métricas expuseram limites precisos. Largura máxima de 1200 pixels em 25 das 26 análises. E o espaçamento? Base ancorada em 4 pixels. Com 80 pixels de distância entre sessões. Cartões padronizados contendo pedem de 24 pixels e espaço interno de 16 pixels. E colunas de leitura variando estritamente entre 480 e 560 pixels. E tem os limites de estética também. A estética obedece ativamente a três regimes de raio, de borda à pílula, médio e reto. A cor emprega um assento racionado sobre um neutro quente. O As sombras brotam tingidas pela cor da marca, oscilando entre 1% e 5% de opacidade.
O que mais me deixa impressionada nesse estudo é a questão do sigilo das cores. O espaço OCCL não figurou em nenhuma das 26 fichas analisadas. A conclusão retirada pelo curso demonstra que a disciplina métrica é replicada pela indústria, ao passo que os valores absolutos de cor seguem privados. É fascinante, sabe? Mesmo a gente possuindo toda agilidade do CSS moderno e a velocidade absurda das IAS, a excelência visual de verdade converge para um conjunto numérico altamente conservador. Nada de caos criativo na estrutura.
E para transformar toda essa teoria nas páginas da leadlovers, o dossier trouxe três movimentos práticos para fechar. O primeiro é executar a conferência rigorosa, assegurar que as definições de cor, espaçamento e tipografia residam de forma centralizada no bloco Arroba Fime, adotando nomes baseados em papéis lógicos, os roles. Perfeito, o Movimento 2. Realizar uma varredura completa nas propriedades de cor do projeto em busca de códigos hexadecimais Cruz, trocando cada ocorrência diretamente pelo Tolkien correspondente. Limpesa estrutural total. Exato.
E o terceiro é copiar a política formal das cinco regras de adoção do Baseline e colar lá no arquivo de instruções da IA, como o cloud.md, anexando a data exata da revisão ao lado da regra. Eu só tenho a agradecer por esse detalhamento de dados.
A gente fecha aqui com uma reflexão provocativa sobre o futuro imediato, se as inteligências artificiais operam com essa cegueira estrutural para classes dinâmicas e o treinamento delas depende de documentações que estão ameaçadas de extinção econômica, será que a arquitetura do código da próxima década vai ser escrita pensando primeiramente na leitura perfeita pela máquina, relegando a legibilidade humana um segundo plano quase esquecido, fica o peso desse questionamento para audiência que tenha responsabilidade de construir hoje as bases da web de amanhã.
Arquivos originais do NotebookLM, sem recompressão. A legenda e as transcrições foram geradas localmente por faster-whisper e revisadas por amostragem.
Tokens antes da primeira tela
Um token é um nome dado a uma decisão de design: em vez de espalhar #2563eb por trinta arquivos, você declara --cor-primaria uma vez e todas as telas leem dali. O curso manda pedir os tokens na primeira sessão do projeto, antes da primeira tela, na ordem cor, espaçamento e tipografia.
O formato de intercâmbio amadureceu: o Design Tokens Community Group do W3C anunciou em 28/10/2025 a primeira versão estável da especificação, a 2025.10, com implementações de referência em Style Dictionary, Tokens Studio e Terrazzo. No formato, um token é um objeto com $value, o tipo vai em $type e os arquivos usam a extensão .tokens.json: a mesma paleta viaja do Figma ao código sem retrabalho. O Material Design 3 do Google organiza os tokens em três classes (reference, system e component), e é essa arquitetura em camadas que permite trocar uma decisão globalmente ou num único componente.
- Gere as cores em OKLCH, Baseline Widely Available desde 09/11/2025: a especificação CSS Color 4 do W3C registra a melhora de linearidade e uniformidade de matiz e croma frente ao CIE LCH, e a escala de 50 a 950 do curso mantém contraste parecido em toda a faixa.
- O piso de contraste é o AA da WCAG 2.2 (Recommendation de 05/10/2023, atualizada em 12/12/2024): 4,5:1 no texto normal e 3:1 no texto grande, critério 1.4.3.
- Alvos de toque: 24 por 24 pixels CSS é o mínimo AA (critério 2.5.8); o confortável de 44 por 44 é o critério 2.5.5, nível AAA.
- Dê aos tokens nome de papel:
--color-text-secondarydiz onde o valor é usado e adapta ao tema escuro sozinho;--color-slate-700só diz qual é a cor.
Escreva a convenção no arquivo de instruções do projeto. A documentação do Claude Code recomenda o CLAUDE.md com menos de 200 linhas e instruções concretas e verificáveis, e avisa: instruções são contexto para o agente respeitar, e bloqueio garantido exige hook.
Tailwind v4 na prática, do zero ao primeiro botão
O Tailwind é uma coleção de classes prontas: o estilo mora ao lado do elemento, uma classe por decisão. Na pesquisa State of CSS 2025, ele é o framework CSS mais usado, com mais de 2 mil dos cerca de 4 mil respondentes da questão. O v4.0 estável saiu em 22/01/2025 com um motor novo (apresentado como Oxide no alpha de março de 2024), com as partes mais caras em Rust e o Lightning CSS integrado.
Benchmark dos projetos do próprio time do Tailwind, publicado no anúncio da v4.0 (jan/2025). Navegadores mínimos declarados na documentação: Chrome 111, Safari 16.4 e Firefox 128.
A maior mudança é a configuração em CSS: o tailwind.config.js dá lugar ao bloco @theme dentro do próprio arquivo de estilos, e o v4 dispensa Sass ("Think of Tailwind CSS itself as your preprocessor", diz a documentação). Quem chega da versão 3 migra com npx @tailwindcss/upgrade (Node 20 ou superior), em branch novo e revisando o diff.
| Diretiva | O que faz (doc oficial) |
|---|---|
@theme | Define os design tokens do projeto: fontes, cores, breakpoints. As classes nascem deles (--color-marca vira bg-marca) |
@source | Registra arquivos fora da detecção automática; @source inline() força a geração de classes (a safelist da v4) |
@utility | Cria utilitário próprio que funciona com hover, focus e lg |
@variant | Aplica uma variante existente dentro do seu CSS; desde a v4.3 aceita variantes compostas |
@custom-variant | Cria variante nova, como o dark por data-theme |
@config e @plugin | Carregam config e plugin JavaScript legados; a própria doc os chama de ponte de compatibilidade |
v4.1 (abr/2025)
text-shadow-*, mask-*, alinhamento safe, drop-shadow colorido, variantes pointer-* e degradação mais graciosa em navegador antigo.
v4.3 (mai/2026)
Utilitários de scrollbar, @container-size para container query de altura, zoom-*, tab-* e valores default em utilitários funcionais.
Dark mode com botão de tema
O padrão da variante dark: é prefers-color-scheme. Com botão na tela, sobrescreva: @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *)); e o JS do tema segue seu.
Container queries no core
Sem plugin: classe @container no pai, variantes @sm: e @md: nos filhos pelo tamanho do contêiner, e contêineres nomeados com @container/main.
Classe repetida três vezes virou componente. O erro do iniciante é empilhar quinze classes iguais em cada botão. No React, o estado encontra a classe numa expressão (escuro ? bg-slate-900 : bg-white); passando de duas condições, o curso manda mover a decisão para uma função de variantes ou usar o cva, que faz variantes tipadas.
Onde cada regra mora
Para uma aplicação React em 2026, a recomendação do curso cabe numa frase: Tailwind v4 compõe as telas e um arquivo de CSS de verdade guarda o comportamento do sistema. A pergunta que decide é o que a regra descreve.
Sobre os motores tipados: Tailwind v4, vanilla-extract e Panda CSS geram CSS estático no build, o que tira da mesa o argumento de desempenho. O curso lista três necessidades que justificam a troca (tipos que derrubam o build, variantes por lógica de design, aversão a className longo) e pede dois números antes de decidir: quantos tokens errados chegaram à produção no trimestre e o custo de cada conserto. O pedido de uma frase que fecha a arquitetura: "CSS nativo no arquivo de estilos, Tailwind v4 para compor as telas, sem CSS-in-JS salvo necessidade explícita".
As armadilhas de quem gera código com IA
A regra número um está na documentação oficial do Tailwind, na letra: "Always use complete class names". O scan é texto puro: o compilador não interpreta código.
Hex fixo no tema escuro é o erro de contraste número um em código gerado. color: #1a1a1a cravado num componente vira preto sobre preto quando o tema escurece. Force token que adapta (var(--text)) e inclua na revisão uma varredura por hex cru em propriedade de cor.
Boa parte dos estados dispensa React, porque um prefixo resolve no CSS o que seria mais um useState:
| Prefixo | O que resolve | O cuidado |
|---|---|---|
focus-visible: | Anel de foco só na navegação por teclado | Trocar por focus: devolve o anel a todo clique |
group-hover: | Reage no filho quando o mouse está no pai | Exige a classe group no pai |
peer-checked: | Estiliza pelo estado do irmão | O irmão precisa vir antes na marcação |
disabled: | Aparência de botão desabilitado | Aparência sem o atributo deixa o botão clicável |
motion-safe: | Anima só para quem aceita movimento | Padrão de casa; respeitar movimento é AAA (WCAG 2.3.3), acima do piso |
dark:, data-*, aria-*, has-* | Tema, atributos de dados, ARIA e estado dos descendentes, direto no CSS | dark: exige o tema declarado na raiz; par de cores sempre por token |
Quadro do curso Frontends com Vibecoding, conferido na documentação oficial do Tailwind em 18/08/2026. Conflitos de classe se resolvem com tailwind-merge (v3.6.0, mai/2026, cobre o Tailwind 4.3).
O caso llms.txt
Em 06/01/2026, Adam Wathan, criador do Tailwind, fechou sem merge o pedido de um llms.txt no site oficial, citando tráfego da documentação cerca de 40% menor desde 2023, receita perto de 80% menor e o corte de 75% do time de engenharia. A doc oficial segue sendo a fonte, e o agente precisa ser apontado para ela.
shadcn/ui em 2026
"This is not a component library. It is how you build your component library", diz a doc. Suporte completo a Tailwind v4 e React 19, e um estado multi-base pelo changelog: Radix unificado (jun/2025), Base UI documentado (jan/2026) e React Aria como base de primeira classe (jul/2026).
A defasagem tem mecanismo
O agente aprendeu com texto publicado até uma data e desconhece o que veio depois, sem saber que desconhece. O antídoto é a convenção escrita no repositório e a política de adoção da seção de plataforma, com data de revisão ao lado.
Cor derivada e tema: oito valores e uma função
A conta do curso: oito matizes com quatro estados custam 32 valores mantidos à mão, ou oito valores e uma função. A função é color-mix(in oklch, var(--marca) 88%, white), Widely Available desde 09/11/2025, e o in oklch evita o cinza que a mistura em sRGB produz no meio do caminho. Tom derivado por cálculo pode cair abaixo do contraste mínimo: meça cada variação como cor nova.
light-dark(): só Newly
Newly Available desde 13/05/2024; completa os 30 meses do Baseline por volta de novembro de 2026. Funciona nos quatro grandes, e ainda assim entra com valor de retaguarda na linha anterior. Com botão de tema na tela, fique no [data-theme]: a função só enxerga o sistema.
contrast-color(): leia a letra miúda
Newly Available desde 10/04/2026 (Chrome 147, Firefox 146, Safari 26). Devolve somente preto ou branco, e o MDN diz que ela "commonly ensures" o AA: o advérbio pede auditoria própria. Melhoria progressiva com @supports, nunca piso.
A plataforma e a política de adoção
O programa Baseline define dois selos: Newly Available quando todos os navegadores centrais suportam, e Widely Available 30 meses depois (definição oficial em web.dev/baseline). O retrato de 18/08/2026, pelos dados oficiais do pacote web-features:
| Recurso | Selo em 18/08/2026 | Como entrar |
|---|---|---|
Container queries, OKLCH, color-mix(), subgrid, :has() | Widely Available | Livre |
| View transitions de mesmo documento (out/2025) | Newly | @supports com a navegação inteira funcionando sem elas |
::details-content (set/2025), anchor positioning no núcleo (jan/2026) | Newly | @supports e fallback funcional |
@scope (mar/2026), contrast-color() (abr/2026), :open e style queries (mai/2026), field-sizing (jun/2026) | Newly | @supports e fallback funcional |
light-dark() | Newly (Widely ~nov/2026) | Valor de retaguarda na linha anterior |
Carrossel CSS (::scroll-button, ::scroll-marker, :target-current) | Fora do Baseline (só Chromium 135+) | Só sob pedido, com a biblioteca de retaguarda |
@function, if(), sibling-index(), corner-shape, reading-flow, text-box-trim, view transitions entre documentos | Fora do Baseline | Melhoria que degrada limpa, sob pedido |
Datas e selos do pacote web-features (a base do webstatus.dev), acesso em 18/08/2026. O selo muda com o tempo: confirme no painel antes de decidir.
O caso masonry virou grid-lanes
O CSS Working Group resolveu em 13/11/2025: "masonry switch will be display: grid-lanes". A sintaxe grid-template-rows: masonry ficou pelo caminho. O Safari 26.4 (24/03/2026) foi o primeiro estável a entregar; produção exige fallback em colunas de CSS.
O Chrome acelera em setembro
Anúncio oficial de 03/03/2026: versão estável a cada duas semanas a partir do Chrome 153, em 08/09/2026, com beta três semanas antes e o canal corporativo seguindo em oito semanas. Política de adoção escrita deixa de ser luxo.
A verificação certa
O @supports precisa testar a propriedade exata que o agente escreveu: testar outra da mesma família dá falsa segurança. E entre o recurso do navegador e uma dependência nova, o navegador ganha sempre que cobrir o requisito.
As medidas dos sites de alto padrão
A auditoria de 26 sites reconhecidos por design, relatada no curso Frontends com Vibecoding, mediu o CSS publicado em vez de olhar capturas de tela. O conjunto foi curado por um diretório de referências: as medidas valem como repertório de decisão, e a norma continua sendo a sua.
No raio de canto, três regimes: a pílula (assinatura de marca), o médio (entre 8 e 40 pixels na auditoria; o pedido pronto do curso trabalha com a faixa de 8 a 16) e o reto, de 0 a 4. Na cor, um acento racionado sobre neutro quente, texto em quase-preto e sombra tingida da marca entre 1% e 5% de opacidade na medição da auditoria. A elevação nasce de empilhar superfícies com um fio de 1 pixel. OKLCH aparece em zero das 26 fichas: copie deles a disciplina e mantenha a sua base em OKLCH, que dá contraste mais previsível.
Fonte sem pulo de layout: o web.dev considera bom um CLS de até 0,1, e o descritor size-adjust no @font-face (com ascent-override e irmãos) faz a fonte local de reserva ocupar o mesmo espaço da fonte da marca: a troca some e o pulo vai a zero.
Prompts prontos
Tokens de layout e cor no padrão dos sites de alto padrão
Monte meus tokens de layout e cor no padrão técnico dos sites de alto padrão, num
único arquivo de CSS, mantendo a base de cor em OKLCH:
- Container: --container-max: 1200px, centralizado sobre canvas full-bleed.
- Espaçamento em base 4 (4/8/12/16/24/32) e --section-gap: 80px; padding de card
24px com gap interno de 16px; coluna de leitura limitada a ~560px.
- Raio: escolha UM regime entre pílula, médio 8-16px e reto 0-4px, justifique e
aplique consistente; exceção documentada (ex.: inputs em 0).
- Cor: um único acento de marca, usado SÓ em CTA/ações; canvas neutro quente
(jamais #fff puro); texto em quase-preto (jamais #000); par semântico com AA.
- Elevação: profundidade por empilhamento de superfícies e hairline de 1px;
sombra, se houver, tingida da marca com 1-5% de opacidade.
Regra: nenhum valor solto nos componentes; tudo de token nomeado. Contraste AA
nos dois temas.Refatoração do CSS para a plataforma de 2026
Refatore o CSS deste projeto mantendo o Tailwind v4:
1. Declare @layer reset, tokens, base, componentes, utilities no topo do CSS
global, para as utilitárias sempre vencerem meu CSS de componente.
2. Derive hover/active e bordas com color-mix(in oklch, var(--primary) ...):
NÃO crave hex novos.
3. Onde houver bloco [data-theme="dark"] de superfície e texto, avalie
light-dark() com color-scheme: light dark no :root e fallback antes de cada
linha (o selo Widely só chega por volta de nov/2026).
4. Alinhe títulos e rodapés de cartões com grid-template-rows: subgrid.
5. Aplique field-sizing: content no textarea, com @supports e fallback de altura.
Contraste AA e prefers-reduced-motion respeitados em toda animação.Política de adoção pronta para colar no repositório
## Política de CSS de plataforma (Baseline) — revisada em 18/08/2026
- Widely Available: use livremente, sem @supports.
- Newly Available: SEMPRE atrás de @supports com fallback funcional.
- Fora do Baseline: só se EU pedir, como progressive enhancement 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 (carrossel, acordeão,
posicionamento, animação de altura) quando ele cobrir o requisito.Por onde começar
Assista à aula e aplique três decisões no projeto que o time mantém hoje: confira se cor, espaçamento e tipografia moram num bloco @theme com nome de papel; rode uma varredura por hex cru em propriedade de cor e troque cada achado por token; e cole a política de adoção no arquivo de instruções, com a data da revisão ao lado. O menu Design continua nos guias de ícones e imagens, menus e paginação, React e diagramas, e o restante do portal no glossário.