Série Especial Sobre Inteligência Artificial para Designers & Product Managers AQUI.
DESIGN.md: como dar contexto visual para agentes de IA e LLMs nos seus projetos
O design.md é um arquivo de especificação que descreve a identidade visual de um projeto no formato que agentes de codificação conseguem ler e aplicar. Simples assim. A ideia surgiu com o Google Stitch, uma plataforma de prototipagem visual, e rapidamente ganhou adoção em outros contextos porque resolve um problema real: LLMs não têm memória visual por padrão, e sem contexto eles inventam.
Se você já pediu para o Claude Code ou qualquer outro agente gerar uma interface e recebeu algo completamente fora da identidade do projeto, sabe exatamente do que estou falando. O design.md é a resposta prática para isso.
Neste artigo vou explicar o que é, como funciona, onde encontrar arquivos prontos e como criar o seu.
O que é o design.md, na definição oficial
O projeto foi aberto como open source pelo Google. A definição no repositório é direta: o design.md é uma especificação de formato para descrever identidade visual para agentes de codificação. O arquivo fornece aos agentes uma compreensão estruturada e consistente do sistema de design do projeto.
O que torna isso interessante é a combinação de dois tipos de conteúdo no mesmo arquivo:
- Tokens de design legíveis por máquina: valores exatos de cor, tipografia, espaçamento, no formato que o LLM consegue consumir.
- Justificativas legíveis por humano: texto em Markdown explicando por que esses valores existem e como aplicá-los.
Essa combinação é o que diferencia o design.md de simplesmente jogar um design system em texto no prompt. O agente recebe o valor exato do token e entende o contexto de uso (“cor primária, usada em CTAs e elementos de destaque”).
Onde encontrar arquivos de design.md prontos
Já existe um portal dedicado com uma coleção de arquivos no formato design.md, incluindo referências visuais de marcas conhecidas. Você consegue filtrar por categoria, escolher um estilo e copiar o arquivo inteiro para o seu projeto.
Uma observação importante: os arquivos de marcas famosas disponíveis no portal não são os design systems oficiais dessas empresas. São referências visuais que se aproximam do estilo da marca, suficientes para dar consistência ao agente.
No portal você tem duas opções: copiar o arquivo markdown diretamente, ou instalar via linha de comando no seu projeto.
Como o arquivo está estruturado
Se você abrir qualquer design.md do portal, vai encontrar uma estrutura consistente:
- Conceitos e características principais da identidade visual
- Paleta de cores com os valores exatos e regras de uso
- Tipografia (família, tamanhos, hierarquia)
- Espaçamento e grid
- Argumentação qualitativa: por que essas escolhas existem
Essa estrutura foi pensada para que o agente consiga navegar pelo arquivo e recuperar a informação relevante no momento certo, sem precisar processar o documento inteiro a cada geração.
Como usar no Claude Code (e em outros agentes)
A forma mais direta é colocar o arquivo design.md na raiz do seu projeto. O Claude Code vai incluir ele automaticamente no contexto quando você estiver trabalhando em arquivos de interface.
Algumas formas de usar:
- Projeto novo sem design system: crie ou adapte um design.md antes de começar a gerar componentes.
- Referência de marca existente: use o portal para encontrar algo próximo e edite os valores para os seus tokens reais.
- Engenharia reversa: se você tem um produto com identidade visual definida mas sem documentação formal, use o formato para documentar os tokens existentes e passar isso para o agente.
O ponto de atenção aqui é o tamanho do arquivo. Um design.md muito longo vai consumir tokens desnecessariamente. Mantenha o foco nos valores que o agente realmente precisa: cores, tipografia, espaçamento, componentes principais.
design.md versus design system: quando usar cada um
Se você trabalha em um produto com design system conectado a uma biblioteca de componentes (Figma + Storybook, por exemplo), o design.md não substitui isso. Seu design system já cobre o caso.
O design.md é útil principalmente em três situações:
- Você está criando uma homepage ou landing page e não tem estrutura de design system montada.
- Você é um founder solo ou pequeno time sem designer dedicado e quer mais consistência visual nas interfaces geradas por IA.
- Você quer dar contexto de marca para um agente que vai gerar código de front-end em um projeto sem documentação formal.
O que está acontecendo com esse formato agora
Enquanto eu gravava o vídeo sobre esse tema, o Google Stitch atualizou a plataforma para aceitar design.md diretamente na criação de novos projetos. Você pode fazer upload do arquivo, colar o conteúdo, gerar a partir de uma codebase existente ou buscar no marketplace de estilos visuais da plataforma.
Essa integração nativa indica a direção: o design.md vai virar um padrão de fato para projetos que usam agentes de codificação. Outras plataformas já estão adotando. Faz sentido entender agora.
Como criar o seu próprio design.md
O processo mais simples:
- Acesse o portal de collections.
- Escolha um arquivo próximo da sua identidade visual.
- Edite os valores de cor, tipografia e espaçamento para os seus tokens reais.
- Adicione a argumentação qualitativa: explique brevemente por que cada escolha existe.
- Salve como
design.mdna raiz do projeto.
Se quiser partir do zero, o repositório oficial do Google tem as instruções de instalação e o spec completo do formato.
Se você quiser ver isso funcionando na prática dentro do Claude Code, com setup completo e fluxo real de geração de interface, esse é exatamente o tipo de conteúdo que a gente cobre no Curso de IA para Designers e Product Managers da PunkMetrics. Tem um módulo dedicado ao Claude Code onde a gente passa por esses tópicos com projetos reais.
Referências
- Google Stitch
- Repositório oficial do design.md no GitHub
- Portal de collections de arquivos design.md
