O que é DESIGN.md

Em março de 2026, o Google Stitch introduziu DESIGN.md como parte de uma atualização que incluiu canvas infinito, agente de design com memória de projeto, prototipagem instantânea e interação por voz. Entre todas essas funcionalidades, DESIGN.md é o componente menos visível — mas o mais reutilizável fora do ecossistema Stitch.

DESIGN.md é um arquivo Markdown que serializa um design system — paleta de cores, tipografia, espaçamento, padrões de componentes e restrições visuais — em formato otimizado para consumo por LLMs. O arquivo fica na raiz do repositório e o agente de IA lê antes de gerar qualquer interface.

A analogia mais precisa: DESIGN.md está para design assim como AGENTS.md está para convenções de código. É contexto persistente que o agente consulta a cada interação.

Formato

Formato e estrutura

Um DESIGN.md é composto por seções com headings Markdown. Cada seção tem uma função específica no contexto do agente. A ordem importa: o LLM processa de cima para baixo.

1. Overview

Descrição do produto e direção visual em 2-3 frases. Dá ao LLM calibração de contexto antes de processar specs técnicas.

## Overview
App de analytics para enterprise financeiro. Visual preciso, confiável, minimal.

2. Colors

Hex + nome semântico + regra de uso. Sem nome semântico, o LLM pode usar a cor de erro como accent.

