Biblioteca de DESIGN.md pronta para colar no Cursor, Claude Code ou Lovable

DESIGN.md: o que é e como usar no seu projeto

Se você pede para um agente de IA criar uma interface sem fornecer contexto de design, ele precisa preencher as lacunas sozinho. É aí que aparecem fontes genéricas, cores arbitrárias, espaçamentos inconsistentes e componentes que mudam de uma tela para outra.

O DESIGN.md foi criado para reduzir esse problema. Ele transforma decisões de design em um arquivo estruturado que pode acompanhar o projeto, ser versionado junto com o código e servir como contexto para agentes de IA.

Hoje, o formato possui uma especificação aberta mantida pelo Google Labs. Ela combina design tokens estruturados em YAML com regras e racional de design escritos em Markdown. Assim, o agente recebe tanto valores exatos quanto contexto sobre como aplicá-los.

Neste guia, você vai entender o que é DESIGN.md, como o formato funciona atualmente, o que colocar no arquivo, como conectá-lo a agentes como Claude Code, Cursor, Windsurf e Codex e quando usar DESIGN.md, Rules, AGENTS.md ou MCP.

O que é DESIGN.md?

DESIGN.md é um formato aberto para descrever a identidade visual e as regras de um design system em um arquivo que pode ser lido por pessoas e por agentes de IA.

O formato surgiu no ecossistema do Google Stitch. Em abril de 2026, o Google Labs publicou a especificação aberta para permitir que essas regras de design fossem transportadas entre diferentes ferramentas e fluxos de trabalho.

Na especificação atual, um DESIGN.md possui duas camadas:

• YAML front matter: concentra valores estruturados, como cores, tipografia, espaçamento, arredondamento e propriedades de componentes.
• Corpo em Markdown: explica a intenção visual, o papel dos tokens, regras de composição, componentes e decisões que não cabem apenas em valores numéricos.

Importante: a especificação oficial ainda está em estágio alpha. O formato já pode ser usado em projetos reais, mas campos e regras podem evoluir antes de uma versão estável.

Isso também significa que DESIGN.md não deve ser tratado como um arquivo mágico que qualquer ferramenta reconhece automaticamente. O arquivo contém o contexto de design, mas cada agente possui sua própria forma de carregar instruções e arquivos adicionais.

Por que a IA precisa de contexto visual para funcionar bem

Agentes de IA conseguem analisar código, texto, imagens e arquivos de projeto, dependendo das ferramentas disponíveis. O problema é outro: as decisões específicas do seu produto não fazem parte do conhecimento padrão do modelo.

Se o agente não sabe qual é a cor primária, qual escala de espaçamento utilizar, quais componentes já existem ou como um estado de foco deve se comportar, ele precisa inferir essas decisões a partir do contexto disponível.

Em tarefas diferentes, essas inferências podem mudar. O resultado é o chamado design drift: pequenas diferenças se acumulam até a interface deixar de seguir um sistema visual coerente.

Qual é o problema que todo designer já viveu?

Em um fluxo tradicional, decisões podem estar distribuídas entre Figma, bibliotecas de componentes, documentação, arquivos de tokens, CSS e conhecimento das pessoas do time.

Quando um agente entra nesse fluxo sem acesso às mesmas fontes, ele não sabe necessariamente que o botão principal usa determinado token, que cards não possuem sombra ou que o produto adota uma escala de espaçamento específica.

Repetir tudo isso manualmente em cada prompt funciona em projetos pequenos, mas é difícil de manter. O DESIGN.md cria uma referência portátil e versionável para essas decisões.

Como agentes de IA recebem contexto de design

O DESIGN.md funciona melhor quando faz parte de uma arquitetura de contexto. Em vez de presumir que o agente encontrará o arquivo sozinho, o projeto informa explicitamente onde estão suas regras.

Por exemplo, um CLAUDE.md, AGENTS.md ou uma Rule do Cursor pode instruir o agente a consultar DESIGN.md antes de criar ou alterar uma interface.

Essa separação é útil: o arquivo de instruções diz como o agente deve trabalhar, enquanto o DESIGN.md registra como o produto deve parecer e se comportar visualmente.

O que vai dentro de um arquivo DESIGN.md

A especificação atual do Google Labs organiza o DESIGN.md em dados estruturados e documentação em linguagem natural. Os tokens representam valores normativos; o texto explica o contexto em que esses valores devem ser usados.

Tokens estruturados em YAML

O início do arquivo pode armazenar tokens em YAML. Isso permite que agentes e ferramentas identifiquem valores sem depender apenas da interpretação de texto livre.

---
version: "alpha"
name: "Produto Exemplo"
description: "Sistema visual do produto"

