DESIGN.md: Uma especificação de formato para descrever identidade visual para agentes de codificação

O Google Labs lançou o DESIGN.md, uma especificação de formato para descrever uma identidade visual para agentes de codificação. O arquivo combina tokens de design legíveis por máquina (front matter YAML) com justificativa de design legível por humanos (prosa em markdown). Os tokens fornecem valores exatos aos agentes; a prosa explica por que esses valores existem e como aplicá-los.

Visão Geral do Formato

Um arquivo DESIGN.md tem duas camadas delimitadas por cercas --- no topo: front matter YAML para tokens e um corpo em markdown com seções ##. Exemplo de trecho:

---
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"
  label-caps:
    fontFamily: "Space Grotesk"
    fontSize: "0.75rem"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"

Os tokens são os valores normativos. A prosa fornece contexto para a aplicação.

Principais Recursos

• Tipos de token: Cores (hex sRGB), objetos de Tipografia (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), Dimensões (número+unidade), Referências a tokens ({path.to.token}).
• Componentes: Mapeie um nome para propriedades de sub-token, ex.: components.button-primary.backgroundColor: "{colors.tertiary}".
• Ordem das seções (opcional, mas aplicada): Visão Geral, Cores, Tipografia, Layout e Espaçamento, Elevação e Profundidade, Formas, Componentes, O que Fazer e o que Não Fazer.

Ferramentas CLI

Valide um DESIGN.md com o linter:

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) em backgroundColor (#1A1C1E) tem taxa de contraste 15.42:1 — passa WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Detecte regressões entre versões:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
  "tokens": {
    "colors": {
      "added": ["accent"],
      "removed": [],
      "modified": ["tertiary"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Exemplo de Uso

Um agente lendo o exemplo Heritage produzirá uma interface com títulos em tinta escura em Public Sans, um fundo de calcário quente (#F7F5F2) e botões de call-to-action em Boston Clay (#B8422E) — tudo a partir de um único arquivo.