Como gerar um DESIGN.md (e o que ele é)

Um DESIGN.md fica ao lado do código e descreve o design pretendido em termos que um agente possa executar. Agentes de código implementam bem a UI, mas, sem direção de arte, tendem a recorrer a um estilo visual neutro. Desde então, o nome tornou-se um pequeno ecossistema: o Google Labs abriu o código de uma especificação de formato DESIGN.md (da equipe Stitch, Apache 2.0, ainda em versão alpha), que atraiu dezenas de milhares de estrelas no GitHub em poucos meses. A especificação deles combina tokens legíveis por máquina em front matter YAML com a justificativa legível por humanos em prosa, e fornece uma CLI que valida arquivos e exporta para Tailwind e para o formato de design-token da W3C.

Essa estrutura — valores exatos mais a intenção escrita em um único arquivo — é a mesma conclusão que este guia defende, e vale a pena ser preciso sobre o que a especificação oferece e o que não oferece. Um formato diz onde os tokens e a prosa devem ficar. Ele não produz o design system em si: os tokens ainda precisam vir de algum lugar, e os motivos, as proibições e as regras de estrutura de página ainda precisam ser decididos por alguém. Sites de catálogo reúnem arquivos DESIGN.md finalizados; as abordagens de geração abaixo produzem um a partir de um sistema real, que é a diferença entre um arquivo que é válido e um arquivo que altera o que um agente constrói.

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 brief útil dedica a maior parte do seu texto a essas decisões.

Um brief completo abrange todo o sistema, não apenas os tokens. O DESIGN.md que o Identity Forge gera é organizado nestas seções:

• Visão Geral: o que é o design, para quem ele é e a sensação pretendida em uma ou duas frases.
• Cores: os tokens semânticos como variáveis CSS prontas para colar no globals.css, em modo claro e escuro. Explicação sobre tokens de cores semânticas.
• Tipografia: a combinação de fontes, escala, tracking e pesos, além de uma configuração de fonte pronta para Next.js.
• Layout: base de espaçamento, largura do container e regras de composição.
• Elevação e Profundidade: o sistema de sombras (ou a ausência deliberada de um).
• Formas: raios de borda por elemento (botões, cards, inputs, badges) e tratamento de bordas.
• Componentes: como os componentes principais devem ser tratados, com um exemplo.
• Estrutura e Layout de Página: como compor páginas inteiras; é aqui que se evita a saída genérica de IA.
• Personalidade e Referências: a voz e as referências por trás do design.
• Motivos Distintivos: os elementos de assinatura para reproduzir; "eles definem o design tanto quanto os tokens".
• O que fazer e o que não fazer: as regras que mantêm a UI gerada dentro do universo do design.
• Regras do Agente: instruções explícitas para o próprio agente de código.

A lista acima cobre o que um brief completo deve ter. Vale a pena saber o quanto os arquivos publicados ficam aquém disso, pois a lacuna é consistente e indica exatamente quais seções priorizar se você estiver escrevendo um manualmente.

Analisamos 299 arquivos DESIGN.md publicados em repositórios e diretórios públicos: arquivos reais, escritos para fornecer orientações de design aos agentes. 72 eram especificamente arquivos de design visual.

Compare as duas últimas linhas e o padrão é inconfundível. A tipografia é mencionada em 83% dos arquivos, mas 44% dos arquivos nunca declaram um único tamanho. São documentos que falam sobre tipografia sem dizer o tamanho de nada.

O dado sobre adjetivos explica o restante. "Clean" aparece em 39% desses arquivos e "modern" em 36%. Ambas são palavras que um modelo satisfaz produzindo a média de sua distribuição de treinamento, que é precisamente a entrega genérica que o arquivo deveria evitar.

A única distinção que separa um brief que altera a entrega de um que não altera: uma frase pode ser verificada em relação a uma tela renderizada? Se não, ela é apenas decorativa.

Cada entrada na coluna da direita pode ser verificada consultando uma tela ou fazendo um grep no código. Cada entrada na coluna da esquerda pode ser satisfeita por quase qualquer coisa, o que significa que ela não impõe restrição alguma.

Três propriedades separam uma proibição que surte efeito de uma que é ignorada.

A terceira linha é a que mais frequentemente é esquecida. Uma proibição sem alternativa abre uma lacuna que o modelo preenche com a mesma distribuição de treinamento da qual você estava tentando escapar. Todo "nunca X" precisa de um "em vez disso, Y".

