WaveSpeedAI
← Blog

design.md vs Design Tokens para Fluxos de UI com IA

Compare design.md vs tokens de design tradicionais para fluxos de UI com IA, com foco em legibilidade para agentes, consistência e portabilidade de fluxo de trabalho.

By Dora 11 min read

Meu nome é Dora. Passo a maior parte da semana dentro de agentes de código e ferramentas de UI com IA — Cursor, Claude Code, Stitch, o conjunto habitual — construindo e reconstruindo interfaces mais rápido do que tenho tempo de documentar. Há cerca de um mês, comecei a ver o mesmo arquivo aparecer em quase todos os repositórios que eu tocava: DESIGN.md. Mesmo nome, mesma estrutura de YAML no topo com prosa embaixo. No terceiro projeto, percebi que não era coincidência. Era a coisa que estava substituindo o que a maioria de nós costumava entregar como um tokens.json.

Então reconstruí uma das minhas próprias bibliotecas de componentes duas vezes — uma com um arquivo de tokens no estilo DTCG clássico, outra com um DESIGN.md — e rodei o mesmo agente de código contra ambos. Esta é a parte da comparação que eu não consegui encontrar escrita em lugar algum: não o que cada formato é, mas para o que cada um está realmente otimizando, e qual pertence à sua stack agora.

design.md vs Tokens de Design Tradicionais

Para o que cada formato está otimizando

Tokens de design, no sentido clássico, são uma metodologia. O termo foi cunhado na Salesforce por volta de 2014 para resolver um problema de escalabilidade muito específico: como manter uma decisão de cor sincronizada entre web, iOS, Android e quatro bases de código sem abrir quatro tickets? A resposta foi um par nome-valor agnóstico de plataforma, armazenado em JSON ou YAML, transformado no momento da build no que cada plataforma precisasse. Essa metodologia agora está codificada pelo Design Tokens Community Group no W3C, e no final de 2025 o formato DTCG tem uma especificação v1 estável.

Tokens otimizam para distribuição determinística. Um código hex entra, o mesmo código hex sai em todas as plataformas, em todas as builds, para sempre. Não há ambiguidade. Também não há narrativa — um arquivo de tokens diz primary: #1A1C1E, mas não diz por que essa cor existe ou quando não usá-la.

O DESIGN.md, com código aberto pelo Google Labs em abril de 2026, otimiza para algo diferente: dar a um agente de código contexto suficiente para tomar decisões que o arquivo de tokens não cobre. É um único arquivo markdown com front matter YAML para tokens e prosa abaixo para justificativa. Mesmo arquivo, dois públicos — a parte determinística para parsers, a parte narrativa para qualquer LLM que esteja lendo o repositório.

Essa é a divisão real. Não “velho vs novo.” Não “JSON vs Markdown.” É valores vs valores mais raciocínio no mesmo arquivo.

Por que agentes de IA criam um novo conjunto de requisitos

Quando um humano implementa um design, a lacuna entre “o token diz #1A1C1E” e “este estado vazio precisa de um tom de voz” é preenchida pelo humano. Ele viu o arquivo do Figma. Participou do workshop de marca. Sabe que o botão secundário deve parecer discreto, não assertivo.

Um agente de código não tem nada disso. Ele tem o que você colocou no repositório e o que pode inferir a partir dos nomes dos arquivos. Então, quando você pede para ele gerar uma tela que o arquivo de tokens não especifica totalmente — um caso extremo, um novo componente, uma decisão de layout — ele ou adivinha ou recorre ao que viu com mais frequência no treinamento. Essa é a origem da estética “bege de IA” de que todos reclamam: não modelos ruins, apenas contexto ausente.

É isso que o DESIGN.md está resolvendo. A especificação oficial no GitHub é explícita sobre isso — tokens dão aos agentes valores exatos, a prosa diz a eles por que esses valores existem e como aplicá-los. O formato espera ambas as metades.

Onde o design.md Agrega Valor

Contexto narrativo persistente

