DESIGN.md: Resolva a Inconsistência de UI com IA

Problema: Claude Code tem forte contexto local e fraco contexto de produto. Ele sabe o arquivo que está editando. Ele não sabe como seu produto deveria parecer. Entre sessões, seu design system evapora. Botões aparecem onde deveriam ser links. Estados vazios somem. Uma cor que era #E07850 num componente vira orange-400 no próximo.

Resultado rápido: Coloque um arquivo design.md na raiz do projeto e referencie-o no CLAUDE.md. Seus valores de design viajam com o código. Cada sessão começa com as mesmas restrições no contexto.

O Que design.md Realmente É

Um arquivo design.md é um design system em texto simples. Sem sintaxe especial. Sem tooling necessário. Cores, espaçamento, tipografia, regras de componentes e estados de interação escritos em Markdown legível.

O Google Stitch introduziu o formato em março de 2026 e o posicionou como infraestrutura de interoperabilidade, similar a como o README.md se tornou uma convenção universal. A coleção awesome-design-md no GitHub chegou a 62,3 mil estrelas em abril de 2026 e inclui 60+ sistemas de design de marcas no formato: Stripe, Linear, Supabase, Vercel, Notion e outros.

A ideia é simples. Claude Code lê arquivos. Se o design system é um arquivo, Claude Code lê o design system.

Por Que as Sessões Derivam Sem Ele

Claude Code carrega contexto no início de cada sessão. Ele lê o CLAUDE.md, varre os arquivos abertos e constrói uma imagem do seu projeto. Sem um arquivo de design explícito, não há nada que vincule as decisões de UI a uma fonte de verdade.

Você pode descrever a cor primária em um comentário em algum lugar. Ou uma classe Tailwind em um componente. Claude lê o que abrir primeiro e extrapola daí. Três sessões depois, sua UI é uma coleção de melhores palpites.

Um arquivo design.md no CLAUDE.md muda o input. Os valores são explícitos, não inferidos. Cada sessão abre com a mesma fonte de verdade no contexto.

Obtenha o design.md do Google Stitch

O Google Stitch é uma ferramenta de design de UI do Google Labs, lançada no Google I/O em maio de 2025. Roda no Gemini 2.5 Pro, fica em stitch.withgoogle.com e é gratuito durante a fase Labs (conta Google, sem lista de espera, 350 gerações por mês no tier gratuito). A exportação design.md chegou no Stitch 2.0 em 18 de março de 2026.

O fluxo para gerar seu arquivo:

1. Vá para stitch.withgoogle.com. Clique na aba Web (não App). Selecione o modelo Pro mais alto disponível.
2. Opcionalmente faça upload de uma captura de tela de referência da sua UI atual ou uma imagem de inspiração.
3. Escreva um brief descrevendo sua marca: cores, tom, estilo de componente, o que o produto faz.
4. Itere conversacionalmente até que o output corresponda à sua intenção.
5. Clique em Export, escolha DESIGN.md, salve o arquivo na raiz do seu projeto.

O Stitch cria um arquivo estruturado cobrindo tokens de cor, escala tipográfica, unidades de espaçamento, padrões de componentes e definições de estado (hover, focus, active, disabled). O output é portável. Funciona com Claude Code, Cursor, Windsurf ou qualquer ferramenta que leia arquivos.

Conecte o CLAUDE.md ao Arquivo

Colocar o design.md na raiz não é suficiente. Sem instruções explícitas no CLAUDE.md, Claude trata o arquivo como material de referência que pode consultar. Com instruções explícitas, Claude trata os valores como restrições que deve seguir.

O bloco que funciona:

## Design System
This project uses a design system defined in `design.md` at the project root.
Always refer to this file when generating or modifying any UI component.
- Use only colors, fonts, and spacing values defined in design.md.
- Do not invent new values or use defaults from any framework.
- Match component states (hover, focus, active, disabled) to the patterns in design.md.
- Follow the typographic scale and weight assignments in design.md.
@design.md

O import @design.md no final injeta o conteúdo completo do arquivo no início da sessão. Os quatro pontos transformam uma referência passiva em restrições ativas. Ambas as partes importam. O import sozinho dá a Claude um documento. As instruções dão a Claude uma regra.

