Achei interessante o formato DESIGN.md proposto pelo Google Labs no projeto Stitch, então passei alguns dias destrinchando a especificação e organizei tudo em coreano no formato de um currículo de 28 capítulos, porque seria um desperdício guardar isso só para mim. Trabalhei com a ideia de permitir que quem está estudando o mesmo tema não precise vasculhar a especificação em inglês desde o começo e que pessoas que, como eu, têm a pergunta “como fazer a IA ler um sistema de design” possam ter uma visão geral de uma vez só.
DESIGN.md é um formato que busca representar um sistema de design em um único arquivo Markdown. Valores como cores, tipografia, spacing, radius e tokens de componentes ficam no YAML frontmatter em uma forma legível por máquina, e no Markdown abaixo entram critérios de decisão de design como “por que usamos esta cor”, “em que situação este estilo de botão deve ser usado” e “quais padrões devem ser evitados”. Ou seja, está mais próximo de um “arquivo-fonte do sistema de design” que agentes de programação com IA como Claude Code, Cursor e Codex consultarão repetidamente, e não de um simples guia de estilo.
Contexto — mudanças que voltei a revisar ao organizar isso
• Pergunta antiga: “como organizar bem o sistema de design no Figma”
• Pergunta atual: “como fazer as ferramentas de programação com IA lerem nosso sistema de design” e “o que é necessário para que a IA siga as regras de cor, espaçamento e componentes da nossa marca ao criar uma nova página”
• Em conjunto com movimentos como Claude Design, Claude Code e Figma MCP, há uma mudança em que o sistema de design deixa de ficar apenas dentro do Figma, entra no codebase, é revisado em PRs e passa a ser o “contexto contínuo” de agentes de IA
Pontos centrais do formato DESIGN.md (partes que mais me chamaram atenção ao ler a especificação)
• Estrutura dupla YAML (para máquinas) + Markdown (para pessoas e IA) — os tokens são analisados pela máquina, enquanto o corpo do texto é a camada em que humanos registram os motivos de julgamento
• Os tokens são a resposta certa, o corpo é a justificativa — é elegante o fato de a prioridade sobre em quem confiar quando os dois entram em conflito já estar definida de antemão
• A ordem de 8 seções é fixa — seções como colors, typography e spacing, além de components, funcionam por si só como o mental model do sistema de design
• lint / diff / export / spec CLI — faz verificação automática de itens como referências quebradas, contraste insuficiente, tokens órfãos e violação da ordem das seções
• A política de interoperabilidade com DTCG, Tailwind e variáveis do Figma é especificada separadamente
Estrutura do currículo (28 capítulos, 7 módulos)
• M1 filosofia do formato · 3 capítulos — o problema que este formato tenta resolver, a estrutura dupla e a prioridade entre tokens e texto
• M2 esquema de tokens · 5 capítulos — esquema completo / cores / comprimentos e unidades / fontes / referências de tokens
• M3 estrutura das seções · 6 capítulos — a ordem das 8 seções e os princípios de projeto de cada uma
• M4 leitura de exemplos reais · 3 capítulos — casos Atmospheric Glass, Paws & Paths e Totality Festival
• M5 CLI · 4 capítulos — lint, diff, export, spec
• M6 regras de lint · 4 capítulos — 8 itens, incluindo broken-ref, contrast, orphaned e section-order
• M7 extensibilidade · 2 capítulos — política para lidar com conteúdo desconhecido e relação com DTCG e Tailwind
• Resumo final · 1 capítulo — síntese de 27 capítulos + 10 princípios para levar à prática
Pensamentos que tive ao organizar isso
• Quanto mais a IA criar interfaces, mais importante o sistema de design provavelmente se tornará. A questão parece estar deixando de ser “a IA é boa em design?” para se tornar “quão claramente a equipe deixou registrados os critérios que a IA deve seguir?”
• O DESIGN.md é uma tentativa prática de colocar esses critérios dentro do codebase, em vez de deixá-los em Notion ou PDF. Isso também significa que o trabalho produzido por designers passa a ser alvo de revisão em nível de PR
• Estou compartilhando porque acho que pode ser útil para quem está criando um sistema de design ou para quem já sentiu, ao fazer UI com ferramentas de programação com IA, “por que o resultado sai diferente toda vez?”. Se houver partes que eu tenha entendido ou organizado de forma incorreta, por favor me avisem nos comentários para que eu possa corrigir.
2 comentários
Tenho uma dúvida: pelo que entendi, o DESIGN.md seriam instruções para gerar o design. No fim, ele acaba sendo usado para criar as primeiras páginas... ou uma página, um mood board. Depois disso, não surge uma divergência entre o código e o arquivo de instruções
.md, exigindo sincronização bidirecional contínua?No fim das contas, para o design posterior, parece que o código deveria ser a source of truth, reutilizando de forma consistente coisas como variáveis e nomes. Se o DESIGN.md não for atualizado continuamente e gerenciado como SSoT, não acaba levando a tokens hardcoded o tempo todo? Fiquei curioso para saber se, no uso real, esse problema não acontece.
DESIGN.md => a direção do código é fácil de automatizar, mas o contrário — fazer com que novos padrões surgidos no código subam para o DESIGN.md — não acontece automaticamente, então a equipe precisa cuidar disso manualmente. Com o tempo, pequenos hardcodings vão se acumulando no código, mas não chegam à documentação, e isso acaba se somando.
Ainda assim, a filosofia desse formato em si é mais a de “continuar cultivando o design system dentro da codebase”, então vejo isso menos como uma desvantagem e mais como um modo de operação intencional. Como os guias que antes ficavam congelados no Notion ou em PDF foram trazidos para o escopo de revisão em nível de PR, parece que a responsabilidade de revisá-los periodicamente por pessoas vem junto nessa estrutura. Nós testamos isso no nosso projeto, e a consistência das telas claramente melhorou em comparação com antes da adoção; como o benefício ficou perceptível na prática, a revisão manual não pareceu um fardo. No fim, concluímos que a questão é o quanto a equipe deixa claros os critérios que a IA deve seguir, e que a parte de manter esses critérios vivos continua sendo uma responsabilidade humana.