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. O CLI publicado no npm está em 0.4.0 (2026-07-27).

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:

YAML front matter — Design tokens delimitados por ---. Valores normativos que máquinas consomem diretamente (colors, typography, rounded, spacing, components).
Corpo Markdown — Prosa organizada em seções ## que explica o racional e como aplicar os tokens.

Não use CSS custom properties (--color-primary) no corpo como fonte da verdade dos tokens. O linter e o export leem o YAML.

---
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
# Opcional desde 0.4.0 — silencia avisos de seções/categorias que você pula de propósito
# omitted:
#   - spacing
#   - name: elevation
#     reason: UI flat neste produto
---

## 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. Em 0.4.0, a chave omitted no front matter + a regra omitted-rules documentam omissões intencionais sem confundir com erro.

CLI oficial

O pacote @google/design.md (0.4.0+) inclui ferramentas para validar e converter. Use npx para pegar a versão publicada:

# 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 (formatos reais do 0.4.0)
npx @google/design.md export --format json-tailwind DESIGN.md
npx @google/design.md export --format css-tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md
npx @google/design.md export --format css-vars DESIGN.md
npx @google/design.md export --format css-vars --prefix ds DESIGN.md

# Ver o conjunto de regras ativo
npx @google/design.md spec --rules-only --format json

Exit codes: 0 ok (warnings/info permitidos), 1 erros de spec, 2 falha de input (arquivo ausente ou ilegível). Regras úteis do 0.4.0 incluem broken-ref, contrast-ratio, token-like-ignored e omitted-rules.

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.