Construir a identidade com tokens, CSS moderno e DESIGN.md

Um azul reescrito em dez telas por engano custa um dia de revisão. Token de design (o valor de estilo guardado com nome, como a etiqueta na lata de tinta) corrige a cor com uma edição só. Quem aprova ou constrói o site da empresa ganha cor, espaço e tipografia num arquivo aberto, lido por Figma e por código.

Comece por três famílias, nesta ordem: cor, espaçamento e tipografia. Cor concentra a maior parte da inconsistência visível; espaçamento numa escala de quatro pixels resolve o desalinhamento; três tamanhos de fonte resolvem a hierarquia entre título e corpo.

Gere a cor em OKLCH, a forma de descrever cor por luminosidade, croma e matiz, como brilho, saturação e tom de uma TV. Mexer só na luminosidade muda o brilho de forma previsível. A escala de 50 a 950 nasce com contraste linear em toda a faixa, e o 500 de qualquer matiz tem o mesmo peso visual.

O uso é seguro em base ampla. As funções modernas de cor, oklch(), color() e color-mix() entre elas, estão em Baseline Widely Available desde 9 de novembro de 2025. O rótulo significa mais de 30 meses de estabilidade nos navegadores que o critério cobre.

Dessa escala derivam os estados sem hexadecimal novo. color-mix(in oklch, var(--marca) 88%, white) calcula o tom de passar o mouse com um valor só. Oito matizes com quatro estados passam de 32 valores para oito e uma função.

O light-dark() devolve um valor no tema claro e outro no escuro, desde que color-scheme esteja declarado. Ele ainda não chegou a todo navegador em uso. Por isso escreva a cor de reserva na declaração anterior, que o navegador sem a função aproveita.

Contraste é requisito medido: o piso é 4,5:1 no texto normal e 3:1 no texto grande, nos dois temas. Cor gerada por cálculo pode cair abaixo do piso num tom que ninguém escolheu, e a medição no painel do navegador leva um minuto.

Peça os tokens na primeira sessão do projeto, antes da primeira tela. Sem eles, cada tela que o agente (a ferramenta de IA que escreve o código) gera inventa um azul próprio. A inconsistência chega em lote, em vez de chegar aos poucos.

Tokens merecem um formato que sobreviva à troca de ferramenta. O DTCG é um arquivo neutro, como a receita que qualquer cozinha lê, e Figma, Penpot, Tokens Studio, Style Dictionary e Terrazzo leem e escrevem o formato.

A edição 2025.10 foi publicada em 28 de outubro de 2025 como relatório final do Community Group do W3C. Ela não é uma W3C Recommendation. Fixe a edição usada pelo projeto. Cada token tem um valor em $value e precisa de um tipo determinável: $type pode estar no próprio token ou ser herdado do grupo. $description é opcional, e uma referência como {cor.marca.primaria} reaproveita outro token. Confira se as ferramentas escolhidas suportam essa edição.

Tailwind, a coleção de classes prontas que você escreve direto no elemento, como etiquetas coladas na peça, lê esses tokens no código. Da versão 4.0 em diante, a cor e a medida vivem num bloco @theme dentro do próprio CSS, e a paleta padrão passou a ser OKLCH. Um botão então vira bg-marca text-white.

Use em projeto React, Astro ou Vue. Deixe fora de e-mail HTML e de relatório de arquivo único, sem passo de build.

A armadilha que mais derruba tela gerada por agente é a classe montada em tempo de execução, como bg-$cor-500. O compilador do Tailwind varre o texto do código procurando classes escritas por inteiro. A concatenada nunca aparece escrita, some no build e o botão chega sem cor em produção. A saída é um mapa de classes completas, escolhido por chave.

As ferramentas de design de 2026 leem esse arquivo. O Figma, na Config 2026, ganhou AI Agent, o Make, o Sites com CMS e uma camada de código. O v0 da Vercel integrou Git, com editor completo e preço por token. O Penpot, open source, ganhou servidor MCP (o protocolo que deixa o agente ler o desenho) em julho.