colors:
  primary: "#0642CE"
  surface: "#FFFFFF"
  text-primary: "#161616"
  danger: "#C1121F"

typography:
  heading-lg:
    fontFamily: "Sora"
    fontSize: "2.5rem"
    fontWeight: 700
    lineHeight: 1.1

  body-md:
    fontFamily: "Source Sans 3"
    fontSize: "1rem"
    fontWeight: 400
    lineHeight: 1.6

rounded:
  sm: 4px
  md: 8px

spacing:
  sm: 8px
  md: 16px
  lg: 24px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: 12px
---

Tipografia

Documente famílias tipográficas, tamanhos, pesos, altura de linha e espaçamento entre letras quando essas propriedades fizerem parte do sistema.

Prefira tokens semânticos, como heading-lg e body-md, em vez de apenas listar tamanhos soltos. Isso comunica não apenas o valor, mas sua função.

Paleta de cores e tokens

Não registre apenas códigos de cor. Explique também o papel de cada token: ação principal, superfície, texto, borda, feedback de erro ou outro significado semântico.

Isso reduz situações em que um agente utiliza uma cor correta no contexto errado.

Espaçamento e layout

Registre a escala de espaçamento e as principais regras de layout. Podem entrar aqui largura máxima de conteúdo, comportamento de grids, densidade, margens, gaps e princípios de responsividade que afetam a composição.

Formas, profundidade e elevação

Border radius, bordas, sombras e níveis de elevação também fazem parte da linguagem visual. Uma interface pode usar os tokens de cor corretos e ainda parecer completamente diferente se o agente improvisar essas propriedades.

Componentes e estados

Componentes importantes podem receber referências aos tokens usados em background, texto, tipografia, padding, tamanho e arredondamento.

Estados como hover, active ou pressed podem ser documentados como variações relacionadas. Quando foco, disabled, loading ou outros estados forem importantes para o produto, registre também as regras necessárias para que o agente não invente comportamentos.

Do’s and Don’ts: o que fazer e o que evitar

Restrições explícitas são especialmente úteis. Se a identidade não usa gradientes, sombras fortes, cards excessivamente arredondados ou determinadas combinações de cor, documente isso.

## Do's and Don'ts

### Do
- Usar apenas tokens definidos para cores de interface
- Manter a escala de espaçamento do sistema
- Reutilizar componentes existentes antes de criar novos

### Don't
- Não criar gradientes decorativos
- Não adicionar sombras sem token correspondente
- Não introduzir uma nova fonte sem necessidade
- Não criar valores arbitrários de espaçamento

Acessibilidade, movimento e outras regras

Nem toda decisão precisa virar um token. Regras de acessibilidade, comportamento responsivo, movimento, iconografia, conteúdo ou princípios específicos do produto podem aparecer como documentação adicional quando forem relevantes.

A especificação permite preservar seções adicionais. O importante é não transformar o arquivo em uma cópia de toda a documentação do projeto.

O que não colocar no DESIGN.md

• Regras de negócio que não ajudam o agente a tomar decisões de interface.
• Credenciais, chaves, dados privados ou qualquer segredo do projeto.
• Grandes cópias de documentação que já possuem uma fonte de verdade melhor.
• Valores duplicados que podem entrar em conflito com tokens reais do produto.
• Recomendações vagas como “deixe bonito”, “seja moderno” ou “use boas práticas”.

Para um passo a passo completo, veja como criar e aplicar um DESIGN.md com IA. Se você já possui um site, também pode experimentar o Gerador de DESIGN.md da CamaraUX.

DESIGN.md vs design system: eles coexistem

DESIGN.md não precisa competir com Figma, design tokens ou um design system estruturado. Ele funciona como uma nova camada de documentação e interoperabilidade para fluxos assistidos por IA.

DESIGN.md substitui o Figma?

Não. O Figma continua sendo um ambiente visual para explorar, construir, avaliar e comunicar interfaces. DESIGN.md transforma parte dessas decisões em contexto textual e estruturado para agentes.

Dependendo da infraestrutura disponível, um agente também pode acessar diretamente arquivos, componentes ou informações do Figma por integrações e ferramentas. Nesse cenário, DESIGN.md deixa de ser a única ponte possível, mas continua útil como referência portátil e versionável dentro do repositório.

DESIGN.md substitui o design system?

Também não. Um design system pode envolver componentes implementados, bibliotecas, tokens, documentação, governança, processos e critérios de qualidade. DESIGN.md representa apenas uma parte desse conhecimento em um formato adequado para agentes.

Quanto mais maduro o design system, mais importante é definir qual fonte possui autoridade sobre cada informação. O DESIGN.md não deve criar uma segunda versão conflitante dos mesmos tokens.