Verifique a Conexão Antes de Construir

Depois de atualizar o CLAUDE.md, confirme que Claude realmente carregou os valores corretamente:

Pergunte ao Claude: Qual cor primária está definida em design.md?

Se ele retornar o hex correto, o import está funcionando. Se hesitar ou chutar, verifique se @design.md aparece no final do bloco e se o caminho do arquivo está exatamente certo (sensível a maiúsculas/minúsculas no Linux).

Execute essa verificação no início de qualquer sessão com trabalho de UI. Leva dez segundos e captura um import faltando antes que vire um problema de deriva.

Adicione uma Camada de Enforcement com Tailwind

CLAUDE.md é contexto. Tailwind é enforcement. Os dois trabalham juntos.

Traduza os valores de token do seu design.md para o tailwind.config.js. Quando Claude escreve bg-blue-500 em vez de bg-primary, o build falha. Esse é o comportamento correto. Um erro de tipo no build é melhor do que uma inconsistência visual que você percebe na quarta tela.

Um bloco de config mínimo para uma marca de duas cores:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#E07850',
        'primary-dark': '#C5613A',
        surface: '#1A1A1A',
        'surface-elevated': '#1E1B18',
        text: '#FFFFFF',
        'text-muted': '#999999',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

Qualquer valor no design.md deve ter um token nomeado nessa config. Claude então escreve tokens, não valores brutos. O build captura qualquer coisa que escape.

Seis Modos de Falha

Esses são os jeitos que a configuração quebra na prática.

Exportar cedo demais. O Stitch gera cores de placeholder e estados faltando se seu brief for raso. Itere até o output estar completo antes de exportar. Lacunas no design.md viram lacunas nas restrições de Claude.

Instruções vagas no CLAUDE.md. O import sozinho não é suficiente. Os quatro pontos no bloco acima transformam um documento em um conjunto de regras. Sem eles, Claude lê o arquivo e decide quanto seguir.

Sem tradução para Tailwind. Deriva capturada em revisão visual depois de quatro telas custa mais do que um erro de build após um componente. Adicione a camada de config antes de começar a construir.

design.md fora do controle de versão. Se não está no repo, um novo clone ou um novo membro do time começa sem design system. Faça commit do arquivo no momento em que criá-lo.

Arquivo desatualizado após redesign. Quando você muda a marca, re-exporte do Stitch. Um design.md que descreve as cores do trimestre passado é pior do que nenhum arquivo: dá a Claude respostas erradas com confiança.

Rot de contexto em arquivos longos. Informações no meio de uma janela de contexto longa são lembradas com menos confiabilidade do que informações no início ou no final. Mantenha o design.md abaixo de 2.000 a 3.000 tokens. Divida por categoria (cor, tipografia, espaçamento, componentes) se o arquivo crescer além disso.

Alternativas ao Stitch

O Stitch é o caminho mais rápido para um design.md completo, mas quatro outras abordagens funcionam.

Extração manual do DevTools. Abra o Chrome DevTools, inspecione elementos-chave (botões, títulos, cards), copie o CSS computado para Claude e peça: Transforme isso em um design system como arquivo markdown. Cinco minutos. Funciona bem para produtos existentes onde você precisa capturar o estado atual em vez de definir um novo sistema.

awesome-design-md no GitHub. A coleção em github.com/VoltAgent/awesome-design-md tem 60+ sistemas de design de marcas em formato DESIGN.md a partir de abril de 2026. Se você está construindo algo próximo a uma estética de marca existente, comece a partir de uma referência e edite em vez de gerar do zero.

Figma MCP. Claude Code se conecta ao Figma diretamente via MCP e lê tokens de design em tempo real. Um estudo de caso da Parallel HQ relatou 62% menos inconsistências de design e 78% melhor eficiência de fluxo ao longo de seis meses. A troca é o atrito de autenticação. O Stitch exporta um arquivo autocontido; o Figma MCP requer uma conexão ativa e gerenciamento de token.

