O Que É design.md para Agentes de Programação?

Sou Dora. Na semana passada, pedi ao Claude Code para adicionar três novas telas a um projeto paralelo. Na segunda tela, o raio dos botões havia mudado, a fonte dos títulos tinha silenciosamente se alterado, e o cinza “secundário” era um cinza diferente. Mesma estrutura de prompt. Mesmo modelo. Mesma sessão. O resultado simplesmente parou de se preocupar com o que veio antes.

Essa é a fricção que o design.md para agentes de código tenta eliminar. É um arquivo markdown simples que mantém seu design system em um formato que um agente de IA pode ler toda vez que gera UI — não como um prompt único, mas como contexto persistente. O Stitch o lê. O Claude Code o lê. O Cursor o lê. Qualquer outra ferramenta que leia arquivos de contexto da raiz de um repositório também o lê.

O que é design.md e Por que o Google Labs o Publicou

Formato do arquivo e papel no design system

Um arquivo DESIGN.md é composto por duas camadas em um único documento. A parte superior é um front matter YAML — cores, tipografia, espaçamento, cantos arredondados, componentes — escrito como tokens estruturados. Abaixo disso, há texto em markdown que explica para que servem os tokens e como usá-los. Os tokens fornecem valores exatos ao agente. O texto explica por que esses valores existem.

Aqui está aproximadamente como o front matter se parece, extraído da especificação oficial do DESIGN.md no GitHub:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

Abaixo disso, ## Visão Geral, ## Cores, ## Tipografia em markdown simples. A ordem das seções é fixa — Visão Geral, Cores, Tipografia, Layout, Elevação e Profundidade, Formas, Componentes, O que Fazer e Não Fazer. As seções podem ser omitidas, mas as presentes devem aparecer nessa ordem. Títulos de seção duplicados são um erro e rejeitam o arquivo.

A sintaxe de referência de tokens vem do W3C Design Tokens Format Module — caminhos entre chaves como {colors.primary}. As referências devem apontar para valores primitivos (não grupos), exceto dentro da seção de componentes, onde referências compostas a tokens de tipografia são permitidas. Os valores de cores são apenas hex SRGB na especificação atual. Display P3 e Oklch — ambos suportados pela especificação estável W3C DTCG 2025.10 — ainda não são suportados pelo DESIGN.md, algo que o repositório sinaliza abertamente com o marcador version: alpha. Vale saber se você mantém tokens de gamut amplo.

O formato é acompanhado de uma CLI — @google/design.md no npm. npx @google/design.md lint executa sete regras contra um arquivo analisado. As duas que mais encontrei: broken-ref (severidade de erro) detecta referências de tokens que não resolvem, e contrast-ratio (aviso) verifica pares backgroundColor/textColor de componentes contra o mínimo de 4,5:1 do WCAG AA. Mais três — missing-primary, orphaned-tokens e as regras estruturais — expõem problemas que a maioria das equipes introduz dentro de uma semana editando o arquivo. A CLI também tem diff (regressões no nível de tokens entre versões) e export (config Tailwind v3, CSS @theme Tailwind v4, ou JSON W3C DTCG).

Por que o contexto visual persistente importa para agentes de código

O problema é simples. Um agente que gera UI não tem memória do seu design system a menos que você lhe dê algo estruturado para ler. Você pode descrever sua paleta em um prompt, receber um botão de volta, depois pedir um cartão e ver a lógica de espaçamento resetar. O modelo não é ruim em escrever código. Ele simplesmente não tem âncora.

O design.md é a âncora. O Stitch o passa como contexto em cada solicitação de geração. O Claude Code e o Cursor o leem da mesma forma que leem CLAUDE.md ou AGENTS.md — um arquivo na raiz do repositório que o agente lê antes de responder. O enquadramento do Google no anúncio open-source é que isso permite que os agentes “saibam exatamente para que serve uma cor” em vez de adivinhar a intenção a partir de um prompt.

