O que é o DESIGN.md no OpenDesign e como esse arquivo vira o contrato de marca do seu projeto?

Fala aí, beleza? Todo mundo que gera interface com agente já viveu isso: você pede uma tela, vem um azul, pede a próxima, vem outro azul, o botão muda de raio, a fonte troca sozinha e no fim você tem cinco telas de cinco produtos diferentes

O agente não tem memória de marca, ele tem prompt

É exatamente aí que entra o DESIGN.md: um arquivo único, versionado junto do projeto, que descreve a marca em formato que máquina lê. E é assim que ele funciona dentro do OpenDesign, projeto open source distribuído sob licença Apache-2.0, com execução local (local-first) e modelo BYOK, ou seja, você pluga a sua própria chave de agente

Bora entender o arquivo por dentro?

De onde vem o DESIGN.md: a spec aberta do Google Labs

O formato não nasceu no OpenDesign

A especificação aberta do DESIGN.md foi publicada pelo Google Labs em 21 de abril de 2026, como uma saída do Stitch, sob licença Apache-2.0, com o objetivo declarado de virar padrão entre agentes

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Ou seja: a ideia desde o dia zero é interoperabilidade, não formato proprietário

A spec oficial mora no repositório google-labs-code/design.md, com o documento em docs/spec.md. Vale a leitura antes de sair escrevendo o seu

E o contexto ao redor ajuda a entender o timing. Poucos dias antes, em 17 de abril de 2026, a Anthropic lançou o Claude Design, produto do Anthropic Labs para gerar protótipos, slides, mockups e one-pagers a partir de prompts, documentos e código

Tem também um sinal interessante do lado da Anthropic: existe no repositório anthropics/skills a issue #1008 propondo que a skill frontend-design consuma e produza DESIGN.md conforme a spec aberta do Google Labs

Um formato de arquivo virando assunto no repositório de skills de outra empresa? Isso é o cheiro de padrão se formando 🙂

Por que o agente precisa de um contrato de marca

Para antes do como: por que isso existe?

O problema é bem chato de descrever mas todo mundo reconhece na hora. Sem uma fonte canônica de verdade visual, cada geração recomeça do zero

Você descreve a paleta no prompt

O agente acerta

Na próxima sessão, contexto novo, prompt novo, e você descreve tudo de novo

Isso é re-briefing, e re-briefing é o imposto invisível de quem gera interface com IA

A lógica do contrato resolve por inversão: em vez de instrução solta que vive no prompt e morre com a sessão, você tem um artefato único que o agente lê antes de produzir. A marca deixa de ser algo que você lembra de falar e vira algo que está no repositório

É a mesma ideia de qualquer arquivo de convenção que o agente consome no seu projeto: se está escrito, não precisa ser repetido. Por sinal, se você já se preocupa com o que o agente lê no seu repositório, o raciocínio aqui é o irmão gêmeo desse cuidado, só que pelo lado positivo: o que você QUER que ele leia sempre

E tem um detalhe que muda o jogo: sendo arquivo, ele entra no git. Mudança de marca vira diff, vira review, vira histórico

Anatomia do arquivo: frontmatter YAML e corpo markdown

Agora a parte concreta

Um arquivo DESIGN.md tem duas partes, e cada uma tem um público diferente:

O frontmatter YAML é opcional e é onde ficam os design tokens legíveis por máquina

Os campos previstos na spec são: version, name, description, seções omitidas, colors, typography, rounded, spacing e components

E todos esses campos são opcionais, você inclui os que fizerem sentido pro seu projeto

Porém (e presta atenção nisso) as seções que estiverem presentes devem seguir uma ordem específica, e o linter sinaliza seção fora de ordem

Então não é um YAML solto onde você joga chave em qualquer lugar. Tem gramática

O esqueleto do frontmatter, grosso modo, fica assim:

---
version: ...
name: ...
description: ...
colors: ...
typography: ...
rounded: ...
spacing: ...
components: ...
---

Já o corpo em markdown é a parte legível por humanos: o racional e as diretrizes. É onde você explica POR QUE a marca é do jeito que é, não só quais são os valores

E isso não é enfeite. O corpo é o que dá contexto pro agente decidir os casos que o token não cobre

O que cada seção governa nas saídas

No corpo, as seções usam títulos de nível ##

Duas delas dão bem a ideia do que o arquivo governa

A seção Overview descreve o look and feel do produto: personalidade de marca, público e a resposta emocional pretendida

