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 está em Baseline Newly Available, com a promoção a Widely prevista para 13 de novembro de 2026, então escreva a cor de reserva na declaração anterior, para o navegador que ignora a função.

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.

Ele é mantido por um Community Group do W3C e não tem status de Recommendation. A diferença muda a decisão de quem escolhe arquitetura pelo texto: cite o rascunho de editor com a data da leitura, porque ele ainda pode mudar. Cada token guarda $value e $type obrigatórios, aceita $description e cita outro token entre chaves, como {cor.marca.primaria}.

Tailwind, a coleção de classes prontas escritas direto no elemento, lê os tokens no código. A versão 4.0, de 22 de janeiro de 2025, tirou a configuração do JavaScript e trocou a paleta padrão de hexadecimal para OKLCH. Cor e medida vivem num bloco @theme no CSS, um botão vira bg-marca text-white, e a estável no fechamento é a 4.3.3, de 16 de julho de 2026.

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.

Três tiques denunciam página gerada, e a skill frontend-design manda evitar os três. Uma palavra do título em cor ou itálico, rótulo em caixa alta e um rótulo desnecessário acima do conteúdo. Cada um aparece por padrão em tela gerada sem instrução, e sai com uma linha no pedido.

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() cresce com a tela sem media query, e font-variant-numeric: tabular-nums alinha os dígitos em qualquer coluna de número, o que faz a tabela de preços parar de dançar.

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. No ateliê de cerâmica cuja terracota variava entre catálogo, carrinho e e-mail, o token em OKLCH e o arquivo DTCG fizeram o ajuste no Figma valer para o CSS regerado.

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.

O que o CSS nativo de 2026 resolve sem biblioteca

Uma biblioteca a mais custa peso no pacote e mais uma dependência para manter. O CSS de 2026 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 e entra atrás de @supports, a pergunta ao navegador se ele conhece a regra, como testar a tomada antes de ligar.

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 no conjunto 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, lista 19 áreas de foco, 11 delas de CSS, e o que está lá chega a todos dentro do ano.

A ordem das camadas vence a força do seletor. O @layer declara as camadas numa linha. A camada declarada por último vence, mesmo quando a regra da anterior tem seletor mais forte ou aparece depois no arquivo. 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.

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 cumpre a tarefa, e segure a biblioteca só enquanto esse desenho a quebra.

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. Confira a fatia de Firefox e Safari antigos no painel de visitas antes de pedir um recurso ainda em chegada, e só aceite quando a reserva cumpre a tarefa.

DESIGN.md: o sistema de design escrito para o agente ler

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ê por trás de cada escolha, que só o DESIGN.md guarda, decide o caso que nenhum token previu.

Quem já tem cores com nome ganha toda tela com a cara da marca, com o arquivo escrito, verificado e lido pelo agente 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ê.

O agente (a ferramenta de IA que escreve o código) lê as duas camadas. 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, e é a diferença que mais surpreende quem vem de um arquivo de tokens moderno.

A ferramenta de linha de comando npx @google/design.md faz três coisas. O lint confere nove regras, entre elas referência quebrada, par de fundo e texto abaixo de 4,5:1, token sem uso, seção fora de ordem e 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.

O arquivo fica 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 antes de a linha "sem sombra, só linha de 1 px" entrar 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 e aponte o CLAUDE.md para o arquivo antes de pedir a próxima tela; sem essa linha, o agente não lê o arquivo.