Extrair de uma URL. O Stitch aceita URLs públicas como input. Cole a URL de um site de marketing limpo e o Stitch lê o estilo visual. Funciona bem para páginas públicas limpas, tem dificuldades com dashboards autenticados.

Claude Design vs. design.md

O Claude Design foi lançado em 17 de abril de 2026, alimentado pelo Opus 4.7 com um novo modo de visão de 2.576px. Ele cria trabalho visual por meio de conversa e produz um bundle de handoff dentro do ecossistema Anthropic. Uma empresa de edtech relatou que páginas que precisavam de 20+ prompts em outras ferramentas precisaram de apenas 2 no Claude Design.

A diferença do fluxo design.md se resume à portabilidade. O Claude Design produz artefatos vinculados à stack Anthropic. Um design.md do Stitch é um arquivo simples que funciona com qualquer ferramenta que leia arquivos: Claude Code, Cursor, Windsurf ou um script de build customizado.

O Claude Design é mais rápido se você ficar dentro do ecossistema Anthropic. O design.md é melhor se você quer que o design system viaje com o código, versionado ao lado do código que ele governa.

O Que Você Ganha

Um arquivo na raiz do repo. Quatro linhas no CLAUDE.md. Tokens nomeados no tailwind.config.js.

Cada sessão abre com as mesmas restrições de design no contexto. Cada build falha em valores brutos em vez de deixar a deriva acumular. Cada tela que Claude toca segue as mesmas regras da última.

Consistência de design não é um processo de revisão. É um arquivo.

Perguntas Comuns

O que é design.md no Claude Code?

design.md é um arquivo de texto simples na raiz do seu projeto que define seu design system: cores, tipografia, espaçamento, regras de componentes e estados de interação. Quando referenciado no CLAUDE.md com o import @design.md, Claude Code carrega esses valores no início da sessão e os trata como restrições em vez de sugestões, mantendo cada tela consistente entre sessões.

Como uso design.md com Claude Code?

Exporte um arquivo design.md do Google Stitch ou escreva um manualmente, coloque-o na raiz do projeto, depois adicione um bloco ## Design System ao CLAUDE.md que inclua o import @design.md e quatro regras em formato de pontos. Por fim, traduza seus valores de token para o tailwind.config.js para que o build falhe em qualquer valor bruto que contorne o sistema.

O Google Stitch é gratuito?

Sim, durante a fase do Google Labs. O tier gratuito em stitch.withgoogle.com inclui 350 gerações por mês com acesso a todos os recursos principais e requer apenas uma conta Google sem lista de espera. O Stitch 2.0, que introduziu a exportação design.md, foi lançado em 18 de março de 2026. O preço pode mudar quando o Stitch sair da fase Labs.

O que é o repo awesome-design-md?

awesome-design-md é uma coleção no GitHub mantida pelo VoltAgent em github.com/VoltAgent/awesome-design-md. Contém 60+ arquivos DESIGN.md prontos para uso, modelados em sistemas de design de marcas reais incluindo Stripe, Linear, Supabase, Vercel e Notion. Você pode colocar um diretamente no seu projeto como ponto de partida e editá-lo para corresponder à sua marca em vez de gerar do zero.

Como faço o Claude Code parar de ignorar meu design system?

Duas coisas são necessárias juntas, não separadamente. Primeiro, adicione o import @design.md no final do bloco de design no CLAUDE.md para que o conteúdo do arquivo carregue no início da sessão. Segundo, adicione regras explícitas em formato de pontos acima do import dizendo a Claude para usar apenas valores do arquivo e não inventar novos. O import sozinho dá a Claude um documento; as regras dão a Claude uma restrição.

design.md vs Figma MCP: qual é melhor para Claude Code?

Eles resolvem o mesmo problema de formas diferentes. O Figma MCP conecta Claude ao Figma em tempo real, dando a ele acesso a tokens e componentes de design ao vivo, mas requer configuração de autenticação e uma conexão persistente. Um design.md do Stitch é um arquivo autocontido que funciona offline, viaja com o repo e é versionado ao lado do código. O Figma MCP serve para times já imersos no Figma; o design.md serve para construtores solo que querem zero infraestrutura.