A coisa que percebi nas primeiras 48 horas de testes: o mesmo agente, dado o mesmo briefing, gera uma saída visivelmente diferente quando há contexto em prosa. Não “cores um pouco melhores.” Escolhas de layout diferentes, registro de copy diferente, densidade de componentes diferente. Os valores dos tokens eram idênticos nas duas execuções — o que mudou foi se o agente tinha um parágrafo dizendo “a voz da marca é contida e editorial; favoreça espaço em branco em vez de decoração.”

Esta é a parte que o pipeline tradicional de tokens não carrega. Um arquivo JSON DTCG pode descrever --color-primary com precisão, mas não pode dizer a um agente que a cor primária deve ser usada com moderação. O DESIGN.md carrega esse julgamento para cada passagem de geração, de forma persistente, sem que ninguém precise redigitá-lo em um prompt.

Funciona.

Melhor consistência em múltiplas telas para fluxos de trabalho de geração

No meu segundo teste, gerei oito telas para o mesmo aplicativo ao longo de dois dias. Com contexto apenas de tokens, as telas 5–8 começaram a divergir — mesma paleta, mas a linguagem de layout ficou mais solta. Com o DESIGN.md presente, a divergência foi muito menor. Não zero. Menor.

Minha leitura do porquê: a seção de prosa age como uma re-ancoragem toda vez que o agente lê o arquivo. Tokens sozinhos dão ao agente o suficiente para estar correto em valores individuais. A narrativa dá a ele o suficiente para ser consistente nas decisões que os tokens não anteciparam. Para uma geração pontual, essa lacuna não importa. Para saídas de múltiplas telas e iteração contínua, ela se acumula.

É também aqui que o DESIGN.md se encaixa bem com a stack mais ampla de instruções de agentes — a maioria das configurações agora o referencia a partir de um AGENTS.md junto com arquivos SKILL.md, para que o design system fique na mesma camada de contexto que o resto das instruções persistentes do agente.

Onde os Tokens Tradicionais Ainda Vencem

Dois cenários, ambos reais.

Distribuição multiplataforma além da web. Se você está entregando o mesmo design system para iOS, Android, um aplicativo React Native e um site de marketing, o pipeline DTCG através do Style Dictionary ou Terrazzo ainda é o caminho de menor resistência. O YAML do DESIGN.md pode exportar para DTCG JSON via o CLI oficial @google/design.md, mas a questão da fonte da verdade ainda importa — se o seu grafo de tokens for grande, com múltiplos temas e consumido por ferramentas não-IA, manter o DTCG como formato canônico é a configuração mais limpa.

Design systems maduros com governança estabelecida. Tokens não são apenas um formato de arquivo. São uma metodologia com cerca de uma década de prática acumulada — camadas primitivas, camadas semânticas, aliasing, tematização, toda a taxonomia que Nathan Curtis descreveu em Tokens in Design Systems. Se sua equipe já opera dessa forma, o DESIGN.md não o substitui. Ele fica em cima dele, ou ao lado dele, como uma camada de contexto para agentes. Os tokens continuam sendo a fonte canônica; o markdown se torna a tradução voltada para IA.

O erro seria ler o DESIGN.md como um substituto para o pipeline de tokens. Não é. É uma camada diferente com um consumidor diferente.

Um Framework de Decisão para Equipes Construindo Pipelines de UI com IA

