Pular para o conteúdo
Guia de execução · menu Design

Tailwind, tokens e CSS moderno: a base visual num lugar só

O Tailwind CSS v4 troca o tailwind.config.js pelo bloco @theme dentro do próprio CSS, e cada token declarado ali vira classe: --color-marca gera bg-marca. A versão estável no registro npm em 2 de outubro de 2026 é a 4.3.3, de 16 de julho de 2026. 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.

Vídeo da aula Tailwind, tokens e CSS moderno: o panorama Vídeo
Baixar o vídeo Baixar a legenda Baixar o texto

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!

Podcast da aula A conversa aprofundada, para ouvir no deslocamento Podcast
0:00 0:00
Baixar o episódio Baixar o texto

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.

O fluxo de trabalho do guia, em cinco passos O fluxo de trabalho do guia, em cinco passos 1 Tokens no @theme cor, espaço, tipo 2 Compor com utilitárias classes completas 3 Derivar cor com color-mix sem hex novo 4 Recurso novo pelo selo Baseline decide a entrada 5 Medir contraste AA nos dois temas
O fluxo de trabalho do guia em cinco passos: dos tokens no @theme à medição de contraste nos dois temas.

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 token viaja da decisão de design, passa pelo @theme no CSS e chega a todas as telas 1. Decisão de design cor da marca: oklch(0.55 0.18 260) Escolhida uma vez, com nome 2. @theme no CSS --color-marca --space-4: 4px --text-lg Um só lugar para o valor 3. Todas as telas leem dali O mesmo rosa em cada tela A ordem de adoção do curso cor espaçamento tipografia Cada etapa entrega valor antes da próxima
O token viaja da decisão para todas as telas. A ordem de adoção é a do curso Frontends com Vibecoding.

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.

95,9%das home pages com falhas de WCAG (WebAIM Million, 2026)
83,9%delas com texto de contraste baixo (WebAIM Million, 2026)
34instâncias de contraste baixo por página, em média (WebAIM Million, 2026)

O token que muda o componente: style queries

Token nomeado por papel serve também de chave de estado. A consulta de estilo de contêiner lê uma custom property herdada do pai e aplica a regra quando o valor bate, o que dispensa repetir classe modificadora em cada filho: o pai declara --estado: alerta e o título, o selo e a borda do cartão se ajustam sozinhos, cada um lendo o mesmo token. Como o recurso ainda pede retaguarda, o visual normal do componente fica fora do bloco e a consulta acrescenta a camada de alerta onde o navegador a entende.

/* o pai guarda o estado num token semântico */
.painel-de-status { --estado: normal; }
.painel-de-status[data-estado="alerta"] { --estado: alerta; }

/* qualquer elemento já é contêiner de estilo; só o nome precisa ser declarado */
.cartao { container-name: status; }

@container status style(--estado: alerta) {
  .cartao__titulo { color: var(--cor-alerta-texto); }
  .cartao__selo   { background: var(--cor-alerta-fundo); }
}

Confira a tabela atual de compatibilidade em consultas de tamanho e estilo na MDN. O estado básico precisa continuar legível quando a consulta de estilo não for aplicada.

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.

Linha do tempo do Tailwind v4, de janeiro de 2025 a julho de 2026 A linha do Tailwind v4 jan/2025 v4.0 estável, motor novo em Rust abr/2025 v4.1: text-shadow, mask, alinhamento safe mai/2026 v4.3: scrollbar, container query de altura jul/2026 v4.3.3, a versão corrente builds até 182x mais rápidos Datas do blog oficial e das releases do Tailwind
A linha do Tailwind v4, nas datas do blog oficial e das releases: de janeiro de 2025 à v4.3.3 de julho de 2026.
3,78xfull build mais rápido: de 378ms para 100ms (anúncio oficial da v4.0)
8,8xrebuild incremental com CSS novo: de 44ms para 5ms (anúncio oficial)
182xrebuild sem CSS novo: 192 microssegundos (anúncio oficial)

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.

O peso do CSS conta na landing page de campanha, em que cada segundo de carregamento custa visita paga. A página oficial do Tailwind CSS informa, em outubro de 2026, que a maioria dos projetos entrega menos de 10 kB de CSS ao navegador, porque o build gera só as classes que encontra no código. O resto da página que converte, do formulário à mensagem de confirmação, está no guia de landing page e formulário.

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.

Dispensar o pré-processador ganhou uma segunda perna, anterior ao motor em Rust. O aninhamento de seletor, que foi a razão histórica de adotar Sass num projeto, está em Baseline desde 2023 e roda nativo nos quatro navegadores: quem escreve &:hover dentro do bloco do componente já usa a plataforma, sem etapa de compilação para isso. Do Sass restam as funções, os mixins e os laços, e a pergunta prática antes de manter a dependência é quantos deles o projeto realmente usa.

DiretivaO que faz (doc oficial)
@themeDefine os design tokens do projeto: fontes, cores, breakpoints. As classes nascem deles (--color-marca vira bg-marca)
@sourceRegistra arquivos fora da detecção automática; @source inline() força a geração de classes (a safelist da v4)
@utilityCria utilitário próprio que funciona com hover, focus e lg
@variantAplica uma variante existente dentro do seu CSS; desde a v4.3 aceita variantes compostas
@custom-variantCria variante nova, como o dark por data-theme
@config e @pluginCarregam 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.

Fluxograma de decisão: a regra descreve aparência, comportamento ou token, e cada resposta leva a um lugar do projeto A regra descreve o quê? Aparência de um elemento Comportamento do sistema de estilos Sobrou? É um token Utilitário Classe utilitária no JSX bg-marca p-4 Regra global Arquivo CSS de verdade @layer, color-mix, subgrid Token Bloco @theme --color-marca
A decisão do curso em um fluxo: aparência vira classe no JSX, comportamento vira arquivo CSS, o que sobra é token.
A pilha @layer com cinco camadas, onde utilities no topo vence, e um exemplo em que a classe supera o id A pilha @layer prioridade cresce utilities: as classes do Tailwind vencem componentes base tokens reset Quem vem depois na pilha vence a disputa Na prática Cartão A #id na camada base Especificidade alta, camada fraca Cartão B .classe na camada utilities Camada mais alta decide o estilo final vence sobe
Entre declarações normais da mesma origem em camadas distintas, a última camada vence. Regras normais fora de camadas têm precedência; com !important, a ordem das camadas se inverte.

Escopo com limite, para o bloco que veio de fora

@scope limita onde os seletores de um bloco se aplicam, com uma raiz e uma fronteira. Ele ajuda a escrever regras para um widget sem selecionar diretamente seu conteúdo aninhado. Isso não isola toda a cascata: propriedades herdadas, como fonte e cor, ainda atravessam a fronteira, e regras externas continuam podendo alcançar os elementos. A documentação de @scope distingue esses limites; teste a integração antes de dispensar outro mecanismo de isolamento.

/* raiz: o contêiner do widget · limite: o conteúdo da casa aninhado nele */
@scope (.widget-terceiro) to (.conteudo) {
  :scope { font-family: var(--fonte-base); background: var(--surface-2); }
  a      { color: var(--color-marca); text-decoration: underline; }
  button { border-radius: var(--raio-md); }
}
/* Os seletores param no limite; a herança de fonte e cor continua. */

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".

Quem minifica o CSS que fica fora do Tailwind

Essa arquitetura deixa um arquivo de CSS de verdade fora do alcance do motor, e ele continua precisando de minificação e de prefixo de fornecedor. O Lightning CSS, que a v4 carrega por dentro, roda também como ferramenta autônoma, por linha de comando ou por API de Node. Apontar o mesmo compilador para o arquivo escrito à mão mantém uma implementação só de minificação e de prefixo no projeto, com o alvo de navegadores declarado uma vez, no lugar de acoplar um segundo pipeline de PostCSS ao build.

# o CSS de plataforma, o que o Tailwind não toca, tratado pelo mesmo compilador
npx lightningcss --minify --bundle --browserslist \
  src/estilos/plataforma.css -o public/estilos/plataforma.css

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.

Classe montada por concatenação some no build; nome completo em mapa sobrevive Always use complete class names (doc oficial) classe montada em tempo de execução bg-${cor}-500 o nome completo nunca aparece no código mapa de variantes com nomes completos variantes[cor] vermelho: bg-red-500 verde: bg-green-500 scan de texto puro do compilador nada aqui classe inexistente no CSS final, falha em silêncio .bg-red-500 { ... } .bg-green-500 { ... } CSS gerado
O scan de texto puro do compilador: a classe montada dinamicamente atravessa o build sem gerar CSS e falha em silêncio.
Ilustração: mão robótica encaixa peças de interface num navegador enquanto uma peça se dissolve em partículas, a classe que some no build.
A peça que o build descarta em silêncio: ilustração da seção, gerada por IA para esta aula.

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:

PrefixoO que resolveO cuidado
focus-visible:Anel de foco só na navegação por tecladoTrocar por focus: devolve o anel a todo clique
group-hover:Reage no filho quando o mouse está no paiExige a classe group no pai
peer-checked:Estiliza pelo estado do irmãoO irmão precisa vir antes na marcação
disabled:Aparência de botão desabilitadoAparência sem o atributo deixa o botão clicável
motion-safe:Anima só para quem aceita movimentoPadrã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 CSSdark: 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.

Comparação: 32 valores de cor mantidos um a um contra 8 tokens que geram hover, borda e véu com uma chamada de color-mix à mão base hover borda véu 8 matizes x 4 estados = 32 valores mantidos um a um com color-mix color-mix(in oklch, var(--marca) 88%, white) 8 valores e uma função hover, borda e véu derivados do mesmo token
A troca que a função compra: 32 valores mantidos um a um viram oito tokens e uma linha de color-mix.
Ilustração: uma gota de tinta rosa se divide em quatro tons mais claros que abastecem quatro cartões de interface.
Um token de origem, quatro tons derivados: a ideia do color-mix em imagem, gerada por IA para esta aula.

light-dark(): só Newly

light-dark() segue o esquema de cor usado pelo elemento, definido por color-scheme. O seletor manual também funciona: aplique color-scheme: dark em [data-theme="dark"] e color-scheme: light em [data-theme="light"]; reserve color-scheme: light dark para acompanhar a preferência do sistema. Mantenha a cor de retaguarda para navegadores fora do suporte do projeto e confira contraste em cada escolha. A MDN demonstra a seleção explícita de tema.

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:

Linha do tempo do Baseline, de agosto de 2025 a junho de 2026, com selos Widely e Newly O Baseline em 2025 e 2026 ago/2025 container queries Widely out/2025 view transitions Newly nov/2025 OKLCH e color-mix Widely jan/2026 anchor positioning (Firefox 147) Newly mar/2026 subgrid Widely abr/2026 contrast-color() Newly mai/2026 :open e style queries Newly jun/2026 :has() Widely Widely: uso livre Newly: com @supports Datas oficiais do pacote web-features (acesso 18/08/2026)
Um ano de Baseline: os marcos de agosto de 2025 a junho de 2026, nas datas oficiais do pacote web-features.
RecursoSelo em 18/08/2026Como entrar
Container queries, OKLCH, color-mix(), subgrid, :has()Widely AvailableLivre
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 documentosFora do BaselineMelhoria 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.

Fluxo de adoção: um recurso CSS novo passa pelo painel de compatibilidade e cai em uma de três faixas do Baseline Recurso novo chegou Em que faixa o painel de compatibilidade o coloca? Widely Available entra livre, sem @supports Newly Available sempre atrás de @supports com fallback funcional Fora do Baseline só sob pedido, como melhoria que degrada Regra dos 30 meses: Newly vira Widely (web.dev/baseline)
A política de adoção em uma olhada: o selo do recurso decide como ele entra no projeto.

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.

Animar height: auto pela plataforma, com calc-size()

interpolate-size permite transições entre comprimentos e certos tamanhos intrínsecos, como auto. A função calc-size() permite calcular sobre esse tamanho. Isso evita parte da medição manual em JavaScript, mas alterar altura ainda exige trabalho de layout, o cálculo da posição e do tamanho dos elementos. Use a interpolação nativa quando a continuidade ajudar a leitura e confira o custo de layout no perfil da página; abertura imediata continua sendo uma alternativa funcional.

Chrome e Edge entregam o par desde a versão 129, o recurso está entre os focos do Interop 2026 e os outros motores seguem de fora, o que o coloca na faixa do @supports desta política. Onde a consulta falha, o painel abre e fecha sem animação e a interface continua inteira.

@supports (interpolate-size: allow-keywords) {
  :root { interpolate-size: allow-keywords; }

  /* block-size é a altura na família lógica, e vale a mesma interpolação */
  .painel { block-size: 0; overflow: hidden; transition: block-size 240ms ease; }
  .painel[data-aberto] { block-size: auto; }

  /* teto de altura preservando a medida intrínseca do conteúdo */
  .painel--teto[data-aberto] { block-size: calc-size(auto, min(size, 24rem)); }
}
@media (prefers-reduced-motion: reduce) { .painel { transition: none; } }

Suporte a interpolate-size e calc-size() em Chrome e Edge a partir da versão 129, com o recurso na lista de focos do Interop 2026. Conferido em 02/09/2026.

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.

