---
title: "DESIGN.md: o arquivo que ensina identidade visual para agentes de IA"
date: 2026-05-07T00:09:00Z
modified: 2026-06-17T14:42:29Z
permalink: "https://camaraux.com.br/design-md-agentes-ia-ux/"
type: post
status: publish
excerpt: ""
wpid: 6386
categories:
  - Fundamentos de UX
rank_math_title: "DESIGN.md: contexto visual para agentes de IA  %sep% %sitename%"
rank_math_description: O design.md é um arquivo que ensina identidade visual para agentes de IA. Saiba como funciona, como criar o seu e usar no Claude Code e Cursor.
rank_math_focus_keyword: design.md
featured_image: /wp-content/uploads/2026/05/DESIGN.md-para-agentes-de-IA.png
featured_image_alt: Ilustração minimalista de identidade visual para agentes de IA com elementos modulares em roxo
author: Lucas Camara
---

Você pediu para um agente de IA gerar uma interface. O resultado voltou com botões azuis genéricos, tipografia padrão do sistema e cores que não têm nada a ver com o projeto. Isso não é falha do agente. É falta de contexto.

LLMs não têm memória visual. Sem instruções explícitas sobre cores, tipografia e espaçamento, o agente inventa — e o que ele inventa é sempre o mesmo: uma interface anônima que poderia ser de qualquer produto.

O `design.md` resolve isso. É um arquivo Markdown colocado na raiz do projeto que descreve a identidade visual em um formato que agentes de codificação conseguem ler, interpretar e aplicar antes de gerar qualquer componente.

## O que é o design.md

O `design.md` é uma especificação de formato open source lançada pelo Google como parte do Google Stitch, plataforma de prototipagem visual com IA. O repositório oficial define o arquivo como uma forma de fornecer aos agentes “uma compreensão estruturada e consistente do sistema de design do projeto.”

Na prática: é o equivalente a sentar com um designer júnior antes do trabalho começar e mostrar o guia de identidade visual do cliente. Sem esse briefing, ele vai tomar decisões visuais por conta própria — algumas aceitáveis, muitas erradas.

O que diferencia o `design.md` de simplesmente colar um trecho de design system no prompt é a combinação de dois tipos de conteúdo no mesmo arquivo:

- **Tokens legíveis por máquina** — valores exatos de cor, tipografia e espaçamento em YAML, no formato que o LLM processa diretamente.
- **Justificativas legíveis por humano** — texto em Markdown explicando o raciocínio por trás de cada decisão visual: por que esse tom de azul, em que contexto usar o peso bold, qual é o grid padrão.

O agente recebe o valor e o contexto de uso juntos. Isso é diferente de um token JSON isolado, que diz o quê mas não diz o porquê nem como.

O projeto é open source e está disponível no GitHub em `github.com/google-labs-code/design.md`. Ganhou tração rápida: o repositório `awesome-design-md` — uma coleção de arquivos prontos para marcas como Stripe, Notion, Figma e Vercel — saiu de zero para mais de 20.000 stars em seis dias após o lançamento.

