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

Se você já pediu para um agente de IA gerar uma tela e recebeu algo com Inter 16px, gradiente roxo e bordas arredondadas genéricas — sem nenhuma relação com a identidade visual do seu produto — você conhece o problema que o DESIGN.md resolve. A IA não é ruim em design. Ela só não tem memória visual por padrão. Sem contexto, ela inventa.

O DESIGN.md é um arquivo de especificação criado para resolver exatamente isso: dar ao agente de IA as regras visuais do seu projeto antes de ele escrever uma linha de código. O resultado é uma interface que respeita a identidade da marca, os tokens do design system e as decisões que você já tomou — sem precisar repetir isso em cada prompt.

Este guia explica o que é, como funciona, o que colocar dentro dele e como integrá-lo ao seu fluxo de trabalho como designer ou Product Designer.

O que é DESIGN.md?

DESIGN.md é um arquivo Markdown que descreve a identidade visual de um projeto em um formato que agentes de IA conseguem ler e aplicar. Ele reúne tipografia, paleta de cores, tokens de espaçamento, padrões de componentes e regras de uso em texto puro — legível por humanos e por máquinas ao mesmo tempo.

O formato foi popularizado pelo Google Stitch, plataforma de prototipagem com IA do Google Labs, e rapidamente ganhou adoção em outros contextos porque resolve um problema real no fluxo de desenvolvimento com agentes de IA.

Por que a IA precisa de contexto visual para funcionar bem

LLMs como Claude, GPT e Gemini processam cada prompt de forma isolada. Sem uma referência persistente no repositório, cada componente gerado usa decisões visuais diferentes. O botão de um componente fica com border-radius: 8px. O do próximo fica com 12px. A cor primária muda entre arquivos. O espaçamento fica inconsistente.

Não é um bug do modelo. É falta de contexto.

Qual é o problema que todo designer já viveu?

O pipeline tradicional de design — pesquisa → Figma → especificações → handoff → frontend — funciona, mas cada etapa perde um pouco do contexto original. Quando você introduz um agente de IA sem dar esse contexto, ele preenche as lacunas com seus próprios padrões. E os padrões de uma IA generativa tendem ao genérico: fontes neutras, cores seguras, layouts que parecem templates de 2019.

O DESIGN.md é a resposta prática para isso. Em vez de briefingi o agente a cada sessão com instruções vagas como “deixa mais limpo e moderno”, você coloca um arquivo na raiz do projeto. O agente lê antes de gerar qualquer interface e aplica suas regras automaticamente.

Como os LLMs processam (e não processam) design

Um LLM entende texto com precisão cirúrgica. Entende código. Entende Markdown. Mas não tem acesso direto a arquivos do Figma, não enxerga tokens exportados como JSON sem parsing adicional e não mantém memória visual entre sessões.

O DESIGN.md aproveita exatamente o que o modelo faz bem: ler texto estruturado. Quando você escreve primary: "#0A4FD4" e acrescenta “cor usada em CTAs e elementos de destaque”, o agente recebe o valor exato do token e entende o contexto de uso. Isso é diferente de jogar um design system inteiro em texto no prompt — o DESIGN.md é conciso, estruturado e intencional.

O que vai dentro de um arquivo DESIGN.md

Não existe uma estrutura obrigatória, mas o formato mais adotado — e o que usamos na biblioteca de referências da CamaraUX — segue seções bem definidas:

Tipografia

Descreva as famílias de fonte, a escala de tamanhos e os pesos usados para cada nível hierárquico. Inclua line-height e letter-spacing quando forem relevantes para a identidade visual.

markdown

## Typography
- **Heading 1**: Sora, 40px, 700, line-height 1.1
- **Heading 2**: Sora, 28px, 600, line-height 1.2
- **Body**: Source Sans 3, 16px, 400, line-height 1.7
- **Caption**: Source Sans 3, 13px, 400, color token: text-secondary

Paleta de cores e tokens

Liste as cores semânticas com seus valores hexadecimais e a função de cada uma. Não documente apenas a cor — documente quando e como usar.

markdown

