🎨 Design Systems (DESIGN.md) — o vocabulário visual

O que é

Um DESIGN.md válido é Markdown com 9 seções obrigatórias (na ordem):

Cada uma usa formato consistente (tabela ou lista) que o parser do daemon entende.

Por que aprender

9 seções é uma ABI estável: o agente sempre encontra cor em "color", motion em "motion". Skip de seção (cair direto em components) = output incoerente. A ordem importa porque cor → tipografia → spacing → layout = árvore de decisão visual.

Conceitos-chave

• color: tokens em OKLch + role (bg, surface, fg, accent, border)
• typography: display + body + mono em font-stack
• spacing: escala (4-8-12-16-24-32-48-64)
• anti-patterns: 3-5 coisas proibidas nesse sistema (cruciais)
• brand: 1 frase de "personality" — Editorial Monocle? Brutalist? Soft Warm?

O que é

OKLch é um espaço de cor onde L (lightness) é perceptual — duas cores com mesmo L parecem ter o mesmo brilho, independente do hue. Em HSL/HEX, isso não é verdade: hsl(60 100% 50%) (amarelo) parece mais claro que hsl(240 100% 50%) (azul) — apesar de ambos terem L=50%.

/* HEX/HSL — inconsistente */
--bg: #1a1a1a;
--accent: #ff6b35;     /* parece muito mais claro que bg, embora L baixo */

/* OKLch — uniforme */
--bg: oklch(15% 0 0);
--accent: oklch(58% 0.15 35);   /* L=58 é previsível em qualquer hue */

Por que aprender

Três razões. 1) Verifica contraste WCAG mecanicamente — se Lbg − Lfg ≥ 50, contraste é seguro. 2) Display P3 (gama wide de iPhone/Pro Display) sem fallback estranho. 3) Manipulação programática: "azul mais escuro" = baixar L sem cair em cinza. É o motivo de o OD ter saltado HEX/HSL na primeira versão.

Conceitos-chave

• L (lightness): 0-100%, perceptualmente uniforme
• C (chroma): 0-0.4, "saturação" perceptual
• h (hue): 0-360°, ângulo
• Suporte de browsers: Chrome 111+, Safari 15.4+, Firefox 113+ (universal hoje)
• Conversor: oklch.com — paste HEX → OKLch

O que é

O OD vem com 72 DESIGN.md curados de produtos reais — em design-systems/, organizados em 7 categorias:

Por que aprender

Antes de criar um sistema novo, cheque o catálogo. Linear-app já tem o "minimal dev tool" feito. Stripe já tem "fintech polished". Você não precisa redescobrir paleta — você customiza um existente. Default sane > tela em branco.

Conceitos-chave

• design-systems/<name>/DESIGN.md: path padrão
• README por categoria: índice e quando usar cada
• Linear-app é canônico: ler primeiro pra entender o formato
• Editorial Monocle: alternativa quando você quer "magazine-style"
• Não é Theme: é vocabulário; mais do que cores e fontes

O que é

Todo DESIGN.md mapeia para um conjunto canônico de tokens CSS injetados no :root:

:root {
  --bg:      oklch(98% 0.01 90);   /* fundo da página */
  --surface: oklch(96% 0.01 90);   /* card, modal */
  --fg:      oklch(15% 0.02 90);   /* texto principal */
  --muted:   oklch(45% 0.02 90);   /* texto secundário */
  --border:  oklch(85% 0.01 90);   /* divisórias */
  --accent:  oklch(58% 0.15 35);   /* cor de marca */
}

Por que aprender

Esses 6 tokens são o contrato entre DESIGN e SKILL. SKILLs (templates) usam var(--bg) sem saber qual sistema está ativo. Trocar de Linear pra Stripe muda os 6 valores; templates funcionam idênticos. Você nunca acopla skill a sistema visual.

Conceitos-chave

• --bg: fundo de página (o "papel")
• --surface: elementos elevados (card, panel)
• --fg / --muted: texto principal e secundário
• --border: divisórias finas
• --accent: uma cor de marca, sempre uma só
• Dark mode: mesmo nome, outros valores em [data-theme="dark"]

O que é

DESIGN.md inteiro pode ter 600 linhas. O agente não precisa de todas. O daemon faz pruning: na hora de gerar uma landing, injeta só "color, typography, components". Pra um deck, injeta "color, typography, motion, voice". A skill ativa declara em od: qual subset precisa.

od:
  design_system: linear-app
  design_system_sections: [color, typography, components]

Por que aprender

Sem pruning, você queima 6k tokens com seções irrelevantes (ex: "anti-patterns" pra cada gerada). Pruning = mais espaço pro brief do usuário e pra qualidade do output. É a diferença entre "ler um livro" e "consultar uma página".

Conceitos-chave

• design_system_sections: array de strings (nomes das seções)
• Default: color + typography + components (mais usado)
• Override: SKILL pode forçar inclusão de "voice" se for um chatbot
• Token budget: ~3k tokens é o máximo confortável de DESIGN injetado

O que é

A coleção de 72 sistemas é puxada de um repo upstream (awesome-design-md) via script automatizado. pnpm sync-design-systems faz pull, valida o schema das 9 seções, e atualiza os arquivos locais. Você pode contribuir com PR no upstream e ver seu sistema aparecer no OD oficial.

Por que aprender

Coleção viva = você não fica preso a 72 sistemas estáticos. Se Vercel atualiza brand, alguém faz PR no upstream, você roda sync e tem a versão nova. É o GitHub do design system, não uma biblioteca enlatada.

Conceitos-chave

• Upstream: github.com/<org>/awesome-design-md (curated)
• Sync script: valida schema, gera local copy
• Frequência: rodar 1x por mês ou após PR aceito
• PR pattern: add directory + DESIGN.md + README.md
• Local override: coloque em ./design-systems/local/ sem upstream

O que é

Heurística: se o seu cliente é "outro Linear" (dev tool minimal), use linear-app + customize accent. Se é "outro Stripe" (fintech polished), use stripe + customize. Se é genuinamente diferente (cliente brasileiro, sustentabilidade, identidade tropical com Caparaó tipográfico), aí faz DESIGN.md novo. Default: estende. Exception: cria.

Por que aprender

Designers gostam de criar sistema do zero — é tentador. Mas consome tempo: refletir sobre cor, tipografia, spacing, anti-patterns leva ~4 horas pra fazer bem. Estender leva 30 minutos. Reserve criação pra quando estender de verdade não cabe.

Conceitos-chave

• Estender: copia DESIGN.md, edita 6 tokens + voice
• Criar: 9 seções do zero, anti-patterns próprios
• Brand-spec extraction (M 3.3): caminho intermediário — extrai do site do cliente
• Versionamento: Git nas branches do sistema (refresh anual normal)