Anatomia da página de alto padrão: viewport, conteúdo de 1200px, seções com 80px de respiro, cartão com padding 24px e gap 16px, coluna de leitura de 480 a 560px viewport conteúdo centralizado 1200px (25 dos 26 sites) seção 80px entre seções padding 24px gap 16px leitura longa: 480 a 560px Auditoria de 26 sites do curso Frontends com Vibecoding
A anatomia convergente: moldura de 1200px, 80px entre seções, cartão de 24px com espaço interno de 16px e coluna de leitura de 480 a 560px.

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.

Reduza o deslocamento na troca de fonte: size-adjust, ascent-override e os demais ajustes de métricas ajudam a aproximar a fonte de reserva da fonte da marca. Isso não garante CLS zero: confira as quebras de linha e o deslocamento real com as fontes carregadas. O resultado também depende do conteúdo e do espaço reservado.

Oficina: leve o token do JSON ao CSS que o navegador aplica

Converta os tokens, confira os valores resultantes e só então libere a prévia. Você termina com um arquivo CSS e uma entrada JSON que outra pessoa pode revisar. Um nome de cor correto não garante que a referência exista ou que o texto tenha contraste.

As marcas Azul e Verde são cenários fictícios deste exercício. Cada uma possui dois temas e quatro papéis: superfície, texto, ação e texto da ação. O alias, uma referência a outro token, conecta o papel à cor de origem.

O formato DTCG 2025.10 descreve tipos e referências para intercâmbio. É um relatório de Community Group, não uma Recommendation do W3C. O conversor abaixo aceita somente quatro cores sRGB opacas e aliases desses nomes. Não executa Tailwind nem pretende validar toda a especificação.

Cenário: duas marcas, dois temas e um botão ilegível

Quem
Renata, designer de produto da Escola Orbe (escola fictícia de cursos on-line). A Marca Azul veste o portal de cursos; a Marca Verde veste o catálogo de materiais gratuitos.
Tarefa
Entregar um tokens.css por marca e tema, gerado a partir do JSON, para que o time de frontend escreva bg-action e text-ink sem copiar hexadecimais para dentro dos componentes.
Falha vista
O botão "Matricular" do catálogo apareceu com texto da mesma cor do fundo no tema escuro. Ao copiar o bloco da outra marca, alguém trocou o alias de semantic.text para {primitive.surface}, e o CSS derivado foi corrigido à mão, sem atualizar a origem.
Resultado esperado
O conversor recusa a entrada com o caminho da referência quebrada ou com o par de contraste reprovado, e só libera o download do CSS quando texto sobre superfície e texto sobre ação passam de 4,5:1 nos dois temas.

O caso cabe em qualquer operação com mais de uma marca ou mais de um tema: um portal de cursos com área do aluno escura, uma página de vendas com campanha sazonal, um painel de leads que precisa de modo claro para impressão. O ponto comum está na cadeia de transformações entre o arquivo que a designer edita e a classe que o desenvolvedor escreve. Cada elo dessa cadeia pode falhar em silêncio, e o mapa abaixo mostra onde.

Mapa da oficina. O percurso de uma cor, do token JSON até a classe utilitária, com o desvio que interrompe a conversão quando o alias aponta para um nome inexistente.
Do token JSON à classe utilitária do Tailwind Seis caixas ligadas por setas. Primeiro, o token primitivo primitive.action em sRGB. Segundo, o alias semantic.action que aponta para o primitivo. Terceiro, a resolução, que segue o alias até a cor e devolve rgb(24 92 150); um desvio tracejado mostra o alias para primitive.inexistente, que interrompe a conversão com erro. Quarto, a variável CSS --demo-action gravada em :root. Quinto, o bloco @theme inline que liga --color-action à variável. Sexto, a classe bg-action, liberada só depois de o contraste passar de 4,5 para 1. 1. Token JSON (DTCG) primitive.action srgb [0.09, 0.36, 0.59] 2. Alias semântico semantic.action = "{primitive.action}" 3. Resolução do alias rgb(24 92 150) ciclo ou nome ausente: erro "{primitive.inexistente}" conversão interrompida, sem CSS 4. Variável CSS :root { --demo-action: rgb(24 92 150); } 5. @theme inline --color-action: var(--demo-action); 6. Classe utilitária class="bg-action" contraste de 4,5:1 libera Limite do conversor: quatro cores sRGB opacas, aliases entre primitive e semantic, sem Tailwind no navegador.

  1. O token primitivo guarda a cor como objeto: espaço sRGB e três componentes entre zero e um. Nenhum hexadecimal aparece aqui.
  2. O token semântico recebe só uma string entre chaves, o alias. Ele diz "ação usa a cor do primitivo ação" sem repetir o valor.
  3. A função resolveColor segue o alias, confere o tipo e devolve os três canais em 0 a 255. Se o caminho estiver fora do contrato, for circular ou apontar para um nome ausente, ela lança erro e nada mais acontece.
  4. Com as quatro cores resolvidas, o conversor escreve um bloco :root com uma variável --demo-* por papel. Esse é o tokens.css que você baixa.
  5. No projeto, o @theme inline do Tailwind v4 liga --color-action à variável resolvida. O Tailwind passa a conhecer o nome "action".
  6. A classe bg-action vira background-color no CSS compilado. Na amostra, a prévia só aparece quando texto sobre superfície e texto sobre ação passam de 4,5:1.

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

Repare que o conversor da página para no passo 4. Os passos 5 e 6 acontecem na sua máquina, com a CLI do Tailwind, e por isso a seção de código traz os três arquivos necessários. Essa divisão reproduz a de um projeto real: a ferramenta de tokens gera CSS puro, e o framework consome esse CSS. Quando a cadeia quebra, você precisa saber em qual dos seis elos olhar.

Demonstrar: converta e force as duas falhas

Observe três coisas enquanto usa o conversor. Primeiro, a tabela "Tokens resolvidos" lista o caminho semântico e a cor final em rgb(), que é o que a prévia realmente recebe. Segundo, o status informa as duas razões de contraste medidas; o piso de 4,5:1 vem do critério de contraste mínimo da WCAG 2.2 para texto comum. Terceiro, o botão "Baixar CSS aprovado na amostra" só liga quando os dois pares passam, e desliga de novo no instante em que você edita o JSON, porque o CSS compilado deixa de corresponder ao texto na tela.

Os dois botões de injeção mexem na origem e não no resultado. "Injetar alias inexistente" troca o valor de semantic.text por {primitive.inexistente}; o conversor para no passo 3 do mapa e relata o caminho. "Injetar contraste insuficiente" troca o mesmo alias por {primitive.surface}; a conversão termina, mas a razão texto sobre superfície cai para 1,00:1 e a prévia fica bloqueada. Depois de cada falha, "Restaurar marca e tema" recompõe o preset da marca escolhida.

Dados de exercício: os quatro presets que o conversor monta a partir dos seletores de marca e tema. As cores são as mesmas que o código em oficinas-tailwind.js carrega, convertidas para componentes entre zero e um na hora.

Presets das marcas fictícias, por tema. O papel on-action repete a superfície do tema.
Marca e temasurfacetextactionon-action
Azul, claro#ffffff#172238#185c96#ffffff
Azul, escuro#101827#f0f4ff#91cbff#101827
Verde, claro#ffffff#172238#14532d#ffffff
Verde, escuro#101827#f0f4ff#8ce6b0#101827
  1. Escolha a marca e o tema. Leia o objeto de cor, com componentes entre zero e um, e a referência usada pelo papel semântico.
  2. Converta e examine o CSS emitido. Compare texto sobre superfície e texto sobre ação. O cálculo usa as cores sRGB opacas que a prévia recebe.
  3. Injete um alias inexistente e veja qual caminho falhou. Depois provoque contraste insuficiente. Corrija a entrada ou restaure a marca escolhida.
  4. Baixe JSON e CSS. Troque de tema e repita. Em um projeto real, versione a origem e gere novamente a saída; não corrija só o arquivo derivado.

Esta amostra aceita apenas primitive e semantic, com surface, text, action e on-action. Cores precisam ser sRGB, opacas e com três componentes numéricos entre zero e um.

Ative JavaScript para converter. O roteiro de compilação permanece disponível abaixo.

Saída efetivamente usada pela prévia, sem executar texto como código.
PapelCor resolvida
Nenhum CSS válido nesta entrada.

Uma observação sobre o que a amostra deixa de medir. O contraste é calculado entre duas cores opacas, então transparência, gradientes, imagens de fundo e estados como hover e disabled ficam fora. A prévia liberada prova que os dois pares passam; o restante do componente ainda precisa de auditoria com ferramentas de acessibilidade, nos dois temas.

Investigar as falhas

Cada linha abaixo corresponde a um elo do mapa. Reproduza a falha no conversor ou no projeto compilado, confirme no navegador e só então corrija a origem.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
O status diz "Token ausente ou tipo diferente de color: primitive.inexistente" e a tabela fica vaziaO alias aponta para um nome que o grupo primitive não declara (passo 3 do mapa).No textarea, use a busca do navegador (Ctrl+F) pelo nome citado no status. Ele aparece só dentro do alias, nunca como chave do grupo.Troque o alias por um dos quatro nomes aceitos, como {primitive.text}, e converta de novo.
O status diz "Referência circular em semantic.text"Um alias aponta para um token que, por sua vez, aponta de volta. O conjunto seen da função detecta o ciclo.Edite semantic.text para {semantic.text} e converta. O erro cita o caminho repetido.Aliases sempre saem de semantic e chegam a primitive. Um primitivo guarda valor, nunca referência.
A prévia some e o status mostra 1,00:1 em texto sobre superfícieTexto e superfície resolvem para a mesma cor, como no botão "Injetar contraste insuficiente".DevTools, aba Elementos, selecione #llwt-preview e leia os estilos inline: --demo-text e --demo-surface têm o mesmo rgb().Aponte semantic.text para {primitive.text}. Em produção, meça texto sobre superfície e texto sobre ação nos dois temas antes de gerar o CSS.
No projeto compilado, bg-action não pinta nadaA classe foi montada em tempo de execução (bg-${cor}) ou o arquivo que a usa ficou fora de @source; o Tailwind detecta nomes completos em texto.Abra saida.css e busque .bg-action. Se faltar, confira o @source e procure por template strings nos componentes.Escreva os nomes inteiros num mapa de variantes ({ azul: "bg-action", ... }) e inclua a pasta dos componentes em @source.
A cor está certa no tema claro e errada no escuroSó o tokens.css do tema claro foi importado, ou o bloco escuro foi colado dentro do @theme inline, que precisa ficar no nível superior do arquivo.DevTools, aba Elementos, selecione html, alterne data-theme="dark" e observe se --demo-action muda no painel de estilos computados.Gere um bloco por tema e agrupe o escuro sob :root[data-theme="dark"], mantendo a ponte @theme inline única e fora de qualquer seletor.
"Baixar CSS aprovado" fica desativado com um JSON corretoO textarea foi editado depois da conversão; o evento input descarta o resultado anterior para o download nunca divergir do texto visível.O status mostra "Entrada alterada. Converta novamente para conferir os valores."Clique em "Converter e conferir". O botão religa se os dois pares passarem.

Código de referência

O navegador acima aplica variáveis CSS diretamente. Para testar a compilação real, crie uma pasta de exercício e salve nela o tokens.css baixado, ou gere o arquivo com o script abaixo, que reproduz a resolução de aliases do conversor em Node e serve como etapa de build. A CLI oficial transforma as diretivas em CSS; mantenha o lockfile para repetir a instalação.

// Gera tokens.css a partir de cores.tokens.json (subconjunto DTCG desta oficina).
// Uso: node resolver-tokens.mjs cores.tokens.json tokens.css
import { readFile, writeFile } from "node:fs/promises";

const PAPEIS = ["surface", "text", "action", "on-action"];
const [, , entrada = "cores.tokens.json", saida = "tokens.css"] = process.argv;
const raiz = JSON.parse(await readFile(entrada, "utf8"));

// Segue o alias até a cor; recusa caminho fora do contrato, ciclo e tipo errado.
function resolver(caminho, vistos = new Set()) {
  if (vistos.has(caminho)) throw new Error(`Referência circular em ${caminho}.`);
  if (!/^(primitive|semantic)\.(surface|text|action|on-action)$/.test(caminho)) {
    throw new Error(`Caminho fora do contrato: ${caminho}.`);
  }
  const [grupo, nome] = caminho.split(".");
  const token = raiz[grupo]?.[nome];
  if (!token || token.$type !== "color") throw new Error(`Token ausente ou sem tipo color: ${caminho}.`);
  vistos.add(caminho);
  if (typeof token.$value === "string") {
    const alias = /^\{([^{}]+)\}$/.exec(token.$value);
    if (!alias) throw new Error(`Alias inválido em ${caminho}.`);
    return resolver(alias[1], vistos);
  }
  const cor = token.$value;
  const ok = cor?.colorSpace === "srgb" && Array.isArray(cor.components) && cor.components.length === 3
    && cor.components.every((n) => Number.isFinite(n) && n >= 0 && n <= 1) && (cor.alpha ?? 1) === 1;
  if (!ok) throw new Error(`Use cor sRGB opaca com três componentes de 0 a 1 em ${caminho}.`);
  return cor.components.map((n) => Math.round(n * 255));
}

