DESIGN.md em escala: quando os tokens não bastam (e o que adicionar)

Seu DESIGN.md está com 200 linhas, o agente gera interfaces on-brand, e você acha que resolveu o problema. Não resolveu. Você resolveu um terço do problema — e o terço mais fácil.

Tokens são a parte trivial. Cores, tipografia, espaçamento, border-radius: isso é uma tabela de lookup. O agente lê primary: #2563EB e aplica. Pronto. A dificuldade começa quando ele precisa decidir qual componente usar, como esse componente se comporta em estados diferentes, e o que jamais fazer com ele. Aí o DESIGN.md fica em silêncio — e o agente adivinha.

O diagnóstico: tokens resolvidos, comportamento no escuro

Vou ser direto sobre o que acontece quando seu DESIGN.md tem só tokens:

O agente recebe a paleta. Recebe as fontes. Recebe os espaçamentos. E aí precisa construir um card de pricing. Qual variante usar? Tem highlight no plano recomendado? O badge de “popular” fica dentro ou fora do card? O CTA é filled ou outline? O preço antigo fica riscado com qual estilo?

Nenhuma dessas perguntas tem resposta nos tokens. O agente vai inferir — às vezes acerta, geralmente produz algo genérico.

A equipe do Meticulous.com colocou isso de forma precisa:

“DESIGN.md spec is the right portable interchange for AI coding agents. It is not the right canonical source for tokens.”

Traduzindo: DESIGN.md é o formato certo de comunicação entre humano e agente, mas se você trata ele apenas como um dump de design tokens, está subutilizando brutalmente a ferramenta.

E o pessoal do designproject.io complementa:

“The agent has the palette and fonts, so it produces something that is on brand, but it still guesses at which component to use.”

Isso. O resultado é on brand mas não é on system. É a diferença entre “tem as cores certas” e “usa os componentes certos da forma certa”.

O problema escala exponencialmente

Com um landing page simples, tokens bastam. O agente tem margem de erro pequena — são poucos componentes, pouca interação.

Agora pensa num dashboard SaaS com 40 telas. Ou num design system servindo 5 produtos diferentes. O agente precisa escolher entre:

Button primary vs secondary vs ghost vs destructive
Card default vs elevated vs outlined vs interactive
Modal vs Drawer vs Dialog vs Sheet
Table com sorting vs sem, com seleção vs sem, paginada vs infinite scroll

Sem documentação explícita, cada escolha vira uma moeda jogada pro alto. Multiply isso por 200 componentes e 40 telas. A “dívida de adivinhação” explode.

Extensão 1: Seção Components no DESIGN.md

A primeira extensão é óbvia mas ninguém faz: listar seus componentes com contexto de uso.

Não estou falando de documentar a API inteira de cada componente — isso é trabalho do Storybook. Estou falando de dar ao agente informação suficiente para escolher corretamente.

## Components

### Button
- **Variants:** primary, secondary, ghost, destructive, link
- **Use primary for:** main CTA per page (only ONE per visible viewport)
- **Use ghost for:** secondary actions, toolbar items, cancel actions
- **Use destructive for:** irreversible actions (always with confirmation dialog)
- **Never:** two primary buttons side by side. Never a destructive button without text label.

### Card
- **Variants:** default, elevated, interactive, outlined
- **Use elevated for:** content that needs visual hierarchy boost (pricing highlight, featured item)
- **Use interactive for:** cards that navigate somewhere on click (cursor: pointer, hover state)
- **Use outlined for:** content grids where cards are dense and elevation would be noisy
- **Never:** elevated card inside another elevated card. Never interactive card without hover state.

Isso resolve 80% das adivinhações. O agente não precisa saber toda a API — precisa saber quando usar o quê e o que nunca fazer.

Extensão 2: Behavior Annotations

Tokens descrevem aparência. Componentes descrevem estrutura. Mas e o comportamento?

Quando um formulário tem erro, o que acontece? O campo fica vermelho? Aparece mensagem inline? O botão de submit desabilita? O focus vai pro primeiro campo com erro?

Behavior annotations são micro-specs de interação:

## Behaviors

### Form Validation
- Validate on blur (not on keystroke)
- Show error message below field, not as tooltip
- Error border: use `destructive` color on field border
- On submit with errors: scroll to first error, focus that field
- Submit button: never disable. Show loading state instead.

### Loading States
- Buttons: show spinner inside, maintain button width
- Pages: skeleton loader matching content layout (not generic spinner)
- Tables: skeleton rows (5 rows placeholder)
- Cards: pulse animation on full card shape

### Empty States
- Always include: illustration + title + description + CTA
- Never show blank area or just "No data"
- CTA should be the primary action to create first item

Isso elimina toda uma categoria de “funciona mas funciona errado”. O agente sabe que não vai colocar um spinner genérico no meio da tela — vai usar skeleton matching o layout.

Extensão 3: Do/Don’t com exemplos visuais

A seção mais poderosa e mais negligenciada. Humanos aprendem com exemplos — agentes também.

## Do / Don't

