Documentação

O que é DESIGN.md?

DESIGN.md é um arquivo de texto simples que descreve um sistema de design para agentes de IA. O front matter em YAML, no topo, guarda os tokens de design exatos: cores, tipografia, espaçamento, cantos arredondados e componentes. O corpo em Markdown, logo abaixo, explica como e por que aplicá-los. Pessoas e agentes conseguem ler, editar e fazer cumprir o arquivo.

O README.md explica o que é um projeto. O AGENTS.md diz aos agentes de código como construí-lo. O DESIGN.md diz qual deve ser a aparência e a sensação dele, para que as telas geradas por um agente compartilhem uma única paleta, escala tipográfica e linguagem de componentes, em vez de cada uma ir para um lado.

De onde vem o DESIGN.md

O Google lançou o DESIGN.md com o Google Stitch, sua ferramenta de design com IA, como o equivalente de design do AGENTS.md. O Google Labs publica o formato como uma especificação aberta no repositório google-labs-code/design.md, sob a licença Apache 2.0. A especificação do DESIGN.md está marcada como alpha, então espere mudanças no formato à medida que ele amadurece.

O mesmo repositório traz um pacote npm, @google/design.md, com um comando lint que verifica a estrutura, referências de tokens quebradas e o contraste WCAG, e um comando diff que compara duas versões de um arquivo token por token.

Anatomia de um arquivo DESIGN.md

Todo arquivo DESIGN.md tem duas camadas. O front matter em YAML contém tokens de design legíveis por máquina, como valores exatos de cores, propriedades de fontes, escalas de espaçamento e referências a tokens de componentes. O corpo em Markdown traz a lógica do design em texto legível por pessoas.

A especificação trata os tokens como os valores normativos e o texto como contexto para aplicá-los. Os tokens dão aos agentes valores precisos. O texto explica por que esses valores existem e como usá-los de forma consistente em todas as telas.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

As oito seções canônicas

O corpo em Markdown usa títulos ##. Seções que não fazem sentido podem ser omitidas, mas as que existirem devem seguir esta ordem. Um título que aparece duas vezes torna o arquivo inválido; seções desconhecidas são mantidas.

Overview (ou Brand & Style). A aparência e a sensação em poucas frases: clima, densidade, personalidade.
Colors. Cada token de cor e o papel que ele cumpre, como ações principais ou superfícies da página.
Typography. As famílias tipográficas e a escala tipográfica, dos títulos de destaque aos rótulos pequenos.
Layout (ou Layout & Spacing). A escala de espaçamento, o grid, as larguras de conteúdo e as margens.
Elevation & Depth (ou Elevation). Como as superfícies se separam: sombras, bordas, tons.
Shapes. Raios dos cantos e outras regras de forma.
Components. Botões, campos, cards e outros átomos, com seus tokens e estados.
Do's and Don'ts. As regras que um agente não deve quebrar.

Um corpo em Markdown compacto com cada seção canônica na ordem. Adapte o conteúdo ao seu produto e mantenha os títulos e a sequência.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Tokens de design e esquema

O DESIGN.md inclui os tokens de design como front matter em YAML no início do arquivo. O bloco de front matter começa com uma linha que contém exatamente --- e termina com o mesmo delimitador.

version: <string>
name: <string>
description: <string>
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>

Nomes de escala comuns incluem xs, sm, md, lg, xl e full, mas qualquer chave descritiva é válida. Os tokens de espaçamento ficam no YAML em spacing: e são descritos na seção Layout do corpo em Markdown.

Tipos de token

Cor: Qualquer string de cor CSS válida. Hex no formato #RRGGBB é o padrão recomendado, por exemplo "#1A1C1E".
Dimensão: Número com uma unidade px, em ou rem. Exemplos:48px,-0.02em.
Referência a token: Fica entre chaves e aponta para um valor na árvore YAML. Exemplo:{colors.primary}.
Tipografia: Um objeto composto com propriedades de fonte, como família, tamanho, peso, altura de linha e espaçamento entre letras. Veja Propriedades de tipografia.

Propriedades de tipografia

fontFamily: O nome da família tipográfica.
fontSize: O tamanho da fonte, como dimensão.
fontWeight: Peso numérico, como 400 ou 700.
lineHeight: Uma dimensão ou um multiplicador sem unidade. Valores sem unidade são recomendados.
letterSpacing: Ajuste do espaçamento entre letras, como dimensão.
fontFeature: Configura font-feature-settings.
fontVariation: Configura font-variation-settings.

Referências a tokens

Uma referência a token fica entre chaves e contém o caminho de um objeto até outro valor na árvore YAML. Na maioria dos grupos de tokens, a referência deve apontar para um valor primitivo, não para um grupo. Dentro da seção de componentes, são permitidas referências a valores compostos, como níveis tipográficos.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Componentes

A seção de componentes reúne orientações de estilo para átomos de componentes, como botões, chips, listas, campos, checkboxes, radio buttons e tooltips. Sistemas de design podem definir outros componentes importantes para o domínio do produto.

Variantes para os estados hover, active ou pressed são definidas como entradas de componente separadas, com nomes de chave relacionados, como button-primary-hover.

backgroundColor: Cor
textColor: Cor
typography: Tipografia
rounded: Dimensão
padding: Dimensão
size: Dimensão
height: Dimensão
width: Dimensão

Nomes de token recomendados

Estes nomes são sugestões, não exigências. Eles oferecem padrões úteis para manter a consistência entre sistemas.

Cores: primary, secondary, tertiary, neutral, surface, on-surface, error

Tipografia: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Arredondamento: none, sm, md, lg, xl, full

Como os agentes de IA usam o DESIGN.md