// Luminância relativa e razão de contraste, conforme a WCAG 2.2.
const luminancia = (rgb) => rgb
  .map((n) => { const v = n / 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; })
  .reduce((soma, v, i) => soma + v * [0.2126, 0.7152, 0.0722][i], 0);
const contraste = (a, b) => { const [alto, baixo] = [luminancia(a), luminancia(b)].sort((x, y) => y - x); return (alto + 0.05) / (baixo + 0.05); };

const cores = Object.fromEntries(PAPEIS.map((p) => [p, resolver(`semantic.${p}`)]));
const pares = [["text", "surface"], ["on-action", "action"]];
for (const [frente, fundo] of pares) {
  const razao = contraste(cores[frente], cores[fundo]);
  if (razao < 4.5) throw new Error(`Contraste ${frente}/${fundo} = ${razao.toFixed(2)}:1, abaixo de 4,5:1. CSS não gerado.`);
}
const css = `:root {\n${PAPEIS.map((p) => `  --demo-${p}: rgb(${cores[p].join(" ")});`).join("\n")}\n}\n`;
await writeFile(saida, css);
console.log(`${saida} gerado com ${PAPEIS.length} variáveis.`);

Em entrada.css, o @theme inline conecta os nomes de utilitários às variáveis resolvidas. Defina a ponte no nível superior do arquivo, sem colocá-la dentro de um seletor de tema. Os comandos de instalação ficam como comentário no topo para o arquivo contar a própria história.

/* Instalação e compilação (uma vez por pasta de exercício):
 *   npm init -y
 *   npm install --save-dev --save-exact tailwindcss@4.3.3 @tailwindcss/cli@4.3.3
 *   node resolver-tokens.mjs cores.tokens.json tokens.css
 *   npx @tailwindcss/cli -i ./entrada.css -o ./saida.css --minify
 */
@import "tailwindcss";

/* Variáveis resolvidas pelo conversor. Um arquivo por tema, se houver dois. */
@import "./tokens.css";
@import "./tokens-escuro.css" layer(base);

/* O Tailwind só emite as classes que encontra em texto nestes arquivos. */
@source "./index.html";
@source "./componentes";

/* Ponte: o nome que o utilitário usa aponta para a variável do token.
 * "inline" faz o utilitário carregar var(--demo-action) em vez do valor
 * copiado, então a troca de tema em :root[data-theme="dark"] continua valendo. */
@theme inline {
  --color-surface: var(--demo-surface);
  --color-ink: var(--demo-text);
  --color-action: var(--demo-action);
  --color-on-action: var(--demo-on-action);
}

/* tokens-escuro.css, gerado pelo mesmo script com o preset escuro:
 * :root[data-theme="dark"] {
 *   --demo-surface: rgb(16 24 39);
 *   --demo-text: rgb(240 244 255);
 *   --demo-action: rgb(145 203 255);
 *   --demo-on-action: rgb(16 24 39);
 * }
 */

Salve este documento como index.html, execute a CLI e abra o arquivo. Ao trocar o JSON, gere o CSS atualizado e compile de novo. O botão de tema no topo troca data-theme em html, e as classes continuam as mesmas porque a ponte aponta para variáveis.

<!doctype html>
<html lang="pt-BR">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Teste de tokens</title>
<link rel="stylesheet" href="./saida.css">
<main class="bg-surface text-ink min-h-screen p-6 text-base">
  <h1 class="text-2xl font-semibold">Marca fictícia em CSS compilado</h1>
  <p class="mt-2 max-w-prose">Texto sobre superfície. Alterne o tema e confira o contraste.</p>
  <button type="button" class="bg-action text-on-action min-h-11 px-4 mt-4 rounded-md
    focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-ink">Conferir foco</button>
  <button type="button" id="tema" class="ml-3 min-h-11 px-4 mt-4 border border-ink rounded-md">Alternar tema</button>
</main>
<script>
  // Troca o tema no elemento raiz; as classes não mudam, só as variáveis.
  const raiz = document.documentElement;
  document.getElementById("tema").addEventListener("click", () => {
    raiz.dataset.theme = raiz.dataset.theme === "dark" ? "light" : "dark";
  });
</script>
</html>

A falha seguinte costuma aparecer quando uma classe é montada como bg-${cor}. A detecção do Tailwind lê texto; use nomes completos em um mapa de variantes. Para muitos arquivos e tipos, avalie Style Dictionary com versão e transformações testadas, preservando o contrato escolhido.

Critérios de aceite

Levar para o projeto. Em React com Next.js, rode o script no prebuild do package.json e importe tokens.css no globals.css, antes do @theme inline; em Astro, o mesmo arquivo entra pelo @import da folha global; em HTML puro, a CLI do Tailwind basta. Versione o JSON e trate o CSS como artefato gerado, com um teste de snapshot que reprova quando a saída muda sem a origem mudar. Em produção, meça o contraste dos dois pares em cada tema com uma ferramenta de auditoria de acessibilidade a cada release e conte os hexadecimais soltos nos componentes: o número deve cair a zero.

Prompt para adaptar: "Converta estes tokens em variáveis sem executar strings. Valide aliases, tipos e ciclos; gere uma ponte @theme inline. Entregue a página de amostra, comando reproduzível e falhas de referência e contraste. Declare qualquer tipo DTCG que o conversor não aceite."

Faça antes "Componente em três marcas" e "Paleta dinâmica" na galeria prática do curso. A pauta de ficha expansível pode reutilizar tokens de movimento em uma etapa posterior; a prévia desta oficina permanece focada na conversão de cores.

Fontes, com acesso em 21/10/2026: formato DTCG 2025.10 (aliases e tipo color); variáveis de tema do Tailwind v4; contraste mínimo da WCAG 2.2.

Oficina: teste o componente na coluna em que ele será usado

Mude a largura do contêiner, o tema e o tamanho do texto sem reescrever o formulário. Você vai conferir se o componente conserva leitura, foco e dados preenchidos quando sai de uma página larga e entra numa coluna lateral.

O formulário abaixo é um briefing fictício salvo apenas na tela. O estado de falha é deliberado e não representa uma requisição. A aula sobre formulário explica por que uma confirmação em produção depende de prova de recebimento no destino.

Cenário: o mesmo briefing em três lugares do portal

Quem
Caio, desenvolvedor frontend da Escola Orbe (escola fictícia), responsável pelo formulário de briefing que os alunos preenchem ao pedir uma mentoria.
Tarefa
Usar um único componente de formulário na página de vendas (coluna de 520 pixels ao lado do vídeo), na barra lateral do painel do aluno (280 pixels) e na página de confirmação, que tem tema escuro fixo.
Falha vista
Na barra lateral, os dois campos ficaram espremidos lado a lado porque a regra de duas colunas media a janela (media query) e não a coluna. No tema escuro, o campo de observações ficou com texto preto sobre fundo escuro: a cor estava fixa no componente em vez de herdada do tema. Uma regra de depuração deixada fora das camadas apagou a borda de foco de todos os formulários do portal.
Resultado esperado
O componente muda de uma para duas colunas conforme a largura do contêiner, herda as cores do tema de quem o envolve, mantém os dados digitados após a validação com erro e nenhuma regra dele escapa para o restante do portal.

Três mecanismos do CSS resolvem o caso, e cada um explica uma divergência diferente entre os contêineres. A consulta de contêiner (@container, regra que mede a largura de um ancestral declarado como contêiner, em vez da janela) cuida das colunas. A herança de propriedades personalizadas (as variáveis --ot-*) cuida do tema. As camadas de cascata (@layer, que ordenam grupos de regras independentemente da especificidade) cuidam de quem vence quando duas declarações disputam a mesma propriedade. O mapa percorre os três.

Mapa da oficina. Um componente, dois contêineres de larguras diferentes, dois temas e uma disputa de cascata: o que muda em cada caso e por quê.
Componente portátil: contêiner, herança e camadas Linha de cima: a caixa do componente .llwt-form envia setas para dois contêineres. O de 280 pixels mostra os campos em uma coluna; o de 520 pixels mostra os campos em duas colunas, porque a regra @container llwt-form (min-width: 480px) se aplica. Linha do meio: o atributo data-tone="dark" redefine as variáveis --ot-bg e --ot-ink no formulário, e o campo de texto herda a cor sem nenhuma regra própria; ao lado, o ResizeObserver mede a largura e conta as colunas. Linha de baixo: a disputa de cascata. A camada llwt-base declara borda de 2 pixels, a camada llwt-utilities declara 6 pixels e vence entre as camadas; uma regra normal fora de camadas, com 1 pixel, vence as duas, destacada como alerta. 1. Um componente .llwt-form cores só via var(--ot-*) 2. Contêiner 280 px uma coluna 3. Contêiner 520 px @container (min-width: 480px) 4. Tema por herança [data-tone="dark"] { --ot-bg; --ot-ink } textarea { color: var(--ot-ink) } herda, sem regra própria ResizeObserver mede o contêiner e conta as colunas do grid 5. @layer llwt-base border-width: 2px @layer llwt-utilities border-width: 6px (vence) 6. Fora de camadas border-width: 1px (vence) Regra normal sem camada vence toda camada normal da mesma origem, mesmo com seletor mais fraco.

  1. O componente .llwt-form declara cores apenas por variáveis --ot-* e nunca mede a janela. Ele não sabe onde vai ser usado.
  2. Dentro de um contêiner de 280 pixels, a regra @container não se aplica e os campos ficam em uma coluna. O grid continua com gap de 1rem.
  3. No contêiner de 520 pixels, a regra @container llwt-form (min-width: 480px) passa a valer e o grid ganha duas colunas. A janela não mudou em nenhum dos casos.
  4. O atributo data-tone="dark" redefine as variáveis no formulário; os campos herdam a cor pelo valor da variável. Em paralelo, o ResizeObserver mede o contêiner e relata quantas colunas o grid calculou.
  5. Na cascata, a camada llwt-utilities foi declarada por último e vence a camada llwt-base: 6 pixels de borda.
  6. Uma regra normal fora de qualquer camada vence as duas camadas, mesmo com 1 pixel. É o caso da regra de depuração esquecida no cenário.

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

Repare na assimetria do passo 6. A intuição diz que uma regra com seletor mais específico vence, mas a ordem de resolução da cascata examina origem e camadas antes da especificidade. Entre declarações normais da mesma origem, as que estão fora de camadas ganham de todas as que estão dentro, e só então a especificidade decide entre regras do mesmo grupo. O Tailwind v4 coloca base, components e utilities em camadas por esse motivo: qualquer CSS seu fora de camadas passa por cima dos utilitários.

Demonstrar: varie o contexto sem alterar o componente

O painel tem quatro seletores e um palco redimensionável. O seletor de largura muda apenas o width do palco; o componente dentro dele reage pela consulta de contêiner. O status logo abaixo dos seletores é escrito por um ResizeObserver (API que avisa quando o tamanho de um elemento muda) e relata a largura medida e o número de colunas que o grid calculou, lido do estilo computado. Observe que a frase termina com "O viewport não foi alterado": a janela segue do mesmo tamanho o tempo todo.

O seletor de tema grava data-tone no formulário, e as regras de oficinas-tailwind.css redefinem as variáveis --ot-* só dentro dele. Nenhum campo tem cor própria; todos herdam. A opção "Acompanhar a página" remove o atributo e o formulário volta a seguir o tema do portal. O tamanho ampliado muda o font-size da raiz do componente para 20 pixels e serve para conferir se rótulos quebram linha em vez de cortar.

O experimento da cascata, ao final do painel, adiciona ou remove a classe que ativa a regra fora de camadas. O status lê getComputedStyle(...).borderTopWidth na hora do clique, então o número exibido é o que o navegador calculou naquele instante.

Dados de exercício: os três contextos do cenário e o comportamento esperado em cada um.
ContextoLargura do contêinerTemaColunas esperadas
Página de vendas520 pixelsAcompanhar a página2
Barra lateral do painel do aluno280 pixelsAcompanhar a página1
Página de confirmaçãoLargura disponívelEscuro2 acima de 480 pixels, 1 abaixo
  1. Preencha nome e projeto. Selecione 280 pixels, 520 pixels e largura disponível. A consulta de contêiner altera as colunas quando o espaço permite.
  2. Troque o tema da amostra e amplie o texto. Percorra os campos com Tab. Abra as observações e feche novamente; o campo fechado não pode continuar na ordem de foco.
  3. Valide com a falha didática selecionada. Os valores devem permanecer. Escolha confirmação local e repita, sem interpretar a mensagem como envio a um CRM.
  4. Adicione a regra fora de camadas no experimento seguinte. Observe a borda calculada e remova a regra para conferir qual declaração passa a vencer.

A largura será medida neste navegador.

Briefing de exemplo, sem envio. Confira a disposição com texto longo: atendimento para uma campanha com vários responsáveis.

Preencha os campos; nenhuma informação será enviada.

A preferência de movimento será lida ao ativar JavaScript.

Esta borda pertence ao experimento da cascata.

Sem a regra externa, a última camada normal define a borda de seis pixels.

