O que é o DESIGN.md e de onde ele veio?
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 testes de contexto de design portátil 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.
Por que um arquivo em vez de um prompt
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.
O formato não é complexo. Ele apenas reside em um lugar que é relido, o que acaba sendo a solução para todo o problema.
O que arquivos DESIGN.md reais realmente contêm?
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 reformula todo o resto.
Apenas 24% dos arquivos DESIGN.md públicos são sobre design
De 299 arquivos, apenas 72 possuíam uma seção de cores ou tipografia. O restante são documentos de arquitetura de software: como um sistema é construído, não como um produto se parece. DESIGN.md é uma colisão de nomes de arquivos, e o significado de design visual é atualmente a minoria. Se você adicionar um ao repositório, espere que alguns leitores cheguem esperando um documento de arquitetura.
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 pulando as mesmas quatro.
| Arquivos que o cobrem | |
|---|---|
| Tipografia | 83% |
| Cor | 67% |
| Componentes | 67% |
| Espaçamento | 57% |
| Motivos ou princípios | 43% |
| Elevação | 26% |
| Movimento | 25% |
| O que fazer e o que não fazer | 24% |
| Acessibilidade | 22% |
| Raio | 21% |
| Iconografia | 10% |
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.
O problema do modo escuro: 69% dos arquivos o ignoram
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.
Modo escuro não é uma inversão
Inverter a escala de luminosidade produz um tema escuro onde o destaque fica pálido e a elevação deixa de funcionar, pois as sombras mal são percebidas em fundos escuros. Em vez de aprofundar as sombras, eleve as superfícies; mantenha o fundo longe do preto puro, o primeiro plano longe do branco puro e aumente o croma do destaque em vez de diminuí-lo.
## 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 que analisamos usam OKLCH. Vale a pena a mudança especificamente porque seu canal de luminosidade é perceptualmente uniforme, permitindo que você altere um matiz sem precisar re-verificar cada par de contraste.
O que deve constar em um DESIGN.md, seção por seção?
Cores: papéis semânticos, ambos os modos
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 rebranding.
86% dos arquivos que analisamos 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.
Tipografia: famílias, escala e a função de cada uma
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*. Isso é 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.Espaçamento, raio, elevação
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.Motivos e proibições: a parte que a maioria dos arquivos ignora
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 a saída e um que apenas a 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.Tratamento de componentes e iconografia
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.
Quais são os erros mais comuns?
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 no lugar de 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.
O teste para cada linha
Leia uma linha e pergunte se duas pessoas competentes produziriam os mesmos pixels a partir dela. 'Clean and modern' falha. '96px entre seções no desktop' passa. Qualquer coisa que falhe ainda é uma decisão que você não tomou, e o agente a tomará por você: de forma diferente a cada vez.
- Adjetivos em vez de valores. O defeito mais comum, presente em mais da metade dos arquivos.
- Dark mode omitido. Em 69%, e a falha ocorre silenciosamente.
- 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.
- Sem proibições. Em 76%. Proibições são seguidas com mais rigor do que preferências.
- 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.
Onde o arquivo deve ficar e como os agentes o encontram?
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.
Como fica um arquivo completo quando renderizado?
Esta é a parte que todos os outros guias 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.
Terrain Vivant
Live renderRendered from the kit's actual tokens, fonts, and treatments
Typography
Space Mono
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Kit showcase · live surfaces
Terrain Vivant
Live renderTerrain Vivant rendered from its real tokens across 3 surfaces.
Você deve escrever um manualmente ou gerá-lo?
| Escrito à mão | Gerado a partir de um kit | |
|---|---|---|
| Ideal quando | Já existe uma marca para transcrever | Começando do zero |
| Falha comum | Adjetivos em vez de valores; dark mode omitido | Aceitar o primeiro resultado sem editar |
| Dark mode | Ausente em 69% dos arquivos reais | Derivado junto com o light mode |
| Motivos e proibições | Ignorados em 57% e 76% | Incluídos, vale a pena revisar |
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 que as pessoas pulam, e são elas que determinam se o arquivo realmente impõe restrições.
Obtenha um DESIGN.md completo com um único comando
Cada kit do Identity Forge é serializado em um DESIGN.md completo (design tokens light e dark, combinações de fontes reais, motivos e proibições) e instala os arquivos de tokens junto a ele. Kits gratuitos não exigem conta.
Quem criou o DESIGN.md?
O Google Labs, como o formato por trás de sua ferramenta de geração de UI, o Stitch. O Google tornou a especificação open source, que agora reside em github.com/google-labs-code/design.md. A adoção se espalhou muito além do Google. A Atlassian publicou seu próprio relato sobre o uso do formato.
O que significa o .md em DESIGN.md?
Apenas markdown. Não há sintaxe especial, nem schema, nem etapa de build. O arquivo é markdown puro, portanto, um agente o lê exatamente como lê qualquer outra coisa no repositório.
O DESIGN.md é um padrão oficial?
É uma especificação publicada e open source com uma origem clara, em vez de um padrão ratificado. Na prática, as ferramentas concordam com a estrutura — um arquivo markdown de valores visuais na raiz do repositório — e variam quanto às seções que leem.
Onde o arquivo deve ficar?
Na raiz do repositório, ao lado do AGENTS.md. Um DESIGN.md aninhado em docs/ é interpretado como documentação para humanos; agentes que buscam a convenção procuram na raiz.
Qual deve ser a extensão do arquivo?
A mediana dos arquivos públicos é de 1.337 palavras. O comprimento não é o ponto central: a completude sim. Um arquivo de 400 palavras com ambos os modos de cor, uma escala tipográfica e cinco proibições supera um arquivo de 2.000 palavras cheio de adjetivos.
Posso copiar o DESIGN.md de outra pessoa?
Você pode, mas terá a marca dela. É uma maneira razoável de estudar o formato e uma maneira ruim de chegar a uma identidade. Copie a estrutura, gere os valores a partir da sua própria marca.
Ele substitui um design system?
Ele é a projeção de um design system legível por agentes. Se você tem bibliotecas no Figma e uma biblioteca de componentes, o DESIGN.md é a forma como as decisões delas chegam a um agente de código, não um substituto para elas.
E se o meu agente ignorá-lo?
Verifique três coisas em ordem: se ele é referenciado no AGENTS.md, se está redigido como uma proibição em vez de uma preferência e se os valores são, de fato, valores. A maioria dos relatos de 'arquivo ignorado' revela-se um arquivo cheio de adjetivos.