Continuo voltando a quatro perguntas ao decidir o que colocar em um repositório:

  1. Quem está lendo este arquivo? Se o consumidor principal é um pipeline de build que emite CSS, Swift e Kotlin, você quer tokens em um formato canônico. Se o consumidor principal é um agente de código gerando UI sob demanda, você quer DESIGN.md. Se são os dois, você mantém os dois — e deixa o YAML do arquivo markdown espelhar um subconjunto dos tokens.
  2. Com que frequência sua superfície de UI é regenerada? Equipes de baixa frequência (um produto estável, novas telas ocasionais) obtêm a maior parte do valor dos tokens. Equipes de alta frequência (prototipagem rápida, iteração dirigida por agentes, novas telas toda semana) sentem agudamente a lacuna de contexto ausente. Quanto maior a frequência de regeneração, mais a camada de prosa justifica seu lugar.
  3. Quantas plataformas? Somente web ou web primária com geração dirigida por agentes — DESIGN.md é a stack mais simples. Três ou mais plataformas com presença nativa significativa — tokens primeiro, com DESIGN.md como artefato derivado.
  4. A justificativa já está documentada em algum lugar? Se suas diretrizes de marca, documento de voz e filosofia de componentes vivem em uma página do Notion que nenhum agente jamais lerá, o DESIGN.md é o movimento de maior alavancagem que você pode fazer neste trimestre. Você não está criando nova documentação — está movendo a documentação existente para um arquivo que o agente realmente abre.

Esse é meu framework. O seu pode ser diferente. O que eu destacaria: não escolha um formato porque é novo. Escolha-o por causa de quem está lendo o arquivo.

Perguntas Frequentes

O design.md é um substituto para tokens de design?

Não. O DESIGN.md é um wrapper que contém tokens de design (no front matter YAML) mais a justificativa em torno deles (na prosa markdown). Os tokens dentro dele ainda são tokens de design no sentido convencional. Se você já tem um arquivo de tokens no formato DTCG, o DESIGN.md não o substitui — ele fica como um artefato paralelo para agentes de IA, ou você pode fazer o markdown exportar DTCG JSON quando necessário.

Por que agentes de IA precisam de mais do que tokens numéricos?

Porque a maioria das solicitações de geração de UI não é totalmente especificada pelo grafo de tokens. “Gerar uma página de preços” requer centenas de micro-decisões — hierarquia, densidade, tom, o que enfatizar — que nenhum arquivo de tokens cobre. Sem contexto narrativo, o agente preenche essas lacunas com o que viu nos dados de treinamento, o que produz o visual genérico que a maioria das UIs geradas por IA compartilha. A prosa no DESIGN.md é o que fecha essa lacuna.

Quais fluxos de trabalho se beneficiam mais do design.md?

Três padrões que vi dar mais resultado:

  • Desenvolvedores solo e equipes pequenas usando Cursor, Claude Code ou Stitch para entregar UI mais rápido do que conseguem escrever à mão.
  • Equipes de design system mantendo vários produtos internos onde a consistência entre telas geradas por IA está se tornando um problema real.
  • Agências e equipes de contrato que querem um único arquivo plug-and-play que codifica a linguagem de design de um cliente para qualquer agente de código.

Se o seu fluxo de trabalho é principalmente codificado à mão com assistência ocasional de IA, o valor marginal cai.

Quando a infraestrutura clássica de tokens de design ainda é suficiente?

Quando você não está gerando UI com agentes, ou quando o alcance da sua plataforma vai muito além da web. Mobile nativo intenso, produtos white-label com múltiplos temas, práticas maduras de design ops — esses ainda obtêm mais do ecossistema DTCG do que de um arquivo markdown. Os dois não são mutuamente exclusivos, mas se você tiver que escolher um para investir, a resposta depende de onde está o seu atrito de geração real.

Conclusão

A versão honesta: o DESIGN.md não é uma mudança de paradigma. É uma solução focada para uma lacuna específica — agentes de código sem a justificativa que os arquivos de tokens não carregam. Para os fluxos de trabalho onde essa lacuna é real, o ganho é imediato e óbvio. Para os fluxos de trabalho onde não é, os tokens tradicionais ainda fazem o trabalho.

Estou há dois meses usando o DESIGN.md em todos os projetos de geração com IA que executo. Ele permaneceu no fluxo de trabalho, que é o único teste em que confio. Os arquivos de tokens também não foram a lugar algum — ainda estão fazendo o que sempre fizeram, apenas com um arquivo irmão agora para o público que precisa de mais do que números.

Execute-o você mesmo em um projeto. Dois dias vão te dizer mais do que este artigo pode.

Posts anteriores:

Compartilhar