A abertura das observações usa uma entrada por opacidade com a Web Animations API (element.animate) e muda o estado visível imediatamente. O atributo hidden remove o campo fechado da navegação, e o botão recupera o foco se ele estava dentro do painel na hora de fechar. Se você optar por animar altura, meça o custo: interpolate-size não elimina o cálculo de layout. A preferência de movimento é lida de duas fontes, a media query prefers-reduced-motion e o interruptor do portal em data-llx-motion, e qualquer mudança cancela a animação em andamento.

Investigar as falhas

As falhas abaixo são as do cenário, mais duas que aparecem ao portar o componente para outro projeto. Todas podem ser reproduzidas no painel ou numa cópia local do código.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
Os campos ficam em duas colunas mesmo no contêiner de 280 pixelsA regra de colunas usa @media (min-width: 480px) e mede a janela inteira em vez do contêiner.Selecione 280 pixels e leia o status: largura 280 e colunas 2. DevTools, aba Elementos, painel Estilos: a regra ativa vem de uma media query.Declare container: llwt-form / inline-size no palco e troque a media query por @container llwt-form (min-width: 480px).
A consulta de contêiner nunca se aplica, em nenhuma larguraNenhum ancestral declarou container-type, ou o nome na regra difere do nome declarado.No painel Estilos do palco, procure a propriedade container. Se faltar ou tiver outro nome, a regra fica sem contêiner para medir.Declare o contêiner no elemento que envolve o componente e use o mesmo nome nos dois lugares.
No tema escuro, o campo de observações mostra texto escuro sobre fundo escuroO textarea recebeu color fixa (como #172238) em vez de var(--ot-ink); a herança parou ali.Selecione o campo em Elementos; no painel Computed, a propriedade color aponta para uma regra com valor literal em vez da variável.Remova o valor literal e deixe o campo herdar, ou declare color: var(--ot-ink) no campo.
A borda do experimento aparece com 1 pixel em todo o portalA regra de depuração ficou fora de camadas e sem a classe que a restringe ao experimento (.llwt-cascade[data-conflict="true"]).Clique em "Adicionar ou remover regra fora de camadas" e leia o status; depois procure a mesma regra num formulário de outra seção.Prefixe a regra com o escopo do experimento ou mova-a para uma camada declarada antes de llwt-utilities.
Ao fechar as observações com o cursor dentro do campo, o foco some da páginaO painel recebeu hidden com o foco ainda dentro dele; o navegador devolve o foco ao body.Abra o painel, clique no textarea, pressione Shift+Tab até o botão e Enter. Em seguida pressione Tab e observe onde o foco cai.Antes de ocultar, teste panel.contains(document.activeElement) e chame disclosure.focus(), como o código desta oficina faz.
Os valores digitados somem após a validação com erroO manipulador de submit deixou o formulário navegar, ou chamou form.reset() na falha.Aba Rede do DevTools: uma requisição de documento aparece ao validar. Ou o campo fica vazio sem requisição alguma, o que aponta para o reset.Chame event.preventDefault(), use reportValidity() e escreva a mensagem no status; limpe só após confirmação do destino.

Código de referência

Na cascata do CSS, declarações normais fora de camadas têm precedência sobre as normais em camadas da mesma origem. Declarar utilities por último resolve a ordem entre camadas, mas não elimina essa outra categoria. O primeiro arquivo reúne contêiner, herança de tema e camadas no formato que o Tailwind v4 espera; o segundo traz o comportamento do painel.

/* Ordem das camadas declarada uma vez, no topo da folha global.
 * O Tailwind v4 usa theme, base, components e utilities; a camada do
 * componente entra antes de utilities para que utilitários a sobrescrevam. */
@layer theme, base, components, utilities;
@import "tailwindcss";

@layer components {
  /* Quem envolve o componente vira contêiner. O nome permite consultar
   * este contêiner mesmo que outro ancestral também seja contêiner. */
  .coluna { container: briefing / inline-size; }

  /* O componente só conhece variáveis. Sem valor literal de cor aqui. */
  .briefing {
    --ot-bg: #ffffff; --ot-ink: #172238; --ot-line: #718096; --ot-accent: #185c96;
    background: var(--ot-bg); color: var(--ot-ink);
  }
  /* O tema redefine as variáveis; todos os descendentes herdam. */
  .briefing[data-tone="dark"] { --ot-bg: #101827; --ot-ink: #f0f4ff; --ot-line: #94a3b8; --ot-accent: #91cbff; }
  .briefing[data-size="large"] { font-size: 20px; }

  .briefing .campos { display: grid; gap: 1rem; grid-template-columns: 1fr; }
  .briefing :is(input, textarea, button) { color: var(--ot-ink); background: var(--ot-bg); border: 1px solid var(--ot-line); min-height: 44px; }
  .briefing :is(input, textarea, button):focus-visible { outline: 3px solid var(--ot-accent); outline-offset: 3px; }

  /* Mede o contêiner, nunca a janela. */
  @container briefing (min-width: 480px) {
    .briefing .campos { grid-template-columns: 1fr 1fr; }
  }
}

/* Experimento de cascata: duas camadas e uma regra solta. */
@layer base-da-oficina, utilitarios-da-oficina;
@layer base-da-oficina { .amostra { border-width: 2px; } }
@layer utilitarios-da-oficina { .amostra { border-width: 6px; } }
/* Fora de camadas, esta regra normal vence as duas, apesar do seletor
 * de classe simples. Restrinja-a ao experimento para não vazar. */
.com-conflito .amostra { border-width: 1px; }

@scope restringe seletores e continua sujeito à herança. Para provar isso num arquivo de exercício, aplique uma fonte à raiz do escopo e observe o texto dentro do limite. A MDN explica essa passagem; acrescente uma declaração explícita no conteúdo interno se a fonte não puder ser herdada.

/* @scope limita onde os seletores do bloco se aplicam: da raiz .widget
 * até o limite .conteudo-interno, sem incluir o limite. */
@scope (.widget) to (.conteudo-interno) {
  :scope { font-family: ui-monospace, monospace; }
  a { text-decoration: underline; }
}
/* A fonte herdada ainda chega ao conteúdo interno, porque herança e
 * escopo são mecanismos diferentes. O limite impede apenas que o "a"
 * deste bloco selecione links dentro de .conteudo-interno. */
.conteudo-interno { font-family: system-ui, sans-serif; } /* declara de novo se quiser outra fonte */
// Comportamento do briefing portátil: abertura acessível, preferência de
// movimento com duas fontes, medição do contêiner e validação sem envio.
const form = document.querySelector(".briefing");
const palco = document.querySelector(".coluna");
const campos = form.querySelector(".campos");
const abrir = form.querySelector("[aria-controls]");
const painel = document.getElementById(abrir.getAttribute("aria-controls"));
const status = form.querySelector("[role='status']");
const media = matchMedia("(prefers-reduced-motion: reduce)");
let animacao = null;

const reduzido = () => media.matches || document.documentElement.dataset.llxMotion === "reduce";
const encerrar = () => { if (animacao) { animacao.cancel(); animacao = null; } };

abrir.addEventListener("click", () => {
  encerrar();
  const abrindo = abrir.getAttribute("aria-expanded") !== "true";
  // Ao fechar com o foco dentro do painel, devolve o foco ao botão.
  if (!abrindo && painel.contains(document.activeElement)) abrir.focus();
  abrir.setAttribute("aria-expanded", String(abrindo));
  painel.hidden = !abrindo; // hidden tira o painel da ordem de foco
  if (abrindo && !reduzido() && typeof painel.animate === "function") {
    animacao = painel.animate([{ opacity: 0.25 }, { opacity: 1 }], { duration: 180, easing: "ease-out" });
    animacao.onfinish = () => { animacao = null; };
  }
});

// Mudança de preferência durante a sessão cancela a animação em andamento.
media.addEventListener("change", encerrar);
new MutationObserver(encerrar).observe(document.documentElement, { attributes: true, attributeFilter: ["data-llx-motion"] });

// Mede o contêiner e conta as colunas que o grid calculou.
new ResizeObserver(() => {
  const largura = Math.round(palco.getBoundingClientRect().width);
  const colunas = getComputedStyle(campos).gridTemplateColumns.split(" ").length;
  status.textContent = `Contêiner: ${largura} px. Colunas: ${colunas}. O viewport não foi alterado.`;
}).observe(palco);

// Validação local: nenhum dado sai do navegador; os valores permanecem.
form.addEventListener("submit", (evento) => {
  evento.preventDefault();
  if (!form.reportValidity()) return;
  status.textContent = "Rascunho validado neste navegador. Nenhum envio foi feito.";
});

Critérios de aceite

Levar para o projeto. Em React com Next.js, o componente recebe tone e size como props e os grava em data-*; quem o renderiza declara o contêiner na coluna, e o ResizeObserver entra num useEffect com limpeza no retorno. Em Astro, o mesmo CSS vive num <style> com is:global para as camadas e o script entra como módulo do cliente. Em HTML puro, basta o par de arquivos acima. Em produção, meça três coisas: a proporção de componentes com cor literal (meta zero), o número de regras fora de camadas na folha global e o tempo de layout nas páginas em que o formulário aparece dentro de colunas estreitas, lido na aba Desempenho.

Prompt para adaptar: "Torne este formulário portátil usando consultas de contêiner. Preserve dados após erro, associe rótulos, retire campos fechados da ordem de foco e reaja à preferência de movimento. Entregue um caso de conflito entre camadas com a regra vencedora explicada e testada."

Retome "Bento responsivo" e "Auditoria de interface" nos laboratórios do curso. As propostas de estados e eventos aprofundam a coordenação de interações; este exemplo mantém validação e feedback locais, sem simular uma integração real.

Fontes, com acesso em 21/10/2026: consultas de contêiner na MDN; ordem de resolução da cascata, CSS Cascading and Inheritance Level 5; camadas do Tailwind v4.

Oficina: site amplo que qualquer pessoa digere

Um portal com centenas de páginas, dezenas de menus e milhares de ligações internas cansa quem chega sem repertório técnico. O problema está na falta de camadas, mais do que na quantidade de conteúdo: tudo aparece com o mesmo peso, ao mesmo tempo, e a pessoa precisa adivinhar onde está, o que fazer agora e como voltar. Esta oficina reúne as nove técnicas que resolvem isso em 2026 com HTML, CSS e Tailwind v4, sem biblioteca obrigatória, e mostra todas elas funcionando numa mesma página de exercício.

A regra que organiza tudo vem de Jakob Nielsen, em Progressive Disclosure (NN/g, 3 de dezembro de 2006): mostre primeiro as poucas opções mais importantes, deixe óbvio o caminho para o resto e pare em dois níveis, porque "designs que passam de dois níveis de revelação costumam ter baixa usabilidade". O benchmark de 2026 confirma o princípio e troca as ferramentas: o que antes exigia um plugin hoje é atributo do HTML ou regra de CSS com selo Baseline.

O que o benchmark de 2026 sustenta, com fonte e data

A tabela separa a técnica, o problema que ela resolve para quem tem pouca experiência, a forma nativa de implementar em 2026 e a evidência. Onde a evidência é pesquisa de usabilidade, a fonte é a NN/g. Onde é suporte de navegador, a fonte é a MDN, o web.dev ou o caniuse, lidos em 21 de outubro de 2026. Números de adoção que circulam em blogs de tendência, como "67% dos sites de SaaS usam bento grid em 2026", ficaram de fora porque nenhum deles cita a amostra.

Nove técnicas para sites amplos, do problema à implementação nativa em 2026.
TécnicaProblema que resolve para a pessoa leigaComo fazer em 2026Evidência e data
Resumo no topo de cada seçãoDescobrir em três linhas se vale ler a seção antes de rolar duas telas.Um bloco aside com tese e três pontos, gerado a partir do texto e revisado por pessoa.Primeiro nível da revelação progressiva (Nielsen, NN/g, 2006).
Índice "Nesta página" fixo com seção atual marcadaSaber onde está e pular direto, sem decorar a estrutura.position: sticky na coluna lateral e IntersectionObserver para marcar aria-current.Amy Schade, Anchors OK? (NN/g, 7 de maio de 2017): índice fixo "deve mostrar a posição atual" e usar rótulo como "Nesta página".
Cabeçalho fixo que encolheManter busca e menu à mão sem roubar a tela do celular.position: sticky e animation-timeline: scroll() atrás de @supports, com observador como reserva.Page Laubheimer, Sticky Headers (NN/g, 4 de abril de 2021): o menor espaço possível, cor opaca e pouco movimento. Suporte do scroll(): Chrome 115, Safari 26, Firefox só a partir da 161 (caniuse, 21/10/2026).
Trilha de localização (breadcrumb)Entender a hierarquia e subir um nível com um toque.nav aria-label="Você está em", última etapa sem link, no celular só o nível acima.Laubheimer, Breadcrumbs: 11 Design Guidelines (NN/g, 2018, revisado em 1 de setembro de 2026).
Menu amplo com préviaVer todas as opções de uma vez em vez de lembrar onde cada uma mora.Atributo popover no painel e anchor-name mais position-area para prendê-lo ao botão.Nielsen e Li, Mega Menus Work Well (NN/g, 26 de março de 2017). Popover: Baseline Newly available desde janeiro de 2025 (MDN). Anchor positioning: Baseline Newly available desde janeiro de 2026, com Firefox 147 (web.dev).
Paleta de comandos (Ctrl+K)Chegar a qualquer página digitando duas palavras, sem abrir menu nenhum.dialog nativo com showModal(), campo de busca, setas e Enter; índice estático em JSON.Padrão consolidado em produtos densos como GitHub, Linear e Vercel; sem estudo da NN/g dedicado até 21/10/2026, por isso entra como prática de mercado e pede teste próprio.
Acordeão exclusivo e abas com transiçãoComparar alternativas sem perder o contexto nem rolar de volta.details name="grupo" para abrir um e fechar os outros; abas com document.startViewTransition().Atributo name do details: Chrome 120, Firefox 130, Safari 17.2 (Chrome Developers). View Transitions no mesmo documento: Baseline Newly available em 14 de outubro de 2025, com Firefox 144 (web.dev).
Tabela longa com cabeçalho preso e filtroLer a coluna certa na linha 80 e achar um item sem rolar tudo.thead th { position: sticky } dentro de um contêiner com rolagem e um campo de filtro que anuncia a contagem por aria-live.Prática padrão de documentação técnica; a parte medida é a duração do movimento, de 100 a 500 ms (Laubheimer, NN/g, 9 de fevereiro de 2020).
Esqueleto de carregamentoEntender que a página está chegando e qual forma ela terá.Blocos cinza no formato do conteúdo, pulsando um número finito de vezes, trocados pelo conteúdo com uma entrada de opacidade.Samhita Tankala, Skeleton Screens 101 (NN/g, 4 de junho de 2023, revisado em 2 de setembro de 2026): esqueleto para esperas abaixo de 10 segundos e nada para cargas abaixo de 1 segundo.

Duas decisões ficam fora do palco porque são de arquitetura, e não de componente. A primeira é manter a navegação visível no computador: Page Laubheimer, em Left-Side Vertical Navigation on Desktop (NN/g, 16 de maio de 2021), lembra que "navegação visível é o padrão ouro no celular e no computador", e a coluna lateral comporta mais itens e rótulos longos do que a barra horizontal. A segunda é a trilha por papel: quem é assistente, gestor ou cliente vê na primeira tela as três tarefas do seu papel, e o resto fica no menu amplo. O GOV.UK Design System separa Details, Accordion e Tabs pela intenção de uso, e vale copiar o critério: detalhe para a minoria que precisa de mais, acordeão para seções independentes, abas para comparar visões da mesma coisa.

Página de exercício com os nove elementos funcionando juntos

O palco abaixo é um portal fictício, o "Manual da Agência Horizonte", que rola dentro da própria caixa. Tudo o que você vê usa recursos nativos: o cabeçalho encolhe pela linha do tempo de rolagem onde há suporte e pelo observador onde não há; o índice marca a seção atual; o menu amplo abre por popover; a paleta é um dialog; o acordeão usa details name; as abas trocam com View Transition quando o navegador e a sua preferência de movimento permitem. Desligue o movimento no botão do portal e repita cada ação: o resultado precisa ser o mesmo, só sem a animação.

  1. Role o palco e observe o cabeçalho encolher e ganhar sombra enquanto o índice da esquerda acompanha a seção atual.
  2. Abra a paleta com o botão ou com Ctrl+K com o foco dentro do palco. Digite "tabela", escolha com as setas e confirme com Enter.
  3. Abra o menu amplo, passe o foco pelas ligações e leia a prévia. Feche com Esc e confira se o foco volta ao botão.
  4. Abra um item do acordeão e veja o anterior fechar. Troque as abas pelas setas do teclado. Filtre a tabela por "SEO" e leia a contagem.
  5. Arraste o canto inferior direito da vitrine para estreitá-la: o bento reorganiza as colunas pelo tamanho do contêiner. Por fim, simule o carregamento e observe o esqueleto dar lugar ao conteúdo.

Passe o foco por uma ligação para ler a prévia da área.

  • Visão geral da operaçãoPágina
  • Como o menu amplo funcionaPágina
  • Camadas de revelaçãoPágina
  • Comparar planos nas abasPágina
  • Tabela de páginas do portalPágina
  • Vitrine de indicadoresPágina
  • Relatório mensalPágina
  • Criar nova landing pageAção
  • Exportar tabela em CSVAção
  • Abrir glossário de SEO e GEOAção
10 destinosSetas para navegar, Enter para abrir, Esc para fechar

Visão geral da operação

O manual da Agência Horizonte tem 240 páginas de exercício. Ninguém lê tudo. A pessoa que chega quer três coisas: saber onde está, achar a página certa e executar uma ação sem errar. Os elementos desta página existem para isso.

Como o menu amplo funciona

O botão "Menus" no cabeçalho abre um painel com todas as áreas de uma vez, agrupadas em três colunas. A prévia embaixo muda quando o foco passa por uma ligação, o que ajuda quem ainda está aprendendo os nomes. O painel vive na camada superior do navegador por causa do atributo popover, por isso aparece por cima do conteúdo mesmo dentro desta caixa com rolagem.

Camadas de revelação

Primeira camada: o que decidir hoje

Escolha uma página para publicar nesta semana, defina quem aprova e qual a meta medida. Só isso aparece aberto por padrão.

Segunda camada: como executar

Roteiro de publicação em cinco passos, com o checklist de SEO e GEO (Generative Engine Optimization) e o modelo de briefing. Abre sob demanda e fecha a camada anterior.

Referência: todos os detalhes

Parâmetros, exceções e histórico de mudanças. Fica fechado até que alguém precise, e a página nunca passa de dois níveis para chegar aqui.

Comparar planos nas abas

Essencial: uma landing page por mês, automação de boas-vindas e relatório trimestral. Para quem está começando a medir.

Tabela de páginas do portal

Páginas do manual de exercício, com menu, última revisão e estado.
PáginaMenuRevisada emEstado
Landing page de eventoAtrair02/10/2026publicada
Checklist de SEO técnicoAtrair07/10/2026publicada
Guia de GEO para artigosAtrair14/10/2026rascunho
Calendário editorialAtrair18/09/2026publicada
Sequência de boas-vindasConverter30/09/2026publicada
Automação de carrinhoConverter11/10/2026em revisão
Roteiro de atendimentoConverter21/08/2026publicada
Página de oferta anualConverter15/10/2026rascunho
Relatório mensal modeloReter01/10/2026publicada
Sinais de abandonoReter09/10/2026publicada
Reconquista em três e-mailsReter16/10/2026em revisão
Pesquisa de satisfaçãoReter25/09/2026publicada
Glossário de SEO e GEOReferência19/10/2026publicada
Política de adoção de CSSReferência18/08/2026publicada

Vitrine de indicadores

Arraste o canto inferior direito da moldura tracejada. A grade lê a largura do próprio contêiner, por isso a mesma vitrine serve na página larga e na coluna lateral. Largura atual: aguardando medição.

Leads do mês
1.284

Dado de exercício. Em um painel real, este número vem da mesma consulta que alimenta o relatório.

Páginas publicadas
11

De 14 planejadas.

E-mails enviados
4.120

Sequência de boas-vindas.

Em revisão
2

Automação e reconquista.

Próxima entrega
24/10

Página de oferta anual.

Relatório mensal

Relatório de setembro: 1.284 leads, 11 páginas publicadas e duas automações em revisão. O esqueleto que você acabou de ver tem o formato deste parágrafo, pulsa três vezes e para; a entrada do conteúdo usa só opacidade.

Fim da página de exercício. Dados fictícios da Agência Horizonte.

Estado dos elementos nesta visita, útil para explicar a quem revisa qual caminho o navegador tomou:

Como cada elemento foi feito e o que conferir

O cabeçalho encolhe por uma animação ligada à rolagem do palco. Onde animation-timeline: scroll() existe, o CSS faz tudo; onde não existe, um IntersectionObserver observa uma sentinela de 120 px no topo e liga o atributo data-compacto. As duas rotas mudam só sombra e transform, nunca altura, porque altura força o navegador a recalcular o layout a cada quadro.

.palco { overflow: auto; }
.topo { position: sticky; top: 0; transition: box-shadow 240ms; }
.topo[data-compacto] { box-shadow: 0 6px 18px color-mix(in oklch, var(--ink) 12%, transparent); }
.topo[data-compacto] .logo { transform: scale(.82); }
@supports (animation-timeline: scroll()) {
  .palco { scroll-timeline: --rolagem block; }
  .topo { animation: encolher linear both; animation-timeline: --rolagem; animation-range: 0 120px; }
}

O menu amplo é um painel com popover preso ao botão por anchor-name e position-area. O navegador cuida de abrir, fechar com Esc, devolver o foco e trocar de lado quando falta espaço, pelo position-try-fallbacks. Em navegador sem anchor positioning, o script calcula a posição ao abrir. A paleta é um dialog com showModal(): o foco fica preso dentro, o fundo escurece pelo ::backdrop e a busca ignora acentos ao comparar.

<button popovertarget="mega" class="mega-botao">Menus</button>
<div id="mega" popover>…</div>

@supports (position-area: bottom) {
  .mega-botao { anchor-name: --menu; }
  [popover]#mega { position-anchor: --menu; position-area: bottom span-right;
                   position-try-fallbacks: flip-block, flip-inline; }
}
[popover]#mega { opacity: 0; transform: translateY(-6px);
  transition: opacity 240ms, transform 240ms, overlay 240ms allow-discrete, display 240ms allow-discrete; }