Se você está começando a usar [inteligência artificial no processo de design](https://camaraux.com.br/inteligencia-artificial-para-designers/), o `design.md` é o primeiro passo para garantir que os outputs visuais tenham consistência com o produto real.

### Conheça a biblioteca de design.md

Explore templates de design.md inspirados em grandes marcas para usar como referência em projetos com IA, vibe coding e criação de interfaces.

[Ver biblioteca de design.md](https://camaraux.com.br/design-md)

## Como o arquivo está estruturado

Todo `design.md` segue uma estrutura de nove seções canônicas definidas pela especificação oficial. O cabeçalho usa YAML para os tokens — valores exatos que o agente lê como dados. O corpo usa Markdown para a argumentação qualitativa — contexto que o agente usa para tomar decisões.

Um exemplo simplificado:


```
---
name: Produto X
colors:
  primary: "#0F4C81"
  surface: "#F5F5F5"
  on-surface: "#1A1A1A"
typography:
  headline:
    fontFamily: "Inter"
    fontSize: "2rem"
    fontWeight: 600
  body:
    fontFamily: "Inter"
    fontSize: "1rem"
    fontWeight: 400
spacing:
  sm: 8px
  md: 16px
  lg: 32px
rounded:
  sm: 4px
  md: 8px
---

## Visão geral

Interface minimalista voltada para gestão. Alta densidade de informação, hierarquia clara, sem elementos decorativos.

## Cores

A cor primária (#0F4C81) é reservada para CTAs, links e elementos de destaque interativo. Nunca usar em backgrounds de seções inteiras. A surface (#F5F5F5) é o fundo padrão de cards e painéis secundários.

## Tipografia

Inter em todos os contextos. Headline em 2rem/600 para títulos de seção. Body em 1rem/400 para texto corrido. Nunca usar peso abaixo de 400 em interfaces — perde legibilidade em telas de baixa resolução.
```

As nove seções canônicas da especificação são: visão geral da identidade, paleta de cores com regras de uso, tipografia, espaçamento e grid, componentes principais, estilização de botões e formulários, layout e comportamento responsivo, estados de interação e padrões de acessibilidade.

Você não precisa preencher todas as seções para o arquivo ser útil. Um `design.md` com cores, tipografia e espaçamento já elimina a maior parte das inconsistências visuais que os agentes produzem quando trabalham sem contexto.

## Onde encontrar arquivos prontos

Existem portais com coleções de arquivos `design.md` prontos para uso. Os mais completos em maio de 2026:

- **getdesign.md** — coleção organizada por estilo visual e categoria de produto
- **designmd.app** — mais de 400 arquivos documentados, com instruções de configuração para Claude Code, Cursor e Kiro
- **neuform.ai** e **designmd.me** — coleções menores com foco em estilos específicos

Uma observação importante: os arquivos de marcas famosas disponíveis nesses portais não são os design systems oficiais das empresas. São referências visuais que se aproximam do estilo da marca — úteis para dar consistência ao agente, mas não equivalentes à documentação original.

Você pode copiar o arquivo Markdown diretamente ou instalar via linha de comando usando as instruções de cada portal. A instalação via CLI coloca o arquivo na raiz do projeto automaticamente.

> A CamaraUX mantém uma [Biblioteca de Templates Design.md](https://camaraux.com.br/design-md/) com arquivos prontos para marcas como Adobe, IBM, Netflix, Nike, Brastemp e Consul, entre outros.

## Como usar no seu projeto de UX

A mecânica básica é simples: coloque o arquivo `design.md` na raiz do projeto. Agentes como Claude Code, Cursor e Kiro incluem automaticamente o conteúdo no contexto quando você trabalha em arquivos de interface.

Mas existem variações importantes dependendo da ferramenta:

### Claude Code

Coloque o `design.md` na raiz do projeto. O Claude Code o lê automaticamente. Para garantir que ele seja referenciado em toda geração de UI, você pode adicionar uma instrução no arquivo `CLAUDE.md` do projeto:


```
Ao gerar qualquer componente de interface, consulte o DESIGN.md na raiz deste projeto e aplique as especificações de cor, tipografia e espaçamento definidas.
```

### Cursor

Adicione uma referência ao `design.md` no arquivo `.cursorrules` ou nas regras globais (`global_rules.md`). A instrução pode ser direta:


```
Para todos os arquivos de componente (.tsx, .jsx, .vue, .html), aplique as especificações visuais do DESIGN.md antes de gerar qualquer código de interface.
```

### Google Stitch

O Stitch passou a aceitar `design.md` nativamente na criação de novos projetos. Você pode fazer upload do arquivo, colar o conteúdo diretamente ou buscar um estilo no marketplace de estilos visuais da plataforma. Os designs gerados respeitam automaticamente as especificações do arquivo.

### Cenários práticos de uso

**Projeto sem design system documentado:** Você tem uma identidade visual definida mas nunca formalizou os tokens. Use o `design.md` para documentar o que já existe — cores, tipografia, espaçamento — e passe isso para o agente antes de começar a gerar componentes.

**Landing page ou site institucional:** Não tem design system montado porque o escopo não justifica. O `design.md` cobre o caso sem o overhead de uma documentação completa.

**Prototipagem rápida com referência de marca:** Selecione um arquivo de um portal que se aproxime do estilo desejado, edite os valores para os seus tokens reais e use como contexto de partida. É mais rápido do que criar do zero e mais preciso do que trabalhar sem contexto.

**Engenharia reversa de produto existente:** Você tem um produto com identidade consolidada mas sem documentação. Audit as telas existentes, extraia os tokens reais e documente no formato `design.md`. O agente passa a ter o contexto que antes existia só na cabeça do designer.

## design.md vs design system: quando cada um se aplica

Quem já trabalha com [design systems no Figma](https://camaraux.com.br/design-systems-figma/) e tem uma biblioteca de componentes conectada via MCP pode estar se perguntando se precisa de um `design.md`. A resposta depende do contexto.

Se o seu fluxo já conecta Figma ao ambiente de codificação via MCP, com componentes mapeados e tokens sincronizados, o design system cobre o caso de forma mais completa. O `design.md` seria redundante.

O `design.md` se aplica nas situações em que o design system não existe, não está conectado ao ambiente de desenvolvimento ou é excessivo para o escopo do projeto:

- Projetos de menor porte que não justificam infraestrutura de design system
- Times sem designer dedicado que querem consistência visual na geração de interfaces por IA
- Consultores e freelancers trabalhando em projetos paralelos sem suporte de biblioteca de componentes
- Qualquer contexto onde o custo de manter um design system completo supera o benefício

O `design.md` não substitui um design system em projetos complexos. É uma solução pragmática para dar contexto visual a agentes de IA quando a infraestrutura completa não existe ou não é necessária.

## Como criar o seu próprio design.md passo a passo

Se você tem uma identidade visual definida e quer criar um arquivo do zero:

### **1. Levante os tokens existentes**

Abra o seu projeto no [Figma](https://camaraux.com.br/figma/) e documente os valores reais: código hexadecimal das cores principais, nomes de fonte, tamanhos e pesos usados na hierarquia tipográfica, valores de espaçamento do grid.

### **2. Escolha uma referência de base**

Nos portais listados acima, encontre um arquivo que se aproxime do estilo do projeto. Isso acelera o processo porque a estrutura e a argumentação qualitativa já estão escritas — você edita os valores, não a estrutura.

### **3. Substitua os tokens**

Abra o arquivo em qualquer editor de texto e substitua os valores do YAML pelos seus tokens reais. Cor primária, superfícies, tipografia, espaçamento.

### **4. Ajuste a argumentação qualitativa**

Edite o texto em Markdown para refletir as decisões reais do projeto. Adicione restrições importantes: quais cores não devem ser usadas em fundos de seção inteira, qual peso tipográfico é o mínimo aceitável, como o grid se comporta em mobile.

### **5. Revise o tamanho do arquivo**

Um `design.md` muito extenso consome tokens desnecessariamente no contexto do agente. Mantenha o foco nos valores que o agente realmente precisa para gerar UI consistente: cores, tipografia, espaçamento, comportamento dos componentes principais. Documentação de marca, histórico de versões e guidelines editoriais ficam fora.

### **6. Coloque na raiz e teste**

Salve como `design.md` na raiz do projeto, abra o agente e peça para gerar um componente simples — um botão primário, um card, um formulário básico. Verifique se os valores aplicados batem com o arquivo.

## O que isso muda na prática para designers e consultores de UX

O `design.md` representa uma mudança de paradigma pequena na operação, grande nas implicações.

O fluxo tradicional de design coloca o designer como o único portador da identidade visual. Briefings, guias de estilo, apresentações de aprovação — tudo para transmitir contexto que existia originalmente na cabeça do designer ou em documentos que ninguém atualiza.

Com `design.md`, a identidade visual do projeto vira infraestrutura. Um arquivo na raiz do repositório, versionado no Git, acessível a qualquer agente de codificação. Quando alguém entra no projeto — dev, designer, agente de IA — o contexto visual já está lá.

Para designers que trabalham com consultoria ou como freelancers, isso tem implicações diretas: menos tempo corrigindo outputs de IA que ignoraram a identidade visual, mais consistência nos projetos que usam geração de interface, e uma forma estruturada de documentar decisões visuais que antes ficavam implícitas.

O formato ainda está se consolidando. O Google Stitch, Cursor, Claude Code e outras plataformas já têm suporte nativo ou instruções de integração. A tendência é que `design.md` vire um padrão de fato para projetos que usam agentes de codificação — da mesma forma que `README.md` e `AGENTS.md` já são.

Quem documenta os tokens agora constrói a base antes do padrão se fechar.

---

Se você quer entender como integrar IA de forma estruturada no processo de UX — do uso de agentes de codificação à pesquisa com usuários — veja como a consultoria da CamaraUX pode ajudar o seu time a fazer isso sem improvisar. [Fale sobre o seu projeto](https://camaraux.com.br).

> Para aplicar o `design.md` especificamente no Google Stitch, veja o guia [como usar design.md com Google Stitch](https://camaraux.com.br/design-md-google-stitch/). Para criar o seu arquivo do zero com estrutura completa, veja [como criar e aplicar um DESIGN.md em projetos de IA](https://camaraux.com.br/como-criar-aplicar-design-md-ia/).

## Topics

**Categorias:** [Fundamentos de UX](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/fundamentos-de-ux.md)