A escolha segue o time: Figma quando o design já vive nele, v0 quando o protótipo nasce em código, Penpot quando o desenho precisa ficar em servidor seu.

Tipografia carrega a personalidade da página, e o agente entrega a mesma família de sempre quando você não escolhe. Use uma família, ou duas claramente distintas entre título e corpo. Defina uma escala de tamanhos com peso e espaçamento intencionais. Mantenha a linha abaixo de 80 caracteres, com entrelinha um pouco maior quando a fonte tem serifa.

A skill frontend-design chama atenção para três tratamentos recorrentes: destacar uma palavra do título, usar rótulos em caixa alta e acrescentar rótulos desnecessários acima do conteúdo. Revise cada escolha contra o briefing. Um destaque que comunica hierarquia pode ficar; um enfeite sem função pode sair. Esses sinais não demonstram quem criou a página.

Fonte variável é o piso: um arquivo produz todos os pesos e substitui de seis a 12 arquivos estáticos, com suporte em todo navegador. Inter, Geist, Roboto Flex, Source Serif e Fraunces são as referências.

Sirva a fonte do próprio site com o Fontsource e com subsetting, só os caracteres que o site usa, nunca por chamada ao Google Fonts. A sentença de Munique tratou o IP enviado ao Google como dado pessoal, e o endereço do visitante sai para outra empresa sem ele saber.

Três refinos fecham o token de tipografia. A escala fluida por clamp() faz o texto crescer junto com a tela, sem regra extra. E font-variant-numeric: tabular-nums dá a mesma largura a todos os dígitos, então a tabela de preços para de dançar a cada atualização.

O terceiro pede cuidado com o estado de suporte. O text-wrap: balance está em Baseline Newly Available e serve a título e trecho curto, com o Chromium balanceando até seis linhas e o Firefox até dez. O pretty do corpo segue em Limited Availability, sem o Firefox, então ele entra como melhoria progressiva: o texto precisa ficar legível sem ele.

Um tom escolhido de cabeça vira três tons diferentes em três telas. O ateliê de cerâmica tinha uma terracota no catálogo, outra no carrinho e uma terceira no e-mail. Ele passou a guardar a cor num token em OKLCH, dentro do arquivo DTCG. Agora o ajuste feito no Figma vale também para o CSS regerado, sem ninguém reescrever hex.

Antes de aprovar a tela, exija tokens em OKLCH no bloco @theme, um mapa de classes completas em vez de concatenação e a fonte servida pelo Fontsource. Meça o contraste nos dois temas: abaixo de 4,5:1, ajuste a luminosidade antes de seguir.

Recuse uma biblioteca quando o navegador já resolve

Com os tokens guardados em formato aberto, a pergunta seguinte é quanto do CSS nativo já entrega sozinho o que antes pedia uma biblioteca inteira.

Uma biblioteca a mais custa peso no pacote e mais uma dependência para manter. O CSS, a linguagem que dá aparência à página, já ordena estilos, fecha regras numa região e faz o cartão reagir ao conteúdo sozinho.

Quem revisa o que o agente (a ferramenta de IA que escreve o código) entrega ganha o mapa do consolidado e um laboratório com cinco recursos rodando.

Dois estados separam a lista. Consolidado roda em Chrome, Firefox e Safari atuais e admite um plano B trivial. Em chegada falta em pelo menos um navegador. Esse recurso entra atrás de @supports, a pergunta ao navegador se ele conhece a regra, como testar a tomada antes de ligar o aparelho.

Esses dois rótulos têm um equivalente público, e usá-lo evita discussão. O Baseline, mantido pelo WebDX Community Group, classifica cada recurso em Widely Available, Newly Available e Limited Availability, sempre com data.

Widely Available exige 30 meses de estabilidade interoperável num conjunto fixo de navegadores. Esse conjunto reúne Safari de macOS e iOS, Firefox de computador e Android, Chrome de computador e Android e Edge de computador. Newly Available é o recurso que acabou de fechar esse conjunto, e Limited Availability é o que ainda falta em algum deles.