[popover]#mega:popover-open { opacity: 1; transform: none; }
@starting-style { [popover]#mega:popover-open { opacity: 0; transform: translateY(-6px); } }

O acordeão exclusivo dispensa script: três details com o mesmo name abrem um de cada vez. O conteúdo entra por opacidade no pseudoelemento ::details-content. A animação de altura com interpolate-size ficou de fora de propósito: a MDN a marca como disponibilidade limitada em 21 de outubro de 2026, e quem não a tem veria o salto seco. As abas usam document.startViewTransition() com um view-transition-name no painel; o script confere se a função existe e se a pessoa pediu movimento reduzido antes de animar.

function trocar(indice) {
  const aplicar = () => { /* marca aria-selected e esconde os outros painéis */ };
  const reduzido = matchMedia("(prefers-reduced-motion: reduce)").matches;
  if (document.startViewTransition && !reduzido) document.startViewTransition(aplicar);
  else aplicar();
}
/* CSS */
[role="tabpanel"] { view-transition-name: painel; }
::view-transition-old(painel) { animation: 160ms ease-out both sair; }
::view-transition-new(painel) { animation: 220ms ease-out both entrar; }

A tabela prende o cabeçalho com position: sticky no th, dentro de um contêiner de altura fixa, e o filtro espera 120 ms depois da última tecla antes de esconder linhas, para o anúncio por aria-live não disparar a cada letra. A vitrine bento declara container: vitrine / inline-size e reorganiza as colunas por @container, o mesmo recurso da oficina anterior. O esqueleto pulsa três vezes e para; o portal reprova animação infinita, e a NN/g lembra que esqueleto só faz sentido para esperas de 1 a 10 segundos.

Passo a passo para pedir cada elemento por vibecoding

A ordem importa. Peça primeiro a estrutura que funciona sem script e sem movimento; só depois peça a camada de animação. Cada prompt abaixo traz o critério de aceite que você cola no pedido e a armadilha que os agentes de código mais repetem. Use o prompt como está no Claude Code, no Codex ou no Cursor e cobre o aceite antes de aprovar.

Um prompt por elemento, com o que conferir e o erro mais comum da IA.
PassoPrompt para colarCritério de aceiteArmadilha da IA
1. Resumo por seção"Gere um bloco de resumo no topo de cada seção com mais de 600 palavras: tese em uma frase e três pontos. Marque como aside com aria-label. Não altere o texto da seção."Resumo presente só nas seções longas; texto original intacto; leitura em voz alta anuncia o bloco.Reescrever a seção inteira em vez de resumir.
2. Índice fixo"Crie um nav 'Nesta página' com os h2 desta página, fixo na coluna lateral em telas largas, com aria-current na seção visível via IntersectionObserver. Sem rolagem suave forçada."Clique leva ao título sem ficar escondido sob o cabeçalho; marcação acompanha a rolagem; funciona sem JS como lista comum.Usar scroll listener a cada pixel e esquecer o scroll-margin-top.
3. Cabeçalho que encolhe"Cabeçalho sticky que ganha sombra e reduz o logo com transform ao rolar 120 px. Use animation-timeline: scroll() atrás de @supports e IntersectionObserver como reserva. Nunca anime height."Nenhuma propriedade de layout animada; funciona nas duas rotas; reduce-motion desliga tudo.Animar height e padding, e assumir que Firefox já tem scroll-timeline.
4. Menu amplo"Menu com popover e anchor positioning (position-area: bottom span-right, position-try-fallbacks). Prévia por foco. Fallback de posição por JS em navegador sem âncora."Esc fecha e devolve o foco; o painel troca de lado perto da borda; aparece por cima de contêineres com overflow.Instalar biblioteca de posicionamento antes de testar o nativo.
5. Paleta de comandos"Dialog nativo com showModal, aberto por botão e por Ctrl+K dentro do app. Busca sem acento, setas, Enter, contagem anunciada por aria-live. Índice em JSON estático."Foco preso no dialog; fundo não rola; Enter abre o item marcado; leitor de tela anuncia a contagem.Capturar Ctrl+K no documento inteiro e quebrar o atalho do navegador em outras páginas.
6. Acordeão e abas"Acordeão com details name='grupo' e entrada por opacidade em ::details-content. Abas com role=tab, setas e startViewTransition só quando existir e sem reduce-motion."Um item aberto por vez sem script; setas trocam de aba; sem View Transition a troca é imediata.Reimplementar o acordeão em JS e animar altura com interpolate-size sem fallback.
7. Tabela longa"Tabela com thead sticky dentro de contêiner com max-height, filtro com atraso de 120 ms, contagem em aria-live e caption descritiva."Cabeçalho visível na linha 80; filtro ignora acentos; contagem muda só após a pausa.Transformar a tabela em divs e perder a leitura por coluna.
8. Vitrine bento"Grade de seis colunas com cartões span 2 e destaque span 4, reorganizada por @container em 640 px e 400 px. Hover só com transform e sombra."Reorganiza pelo contêiner e ignora a janela; foco visível nos cartões; a transição lista cada propriedade em vez de usar o atalho que anima tudo.Usar media query de viewport e esquecer o contêiner lateral.
9. Esqueleto"Esqueleto no formato do conteúdo, pulsando no máximo três vezes, com aria-busy, trocado por entrada de opacidade. Nada para cargas abaixo de 1 segundo."Formato parecido com o conteúdo final; animação finita; aria-busy sai quando o conteúdo chega.Shimmer infinito e esqueleto genérico que vira um spinner disfarçado.

Bibliotecas de 2026: quando o nativo não cobre

Tudo o que o palco faz roda sem dependência. Uma biblioteca entra quando há um requisito que o nativo ainda não cobre, e cada uma custa peso, memória e manutenção. As versões e datas abaixo foram lidas no registro npm em 21 de outubro de 2026; os pesos vêm do bundlephobia na mesma data, minificados e comprimidos em gzip.

Versão vigente, peso e quando cada biblioteca vale o custo.
BibliotecaVersão e dataPeso gzipUse quandoDispense quando
Motion (ex-Framer Motion)14.5.0, 21/10/202655,6 KB (pacote inteiro; importe só o módulo usado)Animação de layout e listas com identidade em React, gestos e orquestração de sequências.A transição é de opacidade, transform ou troca de tela: CSS e View Transitions bastam.
GSAP3.15.0, 13/04/2026, gratuito desde a compra pela Webflow26,7 KB no núcleoLinhas do tempo encadeadas, rolagem narrativa complexa e precisão de quadro.O efeito é "revelar ao entrar na tela": animation-timeline: view() com @supports resolve.
Base UI1.9.0, 09/10/2026, padrão do shadcn/ui desde julho de 2026varia por componentePrecisa de combobox, menu aninhado ou seleção acessível em React sem desenhar do zero.Um popover, um dialog ou um acordeão: HTML nativo já entrega foco e teclado.
cmdk1.1.1, 14/03/202514,6 KBPaleta de comandos em React com grupos, atalhos aninhados e busca difusa.A paleta tem uma lista plana, como a deste exercício.
Floating UI1.8.0, 11/07/20268,0 KBPosicionar balões em navegadores sem anchor positioning quando o público ainda usa versões antigas.O público está em Chrome 125, Safari 26 e Firefox 147 ou mais novos.
Lenis1.3.27, 15/10/20265,3 KBRolagem suavizada em páginas de marca com efeitos sincronizados.Portal de leitura densa: rolagem nativa é mais previsível para quem tem pouca prática.
TanStack Virtual3.14.21, 16/10/20269,9 KBTabela ou lista com milhares de linhas que trava ao renderizar tudo.Até algumas centenas de linhas, filtro e cabeçalho preso são suficientes.
Fuse.js7.5.0, 13/07/20269,2 KBBusca tolerante a erro de digitação sobre um índice local de centenas de páginas.Bastam prefixo e inclusão de texto normalizado, como na paleta acima.

Para o Tailwind v4, nenhuma delas pede configuração especial: os tokens continuam no @theme e as classes de animação próprias entram como utilitários personalizados. A regra da política de adoção vale aqui também: recurso Newly Available sempre atrás de @supports, e o nativo vence a dependência quando cobre o requisito.

Teste barato com quem não é técnico

O benchmark diz o que costuma funcionar. Só o teste com as suas pessoas diz se funcionou no seu portal. Nielsen defende desde março de 2000 que cinco participantes encontram cerca de 85% dos problemas de usabilidade, e que vale mais repetir estudos pequenos do que fazer um grande. O roteiro abaixo cabe numa tarde.

  1. Convide cinco pessoas do perfil que mais sofre: assistente nova, cliente que acabou de assinar, estagiário. Nada de colega de produto.
  2. Dê três tarefas com resposta verificável: "encontre a página X", "descubra em que etapa está a entrega Y", "exporte a tabela Z". Cronometre e anote sucesso, sucesso com ajuda ou falha.
  3. Peça para pensar em voz alta. Registre a primeira coisa que a pessoa procura e onde ela hesita mais de cinco segundos.
  4. Ao final, aplique o SUS (System Usability Scale, dez perguntas, nota de 0 a 100). A média histórica de referência é 68; abaixo disso, a navegação ainda cobra demais.
  5. Compare com a rodada anterior: taxa de sucesso por tarefa, tempo mediano e nota SUS. Mude uma coisa por vez e repita em duas semanas.

Prompt para adaptar: "Aplique a este portal as nove técnicas para sites amplos: resumo por seção, índice fixo com seção atual, cabeçalho que encolhe, trilha de localização, menu amplo com popover e anchor positioning, paleta de comandos em dialog, acordeão com details name e abas com View Transition, tabela com cabeçalho preso e filtro, vitrine bento por contêiner e esqueleto finito. Entregue primeiro a versão sem script e sem movimento, depois a camada animada atrás de @supports e de prefers-reduced-motion, com o critério de aceite de cada item conferido."

Continue em "Bento responsivo", "Paleta dinâmica" e "Auditoria de interface" nos laboratórios do curso. As propostas de estados e eventos aprofundam a coordenação entre paleta, menu e índice; este exercício mantém dados fictícios e nenhuma integração real.

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. Coloque as regras normais de componente na camada declarada;
   confira regras sem camada e !important antes de concluir quem vence.
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.
Três movimentos para amanhã Três movimentos para amanhã Abra o @theme cor, espaço e tipo com nome de papel Varra hex cru cada achado vira token Cole a política com a data da revisão ao lado o agente lê em toda sessão
Os três movimentos do fechamento da aula, prontos para a agenda de amanhã.
Guias para postar

Dois guias prontos para o LinkedIn e o Instagram

Cada cartão abaixo foi desenhado para sair como imagem: escolha o formato, abra a tela de print, capture a área do cartão e publique com a legenda que o botão copia. O conteúdo resume o método desta página, então o post leva o leitor de volta para cá.

Design · Tailwind e tokensLeadlovers 2026

Peça os tokens antes da primeira tela

Cor, espaçamento e tipografia entram guardados num lugar só, nessa ordem.
  1. Abra o projeto pela cor. Uma paleta em OKLCH, do claro ao escuro, mantém contraste parecido na escala.
  2. Feche o espaçamento em seguida. Uma escala única encerra a margem inventada a cada tela.
  3. Deixe a tipografia por último. Tamanho e peso ganham nome de papel, no lugar do valor solto.
  4. Guarde tudo num arquivo só. Todas as telas leem dali, e trocar a decisão vira uma linha.
brasilgeo.ai/leadlovers2026Guia 1 de 2
Legenda sugerida para LinkedIn e Instagram
Trocar o azul da marca costuma virar uma caçada por arquivo, porque o valor foi colado em trinta lugares.

Token é o nome dado a uma decisão de design: você declara a cor uma vez e todas as telas leem dali. O guia de Tailwind do portal pede essa base já na primeira sessão do projeto, antes da primeira tela, na ordem cor, espaçamento e tipografia. A cor nasce em OKLCH, selo Widely Available desde 09/11/2025, que mantém contraste parecido em toda a escala. E o formato de intercâmbio estável é a especificação DTCG 2025.10 do W3C, então a mesma paleta viaja do Figma para o código sem retrabalho.

Salve o cartão e leve a ordem para a próxima abertura de projeto do seu time.

Guia completo: brasilgeo.ai/leadlovers2026/design/tailwind/

#Leadlovers #DesignSystem #Tailwind #DesignTokens
Design · Tailwind e tokensLeadlovers 2026

Três perguntas que dizem onde cada regra mora

Use na dúvida entre classe no elemento, arquivo de estilos e token.
  • A regra descreve a aparência de uma tela. Vira classe do Tailwind ao lado do elemento.
  • A regra descreve o comportamento do sistema. Vira CSS de verdade no arquivo de estilos.
  • A regra se repete em toda parte. Vira token com nome de papel e some do código da tela.
brasilgeo.ai/leadlovers2026Guia 2 de 2
Legenda sugerida para LinkedIn e Instagram
A discussão sobre onde escrever a regra de estilo consome mais reunião do que a própria regra.

O guia de Tailwind do portal fecha a arquitetura em uma frase: CSS nativo no arquivo de estilos, Tailwind v4 para compor as telas, sem CSS-in-JS salvo necessidade explícita. A pergunta que decide é o que a regra descreve. Aparência de uma tela vira classe ao lado do elemento. Comportamento do sistema vira arquivo de CSS, com a pilha de camadas declarada na primeira linha, para que a ordem resolva a disputa sem exclamação de importância. E o que se repete em toda parte vira token.

Três gavetas bastam para o time inteiro parar de improvisar o destino de cada regra.

Comente qual das três gavetas o seu projeto mais deixa vazia.

Guia completo: brasilgeo.ai/leadlovers2026/design/tailwind/

#Leadlovers #Tailwind #CSS #Frontend

Do DESIGN.md ao @theme do Tailwind

O DESIGN.md é o arquivo de identidade visual que o agente de IA lê antes de desenhar qualquer tela. O formato, publicado pelo Google Labs em versão alfa, abre com um bloco de tokens, os nomes dados a cada decisão de cor, fonte, canto e espaço, escrito em YAML, um texto simples de pares nome e valor.

Depois do bloco de tokens vêm oito seções de regras em texto corrido: visão geral, cores, tipografia, layout, elevação e profundidade, formas, componentes e o que fazer ou evitar. O agente tira do YAML os valores exatos e tira das seções a intenção por trás de cada escolha, o que evita a tela bonita que contraria a marca.

Para aprender a estrutura, o catálogo getdesign.md, mantido pela VoltAgent no repositório awesome-design-md sob licença MIT, reúne arquivos de referência de sites conhecidos. O comando abaixo grava um deles no projeto. Estude a ordem das seções e o jeito de nomear, depois troque cada valor pelos da sua marca.

# grava um arquivo de referência para estudar a estrutura
npx getdesign@latest add stripe

# depois de trocar os valores pelos da sua marca
npx @google/design.md lint
npx @google/design.md export

O pacote @google/design.md confere o arquivo com lint, compara versões com diff e, com export, gera o tema do Tailwind a partir dos tokens. Como o formato ainda está em alfa, confira as opções de cada comando no README do pacote antes de automatizar a geração.

Cuidado de marca. Um arquivo de referência do catálogo é uma análise independente, feita por terceiros, da identidade de outra empresa. Use para entender a forma do documento, nunca como ponto de partida visual. A página publicada leva as cores, a fonte e o nome da sua própria marca, sem nenhum elemento da empresa estudada.

Cenário: a página de vendas que inventou um terracota

Quem
Marina, diretora de arte do Ateliê Barro Vivo (marca fictícia de cerâmica), que vende um curso on-line de modelagem e mantém o DESIGN.md como fonte da identidade.
Tarefa
Gerar o @theme do Tailwind a partir do YAML do DESIGN.md, publicar a página de vendas do curso com classes como bg-primary e text-ink, e garantir que toda cor na tela venha de um token declarado.
Falha vista
O agente que montou a página escreveu bg-[#8A2D10] num botão, um terracota "parecido" que não existe no arquivo. Em outra rodada, a linha primary: #9C3D1E perdeu as aspas, o # abriu comentário em YAML e a cor primária sumiu do tema sem nenhum erro de compilação.
Resultado esperado
O lint do arquivo acusa a cor sem aspas; o conversor gera o @theme com todas as cores; a tabela de contraste mostra que on-primary só serve sobre primary; e um script de conferência reprova qualquer hexadecimal solto no código da página.

O caso tem duas pontas. Na origem, o YAML precisa ser lido sem perda, e a leitura tem armadilhas próprias: indentação por tabulação, cor sem aspas, nome repetido, referência para um nome que não existe. No destino, a tela precisa usar somente o que o tema declara, e a conferência disso é mecânica: todo valor de cor no HTML e no CSS do projeto deve corresponder a um token. O mapa segue a cor da marca por esse percurso inteiro.

Mapa da oficina. Do YAML no topo do DESIGN.md até a tela conferida: leitura, referências, @theme, contraste e a busca por cores fora do tema.
Do DESIGN.md ao @theme e à tela conferida Seis caixas ligadas por setas, em duas linhas. Primeiro, o DESIGN.md com o bloco YAML de tokens no topo e as oito seções abaixo. Segundo, o leitor YAML, que monta mapas por indentação e remove comentários; um desvio tracejado mostra a linha primary: #9C3D1E sem aspas, em que o # abre comentário e a cor some. Terceiro, a resolução de referências, em que accent: {colors.primary} vira #9C3D1E. Quarto, o bloco @theme com --color-primary, --font-body, --radius-md e --spacing-md. Quinto, a tabela de contraste, com on-primary sobre primary aprovado em 6,77 para 1 e on-primary sobre canvas reprovado em 1,08 para 1. Sexto, a tela conferida: cada cor vem de um token; um segundo desvio tracejado mostra bg-[#8A2D10], hexadecimal fora do tema, reprovado pelo script. 1. DESIGN.md --- tokens em YAML --- + oito seções de regras 2. Leitor YAML colors: / primary: "#9C3D1E" indentação, aspas, # comenta primary: #9C3D1E (sem aspas) o # abre comentário: a cor some 3. Referências accent: "{colors.primary}" accent = #9C3D1E 4. @theme --color-primary: #9C3D1E; --font-body; --radius-md 5. Contraste WCAG on-primary / primary 6,77:1 on-primary / canvas 1,08:1 6. Tela conferida bg-primary text-on-primary toda cor vem de um token bg-[#8A2D10] fora do tema: o script reprova Subconjunto do leitor: colors, typography, rounded e spacing; listas e outras seções ficam de fora.

  1. O DESIGN.md abre com o bloco YAML entre linhas de três hifens e segue com as oito seções em prosa. Só o bloco entra no conversor.
  2. O leitor monta mapas pela indentação em espaços, tira comentários fora de aspas e aceita escalares. Uma cor sem aspas vira comentário: o leitor desta oficina detecta o caso e avisa, mas um leitor YAML comum apenas perde o valor.
  3. Valores entre chaves, como {colors.primary}, são seguidos até o valor final, com limite de oito saltos e detecção de ciclo. Referência para nome ausente ou para um grupo gera erro.
  4. Cada token vira uma variável no @theme com o prefixo que o Tailwind v4 espera: --color-*, --font-*, --text-* com --line-height, --font-weight-*, --radius-* e --spacing-*. Nome repetido é recusado.
  5. As cores com nome de texto (ink, text, fg, on-) são medidas sobre as cores com nome de fundo (canvas, bg, surface, paper, white). Um on-* é medido também sobre a cor que acompanha. Aprovação a partir de 4,5:1.
  6. Na tela, cada classe de cor aponta para um token. O script de conferência varre HTML e CSS do projeto, extrai todo hexadecimal e reprova os que não constam no @theme, como bg-[#8A2D10].

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

A tabela de contraste, no passo 5, é o lugar em que o nome do token vira regra de uso. "on-primary" significa "texto sobre primary", e o par aprovado confirma isso. Os pares reprovados do mesmo token sobre canvas e surface mostram o que a identidade proíbe: branco sobre fundo claro. Quando a tela usa só tokens, esse tipo de combinação fica visível na tabela antes de chegar ao navegador.

Demonstrar: transforme os tokens do DESIGN.md em @theme

Cole o bloco YAML do topo de um DESIGN.md e converta. Você recebe o bloco @theme do Tailwind v4, a diretiva que transforma tokens em variáveis CSS e classes utilitárias, uma tabela de contraste entre cores de texto e de fundo e a lista do que precisa de correção.

O leitor aceita um subconjunto do formato: colors com pares nome e cor hexadecimal, typography com fontFamily, fontSize, fontWeight e lineHeight, além de rounded e spacing. Referências como {colors.primary} são resolvidas. O contraste segue a WCAG, a diretriz de acessibilidade do W3C: texto comum passa a partir de 4,5:1.

Observe a lista de avisos, que aparece entre o status e o bloco gerado. Ela tem três níveis. "Erro" interrompe um token (referência inexistente ou circular, tabulação na indentação). "Aviso" indica algo que o leitor corrigiu ou tolerou, mas que precisa de ajuste no arquivo (cor sem aspas, nome repetido, cor fora do formato hexadecimal). "Nota" registra o que ficou fora do subconjunto (listas, seções como shadows). O status resume o total de variáveis e os pares de contraste aprovados. Provoque cada nível editando o exemplo: tire as aspas de uma cor, duplique ink, aponte accent para {colors.inexistente}.

Dados de exercício: o bloco do Ateliê Barro Vivo já carregado no campo, com sete cores, duas famílias tipográficas, três raios e quatro espaços. A tabela abaixo lista os pares de contraste que o leitor monta a partir dos nomes, antes de qualquer edição.

Cores do exemplo e o papel que o nome atribui a cada uma na tabela de contraste.
TokenValorPapel pelo nome
primary#9C3D1EFundo de on-primary (não entra como texto nem como fundo geral)
on-primary#FFFFFFTexto, medido sobre primary e sobre todo fundo
ink#2B1E16Texto
ink-muted#6B5A4ETexto
canvas#FBF6EFFundo
surface#FFFFFFFundo
accent{colors.primary}Resolve para #9C3D1E; sem papel na tabela

Use espaços na indentação e cores entre aspas, como ink: "#2B1E16". Os nomes que contêm ink, text, fg ou começam com on- entram na tabela como texto; canvas, bg, surface, paper e white entram como fundo. Atalho: Ctrl e Enter convertem.

Ative JavaScript para converter um bloco seu. O resultado abaixo é o do exemplo do Ateliê Barro Vivo, uma marca fictícia, já calculado.

@theme {
  --color-primary: #9C3D1E;
  --color-on-primary: #FFFFFF;
  --color-ink: #2B1E16;
  --color-ink-muted: #6B5A4E;
  --color-canvas: #FBF6EF;
  --color-surface: #FFFFFF;
  --color-accent: #9C3D1E;
  --font-body: Nunito Sans, system-ui, sans-serif;
  --text-body: 1rem;
  --text-body--line-height: 1.6;
  --font-weight-body: 400;
  --font-display: Georgia, serif;
  --text-display: 2.5rem;
  --text-display--line-height: 1.1;
  --font-weight-display: 700;
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-full: 9999px;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
}
Contraste WCAG entre cada cor de texto e cada fundo. Cor que começa com on- também é medida sobre a cor que ela acompanha.
TextoFundoContrasteResultado
on-primary #FFFFFFprimary #9C3D1E6,77:1Aprovado
on-primary #FFFFFFcanvas #FBF6EF1,08:1Reprovado
on-primary #FFFFFFsurface #FFFFFF1,00:1Reprovado
ink #2B1E16canvas #FBF6EF15,02:1Aprovado
ink #2B1E16surface #FFFFFF16,15:1Aprovado
ink-muted #6B5A4Ecanvas #FBF6EF6,11:1Aprovado
ink-muted #6B5A4Esurface #FFFFFF6,57:1Aprovado

Repare nas linhas reprovadas do exemplo: on-primary é branco e só serve sobre a terracota. A tabela mostra a combinação proibida antes que ela apareça numa tela. Ao adaptar, mantenha o DESIGN.md como origem, gere o tema de novo a cada mudança e deixe o CSS derivado sem edição manual.

Investigar as falhas

As quatro primeiras falhas acontecem na leitura do YAML e podem ser reproduzidas no campo acima. As duas últimas acontecem no projeto, depois de colar o @theme, e pedem o script de conferência da seção de código.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
A cor primária some do @theme e o lint do pacote não acusa nadaA linha primary: #9C3D1E está sem aspas; em YAML, # precedido de espaço abre comentário e o valor fica vazio.Tire as aspas no campo e converta. O leitor desta oficina emite "Aviso: a cor está sem aspas" e recupera o valor; um leitor YAML comum devolve primary vazio.Escreva primary: "#9C3D1E". Inclua uma regra no lint do projeto que procure : # sem aspas nas linhas de cor.
"Erro: Referência inexistente em colors.accent"O valor {colors.primario} aponta para um nome que o bloco não declara (grafia diferente ou token removido).O aviso cita o caminho. Busque o nome no campo (Ctrl+F): ele aparece só dentro das chaves.Aponte para o nome exato ou declare o token. Renomeie tokens com busca e substituição no arquivo inteiro.
"Erro: a indentação usa tabulação" e metade das cores desapareceO editor converteu espaços em tabulações ao colar; YAML só aceita espaços.Ative a exibição de caracteres invisíveis no editor ou cole o bloco num campo que mostre as tabulações.Configure o editor para indentar com dois espaços em arquivos .md e .yaml e reconverta.
"Aviso: Nome repetido: colors.ink aparece mais de uma vez"Duas rodadas de edição deixaram o mesmo token em dois lugares; vale o último, e a primeira cor fica silenciosamente ignorada.Duplique ink com outro valor no campo e observe qual aparece no @theme.Apague a duplicata. O diff do pacote mostra quando um token muda de valor entre versões.
Um botão da página tem terracota diferente do restoClasse arbitrária bg-[#8A2D10] ou valor literal em CSS, escrito pelo agente ou copiado de outra marca.Rode node conferir-cores.mjs: ele lista o arquivo, a linha e o hexadecimal sem token correspondente. No DevTools, o estilo computado do botão não aponta para nenhuma variável --color-*.Troque por bg-primary. Se a cor nova for mesmo necessária, declare o token no DESIGN.md e regenere o tema.
on-primary aparece sobre o canvas num cartão da páginaA combinação reprovada na tabela (1,08:1) foi usada mesmo assim, porque as classes existem e o Tailwind compila qualquer par.Selecione o cartão em Elementos e confira background-color e color no painel Computed: --color-canvas e --color-on-primary.Use text-ink sobre canvas. Registre na seção "O que fazer ou evitar" do DESIGN.md que on-* só acompanha a cor de mesmo nome.

Código de referência

Três arquivos fecham o circuito. O primeiro é o esqueleto do DESIGN.md com o bloco de tokens e as oito seções; o segundo é a folha do Tailwind que recebe o @theme gerado; o terceiro é o script que varre o projeto e reprova cores fora do tema. Os três ficam no repositório e rodam no CI.

---
# Tokens: valores exatos que o agente e o conversor leem.
name: Ateliê Barro Vivo
colors:
  primary: "#9C3D1E"       # terracota da marca; sempre entre aspas
  on-primary: "#FFFFFF"    # texto sobre primary, e só sobre primary
  ink: "#2B1E16"
  ink-muted: "#6B5A4E"
  canvas: "#FBF6EF"
  surface: "#FFFFFF"
  accent: "{colors.primary}"
typography:
  body: { fontFamily: "Nunito Sans, system-ui, sans-serif", fontSize: "1rem", fontWeight: 400, lineHeight: 1.6 }
  display: { fontFamily: "Georgia, serif", fontSize: "2.5rem", fontWeight: 700, lineHeight: 1.1 }
rounded: { sm: "4px", md: "8px", full: "9999px" }
spacing: { xs: "4px", sm: "8px", md: "16px", lg: "24px" }
---

# Ateliê Barro Vivo

## 1. Visão geral
Marca de cerâmica artesanal que vende um curso on-line. Tom caloroso, pouco contraste de cor, muito contraste de texto.

## 2. Cores
primary só em ações e títulos de destaque. on-primary nunca sobre canvas ou surface (1,08:1 e 1,00:1).

## 3. Tipografia
display para títulos de página; body para o restante. Nada abaixo de 1rem no corpo.

## 4. Layout
Coluna de leitura até 68 caracteres; grade de duas colunas acima de 480px de contêiner.

## 5. Elevação e profundidade
Uma sombra suave em cartões; sem sombras em botões.

## 6. Formas
rounded.md em cartões e campos; rounded.full só em avatares e selos.

## 7. Componentes
Botão primário: bg-primary text-on-primary rounded-md. Cartão: bg-surface text-ink.

## 8. O que fazer ou evitar
Fazer: toda cor por token. Evitar: classes arbitrárias como bg-[#hex] e cor literal em CSS.
/* Folha global do projeto. O bloco @theme é colado do conversor ou gerado
 * por "npx @google/design.md export"; nunca editado à mão. */
@import "tailwindcss";

/* Toda variável abaixo gera utilitários: bg-primary, text-ink, font-display,
 * text-body, rounded-md, p-md e assim por diante. */
@theme {
  --color-primary: #9C3D1E;
  --color-on-primary: #FFFFFF;
  --color-ink: #2B1E16;
  --color-ink-muted: #6B5A4E;
  --color-canvas: #FBF6EF;
  --color-surface: #FFFFFF;
  --color-accent: #9C3D1E;
  --font-body: Nunito Sans, system-ui, sans-serif;
  --text-body: 1rem;
  --text-body--line-height: 1.6;
  --font-weight-body: 400;
  --font-display: Georgia, serif;
  --text-display: 2.5rem;
  --text-display--line-height: 1.1;
  --font-weight-display: 700;
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-full: 9999px;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
}

/* Base mínima: a página inteira nasce dos tokens. */
@layer base {
  body { background: var(--color-canvas); color: var(--color-ink); font-family: var(--font-body); }
  h1, h2 { font-family: var(--font-display); }
}
// Reprova qualquer hexadecimal no código da tela que não exista no @theme.
// Uso: node conferir-cores.mjs app.css src
import { readFile, readdir } from "node:fs/promises";
import { join, extname } from "node:path";

const [, , folhaTema = "app.css", pasta = "src"] = process.argv;
const EXTENSOES = new Set([".html", ".css", ".jsx", ".tsx", ".astro", ".vue", ".svelte"]);
const HEX = /#(?:[0-9a-f]{3}|[0-9a-f]{6})\b/gi;

// Normaliza #abc para #AABBCC, para comparar sem depender da grafia.
const normalizar = (hex) => {
  let h = hex.slice(1).toUpperCase();
  if (h.length === 3) h = [...h].map((c) => c + c).join("");
  return "#" + h;
};

// Lê as cores declaradas no bloco @theme.
const tema = await readFile(folhaTema, "utf8");
const bloco = tema.match(/@theme\s*\{([\s\S]*?)\}/)?.[1] ?? "";
const declaradas = new Set([...bloco.matchAll(HEX)].map((m) => normalizar(m[0])));
if (!declaradas.size) { console.error(`Nenhuma cor encontrada no @theme de ${folhaTema}.`); process.exit(2); }

// Percorre a pasta da tela e acusa cada hexadecimal fora do tema.
async function* arquivos(dir) {
  for (const item of await readdir(dir, { withFileTypes: true })) {
    const caminho = join(dir, item.name);
    if (item.isDirectory()) yield* arquivos(caminho);
    else if (EXTENSOES.has(extname(item.name))) yield caminho;
  }
}
const problemas = [];
for await (const arquivo of arquivos(pasta)) {
  const linhas = (await readFile(arquivo, "utf8")).split("\n");
  linhas.forEach((linha, i) => {
    for (const m of linha.matchAll(HEX)) {
      const cor = normalizar(m[0]);
      if (!declaradas.has(cor)) problemas.push(`${arquivo}:${i + 1}: ${cor} não é um token do tema`);
    }
  });
}
if (problemas.length) { console.error(problemas.join("\n")); process.exit(1); }
console.log(`Conferência concluída: toda cor em ${pasta} vem de um dos ${declaradas.size} tokens do tema.`);

O script trata um hexadecimal igual ao de um token como aprovado, mesmo escrito por extenso. Isso é deliberado para a primeira rodada: a meta imediata é eliminar cores que não existem na marca. Numa segunda rodada, acrescente uma regra que reprove também os literais iguais, para que a tela use só as classes do tema e a troca de valor no DESIGN.md chegue a todos os lugares de uma vez.

Critérios de aceite

Levar para o projeto. Em React com Next.js, o app.css entra em app/layout.tsx e o script roda no prebuild junto com npx @google/design.md lint; em Astro, a folha vai em src/styles e a conferência varre src; em HTML puro, aponte o script para a pasta das páginas. Em produção, acompanhe o número de hexadecimais fora do tema por release (meta zero), o número de pares reprovados na tabela que aparecem em telas, e o tempo entre uma mudança no DESIGN.md e a publicação, que cai quando o tema deixa de ser editado à mão.

Fontes, com acesso em 21/10/2026: formato DESIGN.md do Google Labs, em alfa, e o pacote @google/design.md no npm; catálogo getdesign.md e repositório awesome-design-md da VoltAgent; variáveis de tema do Tailwind v4; critério de contraste mínimo da WCAG 2.2; comentários na especificação YAML 1.2.2.

Perguntas frequentes

Qual a versão mais recente do Tailwind CSS?

Em 2 de outubro de 2026, a versão estável no registro npm é a 4.3.3, publicada em 16 de julho de 2026. A série 4.3, de maio de 2026, trouxe utilitários de scrollbar, @container-size para container query de altura e valores padrão em utilitários funcionais. A linha 3 segue com suporte de longo prazo na 3.4.19. Antes de aceitar código gerado por IA, confira no package.json qual versão ele assume.

Como criar design tokens no Tailwind v4?

Declare cada decisão como variável dentro do bloco @theme do arquivo CSS principal, com o prefixo que diz o tipo: --color-marca, --font-titulo, --text-destaque, --spacing-secao. O Tailwind transforma cada variável em classe, e --color-marca vira bg-marca, text-marca e border-marca, além de ficar disponível como variável CSS comum para estilo próprio. Comece por cor, espaçamento e tipografia, com nomes de papel, como marca e alerta, em vez de nomes de tom.

O Tailwind serve para landing page de campanha?

Serve quando a página é escrita em código, e não montada no construtor visual da plataforma de automação. A vantagem é o peso: a página oficial do Tailwind informa, em outubro de 2026, que a maioria dos projetos entrega menos de 10 kB de CSS. Com os tokens da marca no @theme, cada nova landing nasce com a mesma cor, fonte e espaçamento, e a agência troca de cliente trocando o bloco de tokens.

O que é um token de design e por que começar por ele?

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 estável é a especificação DTCG 2025.10 do W3C.

O que mudou na configuração do Tailwind v4?

O tailwind.config.js deu lugar ao bloco @theme dentro do próprio arquivo de estilos, e o v4 dispensa Sass. O v4.0 estável saiu em 22 de janeiro de 2025 com motor novo, com as partes mais caras em Rust e o Lightning CSS integrado, e builds completos 3,78 vezes mais rápidos. Quem chega da versão 3 migra com npx @tailwindcss/upgrade, em branch novo e revisando o diff.

Por que classe montada dinamicamente quebra no Tailwind?

O compilador lê o código-fonte como texto puro e só gera as classes que enxerga como strings completas, na regra da documentação oficial: Always use complete class names. Uma expressão como bg-${cor}-500 produz classe nenhuma no arquivo final, e a interface quebra em silêncio. A solução é o mapa estático de variantes, um objeto com as strings inteiras que o revisor confere de relance.

Como derivar variações de cor sem manter dezenas de valores à mão?

Com color-mix(in oklch, var(--marca) 88%, white), Widely Available desde 9 de novembro de 2025. A conta do curso: oito matizes com quatro estados custam 32 valores mantidos à mão, ou oito valores base e uma função. O in oklch evita o cinza que a mistura em sRGB produz no meio do caminho, e cada tom derivado se mede como cor nova, porque pode cair abaixo do contraste mínimo.

Quando um recurso novo de CSS pode entrar em produção?

Pela política Baseline: recurso Widely Available entra livre; recurso Newly Available exige @supports com fallback funcional; recurso fora do Baseline entra só como melhoria de degradação elegante, sob pedido formal. O @supports testa a propriedade exata escrita no código, e entre o recurso nativo do navegador e uma dependência nova, o navegador vence sempre que cobrir o requisito.

Como deixar um site com centenas de páginas fácil para quem não é técnico?

Com camadas, no máximo duas, como Nielsen recomenda desde 2006: resumo no topo de cada seção, índice "Nesta página" fixo com a seção atual marcada, cabeçalho que encolhe sem roubar a tela, trilha de localização, menu amplo com prévia, paleta de comandos com Ctrl+K, acordeão e abas para comparar sem perder contexto, tabela com cabeçalho preso e filtro, e esqueleto para esperas de 1 a 10 segundos. Em 2026 tudo isso é nativo: popover, anchor positioning, dialog, details name, View Transitions e consultas ao contêiner. A oficina deste guia mostra os nove elementos numa mesma página de exercício.

Quais recursos de movimento já podem ir para produção em outubro de 2026?

View Transitions no mesmo documento são Baseline Newly available desde 14 de outubro de 2025, com o Firefox 144; anchor positioning é Newly available desde janeiro de 2026, com o Firefox 147; o popover é Newly available desde janeiro de 2025. Os três entram atrás de @supports ou de verificação de função. Animação ligada à rolagem com animation-timeline: scroll() funciona no Chrome 115 e no Safari 26, e o Firefox só a traz a partir da versão 161, por isso precisa de uma reserva por IntersectionObserver. Animar altura com interpolate-size segue com disponibilidade limitada.

Por que uma política de adoção escrita virou manutenção básica?

Porque o ritmo das plataformas acelerou: o anúncio oficial de 3 de março de 2026 marca o Chrome em ciclos de atualização de duas semanas a partir da versão 153, em 8 de setembro de 2026. O movimento prático do guia é colar a política das cinco regras de adoção no arquivo de instruções que os agentes de IA leem, com a data de revisão ao lado de cada regra.

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.

Instruções deste guia para agentes de IA (Markdown e JSON)

Regras, decisões, números, erros comuns, código e checklist destilados da página para Claude, Codex e outros agentes. Arquivos: agentes.md · agentes.json · índice dos guias

# 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)
Dados desta página para agentes de IA
# Tailwind CSS v4: @theme, design tokens e CSS moderno

- Endereço: https://brasilgeo.ai/leadlovers2026/design/tailwind/
- Objetivo: 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.
- Tipo: portal-leadlovers-design
- Atualizada em: 2026-11-16
- Publicada em: 2026-08-18
- Idioma: pt-BR
- Indexável: sim

## Seções
1. [A aula, em vídeo e em podcast](https://brasilgeo.ai/leadlovers2026/design/tailwind/#aula-title)
2. [Tokens antes da primeira tela](https://brasilgeo.ai/leadlovers2026/design/tailwind/#tokens-title)
3. [Tailwind v4 na prática, do zero ao primeiro botão](https://brasilgeo.ai/leadlovers2026/design/tailwind/#tailwind-title)
4. [Onde cada regra mora](https://brasilgeo.ai/leadlovers2026/design/tailwind/#divisao-title)
5. [As armadilhas de quem gera código com IA](https://brasilgeo.ai/leadlovers2026/design/tailwind/#armadilhas-title)
6. [Cor derivada e tema: oito valores e uma função](https://brasilgeo.ai/leadlovers2026/design/tailwind/#cor-derivada-title)
7. [A plataforma e a política de adoção](https://brasilgeo.ai/leadlovers2026/design/tailwind/#plataforma-title)
8. [As medidas dos sites de alto padrão](https://brasilgeo.ai/leadlovers2026/design/tailwind/#medidas-title)
9. [Oficina: leve o token do JSON ao CSS que o navegador aplica](https://brasilgeo.ai/leadlovers2026/design/tailwind/#llwt-token-title)
10. [Oficina: teste o componente na coluna em que ele será usado](https://brasilgeo.ai/leadlovers2026/design/tailwind/#llwt-portable-title)
11. [Oficina: site amplo que qualquer pessoa digere](https://brasilgeo.ai/leadlovers2026/design/tailwind/#lldn-titulo)
12. [Prompts prontos](https://brasilgeo.ai/leadlovers2026/design/tailwind/#prompts-title)
13. [Dois guias prontos para o LinkedIn e o Instagram](https://brasilgeo.ai/leadlovers2026/design/tailwind/#llg-guias-title)
14. [Do DESIGN.md ao @theme do Tailwind](https://brasilgeo.ai/leadlovers2026/design/tailwind/#lldm-titulo)
15. [Perguntas frequentes](https://brasilgeo.ai/leadlovers2026/design/tailwind/#faq-title)
16. [Por onde começar](https://brasilgeo.ai/leadlovers2026/design/tailwind/#proximo-h)

## Números em destaque
- 1.284: Dado de exercício. Em um painel real, este número vem da mesma consulta que alimenta o relatório. (como publicado nesta página, atualizada em 2026-11-16)
- 4.120: Sequência de boas-vindas. (como publicado nesta página, atualizada em 2026-11-16)

## Links principais
- [Início do portal](https://brasilgeo.ai/leadlovers2026/)
- [Design](https://brasilgeo.ai/leadlovers2026/design/)
- [menus e paginação](https://brasilgeo.ai/leadlovers2026/design/navegacao/)
- [React](https://brasilgeo.ai/leadlovers2026/design/react/)
- [diagramas](https://brasilgeo.ai/leadlovers2026/design/diagramas/)
- [Baixe o arquivo da aula](https://brasilgeo.ai/media/leadlovers/r2/design-tailwind/video-tailwind.mp4)
- [Baixar a legenda](https://brasilgeo.ai/media/leadlovers2026/design-tailwind/video-tailwind.pt.vtt)
- [Baixar o texto](https://brasilgeo.ai/media/leadlovers2026/design-tailwind/video-tailwind.txt)
- [Baixe o episódio](https://brasilgeo.ai/media/leadlovers/r2/design-tailwind/podcast-tailwind.m4a)
- [Baixar o texto](https://brasilgeo.ai/media/leadlovers2026/design-tailwind/podcast-tailwind.txt)
- [llms.txt](https://brasilgeo.ai/leadlovers2026/glossario/)
- [consultas de tamanho e estilo na MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) (externo)
- [documentação de @scope](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/%40scope) (externo)
- [MDN demonstra a seleção explícita de tema](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark) (externo)
- [interpolação nativa](https://developer.chrome.com/docs/css-ui/animate-to-height-auto) (externo)
- [custo de layout](https://web.dev/articles/avoid-large-complex-layouts-and-layout-thrashing) (externo)
- [formato DTCG 2025.10](https://www.designtokens.org/tr/2025.10/format/) (externo)

## Para agentes
- JSON com os mesmos dados no elemento script#pagina-para-agentes (esquema pagina-brasilgeo-para-agentes/v1).
- JSON-LD da página no <head>: Article, VideoObject, AudioObject, BreadcrumbList, FAQPage.
- Índice do site para agentes: https://brasilgeo.ai/llms.txt
- Listas resumidas para caber em 12 KB (sem subtítulos); a página completa está no endereço acima.