O DESIGN.md começou no Google Labs como o formato por trás do Stitch, sua ferramenta de geração de UI. O Google abriu a especificação e a spec agora reside no GitHub. Ela se espalhou rapidamente além do Google: a Atlassian publicou um relato sobre a testagem de contextos de design portáteis na prática, e um ecossistema de catálogos cresceu ao seu redor.

O .md é simplesmente markdown. O arquivo não possui sintaxe especial, nenhum schema para validação e nenhuma etapa de build. Isso é deliberado: um agente o lê da mesma forma que lê qualquer outro arquivo no seu repositório.

Um agente de código encarregado de construir a UI precisa obter seus valores visuais de algum lugar. Na ausência de uma fonte, ele usa os padrões da biblioteca — e é por isso que produtos criados por IA convergem para a mesma aparência. Você pode fornecer valores em um prompt, mas prompts vivem em uma conversa, e conversas se degradam à medida que crescem.

Um arquivo não se degrada. Esse é todo o mecanismo, e tudo mais sobre o formato deriva disso.

Em vez de presumir, nós amostramos. Extraímos 299 arquivos DESIGN.md da raiz de repositórios via busca de código do GitHub e medimos o que havia em cada um. O primeiro resultado foi surpreendente e ressignifica todo o resto.

Dentro desses 72 arquivos genuínos de design visual, o cenário é consistente. O arquivo mediano tem 1.337 palavras em 263 linhas, portanto não são apenas esboços — as pessoas estão dedicando esforço real. Elas estão focando nas mesmas três seções e ignorando as mesmas quatro.

Cores e tipografia são quase universais. Raio, elevação, iconografia e acessibilidade são raros. E há uma omissão maior do que todas essas, pois ela é invisível até que alguém mude uma chave.

Dos 72 arquivos de design visual que analisamos, 50 não contêm modo escuro — sem bloco .dark, sem prefers-color-scheme, sem um segundo conjunto de valores. Isso representa 69%.

Esta é a lacuna mais consequente no formato como ele é praticado, e ela falha silenciosamente. Tudo parece correto no modo claro. Então, o usuário alterna o tema e o agente precisa inventar cada valor escuro na hora: um fundo que nunca foi escolhido, um primeiro plano que nunca teve o contraste verificado, um destaque que desaparece porque ninguém aumentou seu croma para um fundo escuro.

## Color

### Light
--background: oklch(0.98 0.006 85)
--foreground: oklch(0.22 0.014 85)
--card:       oklch(1 0 0)
--muted-foreground: oklch(0.48 0.012 85)
--primary:    oklch(0.52 0.13 152)
--border:     oklch(0.90 0.008 85)

### Dark
--background: oklch(0.17 0.010 85)   /* not pure black */
--foreground: oklch(0.95 0.006 85)   /* not pure white */
--card:       oklch(0.22 0.010 85)   /* raised, not shadowed */
--muted-foreground: oklch(0.70 0.010 85)
--primary:    oklch(0.68 0.16 152)   /* higher chroma to survive the dark ground */
--border:     oklch(0.30 0.010 85)

Apenas 6% dos arquivos analisados usam OKLCH. Vale a pena a mudança especificamente porque seu canal de luminosidade é perceptualmente uniforme, permitindo alterar um matiz sem precisar re-verificar cada par de contraste.

A decisão mais consequente no arquivo é nomear por *papel* (role) em vez de matiz. --primary diz ao agente onde o valor deve ser aplicado; --blue-600 não. Os papéis permitem que ele aplique seu sistema corretamente em situações que você nunca previu e sobrevivem a um rebrand.

86% dos arquivos analisados não usam nomes de papéis semânticos. Eles listam hexadecimais ou nomeiam cores por matiz. Essa é a diferença entre um arquivo que o agente consegue aplicar a um componente que você nunca descreveu e um arquivo do qual ele consegue apenas copiar. A camada de tokens semânticos é quem faz o trabalho real aqui.

Nomeie as famílias, os pesos, o tracking e os degraus da escala. A falha comum é escrever *uma serifada para títulos, uma sans para o corpo* — uma instrução que o agente precisa resolver, e ele a resolverá de forma diferente a cada vez.

## Typography

Heading: "Fraunces", serif — 600, tracking -0.02em
Body:    "Inter", sans-serif — 400, line-height 1.6
Mono:    "JetBrains Mono" — 400, tabular figures in tables