Dizer "é Baseline" sem a qualificação é o erro que quebra em produção. O Interop 2026 é o acordo anual entre os navegadores sobre o que cada um vai entregar. Ele lista 19 áreas de foco, 11 delas de CSS, e o que está lá chega a todos dentro do ano.

O @layer organiza a prioridade das regras antes da comparação dos seletores. Entre declarações normais da mesma origem, a camada declarada por último tem prioridade; uma regra normal fora das camadas tem prioridade sobre as que estão nelas. Com !important, a ordem se inverte: a primeira camada tem prioridade, e declarações importantes em camadas vencem as importantes fora delas. Leia o exemplo abaixo como uma disputa entre regras normais em camadas. O aninhamento nativo escreve o estado do botão dentro da própria regra e dispensa o Sass (o pré-processador que fazia isso).

O @scope limita uma regra a uma região, com fronteira inferior. O mesmo seletor de link ganha um estilo dentro da ficha do prato e outro dentro do rodapé. A fronteira to() deixa o link do comentário aninhado fora dos dois. Sem ele, a regra do cartão vaza para tudo o que está dentro dele.

:has() deixa o pai reagir ao filho: o cartão muda de borda quando o checkbox dentro dele está marcado, sem script. Ele chegou a Widely Available em junho de 2026, e o subgrid, em 15 de março de 2026, pelos 30 meses corridos desde o Chrome 117.

O subgrid alinha as linhas de dois cartões vizinhos pela grade do pai, e o preço para de flutuar quando um título ocupa duas linhas.

Já o text-box-trim corta o espaço fantasma que a métrica da fonte deixa acima e abaixo do título, e o título passa a encostar onde o desenho manda. Chegou ao Chrome e Edge 133 e ao Safari 18.2; o Firefox ainda não o tem.

Da lista em chegada, três merecem pedido explícito atrás de @supports. shape() desenha recorte complexo em clip-path e entrou em Chromium e WebKit em fevereiro de 2026. if() e @function trazem condicional e função ao CSS puro, só em Chromium. ::scroll-marker monta carrossel nativo com indicadores, com cerca de 69% de cobertura.

O select estilizável nativo, o customizable select, ainda está em desenvolvimento no grupo que define o CSS. Até lá o agente reimplementa a lista de opções à mão, e é dali que nasce a maior parte do script de menu.

Os outros recursos da lista aparecem rodando em outras aulas, e a tabela remete a cada uma. O critério de adoção cabe numa frase. Use o recurso nativo atrás de @supports quando o desenho de reserva já resolve o caso, e segure a biblioteca só enquanto esse desenho quebra a página.

Num restaurante com cardápio online, o cartão do prato ganha borda quando o filtro "sem glúten" está marcado, por :has(). Os preços de dois pratos vizinhos ficam alinhados por subgrid mesmo quando um nome ocupa duas linhas. Nenhuma biblioteca entra, e atualizar o cardápio segue sendo editar um arquivo de CSS.

Peça o CSS de 2026 num pedido só: camadas em @layer, aninhamento nativo, @scope na região que vaza e :has() com subgrid atrás de @supports. Antes de pedir um recurso ainda em chegada, confira no painel de visitas a fatia de Firefox e Safari antigos. Só aceite o recurso quando a reserva já entrega a mesma tela.

Escreva as regras visuais que o agente lê antes de desenhar

Decisão de token e de recurso nativo só sobrevive ao próximo pedido quando está escrita num arquivo que o agente lê antes de desenhar a tela.

Cinco telas geradas com DESIGN.md saíram com os hex exatos da marca; sem ele, o Cursor errou o raio do card em uma das cinco. O arquivo de tokens diz ao agente qual cor usar. O porquê de cada escolha, que só o DESIGN.md guarda, é o que decide o caso que nenhum token previu.

Esse arquivo é o sistema de design da casa, o manual de regras visuais que todo mundo segue. Quem já tem cores com nome ganha toda tela com a cara da marca, porque o agente lê o manual antes de qualquer mudança.

O DESIGN.md é uma especificação do Google Labs, nascida no Google Stitch, em versão alpha com licença Apache 2.0. É um arquivo Markdown (texto simples com marcas de título) em duas camadas. Em cima, os tokens (os valores de cor, espaço e letra guardados com nome, como a etiqueta na lata de tinta). Embaixo, a prosa com o porquê.