Testei isso em ambos os projetos. Procedimento: colocar um DESIGN.md na raiz, regenerar as mesmas cinco telas que tinham derivado antes (landing, preços, cadastro, dashboard, configurações), e depois contar violações de tokens em relação ao front matter. Com o arquivo presente, o Claude Code produziu 5/5 telas usando os valores hex exatos de primary e tertiary e o rounded.sm declarado. O Cursor produziu 4/5 — o dashboard continuava substituindo rounded.sm (4px) por rounded.md (8px) nos cartões, algo que o texto do DESIGN.md não havia proibido explicitamente. Adicionar uma linha “O que Fazer e Não Fazer” — “cantos de cartão usam rounded.sm, nunca rounded.md” — corrigiu isso na próxima regeneração.

O Problema Real que Ele Resolve na Geração de UI com IA

Consistência entre telas e iterações

O que quebrou na sessão anterior não foi a qualidade de uma tela. Cada tela individualmente parecia boa. A segunda tela não sabia o que a primeira havia decidido. Cada geração começava de uma interpretação levemente diferente de “sua marca.”

Esse é o modo de falha que o design.md combate. Não “tornar a UI mais bonita” — torná-la a mesma UI entre gerações. Os tokens são normativos. Quando o front matter diz tertiary: "#B8422E", o agente não tem espaço para interpretá-lo como “um laranja quente.” É esse valor hex ou está errado, e o lint dirá isso.

Para fluxos de trabalho de alta frequência — cinco, dez, vinte telas por semana com alguém as mantendo — isso importa mais do que a qualidade do primeiro resultado. Uma inconsistência por tela em escala se torna um trabalho de limpeza. Tokens de design para agentes de código, definidos uma vez em um arquivo, eliminam esse trabalho de limpeza antes que ele comece.

Por que texto mais tokens é mais forte do que tokens sozinhos

Quase ignorei essa parte. Por que escrever parágrafos de “Boston Clay é o único motor para interação” quando o valor hex já está no YAML?

Porque o agente usa o texto para tomar decisões que os tokens não cobrem. Os tokens dizem que tertiary é #B8422E. O texto diz que essa cor é apenas para interação — não para acentos decorativos, não para títulos. Quando um prompt é ambíguo (“adicionar um badge de notificação”), o texto decide se o badge recebe a cor de interação ou um neutro. Na minha execução com o Cursor acima, a restrição de texto ausente foi exatamente o motivo pelo qual o dashboard derivou.

A mesma lógica se aplica ao que Fazer e Não Fazer — guardrails explícitos como “nunca usar sombras em cartões” ou “sempre usar sentence case nos rótulos de botões.” Restrições negativas carregam um peso que tokens puros não conseguem expressar. Isso é uma especificação de design para agentes, não um arquivo CSS.

O formato não está vinculado ao Stitch. A especificação é Apache 2.0, a CLI está no npm, a exportação DTCG significa que os tokens fluem para qualquer ferramenta que leia o padrão W3C, e a comunidade já está se movendo. A coleção awesome-design-md do VoltAgent de arquivos DESIGN.md inspirados em marcas ultrapassou 71.000 estrelas no GitHub em semanas após o lançamento, e o tópico design-md no GitHub agora lista ferramentas de extração, extensões para Chrome e registros SKILL.md complementares totalmente externos ao Google. A adoção é o que diz que um formato é real.

Quem Deve se Preocupar com design.md

Sendo honesto sobre os limites, porque design.md não serve para todos.

Ele justifica seu lugar se:

Você gera UI com agentes de código pelo menos semanalmente, em mais de uma tela
Você tem um design system — mesmo um simples — que deseja preservar entre gerações
Você trabalha com mais de um agente ou ferramenta e quer o mesmo contexto de marca em todos eles
Você está cansado de colar “lembre-se que nossa paleta é X, Y, Z” em cada prompt