E os design tokens?

Design tokens continuam sendo uma forma estruturada de representar decisões de design de maneira independente de plataforma. O DESIGN.md pode incluir tokens e, na implementação oficial atual, exportá-los para formatos compatíveis com o Design Tokens Format Module.

Se quiser aprofundar essa camada, veja também o guia sobre design tokens e a arquitetura do formato DTCG.

DESIGN.md, AGENTS.md, CLAUDE.md e Rules: qual é a diferença?

Esses arquivos podem parecer concorrentes, mas normalmente resolvem problemas diferentes.

Uma organização simples pode usar AGENTS.md, CLAUDE.md ou uma Rule como mapa para outras fontes. O DESIGN.md permanece especializado em design.

AGENTS.md

# Contexto de interface

Antes de criar ou alterar componentes visuais:
1. Leia DESIGN.md
2. Reutilize os tokens documentados
3. Verifique se já existe um componente equivalente
4. Não introduza novos padrões visuais sem necessidade

Essa abordagem também reduz um problema comum em agentes: arquivos de instrução enormes. Em vez de colocar toda a documentação dentro de um único AGENTS.md, ele pode funcionar como um mapa curto para fontes especializadas.

Para aprofundar essa arquitetura, veja como usar DESIGN.md com agentes de IA em UX.

DESIGN.md vs MCP: quando usar cada abordagem

DESIGN.md e Model Context Protocol (MCP) também não são substitutos diretos.

Um projeto pequeno pode funcionar muito bem apenas com DESIGN.md e as regras do agente. Já um design system amplo pode usar MCP para consultar componentes, documentação ou outros dados atualizados e manter o DESIGN.md como uma visão concisa das decisões mais importantes.

Em outras palavras: DESIGN.md é contexto documentado; MCP é uma infraestrutura para acessar contexto e executar capacidades. Os dois podem coexistir.

Como usar DESIGN.md no seu fluxo de trabalho

A forma mais segura de usar DESIGN.md é evitar depender de comportamento implícito. Coloque o arquivo sob controle de versão e configure explicitamente o agente para consultá-lo quando trabalhar com interface.

1. Crie e versione o arquivo

Em projetos de código, a raiz do repositório é um local simples e previsível:

meu-projeto/
├── DESIGN.md
├── AGENTS.md
├── README.md
├── package.json
└── src/

Como o arquivo participa das decisões de implementação, mantê-lo no Git permite revisar alterações, comparar versões e atualizar o contexto junto com o produto.

2. Valide o DESIGN.md

O projeto oficial do Google Labs disponibiliza uma CLI para verificar a estrutura do arquivo, referências quebradas, ausência de tokens importantes e alguns problemas de contraste entre cores de componentes.

npx @google/design.md lint DESIGN.md

Para comparar duas versões do sistema:

npx @google/design.md diff DESIGN.md DESIGN-v2.md

E para exportar os tokens para o formato do Design Tokens Community Group:

npx @google/design.md export --format dtcg DESIGN.md > tokens.json

A CLI também possui saídas para Tailwind. Como a especificação ainda está em alpha, vale verificar a documentação oficial antes de automatizar processos críticos em produção.

3. Conecte o arquivo ao agente

O método depende da ferramenta.

Com Claude Code

Claude Code usa arquivos CLAUDE.md para instruções persistentes do projeto. Esses arquivos podem importar outros documentos usando a sintaxe @caminho.

Uma configuração simples é referenciar o DESIGN.md a partir do CLAUDE.md:

# Interface e design

Ao criar ou alterar interfaces, siga as regras de @DESIGN.md.

Não invente novos tokens quando já existir um equivalente.
Reutilize componentes existentes antes de criar novos.

Com Cursor

O Cursor possui Project Rules dentro de .cursor/rules. Elas podem ser sempre aplicadas, associadas a padrões de arquivo ou disponibilizadas para o agente quando forem relevantes.

---
description: Aplica o design system nas interfaces
globs: "src/**/*.{tsx,jsx,css,scss}"
alwaysApply: false
---

Antes de alterar UI, consulte @DESIGN.md.

Use os tokens e componentes existentes.
Não crie novos padrões visuais sem necessidade.

O Cursor também reconhece AGENTS.md como uma alternativa mais simples para instruções gerais do projeto.

Com Windsurf

No Windsurf, você pode usar Rules em .windsurf/rules/ ou arquivos AGENTS.md. Um AGENTS.md na raiz fornece orientação para todo o projeto; arquivos em subdiretórios podem aplicar instruções específicas ao trabalhar naquela área.

# Design