Quem lê as duas camadas é o agente, a ferramenta de IA que escreve o código. O valor ele já tinha; o critério é o que faltava.

A prosa tem oito seções em ordem fixa: visão geral, cores, tipografia, layout, elevação e profundidade, formas, componentes e faça e não faça. Uma seção pode faltar, mas as presentes mantêm a ordem, e um título repetido invalida o arquivo. Um token cita outro entre chaves: {colors.primary}.

Um componente, a peça repetida da tela como o botão, aceita fundo, cor de texto, tipografia, raio, preenchimento, tamanho, altura e largura. O estado de passar o mouse é uma entrada separada.

A cor entra só em hex sRGB. OKLCH e P3, que o rascunho do formato DTCG já aceita, ficam para depois. É a diferença que mais surpreende quem chega de um arquivo de tokens moderno.

Na linha de comando, npx @google/design.md faz três coisas. O lint confere nove regras do arquivo. Entre elas estão a referência quebrada, o par de fundo e texto abaixo de 4,5:1 e o token que ninguém usa. Entram também a seção fora de ordem e a chave com erro de digitação.

O diff compara duas versões e o export gera o arquivo do Tailwind, as classes prontas de estilo, e o formato DTCG. Coleções públicas já trazem arquivos inspirados em Stripe, Linear e Vercel: leia-os como forma, porque o conteúdo é da sua marca.

Guarde o arquivo na raiz do repositório, a pasta do projeto com histórico. O CLAUDE.md ou o .cursorrules ganha uma linha: leia DESIGN.md antes de qualquer mudança de interface.

A WaveSpeed testou em 14 de maio de 2026 com cinco telas. O Claude Code usou os hex exatos em cinco de cinco, e o Cursor acertou quatro, porque trocou o raio pequeno pelo médio. Uma linha no faça e não faça, "card usa rounded.sm, nunca rounded.md", corrigiu o Cursor na rodada seguinte.

O token diz o valor, a prosa decide o caso ambíguo e a regra negativa pesa mais que as duas.

A Vercel contou em 31 de agosto de 2026 como os agentes dela montam páginas com a cara da casa. Há um design.md público numa URL e uma folha de estilo com classes e tokens documentados; o agente usa os nomes e nunca lê o CSS. Sete cenários fixos rodam em Claude Opus 4.8 e em Codex com GPT-5.5.

O arquivo nomeia os padrões de página gerada que a empresa nunca quer ver; o nome faz o agente evitá-los. Cada correção aceita vai para o lugar mais estreito: julgamento vira prosa, mecânica repetível vira CSS e o que dá para checar vira teste.

Quem parte do zero começa de um sistema extraído. O Refero Styles, em beta, reúne mais de 2 mil sistemas lidos de sites reais. Cada um traz frase de personalidade, paleta com papel, escala tipográfica, raios e regras de faça e não faça, e sai como DESIGN.md.

O sistema da Apple España mostra o detalhe que vale imitar na forma. O azul #0071e3 fica reservado ao botão de ação e o #0066cc só ao link. Os cards têm raio de 28 px e os botões são pílulas sem sombra. A precisão do papel de cada cor é o que faz o arquivo funcionar.

Time com pipeline maduro de Figma e Style Dictionary (a ferramenta que gera tokens para cada plataforma) trata o DESIGN.md como subconjunto para o agente. Para o negócio pequeno, o DESIGN.md é a fonte e cabe em uma tarde. Abaixo, o mínimo que passa no lint.

A regra negativa nasce da correção que se repetiu. No escritório de arquitetura do exemplo acima, o agente pôs sombra nos cards duas vezes seguidas. A terceira sombra não veio, porque a linha "sem sombra, só linha de 1 px" já estava no faça e não faça.

Escreva o DESIGN.md com cor só em hex, nunca em OKLCH, que o lint reprova. Rode npx @google/design.md lint DESIGN.md até zerar as nove regras. Depois aponte o CLAUDE.md para o arquivo, antes de pedir a próxima tela: sem essa linha, o agente nem abre o DESIGN.md.