Scale: 0.8125 / 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem
H1 uses 3rem at 1.05 line-height; body copy never exceeds 68ch.

Uma escala de espaçamento, raio que varia conforme o tamanho do elemento e dois ou três níveis de elevação que concordem com uma fonte de luz. O raio é coberto por apenas 21% dos arquivos e a elevação por 26%, razão pela qual tantas UIs geradas apresentam um canto de 0.5rem em cada elemento, independentemente do tamanho.

## Spacing
Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96px
Section rhythm: 96px desktop, 64px mobile.

## Radius
sm 0.25rem (inputs) · md 0.5rem (buttons) · lg 0.875rem (cards) · xl 1.25rem (modals)

## Elevation
0 flush — use a border, no shadow
1 cards — 0 1px 2px rgb(0 0 0 / 0.06)
2 dropdowns — 0 4px 12px rgb(0 0 0 / 0.08)
Dark mode: raise the surface, do not deepen the shadow.

Tokens dizem ao agente quais valores usar. Eles não dizem nada sobre o que fazer ao encontrar um componente que seu arquivo nunca mencionou. Motivos e proibições preenchem essa lacuna, e são a diferença entre um arquivo que restringe o resultado e um que apenas o colore.

76% dos arquivos não declaram proibições e 57% não declaram motivos. Estas são as duas seções mais simples de escrever e as duas mais ausentes.

## Motifs
- Hairline rules separate sections; no boxed cards on marketing pages.
- Numerals are tabular everywhere they can be compared.
- One accent per screen. If two things compete, one becomes muted.

## Don't
- No gradient text, ever.
- No shadow on a flush surface — use --border.
- Never hardcode a hex. If a role is missing, add the role.

Cubra as primitivas que carregam mais identidade: botões, inputs e cards, com seus estados. Você não precisa de todos os componentes. A iconografia é a seção mais simples do arquivo e a mais rara na prática, com 10% — nomeie a biblioteca de ícones, a espessura do traço, os degraus de tamanho e inclua uma linha sobre o tratamento de imagens.

Além das seções ausentes, um modo de falha aparece em mais da metade do corpus: escrever um adjetivo onde deveria estar um valor.

54% dos arquivos que analisamos contêm pelo menos um adjetivo vago substituindo uma decisão. Os mais comuns foram *clean* (39% dos arquivos), *modern* (36%) e *professional* (22%), seguidos por *generous whitespace*, *elegant* e *beautiful*. Além disso, 44% não contêm nenhum valor concreto de espaçamento ou tamanho em lugar nenhum do arquivo.

1. Adjetivos em vez de valores. O defeito mais comum, presente em mais da metade dos arquivos.
2. Dark mode omitido. Em 69%, e a falha ocorre silenciosamente.
3. Cores nomeadas por matiz em vez de função. Em 86%, e isso quebra no momento em que o agente encontra um componente que você não descreveu.
4. Sem proibições. Em 76%. Proibições são seguidas com mais rigor do que preferências.
5. Uma seção que diz 'use seu julgamento'. Pior do que a ausência de uma seção, pois devolve exatamente a discricionariedade que o restante do arquivo tentava retirar.

Coloque-o na raiz do repositório, ao lado do AGENTS.md. A raiz é fundamental: um DESIGN.md aninhado em docs/ é um documento para humanos, e os agentes que buscam a convenção olham para a raiz.

Depois, referencie-o nas instruções do seu agente em uma única linha, para que ele seja descoberto em vez de encontrado por acaso. Ele é um complemento desses arquivos, não um concorrente — os quatro arquivos desempenham funções diferentes.

# AGENTS.md

## Design
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

AGENTS.md é a convenção mais ampla para instruções de agentes e é lido por um conjunto crescente de ferramentas. O DESIGN.md detém o contrato visual; o AGENTS.md aponta para ele.

Esta é a parte que todos os outros tutoriais omitem. Um DESIGN.md é tão bom quanto a interface que ele produz, e as seções acima não são uma ilustração — elas são a forma serializada do kit abaixo.

Se você escrever à mão, as duas seções que deve se forçar a preencher são o dark mode e as proibições. O corpus é inequívoco ao mostrar que essas são as partes que as pessoas pulam, e são elas que determinam se o arquivo realmente impõe restrições.