DESIGN.md — o que é, como funciona, por que importa

DESIGN.md é um arquivo Markdown que combina design tokens legíveis por máquina (YAML front matter) com racional de design legível por humanos (prosa Markdown). Os tokens dão aos agentes valores exatos. A prosa explica por que esses valores existem e como aplicá-los.

Em março de 2026, o Google Stitch introduziu o formato como parte de uma atualização que incluiu canvas infinito, agente de design com memória de projeto e prototipagem instantânea. A especificação oficial é open-source e mantida pelo Google.

Por que isso importa

LLMs processam cada prompt de forma isolada. Sem um arquivo de referência no repositório, o agente não tem como saber que #2665fd é a cor primária do projeto ou que botões usam rounded-lg. O resultado: cada componente gerado segue decisões visuais diferentes.

DESIGN.md resolve isso colocando o design system inteiro no context window do agente. O agente lê antes de gerar qualquer UI.

Duas camadas em um arquivo

A especificação oficial define duas partes:

1. YAML front matter — Design tokens delimitados por ---. Valores normativos que máquinas consomem diretamente.
2. Corpo Markdown — Prosa organizada em seções ## que explica o racional e como aplicar os tokens.

---
name: Productivity App
colors:
  primary: "#2665fd"
  surface: "#0b1326"
  on-surface: "#dae2fd"
typography:
  headline:
    fontFamily: Geist
    fontSize: 2rem
    fontWeight: 600
  body:
    fontFamily: Geist
    fontSize: 1rem
    fontWeight: 400
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    rounded: "{rounded.md}"
    padding: 12px
---

## Overview
Interface minimal para app de produtividade.

## Colors
- **Primary** (#2665fd): CTAs, estados ativos
- **Surface** (#0b1326): Backgrounds

## Typography
- Headlines: Geist, semi-bold, 2rem
- Body: Geist, regular, 14-16px

## Layout
Grid de 12 colunas, max-width 1280px. Escala de 8px.

## Components
- Buttons: rounded-md, primary filled, hover brightness +10%

## Do's and Don'ts
- Do usar primary apenas para ações principais
- Don't misturar cantos arredondados e retos
- Do manter contraste mínimo 4.5:1 (WCAG AA)

8 seções canônicas

A spec define a ordem obrigatória para seções presentes:

#	Seção	Aliases
1	Overview	Brand & Style
2	Colors
3	Typography
4	Layout	Layout & Spacing
5	Elevation & Depth	Elevation
6	Shapes
7	Components
8	Do’s and Don’ts

Seções podem ser omitidas, mas as presentes devem seguir essa ordem. O linter section-order verifica isso.

CLI oficial

O pacote @google/design.md inclui ferramentas para validar e converter:

# Validar estrutura e contraste WCAG
npx @google/design.md lint DESIGN.md

# Comparar duas versões token a token
npx @google/design.md diff DESIGN.md DESIGN-v2.md

# Exportar para Tailwind ou W3C DTCG
npx @google/design.md export --format tailwind DESIGN.md

Próximos passos

Explore a biblioteca de DESIGN.md para encontrar um design system pronto para o seu projeto, leia a referência completa sobre o formato, ou consulte a especificação oficial no GitHub.