Guia prático: partir de um DESIGN.md de referência e chegar ao da sua marca

Escrever o primeiro DESIGN.md do zero é a parte mais lenta do trabalho. Um arquivo de referência bem feito mostra quanto detalhe o agente aproveita, e você troca o conteúdo pelo seu. O catálogo getdesign.md, mantido pela equipe do VoltAgent, publica análises no formato do Google para dezenas de sites conhecidos, de Stripe e Linear a Notion e Nike. O repositório de origem tem licença MIT e passava de 119 mil estrelas em 06/10/2026.

Um comando baixa o arquivo para a raiz do projeto. O de Stripe tem 24 kB: vinte cores nomeadas pelo papel que cumprem, uma escala tipográfica com peso, entrelinha e espaçamento entre letras, e as oito seções de regras, seguidas de comportamento responsivo e um guia de iteração. Ler um arquivo desses ensina mais sobre o formato do que a especificação.

O arquivo descreve a identidade de outra empresa. Cada página do catálogo avisa que a análise é independente e que a marca pertence ao dono. O de Stripe cita uma fonte proprietária, que você não tem licença para usar. Serve como molde de estrutura e como ponto de partida de estudo; a página que você publica leva as suas cores, a sua fonte e o seu nome.

O levantamento que o próprio catálogo publicou em 2026, com as respostas de quem baixou os arquivos, ajuda a dimensionar o problema: 59,4% queriam melhorar a aparência de uma interface que já existia, 23,6% queriam chegar perto de um design que admiravam e 17% buscavam consistência de marca. É uma amostra de usuários do catálogo, e não do mercado. Mesmo assim confirma o ponto central: gerar o código ficou fácil, e a dificuldade passou a ser manter a mesma identidade de uma tela para a outra.

Guia prático: um JSON de marca que muda a identidade da página inteira

Trocar a cor da marca não deveria exigir abrir componente. No curso de edição estudado em 07/10/2026, a identidade de cada vídeo cabe num arquivo JSON pequeno: cinco cores com papel definido (destaque, texto, fundo, apoio e legenda) e duas fontes. Um script transforma esse arquivo em variáveis no :root, e todo o CSS só consome variáveis. Os tons intermediários, como a borda suave e o fundo do cartão, saem de color-mix a partir das cores base.

O teste é a troca. A mesma composição saiu em terracota (#C8552E) e depois em laranja (#F97316) trocando só o JSON, sem tocar em nenhum componente. E uma cor ficou reservada a um sentido: o vermelho só aparece para o que é negativo. Papel definido é o que permite ao agente usar a cor certa sem perguntar.

O guia anterior mostrou um DESIGN.md de referência completo. Os 51 templates estudados mostram o que costuma faltar num DESIGN.md real:

Com uma lista de hex sem papel, o agente não sabe qual é fundo, qual é texto e qual é destaque, e escolhe a cada tela. O JSON com papel resolve as cores; a escala de tipo, o espaçamento e os raios você acrescenta ao DESIGN.md como tokens, extraídos dos valores que o CSS já usa.

Guia prático: do DESIGN.md à classe do Tailwind, e da classe a outro projeto pelo registro

A aula guarda cor, espaço e letra em tokens e escreve o DESIGN.md. Falta ligar as pontas: o valor do DESIGN.md precisa chegar à classe que o agente usa, e a identidade precisa sair do projeto para a próxima campanha sem cópia à mão. Em 2026, o @theme do Tailwind v4 faz a primeira ligação; o registro do shadcn em repositório do GitHub, desde junho, faz a segunda. Você sai daqui com a cadeia DESIGN.md, variável, classe e registro funcionando.

Token é a decisão de marca com nome e endereço

A documentação do Tailwind chama cor, tipografia e espaçamento de *design tokens* e os guarda em variáveis de tema. Para quem aprova, a consequência é prática: trocar a cor da marca vira uma edição, e não trinta. Pergunte ao fornecedor onde ficam os tokens e peça para ver o arquivo.

Aplicar os recursos ao projeto