Repara que nada disso é um valor hexadecimal. É briefing mesmo, escrito uma vez

A seção Colors define as paletas, e a spec exige ao menos a paleta primária. Faz sentido: sem primária não existe marca, existe rascunho

E os tokens, como se conectam?

O sistema de tokens do DESIGN.md é inspirado na spec Design Token JSON

Na prática, isso significa dois comportamentos que quem já mexeu com design system reconhece na hora:

• grupos tipados de tokens, como colors, typography e spacing
• sintaxe de referência {path.to.token} para cruzar valores

A referência é o que evita duplicação

Em vez de repetir o mesmo valor de cor em cinco lugares e rezar pra ninguém esquecer de atualizar um deles, você aponta pro token. Se você já usou variável em CSS ou alias em tema de biblioteca de componentes, é a mesma cabeça, só que num arquivo que o agente lê

Tome cuidado com um ponto aqui: token resolve consistência de VALOR, não de gosto. O que segura o gosto é o corpo em markdown

Como o OpenDesign usa o DESIGN.md na prática

Até aqui falamos do formato. Agora, o papel dele dentro do produto

No OpenDesign, o DESIGN.md funciona como contrato de marca: toda skill lê o DESIGN.md do pacote ativo antes de renderizar

Essa frase é curtinha mas é o coração da coisa toda. Não é "o agente pode consultar se quiser", é leitura como etapa do render. A marca é aplicada ao que o agente produz sem re-briefing a cada geração

No repositório, os design systems ficam na pasta design-systems/, organizados por slug, e cada pasta contém três arquivos:

design-systems/
  <slug>/
    manifest.json
    DESIGN.md
    tokens.css

E o DESIGN.md ali é descrito como a prosa canônica destinada aos agentes

Prosa canônica. Ou seja: o tokens.css é pro navegador, o manifest.json é pra máquina catalogar, e o DESIGN.md é o texto que o modelo lê pra entender a marca

Tem ainda um caminho de entrada que evita a página em branco: o OpenDesign traz a skill brand-extract, cujo arquivo fica em skills/brand-extract/SKILL.md, feita pra extrair um Brand Kit completo de um site ao vivo dirigindo o navegador embutido no app

Sacou a jogada? Em vez de você descrever sua marca de memória, ele vai lá no site e tira dela mesma

E se você não quer partir do seu site, a página de catálogo de design systems do OpenDesign anuncia 152 design systems open source disponíveis em /plugins/systems/

O que isso muda para quem já usa Claude Code, Codex ou Cursor

Agora a leitura prática, que é onde a maioria decide se liga ou não

O OpenDesign se posiciona como alternativa open source e local ao Claude Design, dirigida por agentes de CLI via BYOK. A proposta é transformar o agente de código que você JÁ usa (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, entre outros) em motor de design

Ou seja: não é mais uma ferramenta pra abrir numa aba, é o mesmo terminal de sempre com um contrato visual em cima

O ganho real, pra mim, está numa mudança de categoria: a marca sai do campo "instrução que eu repito" e entra no campo "arquivo que o projeto tem"

Instrução repetida degrada, esquece, muda de sessão pra sessão

Arquivo versionado não

E o sinal de padronização está lá na issue #1008 do anthropics/skills, propondo que a skill frontend-design consuma e produza DESIGN.md conforme a spec aberta. Se isso pegar, o mesmo arquivo serve mais de um agente, e aí o DESIGN.md deixa de ser detalhe de uma ferramenta pra virar interface entre elas

Será que pega? Ainda é cedo pra cravar. Mas formato aberto sob Apache-2.0, com spec pública e outro fornecedor discutindo adoção, é bem mais promissor que schema fechado

Conclusão

O DESIGN.md é, no fim, um contrato entre a sua marca e o agente

De um lado, o frontmatter YAML com tokens tipados e referência {path.to.token} pra máquina não errar valor

Do outro, o corpo em markdown com Overview, Colors e o racional, pra máquina não errar intenção

E dentro do OpenDesign esse contrato é lido por toda skill antes de renderizar, que é o que corta o improviso visual a cada geração

Próximo passo, se você quer sair da teoria: leia a spec em docs/spec.md no repositório google-labs-code/design.md pra entender a gramática do formato, e depois abra a estrutura design-systems/<slug>/ no repositório nexu-io/open-design pra ver o formato aplicado de verdade, com manifest.json, DESIGN.md e tokens.css lado a lado

Ler a spec e depois um exemplo real vale mais que qualquer explicação minha aqui 😀

até o próximo post!