Se você estiver escrevendo um manualmente em vez de gerá-lo, este é um ponto de partida sólido. Ele é curto propositalmente. Um brief que ninguém consegue manter na memória compete com a tarefa real pela atenção do modelo. Aproximadamente 400 linhas é um teto viável; este esqueleto está bem abaixo disso.

# DESIGN.md

## Overview

A dense internal tool for operations staff who work in it for hours.
Quiet, information-first. Nothing here has to convince anyone of anything.

## Don'ts

- No gradients
- No drop shadows — elevation is a surface step plus a 1px border
- No font-weight above 600
- No colour value outside the tokens in globals.css
- No border-radius above 12px
- No decorative use of the state colours

## Colours

Defined as semantic roles in globals.css, light and dark.
Do not restate values here — read them from that file.

- `--primary` — primary buttons and active nav state ONLY.
  Never on text, borders, backgrounds or gradients.
- `--muted-foreground` — secondary and supporting text only.
- `--border` — structural edges and dividers.
- `--destructive` / `--success` / `--warning` — reserved for state.

## Typography

Family: Inter (variable). Weights 400 and 600 only.
Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48.
Tracking: -0.02em at 32px and above, 0 below, +0.02em on 12px caps.
Hierarchy comes from size and colour, never from weight above 600.

## Spacing & density

Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. No other values.
Controls: 8–12px padding. Table rows: 32px. Section gap: 32px.

## Elevation

A surface step plus a 1px `--border`. Never a box-shadow.

## Shapes

Controls 6px. Cards and panels 12px. Nothing above 12px.

## Composition

One primary action per section.
Related controls share a group; unrelated ones are separated by a full step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px `--primary` rule on the left edge.
Numeric columns are always tabular-nums and right-aligned.
Empty states are a single line of `--muted-foreground` text, never an illustration.

## Agent rules

Read this file before writing or editing any UI.
Match the nearest existing component in this repo rather than inventing a
new pattern. If no similar component exists, say so before writing one.

Duas coisas nesse arquivo valem a pena ser copiadas, mesmo que você mude todo o resto. As proibições vêm em segundo lugar, antes de qualquer coisa que possam modificar, para que o modelo, ao ler de cima para baixo, encontre as restrições antes das permissões. E a seção de cores aponta para o globals.css em vez de repetir os valores: assim que um hex existe em dois lugares, um será atualizado e o outro não, e o modelo usará a cópia obsoleta com total confiança.

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:

1. 1

   CLI: escreva o DESIGN.md + tokens no seu repo

   O caminho mais rápido. Escolha um slug de kit na galeria e aplique-o; você receberá um DESIGN.md commitado e um arquivo de tokens correspondente.

   Copy

   identityforge apply ambient-sage

2. 2

   MCP: deixe o agente buscá-lo

   Com o servidor MCP instalado, o agente chama get_design_md(slug) para ler o brief completo e apply_theme para escrevê-lo. Instale para a sua ferramenta:

   Copy

   npx --yes identityforge@latest install --client claude-code

3. 3

   shadcn: instale os tokens referenciados no DESIGN.md

   Se você quiser apenas os valores, o item do registro instala as variáveis CSS do kit diretamente.

   Copy

   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 estilos. Para saber como isso difere de adaptar manualmente uma entrada de catálogo de DESIGN.md, consulte Identity Forge vs getdesign.md.

Escrever o arquivo e assumir que ele foi assimilado é como as equipes descobrem o problema três semanas depois. Quatro verificações, da mais simples para a mais complexa.

1. 1

   Faça grep por valores literais de cores

   Se o agente estiver seguindo papéis semânticos, não deve haver nenhum hex fora do arquivo de tokens. Este é o sinal mais rápido possível.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Use grep para buscar os pesos que você proibiu

   O peso é onde a hierarquia silenciosamente retorna ao padrão, e é o primeiro sinal de que uma proibição não está sendo aplicada.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Peça a mesma tela duas vezes, em sessões separadas

   A consistência entre sessões é o teste real. Se duas execuções diferirem significativamente em espaçamento, raio ou hierarquia, o diff dirá exatamente qual seção do brief está faltando.

4. 4

   Construa primeiro uma tela em modo escuro

   Se o modo escuro foi derivado em vez de definido, é aqui que isso aparece: sombras mortas, cinzas médios turvos, um destaque gritante. É muito mais barato descobrir isso na tela um do que na tela vinte.

Os dois primeiros pertencem ao CI. Uma verificação que reprova um pull request contendo um valor hex bruto faz mais pela consistência a longo prazo do que qualquer quantidade de prosa, que é a mesma conclusão que a Salesforce alcançou com o linter do SLDS.