## Colors
- **brand-primary** (#1A73E8): ações principais, links, estados interativos
- **neutral-surface** (#F8F9FA): backgrounds de superfície e cards
- **status-error** (#D93025): apenas estados de erro e ações destrutivas

3. Typography

Famílias, pesos e escala com valores concretos. O agente precisa de números — "fonte grande" não é instrução útil para um LLM.

## Typography
- Headlines: Inter, 600, 24-48px, tracking-tight
- Body: Inter, 400, 14-16px, leading-relaxed
- Mono: JetBrains Mono, 400, 13px (code blocks, dados numéricos)

4. Spacing

Base unit e escala nomeada. Sem escala definida, cada componente gerado usa espaçamentos arbitrários.

## Spacing
Base: 4px
- xs: 4px | sm: 8px | md: 16px | lg: 24px | xl: 32px | 2xl: 48px

5. Components

Padrões visuais com estados. Sem essa seção, o agente inventa estados diferentes a cada geração.

## Components
### Buttons
- Primary: filled brand-primary, text white, rounded-lg, py-2 px-4
- Hover: brightness +10%
- Disabled: opacity 50%, cursor not-allowed
### Inputs
- Border: 1px neutral-300, rounded-md
- Focus: ring-2 brand-primary

6. Do's and Don'ts

Restrições explícitas. LLMs respondem bem a instruções negativas — dizer o que não fazer é tão importante quanto dizer o que fazer.

## Do's and Don'ts
- DO: usar primary apenas para a ação mais importante da tela
- DON'T: misturar cantos arredondados e retos no mesmo componente
- DO: manter contraste mínimo 4.5:1 para texto
- DON'T: usar sombras em mais de 2 níveis de elevação

Formato

Por que Markdown e não JSON ou YAML

Markdown é o formato que LLMs entendem com maior fidelidade. A maior parte do corpus de treinamento usa essa estrutura. O modelo não precisa de instrução extra para interpretar.

Design tokens em JSON definem valores, mas não regras. Não há como expressar "use primary apenas para a ação principal" em um arquivo tokens.json. DESIGN.md combina valores e semântica no mesmo arquivo, sem build pipeline.

Critério	DESIGN.md	Tokens (JSON)	Style Guide
Legível por LLM	Nativo (treinado em MD)	Requer parsing	Não legível
Legível por humano	Sim, sem tooling	Parcial	Sim
Versionável (Git)	Sim	Sim	Não (binário)
Context window	Leve (~2-5K tokens)	Médio	N/A
Build pipeline	Nenhum	Necessário	N/A
Regras semânticas	Sim (Do's/Don'ts)	Não (só valores)	Sim

Markdown não substitui design tokens em projetos que já usam build pipeline. Os dois podem coexistir.

Obtenção

Como obter um DESIGN.md

Quatro caminhos, do mais rápido ao mais controlado.

1. Copiar da biblioteca designmd.app

Escolha por vertical ou estilo visual, customize os valores para o seu projeto e use. A biblioteca tem mais de 400 arquivos documentados.

2. Gerar com a skill design-md

A skill analisa o codebase existente — componentes, variáveis CSS, tokens — e extrai um DESIGN.md estruturado a partir dos padrões encontrados.

3. Exportar do Google Stitch

Se o projeto já usa Stitch, o export é nativo. O arquivo gerado segue a mesma estrutura documentada aqui.

4. Escrever manualmente

Siga a estrutura das 6 seções acima. Controle total sobre cada decisão de design.

Setup

Configuração por agente

Cada agente de IA tem seu próprio arquivo de configuração. O DESIGN.md fica na raiz do projeto — a configuração apenas diz ao agente para lê-lo.

Agente	Config	Referência
Claude Code	`CLAUDE.md`	`Siga regras visuais de @DESIGN.md`
Cursor	`.cursor/rules/*.mdc`	`Include do DESIGN.md`
Kiro	`.kiro/steering/`	`Copiar DESIGN.md para steering`
Windsurf	`.windsurfrules`	`Referenciar DESIGN.md`
Google Stitch	`UI nativa`	`Import direto`

Claude Code

Adicione a referência no arquivo CLAUDE.md na raiz do projeto:

# CLAUDE.md
Siga as regras visuais definidas em @DESIGN.md para toda geração de UI.
Não use cores, fontes ou espaçamentos que não estejam definidos no DESIGN.md.

Cursor

Crie uma regra em .cursor/rules/:

# .cursor/rules/design.mdc
Leia DESIGN.md na raiz do projeto antes de gerar qualquer componente visual.

Kiro

Copie o DESIGN.md para .kiro/steering/DESIGN.md. O Kiro inclui automaticamente arquivos de steering no contexto.

Windsurf

Adicione a referência no .windsurfrules:

# .windsurfrules
Referencie DESIGN.md para todas as decisões visuais.

Google Stitch

Import via UI: Settings → Design System → Import DESIGN.md. O Stitch criou o formato — o suporte é nativo.

Guias detalhados por agente →

FAQ

Perguntas frequentes

O que é DESIGN.md?

Arquivo Markdown que serializa um design system para consumo por agentes de IA. Define cores, tipografia, espaçamento, padrões de componentes e restrições visuais em formato otimizado para LLMs. Padrão introduzido pelo Google Stitch em março de 2026.

DESIGN.md substitui o Figma?

Não. Figma é ferramenta de design visual para criar interfaces. DESIGN.md é a tradução dessas decisões de design para um formato que agentes de IA leem e aplicam automaticamente. São complementares.

Preciso saber design para usar DESIGN.md?

Não para usar um pronto. A biblioteca designmd.app tem mais de 400 arquivos prontos para copiar. A skill design-md gera um a partir do seu codebase existente.

Funciona com qualquer agente de IA?

Sim. Qualquer agente que leia arquivos do repositório pode usar DESIGN.md: Claude Code, Cursor, Kiro, Windsurf, Google Stitch e outros.

Qual a diferença entre DESIGN.md e design tokens em JSON?

Design tokens em JSON definem apenas valores (cores, espaçamentos). DESIGN.md define valores + regras semânticas + restrições (Do's and Don'ts). Tokens precisam de build pipeline. DESIGN.md é Markdown puro.

Posso usar em projeto existente?

Sim. Adicione o arquivo DESIGN.md na raiz do projeto e referencie no arquivo de configuração do seu agente. Não altera código existente.

Como atualizar quando o design muda?

Edite o arquivo. É Markdown — qualquer editor de texto serve. Versione com Git para manter histórico de mudanças.

Funciona com React, Vue, Svelte?

DESIGN.md é agnóstico de framework. Define regras visuais, não implementação. O agente aplica essas regras independente do framework.

Próximos passos

Explore a biblioteca com mais de 400 DESIGN.md documentados ou gere um a partir do seu codebase existente.

Ver biblioteca Skill design-md →