Coloque o DESIGN.md na raiz do seu repositório, ao lado do README.md e do AGENTS.md. Qualquer agente com acesso aos arquivos consegue lê-lo, mas a maioria não o carrega sozinha. Aponte para ele nas instruções que o seu agente já lê, ou cite o arquivo no prompt quando pedir trabalho de UI. Uma indicação curta basta:

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code: Lê os arquivos do seu repositório e carrega o CLAUDE.md ao iniciar. Adicione ali uma linha que aponte para o DESIGN.md, ou cite o arquivo no seu prompt.
Cursor: Adicione o DESIGN.md ao contexto do chat, ou faça referência a ele em uma regra do projeto para que valha em todo pedido de UI.
GitHub Copilot: Aponte para o DESIGN.md no arquivo de instruções do Copilot do seu repositório, ou anexe o arquivo no chat quando pedir trabalho de UI.
Google Stitch: Onde o formato começou. O Stitch usa um DESIGN.md para que as telas geradas compartilhem uma única paleta, escala tipográfica e linguagem de componentes.

O agente então pega os valores exatos dos tokens (o hex de um botão principal, o tamanho de um rótulo body-md) e usa o texto para decidir onde eles se encaixam.

DESIGN.md vs AGENTS.md vs README.md

Os três arquivos ficam lado a lado e respondem a perguntas diferentes. O DESIGN.md não substitui o AGENTS.md; os dois trabalham juntos.

Arquivo	Escrito para	Responde
`README.md`	Pessoas que usam o projeto ou contribuem com ele	O que é isto e como eu executo?
`AGENTS.md`	Agentes de código	Como eu compilo, testo e altero este código?
`DESIGN.md`	Agentes de código e de design	Qual deve ser a aparência e a sensação da interface?

Exemplos reais de DESIGN.md

O jeito mais rápido de entender o formato é ler alguns arquivos reais. Cada uma destas páginas da galeria mostra um DESIGN.md extraído do site público da marca, com a paleta e uma amostra tipográfica. Eles não são diretrizes oficiais das marcas.

Ver todos os exemplos de DESIGN.md

Como conseguir um DESIGN.md

Escreva à mão. Comece pela especificação e pelos exemplos acima e depois verifique o arquivo com o Validador de DESIGN.md gratuito ou com o comando lint do Google.
Parta de um exemplo. Copie um arquivo da galeria e edite os tokens e o texto para combinar com o seu produto.
Gere a partir de um site no ar. Cole uma URL pública no Design Extractor. Ele renderiza o site em um navegador e devolve um DESIGN.md com as cores, a tipografia, o espaçamento e os componentes, seguindo a especificação acima. A página do gerador de DESIGN.md explica o que você recebe. A mesma extração roda pela extensão do Chrome e pelo seu agente, através do servidor MCP.

FAQ

Perguntas sobre DESIGN.md

Respostas curtas sobre o formato DESIGN.md, de onde ele vem e como usá-lo com agentes de IA.

Um DESIGN.md é um arquivo de texto simples que descreve um sistema de design para agentes de IA. O front matter em YAML, no topo, guarda os tokens exatos (cores, tipografia, espaçamento, cantos arredondados e componentes), e o corpo em Markdown, logo abaixo, explica como e por que aplicá-los. Os agentes leem os tokens para obter os valores e o texto para entender a intenção.

O Google lançou o DESIGN.md com o Stitch, sua ferramenta de design com IA. O Google Labs publica a especificação no GitHub (google-labs-code/design.md) sob a licença Apache 2.0. O formato está marcado como alpha, então espere mudanças à medida que ele amadurece.

O AGENTS.md diz aos agentes de código como construir e trabalhar em um projeto: comandos, convenções, testes. O DESIGN.md diz qual deve ser a aparência e a sensação do produto: cores, tipografia, espaçamento, formas e componentes. O README.md é para as pessoas que usam o projeto ou contribuem com ele. Muitos repositórios mantêm os três lado a lado.

Coloque-o na raiz do repositório, ao lado do README.md e do AGENTS.md, para que agentes com acesso aos arquivos o encontrem. Depois aponte para ele nas instruções que o seu agente já carrega, como AGENTS.md, CLAUDE.md, uma regra do Cursor ou as suas instruções do Copilot, ou cite o arquivo no prompt quando pedir trabalho de UI.

Não. A especificação permite deixar de fora as seções que não se aplicam, mas as que você mantiver devem seguir a ordem canônica: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. O título de uma seção não pode aparecer duas vezes, e seções desconhecidas são mantidas, não rejeitadas.

O pacote npm do Google, @google/design.md, tem um comando lint que verifica a estrutura, referências de tokens quebradas e o contraste WCAG. O Design Extractor também tem um Validador de DESIGN.md gratuito que verifica a estrutura e os tokens no seu navegador e mostra uma prévia do arquivo, sem enviá-lo.

Escreva à mão a partir da especificação, copie um arquivo de uma galeria de exemplos reais como ponto de partida, ou gere um a partir do site no ar. O Design Extractor recebe uma URL pública, renderiza o site em um navegador e devolve um DESIGN.md com as cores, a tipografia, o espaçamento e os componentes dele, pronto para colocar no seu repositório.

Quer um para um site de que você gosta?

Cole uma URL pública e receba o DESIGN.md dela.

Extrair um site

Tipos de token

Propriedades de tipografia

Referências a tokens

Componentes

Nomes de token recomendados

Perguntas sobre DESIGN.md

O que é um arquivo DESIGN.md?

Quem criou o formato DESIGN.md?

Qual é a diferença entre DESIGN.md e AGENTS.md?

Onde coloco o DESIGN.md no meu projeto?

Preciso das oito seções?

Como verifico se um DESIGN.md é válido?

Como consigo um DESIGN.md de um site existente?