O que é DESIGN.md

Em março de 2026, o Google Stitch introduziu DESIGN.md como parte de uma atualização que incluiu canvas infinito, agente de design com memória de projeto, prototipagem instantânea e interação por voz. Entre todas essas funcionalidades, DESIGN.md é o componente menos visível — mas o mais reutilizável fora do ecossistema Stitch.

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. A especificação oficial é open-source e mantida pelo Google.

A analogia mais precisa: DESIGN.md está para design assim como AGENTS.md está para convenções de código. É contexto persistente que o agente consulta a cada interação.

Formato

Duas camadas em um arquivo

Segundo a especificação oficial, um DESIGN.md tem duas partes: YAML front matter com design tokens e corpo Markdown com prosa de racional. Os tokens são os valores normativos. A prosa fornece contexto de como aplicá-los. 

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

Um agente que lê esse arquivo produz uma UI com headlines em Public Sans cor de tinta, fundo limestone quente e botões CTA em Boston Clay.

Tokens

Schema de design tokens

Os design tokens são embutidos como YAML front matter. O sistema é inspirado na spec W3C Design Tokens, adotando grupos tipados e a sintaxe {path.to.token} para referências cruzadas. 

version: <string>          # opcional, atual: "alpha"
name: <string>
description: <string>      # opcional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Tipos de token

Tipo Formato Exemplo
Color # + hex (sRGB) "#1A1C1E"
Dimension número + unidade (px, em, rem) 48px, -0.02em
Token Reference {path.to.token} {colors.primary}
Typography objeto com fontFamily, fontSize, fontWeight, lineHeight, letterSpacing ver exemplo acima

Estrutura

8 seções da especificação oficial

Seções usam headings ##. Podem ser omitidas, mas as presentes devem seguir esta ordem. O LLM processa de cima para baixo.

1. Overview (alias: Brand & Style)

Descrição holística do look and feel do produto. Define personalidade da marca, público-alvo e resposta emocional que a UI deve evocar. Contexto fundacional para decisões estilísticas do agente. 

## Overview
Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish — a high-end broadsheet
or contemporary gallery.

2. Colors

Define paletas de cores com papel semântico. Convenção de nomes: primary, secondary, tertiary, neutral. Hex + nome descritivo + regra de uso. Sem nome semântico, o LLM pode usar a cor de erro como accent. 

## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions.
- **Tertiary (#B8422E):** "Boston Clay" — sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

3. Typography

Define níveis tipográficos (9-15 é o comum). Tokens incluem fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature e fontVariation. O agente precisa de números — "fonte grande" não é instrução útil. 

## Typography
- **Headlines:** Public Sans Semi-Bold — institutional, trustworthy.
- **Body:** Public Sans Regular at 16px — long-form readability.
- **Labels:** Space Grotesk — geometric precision. Uppercase, generous spacing.

4. Layout (alias: Layout & Spacing)

Descreve estratégia de layout e espaçamento. Grid-based, margins, safe areas. Tokens de spacing definem a escala (xs, sm, md, lg, xl). 

## Layout
Fluid Grid model for mobile, Fixed-Max-Width Grid for desktop (max 1200px).
Strict 8px spacing scale with 4px half-step for micro-adjustments.

5. Elevation & Depth (alias: Elevation)

Como hierarquia visual é transmitida. Se usa elevação, define spread, blur e cor das sombras. Para designs flat, explica métodos alternativos (bordas, contraste de cor). 

## Elevation & Depth
Depth through Tonal Layers rather than heavy shadows.
Background uses soft off-white, primary content on pure white cards.

6. Shapes

Linguagem de formas do design system. Define border-radius para botões, cards e outros elementos retangulares. Tokens de rounded (sm, md, lg, full). 

## Shapes
Architectural Sharpness. All interactive elements use minimal 4px corner radius.
Just enough softness to feel modern while maintaining a rigid aesthetic.

7. Components

Tokens de componentes mapeiam nome para grupo de sub-propriedades. Propriedades válidas: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variantes (hover, active, pressed) são entradas separadas com nome relacionado. 

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

8. Do's and Don'ts

Restrições explícitas e guardrails. LLMs respondem bem a instruções negativas — dizer o que não fazer é tão importante quanto dizer o que fazer. 

## Do's and Don'ts
- Do use primary only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

Ferramentas

CLI oficial

O pacote @google/design.md inclui quatro comandos para validar, comparar, exportar e inspecionar arquivos DESIGN.md.

lint — Validar estrutura

Verifica referências quebradas, contraste WCAG AA, tokens órfãos, ordem de seções e tipografia ausente. 

npx @google/design.md lint DESIGN.md

diff — Comparar versões

Detecta mudanças token a token entre duas versões. Exit code 1 se houver regressões. 

npx @google/design.md diff DESIGN.md DESIGN-v2.md

export — Converter tokens

Exporta tokens para Tailwind theme config ou DTCG tokens.json (W3C Design Tokens Format). 

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

spec — Injetar spec no prompt

Imprime a especificação completa do formato. Útil para injetar contexto da spec em prompts de agentes. 

npx @google/design.md spec
npx @google/design.md spec --rules --format json

Validação

Regras de linting

O linter executa 8 regras contra um DESIGN.md parseado. Cada regra produz findings com severidade fixa.

Regra Severidade O que verifica
broken-ref error Token references que não resolvem para nenhum token definido
missing-primary warning Cores definidas mas sem cor primary
contrast-ratio warning Pares backgroundColor/textColor abaixo do mínimo WCAG AA (4.5:1)
orphaned-tokens warning Tokens de cor definidos mas nunca referenciados por componentes
missing-typography warning Cores definidas mas sem tokens de tipografia
section-order warning Seções fora da ordem canônica da spec
token-summary info Resumo de quantos tokens estão definidos em cada seção
missing-sections info Seções opcionais (spacing, rounded) ausentes quando outros tokens existem

Formato

Por que Markdown + YAML e não só JSON

Markdown é o formato que LLMs entendem com maior fidelidade. A maior parte do corpus de treinamento usa essa estrutura. O modelo não precisa de instrução extra para interpretar.

Design tokens em JSON definem valores, mas não regras. Não há como expressar "use primary apenas para a ação principal" em um arquivo tokens.json. DESIGN.md combina tokens YAML (valores exatos para máquinas) e prosa Markdown (semântica para agentes) no mesmo arquivo, sem build pipeline. O comando export converte para Tailwind ou DTCG quando necessário.

Critério DESIGN.md Tokens (JSON) Style Guide
Legível por LLM Nativo (treinado em MD) Requer parsing Não legível
Tokens legíveis por máquina Sim (YAML front matter) Sim (JSON) Não
Legível por humano Sim, sem tooling Parcial Sim
Versionável (Git) Sim Sim Não (binário)
Context window Leve (~2-5K tokens) Médio N/A
Build pipeline Nenhum (export disponível) Necessário N/A
Regras semânticas Sim (Do's/Don'ts) Não (só valores) Sim
Referências entre tokens Sim ({path.to.token}) Sim ($ref) N/A
CLI/linter oficial Sim (@google/design.md) Varia N/A

Markdown não substitui design tokens em projetos que já usam build pipeline. Os dois podem coexistir — use export para converter.

Obtenção

Como obter um DESIGN.md

Quatro caminhos, do mais rápido ao mais controlado.

1. Copiar da biblioteca designmd.app

Escolha por vertical ou estilo visual, customize os valores para o seu projeto e use. A biblioteca tem mais de 400 arquivos documentados.

2. Gerar com a skill design-md

A skill analisa o codebase existente — componentes, variáveis CSS, tokens — e extrai um DESIGN.md estruturado a partir dos padrões encontrados.

3. Exportar do Google Stitch

Se o projeto já usa Stitch, o export é nativo. O arquivo gerado segue a mesma estrutura documentada aqui.

4. Escrever manualmente

Siga a estrutura das 8 seções acima. Valide com npx @google/design.md lint. Controle total sobre cada decisão de design.

Setup

Configuração por agente

Cada agente de IA tem seu próprio arquivo de configuração. O DESIGN.md fica na raiz do projeto — a configuração apenas diz ao agente para lê-lo.

Agente Config Referência
Claude Code CLAUDE.md Siga regras visuais de @DESIGN.md
Cursor .cursor/rules/*.mdc Include do DESIGN.md
Kiro .kiro/steering/ Copiar DESIGN.md para steering
Windsurf .windsurfrules Referenciar DESIGN.md
Google Stitch UI nativa Import direto

Claude Code

Adicione a referência no arquivo CLAUDE.md na raiz do projeto: 

# CLAUDE.md
Siga as regras visuais definidas em @DESIGN.md para toda geração de UI.
Não use cores, fontes ou espaçamentos que não estejam definidos no DESIGN.md.

Cursor

Crie uma regra em .cursor/rules/: 

# .cursor/rules/design.mdc
Leia DESIGN.md na raiz do projeto antes de gerar qualquer componente visual.

Kiro

Copie o DESIGN.md para .kiro/steering/DESIGN.md. O Kiro inclui automaticamente arquivos de steering no contexto.

Windsurf

Adicione a referência no .windsurfrules: 

# .windsurfrules
Referencie DESIGN.md para todas as decisões visuais.

Google Stitch

Import via UI: Settings → Design System → Import DESIGN.md. O Stitch criou o formato — o suporte é nativo.

Guias detalhados por agente →

FAQ

Perguntas frequentes

O que é DESIGN.md?

Um arquivo Markdown com front matter YAML que serializa um design system para consumo por agentes de IA. Combina design tokens legíveis por máquina (cores, tipografia, espaçamento, componentes) com prosa que explica o racional por trás de cada decisão. Formato open-source mantido pelo Google (google-labs-code/design.md).

DESIGN.md substitui o Figma?

Não. Figma é ferramenta de design visual para criar interfaces. DESIGN.md é a tradução dessas decisões de design para um formato que agentes de IA leem e aplicam automaticamente. São complementares.

Preciso saber design para usar DESIGN.md?

Não para usar um pronto. A biblioteca designmd.app tem mais de 400 arquivos prontos para copiar. A skill design-md gera um a partir do seu codebase existente.

Funciona com qualquer agente de IA?

Sim. Qualquer agente que leia arquivos do repositório pode usar DESIGN.md: Claude Code, Cursor, Kiro, Windsurf, Google Stitch e outros.

Qual a diferença entre DESIGN.md e design tokens em JSON?

Design tokens em JSON definem apenas valores (cores, espaçamentos). DESIGN.md define tokens YAML + prosa com regras semânticas + restrições (Do's and Don'ts). Tokens precisam de build pipeline. DESIGN.md é Markdown puro. O comando export converte tokens DESIGN.md para Tailwind ou DTCG (W3C).

Posso usar em projeto existente?

Sim. Adicione o arquivo DESIGN.md na raiz do projeto e referencie no arquivo de configuração do seu agente. Não altera código existente.

Como validar meu DESIGN.md?

Use o CLI oficial: npx @google/design.md lint DESIGN.md. Ele verifica referências quebradas, contraste WCAG AA, tokens órfãos, ordem de seções e tipografia ausente.

Como atualizar quando o design muda?

Edite o arquivo. É Markdown — qualquer editor de texto serve. Use npx @google/design.md diff antes.md depois.md para comparar mudanças token a token. Versione com Git para manter histórico.

Funciona com React, Vue, Svelte?

DESIGN.md é agnóstico de framework. Define regras visuais, não implementação. O agente aplica essas regras independente do framework. Use export --format tailwind para gerar tema Tailwind automaticamente.

O que são Token References?

Referências cruzadas entre tokens usando a sintaxe {path.to.token}. Exemplo: um componente pode referenciar {colors.primary} em vez de repetir o valor hex. Inspirado na spec W3C Design Tokens.

Próximos passos

Explore a biblioteca com mais de 400 DESIGN.md documentados ou gere um a partir do seu codebase existente.

Ver biblioteca Skill design-md → Spec oficial (GitHub) →