Quem já pediu a um agente de IA para fazer uma UI conhece esta situação: ontem a tela tinha um botão azul com cantos arredondados; hoje, em uma nova sessão, aparecem gradiente roxo e botões retos. O mesmo projeto começa a parecer um app de outra marca em cada tela, então você cola em todo prompt: “a cor da marca é #2563EB, o raio é 8px…”.
DESIGN.md é uma especificação de arquivo voltada a esse problema. O Google Labs abriu em 21 de abril de 2026 o formato usado no Stitch, sua ferramenta de design de UI com IA (Anúncio oficial do Google). Em resumo, é “uma especificação de formato para explicar a identidade visual a um agente de codificação”. Basta manter um arquivo Markdown no repositório para o agente lê-lo sempre que criar uma UI.
Por que um arquivo, e não um prompt
A fraqueza de colocar regras de marca no prompt é a volatilidade. Elas somem quando a sessão termina, e cada pessoa da equipe acaba usando uma versão diferente. Um arquivo commitado no repositório é outra história.
- Permite controle de versão. Mudanças nas regras de design ficam no histórico do Git e entram na revisão de PR.
- Fica junto do código. Como as regras estão no mesmo lugar em que o agente lê o código, elas entram no contexto sem ferramenta ou link extra.
- É independente da ferramenta. Como é texto simples, qualquer agente pode lê-lo: Claude Code, Cursor, Copilot etc.
A ideia não é nova. CLAUDE.md·AGENTS.md já seguem o mesmo princípio para fornecer regras de comportamento aos agentes. DESIGN.md estende a convenção ao sistema de design. Se CLAUDE.md registra “como trabalhar neste projeto”, DESIGN.md registra “como este produto deve parecer”. Por que CLAUDE.md deve ser curtoA forma de projetar o contexto carregado continuamente é discutida em detalhes.
Há uma confusão fácil de fazer. No fluxo de desenvolvimento orientado por especificação, o “documento técnico de design design.md”, criado na ordem requirements.md → design.md → tasks.md, é outra coisa com o mesmo nome. O DESIGN.md deste artigo não é um documento de arquitetura, mas um arquivo de sistema de design.
Estrutura do arquivo: tokens para máquinas + prosa para pessoas
Segundo Especificação oficial, DESIGN.md tem duas partes: no início, tokens de design legíveis por máquina em front matter YAML; depois, a intenção de design em prosa Markdown legível por pessoas.
---
name: My Product
version: alpha
colors:
primary: "#2563EB"
surface: "#FFFFFF"
onSurface: "#0F172A"
typography:
headline:
fontFamily: Pretendard
fontSize: 28px
fontWeight: 700
spacing:
sm: 8px
md: 16px
rounded:
card: 12px
components:
button:
backgroundColor: "{colors.primary}"
rounded: 8px
---
## Overview
Serviço financeiro sóbrio e confiável. Prioriza a clareza das informações em vez de ornamentos chamativos.
## Colors
primaryé usado com moderação apenas em elementos de chamada para ação. O 80%da tela permanece na família surface .
...Aqui está o ponto central: tokens são norma; prosa é contexto. O valor colors.primary: "#2563EB" é a resposta correta que o agente deve seguir. A prosa “primary deve ser usado com moderação apenas em chamadas para ação” ajuda a decidir quando e onde usá-lo. Com apenas códigos de cor, o agente pode pintar qualquer coisa; com apenas uma descrição de clima, escolherá cores por conta própria. Por isso os dois ficam no mesmo arquivo.
Estas são algumas regras definidas pela especificação.
- No front matter,
nameé obrigatório, e pelo menos uma corprimarydeve ser definida. - Os tokens se conectam por referências de caminho, como
{colors.primary}. Se o fundo do botão referencia primary, alterar apenas primary propaga a mudança. - O corpo define 8 seções: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components e Do’s and Don’ts. Todas são opcionais, mas as incluídas devem respeitar essa ordem.
- Áreas que não serão tratadas podem ser declaradas no campo
omittedjunto com o motivo. Assim o agente distingue algo não escrito de algo omitido de propósito.
Por que incluir ferramentas de validação
Além da especificação de formato, também foi publicado Ferramenta CLI oficial (@google/design.md, licença Apache-2.0). São quatro comandos.
| Comando | Função |
|---|---|
lint |
Valida a estrutura do arquivo, referências de tokens e contraste WCAG |
diff |
Compara duas versões e relata alterações no nível dos tokens |
export |
Converte tokens para configuração do Tailwind ou formato W3C DTCG |
spec |
Exibe a especificação completa para injetá-la em prompts de agentes |
lint é interessante porque converte internamente os valores de cor para sRGB e verifica o contraste WCAG (Web Content Accessibility Guidelines, diretrizes de acessibilidade para conteúdo web). Mesmo que o agente crie uma combinação que “pareça boa”, ela é rejeitada mecanicamente se não atender aos critérios de acessibilidade. Assim, a conformidade com as regras de design pode ser verificada no CI sem depender do cuidado do agente; o Google também destaca isso na documentação pública. Nas palavras de Anúncio oficial, o objetivo é permitir que o agente “saiba exatamente para que serve cada cor e valide suas escolhas comparando-as com as regras de acessibilidade WCAG”, em vez de adivinhar.
Também é importante, no dia a dia, poder extrair a configuração do Tailwind com export. DESIGN.md pode ser a fonte única de verdade, com a configuração real de CSS derivada dela.
Como usar na prática
Há duas formas de começar.
Gerar no Stitch. Criando o design no Stitch, você pode exportá-lo como DESIGN.md. O fluxo é criar algumas telas, extrair sua linguagem visual para o arquivo e entregá-la ao agente de codificação.
Escrever manualmente. Como é Markdown comum, você pode criá-lo diretamente no editor. Se a equipe já tiver tokens de design organizados, mova-os para o front matter e transfira para as seções do corpo a parte do guia de design que explica “por quê”.
Depois de criar o arquivo, coloque-o na raiz do repositório para o agente consultá-lo. Um cuidado: ao contrário de CLAUDE.md, DESIGN.md não é carregado automaticamente na sessão pelo agente. Como ainda é uma especificação nova em alpha, é mais seguro adicionar em CLAUDE.md ou AGENTS.md uma linha como “leia DESIGN.md antes de trabalhar na UI e siga seus tokens”. Não é preciso ocupar o contexto com todo o sistema de design em sessões sem UI; carregá-lo quando necessário também reduz o custo de contexto.
Limitações e perspectivas
Também há pontos que precisam ser avaliados com realismo.
Ainda está em alpha. O valor version de Especificação é literalmente “alpha”, e a estrutura dos campos pode mudar. Adotá-la agora exige disposição para acompanhar as mudanças da especificação.
A adesão do agente continua probabilística. Mesmo com tokens descritos com precisão, não há garantia de que o agente os seguirá exatamente: no fim, é um LLM executando instruções. É o mesmo motivo pelo qual às vezes ignora instruções de CLAUDE.md. Por isso ferramentas determinísticas como lint foram lançadas junto. Na prática, “instrução no arquivo + validação no CI” deve ser tratado como um conjunto.
A cobertura ainda é limitada. A especificação atual se concentra em cores, tipografia, espaçamento, cantos e componentes. Áreas como motion, conjuntos de ícones e breakpoints responsivos podem ser descritas em prosa, mas não têm um esquema de tokens.
Ainda assim, a direção é clara. O contexto fornecido ao agente passa do prompt para um arquivo versionado no repositório; depois de CLAUDE.md e AGENTS.md, o padrão chega agora ao design. Como o arquivo permanece mesmo quando a ferramenta muda, é um investimento independente do agente. Se você vinha copiando regras de marca nos prompts para manter a consistência da UI, comece transferindo esse conteúdo para um único DESIGN.md.
Continue lendo
Fontes e verificação
- Stitch's DESIGN.md format is now open-sourceGoogle (2026-04-21) · Anúncio oficial · Consultado 8 de agosto de 2026Evidência: Fato de DESIGN.md ser código aberto, objetivo da publicação (permitir que o agente conheça o uso das cores e valide WCAG) e suporte à geração no Stitch
- google-labs-code/design.mdGoogle Labs · Documentação oficial · Consultado 8 de agosto de 2026Evidência: Licença Apache-2.0, status alpha e comandos e funções lint·diff·export·spec da CLI @google/design.md
- DESIGN.md SpecificationGoogle Labs · Padrão ou especificação · Consultado 8 de agosto de 2026Evidência: Campos do front matter (name obrigatório, cor primary obrigatória), 8 seções do corpo, sintaxe de referência de tokens, campo omitted e método de verificação de contraste WCAG