O que é um DESIGN.md
Um DESIGN.md fica ao lado do código e descreve o design pretendido em termos que um agente pode executar. Agentes de codificação implementam interfaces bem, mas sem direção de arte, eles tendem a recorrer a um estilo neutro padrão. O Google Labs agora publica uma especificação e um validador alpha para DESIGN.md. O formato é ativo e útil, embora a especificação ainda avise que pode mudar.
Um DESIGN.md precisa de mais do que uma lista de cores. Os agentes também precisam de orientação sobre layout, espaçamento, tratamento de componentes e os detalhes que distinguem um design de outro. Um briefing útil dedica a maior parte de suas palavras a essas decisões.
O que deve constar em um DESIGN.md
Um briefing completo cobre todo o sistema, não apenas os tokens. O DESIGN.md que o Identity Forge gera é organizado nestas seções:
- Overview: o que é o design, para quem ele é e a sensação pretendida em uma ou duas frases.
- Colors: os tokens semânticos como variáveis CSS prontas para colar no
globals.css, em modo claro e escuro. Tokens de cores semânticas explicados. - Typography: o emparelhamento de tipos, escala, tracking e pesos, além de uma configuração de fontes Next.js pronta para uso.
- Layout: base de espaçamento, largura do container e regras de composição.
- Elevation & Depth: o sistema de sombras (ou a ausência deliberada de um).
- Shapes: raios de borda por elemento (botões, cards, inputs, badges) e tratamento de bordas.
- Components: como os componentes principais devem ser tratados, com um exemplo.
- Page Structure & Layout: como compor páginas inteiras; é aqui que o output genérico de IA é evitado.
- Personality & References: a voz e as referências por trás do design.
- Distinctive Motifs: os dispositivos de assinatura para reproduzir; "eles definem o design tanto quanto os tokens."
- Do's & Don'ts: as regras que mantêm a interface gerada dentro do mundo do design.
- Agent Rules: instruções explícitas para o próprio agente de codificação.
Os motivos e os 'don'ts' são o ponto principal
Qualquer pessoa pode listar cinco códigos hexadecimais. O que separa um sistema de design real de um template apenas com cores alteradas é a intenção escrita: os motivos para reproduzir e os erros para evitar. Essas seções são o motivo pelo qual um DESIGN.md altera o resultado de um agente, enquanto uma paleta não altera.
Veja isso apoiado por um sistema real
Um DESIGN.md é tão bom quanto o sistema por trás dele. Abaixo está o kit gratuito ambient-sage: os tokens, fontes e tratamentos que seu DESIGN.md descreve, renderizados ao vivo:
Ambient Sage
Live renderRendered from the kit's actual tokens, fonts, and treatments
Dashboard
Welcome back — here's how AmbientSage is performing today.
Active users
15.1k
+5%Trending up this month
vs. previous 30 days
MRR
$49.1k
+3%Strong recurring growth
Net of churn
Retention
89%
+2%Engagement above target
Rolling 28-day window
NPS
69
+3Meets growth projections
Survey · n=1,204
Total revenue
Last 12 months
$49.1k+18.2%
Recent sales
You closed 265 deals this month.
Alex Rivera
alex@ambientsage.com
Mira Okonkwo
mira@ambientsage.com
Jonas Feld
jonas@ambientsage.com
Sana Qureshi
sana@ambientsage.com
Theo Lindgren
theo@ambientsage.com
Recent transactions
View all| Customer | Status | Date | Amount |
|---|---|---|---|
AR Alex Rivera Founder & CEO | Paid | 2m ago | $1,999.00 |
MO Mira Okonkwo Head of Product | Pending | 1h ago | $39.00 |
JF Jonas Feld Design Lead | Processing | 3h ago | $299.00 |
SQ Sana Qureshi Engineering Lead | Paid | Yesterday | $99.00 |
TL Theo Lindgren Brand Director | Refunded | 2d ago | $2,400.00 |
Typography
Plus Jakarta Sans
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Gere um (três maneiras)
- 1
CLI: escreva DESIGN.md + tokens no seu repositório
O caminho mais rápido. Escolha um slug de kit da galeria e aplique-o; você recebe um DESIGN.md commitado mais um arquivo de tokens correspondente.
identityforge apply ambient-sage - 2
MCP: deixe o agente buscá-lo
Com o servidor MCP instalado, o agente chama
get_design_md(slug)para ler o briefing completo eapply_themepara escrevê-lo. Instale para sua ferramenta:npx --yes identityforge@latest install --client claude-code - 3
shadcn: instale os tokens que o DESIGN.md referencia
Se você quiser apenas os valores, o item do registro instala as variáveis CSS do kit diretamente.
npx shadcn add https://identityforge.io/r/ambient-sage.json
O Identity Forge gera o DESIGN.md e os tokens a partir do mesmo kit, portanto, o texto descreve os valores na folha de estilo. Para saber como isso difere de adaptar uma entrada de catálogo DESIGN.md manualmente, veja Identity Forge vs getdesign.md.
FAQ
O que é um DESIGN.md?
Um DESIGN.md é um arquivo Markdown no seu repositório que diz a um agente de codificação por IA como o produto deve parecer: sua intenção, sistemas de cores e tipografia, regras de layout e espaçamento, tratamentos de componentes, motivos distintos e o que fazer e não fazer. O agente o lê antes de construir a interface para que seu resultado permaneça fiel à marca e consistente.
Como eu gero um DESIGN.md?
Aplique um kit do Identity Forge: `identityforge apply <slug>` escreve um DESIGN.md completo mais os tokens correspondentes no seu projeto. Com o servidor MCP instalado, o agente também pode buscá-lo sozinho via ferramenta get_design_md.
Um DESIGN.md é apenas uma lista de cores?
Não. Cores são a parte fácil. Um DESIGN.md útil dedica a maior parte de suas palavras ao layout, espaçamento, tratamento de componentes, motivos distintos e o que fazer e não fazer: os lugares onde interfaces construídas por IA realmente se tornam genéricas.
Existe uma especificação oficial de DESIGN.md?
O Google Labs publica uma especificação e um validador alpha de DESIGN.md. O Identity Forge gera seu briefing e tokens a partir do mesmo kit de design, o que mantém as regras escritas vinculadas aos valores exportados.