Perguntas Frequentes
Tudo que você precisa saber sobre arquivos DESIGN.md e como usá-los com agentes de IA.
O que é um arquivo DESIGN.md?
Um DESIGN.md é um arquivo Markdown colocado na raiz do seu projeto que descreve seu design system em um formato que agentes de IA para código conseguem ler. Ele contém YAML front matter com design tokens (cores, tipografia, espaçamento) e prosa em Markdown explicando como aplicá-los. Quando um agente de IA como Claude Code, Cursor ou Kiro lê esse arquivo antes de gerar código de UI, ele produz componentes que seguem suas regras visuais de forma consistente.
Por que preciso de um DESIGN.md se já tenho Figma?
O Figma é ótimo para designers humanos, mas agentes de IA para código não conseguem ler arquivos do Figma. Eles trabalham com texto no seu repositório. O DESIGN.md preenche essa lacuna colocando suas decisões de design em um formato que vive junto ao seu código e pode ser lido por qualquer ferramenta baseada em LLM. Pense nele como a versão legível por máquina do seu design system do Figma.
Quais agentes de IA suportam DESIGN.md?
Todos os principais agentes de IA para código conseguem ler DESIGN.md, já que é apenas um arquivo Markdown. Suporte específico: Claude Code (via referência no CLAUDE.md), Cursor (via .cursor/rules), Kiro (via diretório .kiro/steering/), Windsurf (via global_rules.md) e Google Stitch (exportação nativa). Qualquer agente que leia arquivos do projeto pode usá-lo.
Qual a diferença entre DESIGN.md e design tokens em JSON?
Design tokens em JSON (como o formato W3C Design Tokens) são feitos para ferramentas de build e pipelines de geração de código. O DESIGN.md é feito para agentes de IA que precisam tanto dos valores dos tokens QUANTO do raciocínio por trás deles. A seção YAML fornece tokens estruturados, enquanto a prosa em Markdown explica quando e como usá-los. Um agente precisa de ambos para tomar boas decisões.
O que vai no YAML front matter?
A seção YAML contém seus design tokens: cores (primary, surface, text, accent), tipografia (famílias de fontes, tamanhos, pesos), escala de espaçamento, border radius, sombras e quaisquer outras decisões de design quantificáveis. Mantenha conciso — o agente precisa de valores que pode usar diretamente no código.
O que vai no corpo Markdown?
O corpo Markdown contém orientações qualitativas: uma visão geral da filosofia de design, padrões de componentes (como botões, cards e inputs devem parecer), o que fazer e não fazer, e quaisquer restrições que o agente deve seguir. É aqui que você explica POR QUE certas decisões foram tomadas, não apenas QUAIS são os valores.
Qual deve ser o tamanho de um DESIGN.md?
Entre 30 e 150 linhas é o ponto ideal. Muito curto e o agente não tem contexto suficiente. Muito longo e compete com seu código pelo espaço da janela de contexto. Os arquivos DESIGN.md mais eficazes têm 50-80 linhas: uma seção YAML compacta com 15-20 tokens e 3-5 seções curtas em Markdown.
Posso ter múltiplos arquivos DESIGN.md em um projeto?
Sim, mas não é recomendado para a maioria dos projetos. Se você tem um monorepo com apps distintos (site de marketing + dashboard), cada um pode ter seu próprio DESIGN.md. Para um app único, um arquivo na raiz é o mais claro. Alguns times usam um DESIGN.md base com overrides específicos de componentes em subdiretórios.
O que é o designmd.app?
designmd.app é uma biblioteca de referência aberta com 759 arquivos DESIGN.md prontos cobrindo todos os principais estilos de design — do minimalismo suíço ao cyberpunk, do flat design ao brutalismo. Cada arquivo é um design system completo pronto para baixar e usar com qualquer agente de IA para código. O site também oferece guias de configuração para cada agente e artigos sobre boas práticas de design systems.
Os arquivos DESIGN.md deste site são gratuitos?
Sim. Todos os arquivos DESIGN.md da biblioteca estão disponíveis sob Creative Commons Attribution 4.0 (CC BY 4.0). Você pode usá-los em projetos pessoais e comerciais. Atribuição é apreciada mas não obrigatória para os arquivos de design system em si.
Como escolho o DESIGN.md certo para meu projeto?
Comece pelo tipo de produto e público-alvo. Produtos B2B SaaS geralmente funcionam bem com sistemas minimalistas ou flat. Apps para consumidor se beneficiam de estilos mais expressivos. Portfólios criativos podem usar abordagens brutalistas ou maximalistas. Navegue pela biblioteca filtrando por categoria, ou pesquise por palavras-chave que combinam com a personalidade da sua marca.
Posso personalizar um DESIGN.md da biblioteca?
Com certeza — esse é o fluxo de trabalho esperado. Baixe um DESIGN.md que se aproxime do que você quer, depois modifique os tokens (troque cores, mude fontes, ajuste espaçamento) e atualize as seções de prosa para combinar com sua marca específica. A estrutura permanece a mesma; os valores se tornam seus.
O DESIGN.md substitui uma biblioteca de componentes?
Não. O DESIGN.md define as regras visuais; uma biblioteca de componentes as implementa. Eles trabalham juntos. O DESIGN.md diz ao agente de IA como um botão deve parecer. A biblioteca de componentes fornece o componente real em React/Vue/Svelte. Se você ainda não tem uma biblioteca de componentes, o DESIGN.md ajuda o agente a gerar componentes consistentes do zero.
Com que frequência devo atualizar meu DESIGN.md?
Atualize-o sempre que seu design system mudar — novas cores, novos componentes, espaçamento revisado. Na prática, a maioria dos times atualiza algumas vezes por trimestre. O arquivo deve sempre refletir o estado atual das suas decisões de design, não estados futuros aspiracionais.
Qual é a especificação oficial do DESIGN.md?
O Google publicou a especificação oficial do formato DESIGN.md em github.com/google-labs-code/design.md. Ela define a ordem canônica das seções, o schema YAML de tokens e regras de linting. O pacote npm @google/design.md fornece um CLI para linting, diff e exportação de arquivos DESIGN.md.
O DESIGN.md funciona com Tailwind CSS?
Sim. Seus tokens do DESIGN.md podem mapear diretamente para valores de configuração do Tailwind. Na seção de prosa, você pode referenciar classes utilitárias do Tailwind (ex: "Botões usam rounded-lg e bg-primary"). Agentes como Cursor e Claude Code entendem Tailwind e vão gerar classes utilitárias apropriadas baseadas nos seus tokens do DESIGN.md.
E se meu agente ignorar o DESIGN.md?
Certifique-se de que o agente está configurado para lê-lo. Cada ferramenta tem um mecanismo diferente: Cursor precisa de uma regra em .cursor/rules apontando para o arquivo, Claude Code precisa de uma referência no CLAUDE.md, Kiro lê de .kiro/steering/ automaticamente. Se o agente ainda ignorar, tente referenciá-lo explicitamente no seu prompt: "Siga o design system no DESIGN.md."
Posso gerar um DESIGN.md a partir do meu código existente?
Sim. Peça ao seu agente de IA para analisar seus componentes existentes e extrair um DESIGN.md. Prompt: "Analise os componentes de UI em src/components e gere um DESIGN.md que capture os padrões de design atuais, cores, tipografia e espaçamento." Revise e refine a saída, depois salve como sua referência canônica.
Tem uma pergunta não respondida aqui? Veja nossos guias de configuração ou navegue pela biblioteca.