O que é DESIGN.md

Formato

Duas camadas em um arquivo

Um arquivo DESIGN.md tem duas partes: YAML front matter com design tokens, e um corpo Markdown com o racional por trás deles. Os tokens são a fonte de verdade para valores. A prosa diz ao agente como usar esses valores — e quando não usar.

---
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.

Entregue esse arquivo a um agente e o resultado é previsível: headlines em Public Sans cor de tinta, fundo limestone quente, botões em Boston Clay. Sem adivinhação.

Tokens

Schema de design tokens

Tokens ficam no YAML front matter. O schema se inspira na spec W3C Design Tokens — grupos tipados, sintaxe {path.to.token} para referências cruzadas entre valores. Familiar pra quem já mexeu com Figma variables ou temas Tailwind.

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

Estrutura

8 seções da especificação oficial

Seções usam headings ##. Pode pular qualquer uma, mas as que estiverem presentes devem seguir esta ordem — o LLM lê de cima pra baixo, e a sequência importa pra construção de contexto.

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

## 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.

## 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.

## 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.

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

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

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

## 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 vem com quatro comandos: validar, comparar, exportar e inspecionar. Tudo roda via npx — sem precisar instalar global.

npx @google/design.md lint DESIGN.md

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

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 spec
npx @google/design.md spec --rules --format json

Validação

Regras de linting

O linter verifica 9 regras no seu arquivo. Cada uma gera findings com severidade fixa — errors bloqueiam, warnings avisam, info apenas reporta.

API Programática

Use o linter como biblioteca

Precisa do linter dentro da sua própria tooling — pipelines de CI, extensões de editor, validadores custom? Ele exporta como biblioteca JavaScript.

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

Formato

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

Markdown é o formato que LLMs entendem melhor — a maior parte dos dados de treino usa essa estrutura. Não precisa de instrução extra de parsing.

Tokens JSON definem valores, mas não regras. Não dá pra expressar "use primary só no CTA principal" num tokens.json. DESIGN.md resolve isso juntando tokens YAML (valores exatos pra máquinas) com prosa Markdown (semântica e restrições pro agente) num arquivo só, zero build pipeline. O comando export converte pra Tailwind ou DTCG quando você precisar downstream.

Obtenção

Como obter um DESIGN.md

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

Nomenclatura

Nomes de tokens recomendados (Não-Normativo)

Esses nomes aparecem na maioria dos design systems. Não são obrigatórios — mas usá-los torna seu DESIGN.md instantaneamente familiar pra qualquer pessoa (ou agente) lendo.

Setup

Configuração por agente

Cada agente de IA tem seu arquivo de configuração. O DESIGN.md fica na raiz do projeto — a config só precisa dizer ao agente pra lê-lo. Sem plugins, sem integrações, sem lock-in.

FAQ

Perguntas frequentes