### Spacing
- ✅ DO: Use consistent 8px grid for all spacing
- ✅ DO: 24px padding inside cards, 16px gap between cards
- ❌ DON'T: Mix 5px and 8px spacing in the same component
- ❌ DON'T: Padding smaller than 16px inside any container

### Typography
- ✅ DO: Page title in h1 (one per page), section titles in h2
- ✅ DO: Body text at 16px minimum for readability
- ❌ DON'T: More than 3 font sizes visible simultaneously
- ❌ DON'T: Center-align body text longer than 2 lines

### Color
- ✅ DO: Primary color only for CTAs and key interactive elements
- ✅ DO: Neutral backgrounds for content areas, color for accents
- ❌ DON'T: Primary color as background for large areas
- ❌ DON'T: More than 2 accent colors in one viewport

Cada “DON’T” é um erro que o agente teria cometido sem essa instrução. Pense neles como guardrails — não limitam a criatividade, limitam a besteira.

A estrutura completa que funciona

Depois de experimentar com dezenas de projetos, chegamos nessa estrutura para DESIGN.md em escala:

# DESIGN.md

## Tokens
(cores, tipografia, espaçamento, border-radius, shadows — o que você já tem)

## Components
(lista de componentes com variantes, quando usar cada um, anti-patterns)

## Behaviors
(estados de interação, loading, error, empty states, animações)

## Patterns
(layouts recorrentes: form layout, dashboard grid, card grid, hero sections)

## Do / Don't
(exemplos explícitos do que é certo e errado)

## Decisions
(decisões de design já tomadas que o agente deve respeitar: "modais nunca ultrapassam 640px de largura", "nunca usamos carousel")

Essa estrutura mantém o DESIGN.md como documento único — sem fragmentar em múltiplos arquivos que o agente pode não carregar. E cada seção tem uma função clara.

Quanto é demais?

Pergunta legítima. Se DESIGN.md virar um documento de 2000 linhas, não estoura o contexto do agente?

Resposta prática: um DESIGN.md com todas essas seções para um SaaS de porte médio (30-50 componentes) fica entre 400-600 linhas. Isso consome ~2000-3000 tokens de contexto. Num agente com 128K-200K de contexto, é irrelevante.

Se seu design system é gigante (100+ componentes), aí sim vale considerar uma estratégia de carregamento seletivo — mas esse é problema para outro artigo.

A regra de ouro: se o agente está adivinhando e errando, a documentação precisa crescer. Se o agente acerta consistentemente, o tamanho atual está bom.

O test simples: seu DESIGN.md está completo?

Faça esse exercício:

Pegue uma tela do seu produto que ainda não existe
Dê ao agente só o DESIGN.md e uma descrição da tela
Veja o resultado
Liste tudo que ele adivinhou errado
Cada erro é uma seção faltando no DESIGN.md

Se ele usou o componente errado → falta seção Components. Se ele errou o comportamento de loading → falta seção Behaviors. Se ele colocou duas cores primárias competindo → falta seção Do/Don’t.

Esse loop de feedback é como o DESIGN.md evolui. Não tente documentar tudo de uma vez — documente o que o agente erra.

Na prática: antes e depois

Antes (tokens only):

Pedido ao agente: “Crie uma tela de settings com seções Account, Notifications, Billing”

Resultado: três seções empilhadas, cada uma com estilo diferente, botões inconsistentes, sem separação visual clara, formulários com validação inline e tooltip misturados.

Depois (tokens + components + behaviors + do/dont):

Mesmo pedido, mesmo agente.

Resultado: layout sidebar+content, cada seção num card outlined, formulários com validação on blur e mensagem inline, botão primary só no save principal, secondary nos saves por seção, skeleton loaders nos dados de billing.

A diferença não é sutil. É a diferença entre “refazer do zero” e “pequenos ajustes”.

O DESIGN.md não substitui o design system — ele traduz

Uma confusão comum: “se eu tenho Storybook, pra que DESIGN.md?”

Storybook é documentação de componente para humanos. Mostra props, variantes, playground interativo. Mas agentes não navegam Storybook — eles leem texto.

DESIGN.md é a tradução do seu design system pro formato que agentes consomem. Não é duplicação — é um formato de comunicação diferente para um consumidor diferente.

Pense assim: você tem docs técnicos para devs e release notes para usuários. Mesmo produto, formatos diferentes, audiências diferentes. DESIGN.md é o “formato agente” do seu design system.

Conclusão: tokens são ontem, componentes são hoje

Se seu DESIGN.md ainda é uma lista de cores e fonts, você está preso em 2024. Os agentes de 2025 já sabem aplicar tokens — eles precisam de orientação em camadas mais altas de abstração.

Adicione componentes. Adicione comportamentos. Adicione do/dont. Seu DESIGN.md vai de “paleta de cores” para “guia de design completo” — e o output dos agentes vai de “esteticamente correto” para “funcionalmente correto”.

Quer gerar um DESIGN.md completo com tokens, componentes e behavior annotations? O designmd.app gera sua spec em minutos a partir do seu site existente — incluindo as extensões de componentes e comportamentos que discutimos aqui. Experimente gratuitamente.