Para qualquer tarefa relacionada à interface:
- Consulte DESIGN.md
- Preserve os tokens existentes
- Siga os componentes e restrições documentados
- Verifique acessibilidade antes de concluir

Com Codex

Codex reconhece arquivos AGENTS.md como orientação persistente do repositório. Eles podem informar quais fontes devem ser consultadas antes de uma alteração.

# UI implementation

Before implementing or modifying UI:
- Read DESIGN.md
- Follow existing visual tokens
- Reuse existing components
- Validate the result against the documented design constraints

Com Google Stitch

O Stitch possui suporte direto ao formato porque DESIGN.md nasceu dentro desse ecossistema. O arquivo pode ser usado para transportar regras visuais entre projetos e outras ferramentas compatíveis.

Veja o fluxo com mais detalhes em DESIGN.md com Google Stitch.

Compatibilidade com ferramentas de IA

“Compatível com DESIGN.md” pode significar coisas diferentes. Algumas ferramentas possuem suporte direto ao formato; outras conseguem usar o arquivo quando ele é referenciado por seu sistema de regras ou instruções.

Por isso, é melhor pensar em DESIGN.md como um formato portátil de contexto de design, e não como uma convenção descoberta automaticamente por qualquer IA.

Como manter o DESIGN.md atualizado

Um DESIGN.md desatualizado pode ser pior do que não ter arquivo algum, porque o agente passa a seguir regras que já não representam o produto.

Trate alterações relevantes no sistema visual como alterações de código:

• Atualize o DESIGN.md quando tokens importantes mudarem.
• Revise o arquivo quando componentes centrais forem redesenhados.
• Use Git para registrar histórico e permitir revisão.
• Execute o linter depois de alterações estruturais.
• Compare versões quando mudanças possam afetar várias interfaces.
• Remova regras antigas em vez de acumular exceções indefinidamente.

Também vale avaliar periodicamente se o arquivo realmente melhora a saída do agente. Não basta verificar se ele existe: compare interfaces geradas com e sem o contexto e observe consistência, acessibilidade, fidelidade aos tokens e necessidade de correções.

Veja um processo específico em como avaliar a qualidade de um DESIGN.md.

A biblioteca de referências CamaraUX

Na parte superior desta página, a CamaraUX mantém uma biblioteca de arquivos DESIGN.md que podem ser usados como referência para estudar diferentes linguagens visuais e entender como decisões de interface podem ser documentadas para agentes.

Esses arquivos funcionam melhor como material de estudo e ponto de partida. O objetivo não é copiar a identidade de outra empresa, mas analisar como cores, tipografia, espaçamento, formas e componentes podem ser transformados em regras explícitas.

Quando uma referência for baseada na identidade visual de uma marca, ela não deve ser confundida com documentação oficial daquela empresa, salvo quando isso estiver explicitamente indicado.

Para um produto real, substitua referências genéricas pelos tokens, componentes e restrições do seu próprio sistema.

Perguntas frequentes sobre DESIGN.md

Fontes e documentação oficial

Como DESIGN.md ainda está evoluindo, prefira documentação primária para decisões técnicas e confirme mudanças importantes antes de automatizar o formato no seu fluxo.

• Google Labs: abertura da especificação DESIGN.md
• Google Labs: especificação e CLI oficial do DESIGN.md
• Design Tokens Format Module 2025.10
• Cursor: documentação de Rules e AGENTS.md
• Windsurf: documentação de AGENTS.md
• Anthropic: CLAUDE.md e contexto persistente no Claude Code
• OpenAI: AGENTS.md em fluxos com Codex

Conclusão

DESIGN.md evoluiu de uma convenção associada ao Google Stitch para uma especificação aberta voltada a representar sistemas visuais em fluxos com agentes de IA.

Seu principal valor não está em substituir Figma, design systems, tokens ou documentação. Está em criar uma camada portátil, versionável e legível por agentes para decisões que antes ficavam espalhadas entre diferentes fontes.

Em projetos simples, um DESIGN.md bem estruturado pode ser suficiente para reduzir inconsistências. Em sistemas maiores, ele pode trabalhar em conjunto com AGENTS.md, CLAUDE.md, Rules, bibliotecas de componentes, design tokens e MCP.

O ponto central é manter uma fonte de verdade clara. Se o agente sabe onde encontrar os tokens corretos, quais componentes reutilizar, quais padrões evitar e quando consultar documentação adicional, você reduz a quantidade de decisões que precisam ser reinventadas a cada geração.

Para começar, explore a biblioteca desta página ou use o Gerador de DESIGN.md. Depois, valide o arquivo e conecte-o explicitamente às instruções do agente que faz parte do seu fluxo.