## Colors
- **Primary** (#0A4FD4): botões de CTA, links, ações principais
- **Surface** (#F8F9FA): fundos de cards e painéis elevados
- **Text Primary** (#1A1A1A): corpo de texto e headings
- **Danger** (#D93025): erros, alertas destrutivos

Espaçamento e grid

Defina o módulo base (geralmente 4px ou 8px) e a escala de valores que o agente deve usar para padding, margin e gap. Isso elimina espaçamentos arbitrários nos componentes gerados.

Componentes e padrões

Descreva os componentes principais com todos os estados relevantes: default, hover, active, disabled, focus. Inclua border-radius, sombras e quaisquer regras de comportamento visual.

Anti-patterns: o que o agente não deve fazer

Esta é uma das seções mais valiosas e frequentemente esquecida. Liste explicitamente o que o agente não deve fazer: gradientes proibidos, fontes banidas, estilos que não combinam com a identidade do produto. Um agente com uma lista de anti-patterns clara erra muito menos.

markdown

## Anti-patterns
- Não usar fontes além de Sora e Source Sans 3
- Não usar gradientes decorativos no background
- Não usar sombras elevadas (box-shadow com blur > 8px)
- Não criar layouts com menos de 16px de padding horizontal

Veja como criar um arquivo DESIGN.md completo, com exemplos e templates prontos, no artigo como criar e aplicar um DESIGN.md com IA.

DESIGN.md vs design system: eles coexistem

Essa é uma das perguntas que mais aparecem quando designers conhecem o formato pela primeira vez. A resposta curta: DESIGN.md e design system são ferramentas diferentes que se complementam.

DESIGN.md substitui o Figma?

Não. O Figma é uma ferramenta visual para designers — permite explorar, iterar e apresentar interfaces com fidelidade. O DESIGN.md é textual, voltado para agentes de codificação. Os dois coexistem: o Figma é onde você toma as decisões de design, o DESIGN.md é onde você documenta essas decisões em um formato que a IA entende.

Na prática, o DESIGN.md funciona como uma tradução das decisões do Figma para o repositório. Se você atualiza a paleta no Figma, atualiza o DESIGN.md. E o agente passa a respeitar a mudança automaticamente.

DESIGN.md substitui o design system?

Também não. Um design system estruturado — com biblioteca de componentes, tokens, documentação de uso e governança — é muito mais abrangente. O DESIGN.md é o subconjunto dessa informação que um agente de IA precisa para gerar interfaces consistentes.

Se você tem um design system conectado a uma biblioteca de componentes via Figma + Storybook + MCP, por exemplo, o DESIGN.md pode não ser necessário para o pipeline de código. Mas se você é um founder solo, um designer sem estrutura de design system formalizada ou alguém que usa agentes para gerar landing pages e protótipos rápidos, o DESIGN.md resolve com muito menos overhead.

Um bom ponto de partida para entender a relação entre os dois é o nosso artigo sobre documentação de design e handoff para desenvolvedores.

Como usar DESIGN.md no seu fluxo de trabalho

O arquivo fica na raiz do repositório, ao lado do README.md. A partir daí, a integração depende da ferramenta que você usa.

Com Claude Code

Referencie o DESIGN.md no arquivo CLAUDE.md do projeto para que o agente carregue as regras de design automaticamente em cada sessão. O Claude Code lê os arquivos Markdown do repositório como contexto persistente — o DESIGN.md se torna parte do sistema de instrução do agente.

Com Cursor e Windsurf

No Cursor, adicione uma regra em .cursor/rules apontando para o DESIGN.md. No Windsurf, inclua o arquivo no diretório de steering. Ambos os agentes passam a injetar o contexto visual em toda geração de interface.

Com Google Stitch

O Stitch foi o primeiro a formalizar o formato. Você pode anexar o DESIGN.md diretamente ao prompt da plataforma ou exportar um arquivo gerado automaticamente a partir da URL do seu produto. Saiba mais no artigo DESIGN.md com Google Stitch.

Para entender como o DESIGN.md se encaixa em fluxos com agentes de UX mais complexos, veja o artigo DESIGN.md para agentes de IA.

A biblioteca de referências CamaraUX

A CamaraUX mantém uma biblioteca de arquivos DESIGN.md com referências visuais de mais de 50 marcas e produtos — de ferramentas de IA como Cursor, Mistral e Ollama a marcas globais como Apple, Nike e Netflix, passando por fintechs como Binance, Kraken e Wise.

Cada entrada da biblioteca serve como referência de estudo e ponto de partida para projetos que precisam de um estilo visual consistente. Se você está desenvolvendo um produto com estética minimalista, dark mode pesado ou tipografia editorial, há arquivos prontos para adaptar.

A ideia não é copiar a identidade visual de outra marca — é usar esses arquivos para entender como diferentes sistemas visuais se traduzem em tokens e regras que a IA consegue aplicar.

Perguntas frequentes sobre DESIGN.md

O DESIGN.md precisa ser criado do zero?

Não necessariamente. Existem bibliotecas abertas com dezenas de arquivos prontos, incluindo referências de marcas conhecidas. O repositório awesome-design-md, criado pela VoltAgent, e o portal designmd.app oferecem arquivos que você pode baixar, adaptar e usar como base. A CamaraUX também mantém sua própria coleção de referências em camaraux.com.br/design-md/.

Qual é o tamanho ideal de um arquivo DESIGN.md?

O menor possível para cobrir as decisões que importam. Um arquivo muito longo consome tokens desnecessariamente e dilui a atenção do agente. Foque em cores semânticas, tipografia, espaçamento, componentes principais e anti-patterns. Tudo que o agente precisa saber para não errar — e nada além disso.

DESIGN.md funciona com qualquer framework?

Sim. O arquivo descreve decisões de design, não implementação. O agente traduz as regras para o framework que você usa — React, Vue, Svelte, HTML puro. O DESIGN.md é agnóstico de tecnologia por design.

Conclusão

O DESIGN.md é uma das adições mais práticas ao fluxo de trabalho com agentes de IA que surgiram nos últimos meses. Para designers e Product Designers que usam Claude Code, Cursor ou qualquer outra ferramenta de vibe coding, ele representa a diferença entre receber interfaces genéricas e receber código que respeita as decisões visuais do produto.

Não substitui o Figma, não substitui o design system, e não é uma bala de prata. Mas é um arquivo de texto, fica na raiz do repositório e custa quase nada para criar. A relação custo-benefício é difícil de ignorar.

Se você quer começar agora, explore a biblioteca de referências da CamaraUX, escolha um arquivo próximo da identidade visual do seu projeto e adapte para os seus tokens reais. Ou fale com a CamaraUX se quiser ajuda para estruturar um DESIGN.md alinhado ao design system do seu produto.

Compatibilidade com ferramentas de IA