Ele não justifica seu lugar se:

Você gera mockups únicos e os descarta
Seu “design system” é o que o agente produz desta vez
Você está dentro de um fluxo de trabalho liderado pelo Figma com um pipeline DTCG maduro via Style Dictionary ou similar — o design.md é mais simples do que o que você tem, e seria um rebaixamento
Você precisa de cores de gamut amplo (Display P3, Oklch) hoje — a especificação alpha atual é apenas SRGB

Para equipes de produtos nativos de IA executando design.md junto com outros arquivos de fluxo de trabalho de IA (CLAUDE.md, AGENTS.md), ele se encaixa perfeitamente. Um arquivo markdown por preocupação. Sem etapa de build. Sem esquema JSON para combater. O custo de experimentá-lo é um arquivo na raiz do repositório e um comando lint.

Para plataformas que constroem superfícies de geração orientadas por agentes — incluindo camadas unificadas de geração de IA que roteiam solicitações entre múltiplos modelos e precisam que o contexto de marca se mantenha em cada chamada — design.md é o que mais se aproxima de um contrato portátil entre uma marca e um agente no ecossistema. De acordo com o anúncio do Google Labs, o formato foi construído especificamente para ser exportável e importável entre ferramentas. Essa portabilidade é o ponto.

Perguntas Frequentes

Para que serve o design.md?

É um arquivo markdown que fornece aos agentes de código contexto persistente sobre um design system — cores, tipografia, espaçamento, componentes, além de texto explicando como aplicá-los. O agente o lê toda vez que gera UI, para que o resultado permaneça consistente entre telas e sessões sem você precisar re-especificar as regras de marca em cada prompt.

É apenas para fluxos de trabalho do Google Stitch?

Não. O formato se originou no Stitch, mas o Google tornou a especificação open-source sob Apache 2.0. Qualquer ferramenta de IA que leia arquivos de contexto — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — pode usá-lo. A CLI exporta para config Tailwind, variáveis CSS ou JSON W3C DTCG, então os tokens fluem para ferramentas não baseadas em agentes também.

Por que a UI gerada por IA precisa de um arquivo de design system?

Porque os modelos não têm memória da sua marca entre gerações. Sem um arquivo de design system para IA estruturado, cada prompt reinterpreta sua linguagem de design do zero. Com um, os tokens agem como restrições rígidas e o texto cobre os julgamentos subjetivos. A diferença aparece mais claramente em escala — cinco telas geradas com design.md mantêm seu estilo; cinco telas geradas sem ele derivam.

Quais equipes devem experimentá-lo primeiro?

Equipes que já geram UI com agentes de código semanalmente. Desenvolvedores solo e pequenas equipes de produto executando Claude Code ou Cursor obtêm o retorno mais rápido — coloque o arquivo, regenere, veja a consistência. Organizações maiores com pipelines maduros de Figma + Style Dictionary devem tratar o design.md como complemento, não substituto: use-o para dar aos agentes um subconjunto digerível do sistema existente.

Conclusão

design.md não é um formato de arquivo revolucionário. É um arquivo markdown com YAML no topo. Esse é o ponto — o formato que os LLMs leem melhor é aquele em que foram mais treinados, e esse é o texto simples.

O que ele realmente faz é mudar a pergunta de “como descrevo meu design neste prompt” para “onde meu design fica para que todo agente possa lê-lo.” Um arquivo, um local, toda ferramenta que o pega recebe a mesma resposta. Uma coisa a menos para re-especificar. Parece pequeno. Acumula rápido.

Tenho ele em dois projetos há uma semana. Funciona. A longo prazo — se as equipes mantêm esses arquivos com o mesmo rigor de um design system real, ou se eles apodrecem como READMEs apodrecem — isso ainda está por verificar. Execute-o em um projeto seu. Isso lhe dirá mais do que qualquer coisa que eu possa dizer.

Posts anteriores：