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 com 28 capítulos, porque seria um desperdício guardar isso só para mim. Trabalhei com a ideia de ajudar quem está estudando o mesmo tema a não precisar vasculhar a especificação em inglês desde o início, e também de permitir 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 component token ficam no YAML frontmatter em um formato legível por máquinas, e no Markdown abaixo entram critérios de decisão de design como “por que usar esta cor”, “em que situação usar este estilo de botão” e “quais padrões devem ser evitados”. Ou seja, não é apenas um guia de estilo simples, mas algo mais próximo de um “arquivo-fonte do sistema de design” que agentes de codificação com IA como Claude Code, Cursor e Codex consultariam continuamente.
Contexto — mudanças que revi ao organizar isso
• Pergunta antiga: “como organizar bem o sistema de design no Figma”
• Pergunta atual: “como fazer as ferramentas de codificação com IA lerem nosso sistema de design” e “o que é necessário para que a IA siga as regras de cores, espaçamento e componentes da nossa marca ao criar uma nova página”
• Em sintonia com movimentos como Claude Design, Claude Code e Figma MCP, o sistema de design deixa de ficar apenas dentro do Figma, entra no codebase, passa a ser revisado em PRs e se torna “contexto contínuo” para agentes de IA
Pontos centrais do formato DESIGN.md (o que mais me chamou 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 onde humanos deixam os fundamentos das decisões
• Os tokens são a resposta correta, o corpo é a justificativa — é elegante o fato de a especificação já definir previamente a prioridade de qual dos dois deve prevalecer quando houver divergência
• A ordem de 8 seções é fixa — sections como colors, typography, spacing e components funcionam por si só como o modelo mental do sistema de design
• lint / diff / export / spec CLI — verifica automaticamente 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 / comprimento·unidades / fontes / referência entre tokens
• M3 estrutura de 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
• Fechamento final · 1 capítulo — resumo dos 27 capítulos + 10 princípios para levar à prática
Reflexões que tive ao organizar isso
• Quanto mais a IA cria interfaces, mais importante o sistema de design provavelmente se torna. A questão parece estar deixando de ser “a IA sabe fazer bom design?” para virar “o quanto a equipe deixou claros 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 entregáveis de designers passam a ser alvo de revisão em unidades de PR
• Estou compartilhando porque pode ser útil para quem está criando um sistema de design ou já sentiu, ao fazer UI com ferramentas de codificação com IA, a pergunta “por que o resultado sai diferente toda vez?”. Se eu tiver entendido ou organizado algo de forma incorreta, avisem nos comentários que eu atualizo.
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.