--- title: "Como criar um DESIGN.md: estrutura, exemplo e aplicação em projetos de IA" date: 2026-05-09T19:57:41Z modified: 2026-08-17T22:00:03Z permalink: "https://camaraux.com.br/como-criar-aplicar-design-md-ia/" type: post status: publish excerpt: Aprenda a criar um DESIGN.md para guiar IAs, manter interfaces consistentes e transformar regras visuais em design system reutilizável. wpid: 7299 categories: - Design Systems tags: - Design Systems - claude code - cursor - Design System - design.md - google stitch - IA - UX Design - Vibe Coding rank_math_title: "Como criar um DESIGN.md: guia prático para IA" rank_math_description: Aprenda a criar um DESIGN.md com a estrutura oficial, tokens, exemplos, validação por CLI e aplicação em projetos com agentes de IA. rank_math_focus_keyword: DESIGN.md,como criar DESIGN.md featured_image: /wp-content/uploads/2026/05/ilustracao-Como-criar-um-arquivo-design-md-voltado-para-ux-vibecoding.webp featured_image_alt: Pessoa observando maquete arquitetônica minimalista com pontes, torres e formas geomométricas em tons pastéis author: Lucas Camara timestamp: 2026-08-17T22:00:03Z --- Se você já entendeu o que é um `DESIGN.md` e agora precisa criar um arquivo para o seu projeto, este guia parte direto para a implementação. O objetivo não é simplesmente listar cores, fontes e espaçamentos. Um bom `DESIGN.md` precisa transformar decisões visuais em um contexto que continue compreensível para designers, desenvolvedores e agentes de IA ao longo do projeto. Se você ainda está conhecendo o formato, comece pela [biblioteca e guia de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). Aqui, o foco é outro: **como estruturar, escrever, validar e aplicar o seu próprio arquivo**. Em abril de 2026, o Google tornou pública a especificação draft do DESIGN.md, criada no contexto do Google Stitch para permitir que regras de design possam ser importadas, exportadas e reutilizadas entre projetos e ferramentas. A especificação oficial está disponível no [repositório do Google Labs no GitHub](https://github.com/google-labs-code/design.md) e continua evoluindo. ## Antes de criar um DESIGN.md, defina de onde virão as regras O primeiro passo não acontece no Markdown. Acontece no produto. Se o projeto já possui um design system, biblioteca no Figma, variáveis, tokens ou componentes em produção, use essas decisões como fonte. O DESIGN.md deve documentar o sistema existente, não criar uma segunda identidade visual paralela. Se o produto ainda não tem um sistema formal, levante pelo menos a direção visual, cores, tipografia, ritmo de espaçamento, formas, componentes recorrentes e comportamentos que devem permanecer consistentes. - **Produto existente:** documente o que já é usado. - **Design system existente:** traduza tokens e regras importantes para o arquivo. - **Projeto novo:** defina primeiro a direção visual e depois formalize as regras. - **Referência visual:** use como ponto de partida, mas adapte as decisões ao seu próprio produto. Também é possível começar a partir de um modelo. A [biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/) reúne referências que podem ser adaptadas ao contexto do projeto, em vez de começar sempre com um arquivo vazio. ## Qual é a estrutura oficial de um DESIGN.md? Segundo a [especificação oficial do DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), o documento pode combinar duas camadas: um **YAML front matter opcional**, usado para valores estruturados, e um corpo em **Markdown**, usado para explicar a identidade visual e como aplicar as decisões. Isso é importante porque um design system não é apenas uma coleção de números. Saber que a cor primária é `#5257FF` não explica quando ela deve aparecer, em quais elementos deve ser evitada ou qual papel cumpre na hierarquia da interface. Os tokens fornecem valores objetivos. O texto explica intenção, contexto e restrições. | Seção | O que documentar | | --- | --- | | **Overview** | Direção visual, personalidade, público e sensação que a interface deve transmitir. | | **Colors** | Paleta, papéis semânticos e regras de aplicação das cores. | | **Typography** | Famílias, escalas, pesos, alturas de linha e lógica tipográfica. | | **Layout** | Grid, espaçamentos, densidade, containers e comportamento responsivo. | | **Elevation & Depth** | Como comunicar profundidade: sombras, bordas, contraste ou camadas. | | **Shapes** | Raios, formas e linguagem geométrica utilizada na interface. | | **Components** | Regras para componentes recorrentes e seus principais estados. | | **Do’s and Don’ts** | Decisões que devem ser preservadas e padrões que devem ser evitados. | Essas são as oito seções canônicas documentadas atualmente. Nem todas precisam aparecer quando não forem relevantes para o projeto, e a própria especificação permanece em estágio **alpha**. Por isso, vale consultar a documentação oficial ao construir automações ou validadores que dependam do formato. ## 1. Crie o arquivo DESIGN.md Crie um arquivo de texto com o nome: ``` DESIGN.md ``` A especificação define o formato do arquivo, mas não obriga que ele fique em uma pasta específica. Em projetos versionados, colocá-lo na raiz do repositório costuma facilitar descoberta, versionamento e referência por outras ferramentas. ``` meu-projeto/ ├── DESIGN.md ├── src/ ├── package.json └── ... ``` Não assuma, porém, que qualquer agente vai encontrar ou carregar o arquivo automaticamente apenas porque ele está na raiz. A forma de fornecer o DESIGN.md como contexto depende da ferramenta utilizada. ## 2. Adicione os tokens no YAML front matter quando fizer sentido O YAML no início do arquivo é opcional. Ele é especialmente útil quando você precisa registrar valores exatos de forma estruturada, como cores, tipografia, espaçamento e raios. Um exemplo simples: ``` --- version: alpha name: Produto Exemplo description: Plataforma B2B focada em produtividade e clareza operacional colors: primary: "#5257FF" secondary: "#171821" surface: "#FFFFFF" background: "#F7F7F9" text-primary: "#171821" text-secondary: "#5F6270" typography: h1: fontFamily: Inter fontSize: 48px fontWeight: 700 lineHeight: 1.1 body-md: fontFamily: Inter fontSize: 16px fontWeight: 400 lineHeight: 1.6 spacing: xs: 4px sm: 8px md: 16px lg: 24px xl: 32px rounded: sm: 4px md: 8px lg: 16px --- ``` O ponto não é preencher o maior número possível de propriedades. Registre os valores que realmente funcionam como decisões compartilhadas no produto. Se o seu design system já utiliza tokens estruturados, vale também entender a relação com o [formato e a arquitetura de design tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-tokens-arquitetura-w3c.md). O DESIGN.md não precisa substituir uma infraestrutura de tokens existente. ## 3. Escreva um Overview que realmente descreva a direção visual A seção `Overview` apresenta o contexto que os valores isolados não conseguem transmitir. Evite: ``` ## Overview Interface moderna, bonita e minimalista. ``` Essa descrição permite interpretações demais. Prefira uma direção que ajude alguém a tomar decisões quando não houver uma regra explícita: ``` ## Overview A interface deve transmitir precisão, clareza e confiança. O produto é usado por profissionais que trabalham por longos períodos com dados e tarefas operacionais. A experiência deve ser visualmente calma, com hierarquia evidente, superfícies neutras e poucas cores competindo pela atenção. Priorize legibilidade e previsibilidade antes de decoração. Use espaços generosos para separar grupos de informação, mas preserve densidade suficiente para tarefas produtivas. ``` Uma boa descrição cria critérios para decisões futuras. Ela explica como o produto deve _parecer e se comportar visualmente_, e não apenas quais estilos estão na moda. ## 4. Documente cores pelo papel que desempenham Uma lista de hexadecimal sem contexto é pouco útil. O agente precisa entender a função de cada cor dentro da interface. ``` ## Colors A paleta usa superfícies neutras e uma única cor de destaque. - **Primary {colors.primary}:** reservada para ações principais, links relevantes e elementos interativos selecionados. - **Secondary {colors.secondary}:** usada em texto de alta hierarquia e elementos estruturais. - **Surface {colors.surface}:** fundo padrão de cards, modais e componentes elevados. - **Background {colors.background}:** plano de fundo principal da aplicação. - **Text Primary {colors.text-primary}:** utilizado em títulos e conteúdo principal. - **Text Secondary {colors.text-secondary}:** utilizado em metadados, descrições e informações auxiliares. Evite usar a cor Primary em grandes áreas de fundo. Ela deve manter valor de destaque e não competir continuamente com o conteúdo. ``` A especificação permite referências entre tokens usando caminhos como `{colors.primary}`. Isso reduz duplicação e ajuda a conectar o valor estruturado à explicação textual. Ao definir combinações de cor, considere também contraste e estados de interação. Acessibilidade deve ser tratada como uma característica do sistema, não como correção posterior. Se esse tema ainda não está documentado no seu sistema, veja o guia sobre [acessibilidade em Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/acessibilidade-design-systems-inclusao-wcag.md). ## 5. Transforme a tipografia em uma regra de hierarquia Documente mais do que o nome da fonte. Registre como diferentes estilos ajudam o usuário a compreender a interface. ``` ## Typography Use Inter em toda a interface para manter leitura estável em diferentes densidades de informação. - **H1:** títulos de página. Deve existir apenas uma hierarquia principal evidente por tela. - **H2:** divisões de grandes grupos de conteúdo. - **Body:** texto principal e conteúdo de leitura. - **Label:** controles, campos, filtros e informações funcionais. - **Caption:** metadados e informações auxiliares. Evite usar peso bold apenas para decoração. O aumento de peso deve representar aumento real de hierarquia ou necessidade de destaque. ``` Os valores exatos podem ficar no YAML. A seção textual explica o motivo e o contexto de aplicação. ## 6. Documente layout e espaçamento como um sistema Quando não existe uma regra, modelos generativos tendem a escolher espaçamentos caso a caso. O resultado pode parecer correto em uma tela e inconsistente quando várias telas são comparadas. ``` ## Layout A interface utiliza uma escala de espaçamento baseada em múltiplos consistentes, preservando relação visual entre componentes e grupos. - Use 4px apenas para microajustes. - Use 8px entre elementos diretamente relacionados. - Use 16px para separações internas comuns. - Use 24px em grupos de conteúdo e padding de componentes maiores. - Use 32px ou mais para separar áreas semanticamente diferentes. No desktop, limite blocos de leitura para evitar linhas excessivamente longas. Em telas menores, reduza o número de colunas antes de reduzir excessivamente os espaçamentos internos. A proximidade deve comunicar relação: elementos pertencentes ao mesmo grupo ficam visualmente mais próximos entre si do que do próximo grupo. ``` Esse tipo de regra é mais útil do que simplesmente dizer “use grid de 8px”, porque descreve como o ritmo visual deve orientar agrupamento e hierarquia. ## 7. Explique como a interface comunica profundidade A seção `Elevation & Depth` não significa que o sistema precise usar sombras. Ela documenta como diferentes camadas são diferenciadas. ``` ## Elevation & Depth A profundidade deve ser comunicada principalmente por contraste de superfície e bordas. Cards padrão usam fundo branco sobre background neutro e borda discreta. Sombras são reservadas para elementos temporariamente posicionados acima da interface, como modais, menus flutuantes e popovers. Evite sombras pesadas em cards estáticos apenas para criar decoração. ``` Em um produto mais expressivo, essa seção pode documentar sombras, blur, sobreposição e outras técnicas. Em uma interface flat, pode registrar justamente que a profundidade deve ser comunicada sem sombras. ## 8. Documente a linguagem de formas Raios diferentes usados aleatoriamente também criam inconsistência. A seção `Shapes` define a lógica geométrica da interface. ``` ## Shapes A interface utiliza cantos discretamente arredondados para transmitir precisão sem parecer rígida. - 4px: elementos compactos e controles pequenos. - 8px: inputs, botões e componentes padrão. - 16px: cards de destaque e containers maiores. - Full: avatares, badges e elementos explicitamente circulares. Não misture raios diferentes em componentes equivalentes. ``` ## 9. Documente componentes como padrões, não como telas O DESIGN.md não precisa reproduzir toda a documentação de componentes de um Design System. Priorize os padrões que um agente precisa reconhecer para não reinventar decisões básicas. ``` ## Components ### Primary button O botão primário representa a ação mais importante de um contexto de decisão. - Background: {colors.primary} - Text: branco - Radius: {rounded.md} - Padding vertical confortável para interação - Estado de foco sempre visível Use apenas quando existir uma ação claramente prioritária. ### Secondary button Use para ações alternativas que precisam permanecer disponíveis sem competir visualmente com a ação principal. Nunca diferencie o botão secundário apenas reduzindo contraste a ponto de comprometer legibilidade. ### Input Inputs devem possuir label persistente e estado de foco evidente. Placeholder pode complementar o label, nunca substituí-lo. Mensagens de erro devem aparecer próximas ao campo relacionado e explicar o que o usuário precisa corrigir. ### Card Cards devem agrupar informações que realmente pertencem ao mesmo contexto. Evite transformar qualquer bloco visual em card quando agrupamento, espaçamento ou uma borda simples resolverem a hierarquia. ``` Se o projeto possui muitos componentes, o DESIGN.md deve fornecer direção suficiente para o agente consultar ou reutilizar o sistema existente, em vez de tentar replicar toda a documentação técnica. Em produtos maiores, veja também como estruturar um [Design System completo](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md). ## 10. Use Do’s and Don’ts para reduzir interpretações erradas A seção final é particularmente útil para registrar decisões que não são evidentes apenas observando tokens. ``` ## Do's and Don'ts ### Do - Preserve uma ação principal evidente por contexto. - Reutilize componentes antes de criar novas variações. - Use espaçamento para comunicar agrupamento. - Mantenha estados de foco visíveis. - Preserve contraste adequado entre texto e superfície. - Use a cor primária com função clara. ### Don't - Não invente novas cores quando a paleta existente resolver o problema. - Não misture múltiplos raios em componentes equivalentes. - Não use placeholder como substituto de label. - Não crie novas variantes de botão sem necessidade. - Não dependa apenas da cor para comunicar erro, sucesso ou seleção. - Não adicione elementos decorativos que concorram com tarefas principais. ``` Esse é um bom lugar para registrar erros que já aconteceram durante o desenvolvimento e que não devem reaparecer em gerações futuras. ## Exemplo completo de um DESIGN.md Juntando as duas camadas, um arquivo inicial pode ter esta estrutura: ``` --- version: alpha name: Atlas description: Plataforma B2B de gestão com foco em clareza operacional colors: primary: "#5257FF" surface: "#FFFFFF" background: "#F7F7F9" text-primary: "#171821" text-secondary: "#5F6270" border: "#E5E7EB" typography: h1: fontFamily: Inter fontSize: 48px fontWeight: 700 lineHeight: 1.1 h2: fontFamily: Inter fontSize: 32px fontWeight: 600 lineHeight: 1.2 body-md: fontFamily: Inter fontSize: 16px fontWeight: 400 lineHeight: 1.6 spacing: xs: 4px sm: 8px md: 16px lg: 24px xl: 32px rounded: sm: 4px md: 8px lg: 16px components: button-primary: backgroundColor: "{colors.primary}" rounded: "{rounded.md}" padding: 12px --- # Atlas Design System ## Overview Interface profissional, clara e previsível para pessoas que trabalham diariamente com operações e dados. Use hierarquia forte, superfícies neutras e baixa quantidade de elementos decorativos. A interface deve parecer confiável e eficiente sem assumir estética excessivamente corporativa. ## Colors A cor Primary {colors.primary} é reservada para ações principais, seleção e links importantes. Surface {colors.surface} é utilizada nos componentes que precisam se destacar do background {colors.background}. Text Primary {colors.text-primary} representa conteúdo principal. Text Secondary {colors.text-secondary} é reservado a metadados e informações auxiliares. ## Typography Inter é utilizada em toda a interface. H1 representa o título principal de uma página. H2 organiza grandes grupos. Body é usado para leitura e conteúdo funcional. Não use peso bold apenas para decoração. ## Layout Use a escala de espaçamento definida nos tokens para criar ritmo consistente. Elementos relacionados devem ficar mais próximos entre si do que do próximo grupo de informação. No mobile, reduza colunas e reorganize o layout antes de comprimir excessivamente componentes. ## Elevation & Depth Priorize contraste de superfície e bordas para comunicar camadas. Sombras são reservadas para elementos temporariamente elevados, como modais e menus flutuantes. ## Shapes Use 8px como raio padrão de controles e componentes. Use 16px em containers maiores quando a composição exigir destaque. Evite misturar diferentes raios em componentes equivalentes. ## Components Botões primários representam a ação de maior prioridade em um contexto. Inputs sempre possuem label persistente, foco visível e mensagens de erro próximas ao campo. Cards agrupam conteúdo semanticamente relacionado. Não use card apenas como decoração. ## Do's and Don'ts ### Do - Reutilize componentes existentes. - Preserve hierarquia visual clara. - Garanta estados de foco. - Use cores com função semântica. - Mantenha padrões responsivos. ### Don't - Não invente novas cores sem necessidade. - Não dependa apenas de cor para transmitir estado. - Não substitua labels por placeholders. - Não crie componentes redundantes. - Não use decoração que concorra com a tarefa. ``` Esse exemplo é deliberadamente compacto. O tamanho ideal depende da complexidade do produto. Um arquivo maior não é automaticamente melhor: quanto mais regras forem adicionadas, maior também será o trabalho para mantê-las coerentes e atualizadas. ## Como validar um DESIGN.md com o CLI oficial O projeto oficial do Google Labs disponibiliza o pacote `@google/design.md`, que pode ser usado para verificar a estrutura do arquivo. Instale o pacote: ``` npm install @google/design.md ``` Depois execute o linter: ``` npx @google/design.md lint DESIGN.md ``` O validador verifica problemas estruturais, como referências quebradas e inconsistências previstas pelas regras atuais da especificação. Também é possível comparar versões: ``` npx @google/design.md diff DESIGN-anterior.md DESIGN.md ``` Ou exportar os tokens para outros formatos suportados pelo CLI. Por exemplo, para o formato DTCG: ``` npx @google/design.md export --format dtcg DESIGN.md > tokens.json ``` O Design Tokens Community Group publicou em 2025 sua primeira versão estável do formato de interoperabilidade de design tokens. O relatório é hospedado pelo W3C como uma especificação de Community Group, não como uma Recomendação W3C. Consulte a [documentação do Design Tokens Format Module](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) para entender a diferença. ## Como aplicar o DESIGN.md em projetos com IA Criar o arquivo é apenas metade do trabalho. O agente precisa receber esse contexto durante a geração. A especificação do DESIGN.md foi aberta justamente para que as regras visuais possam circular entre ferramentas, mas cada ambiente possui sua própria forma de importar, referenciar ou incluir arquivos no contexto. Por isso, evite depender da ideia de que qualquer agente “lerá o DESIGN.md automaticamente”. Configure explicitamente a ferramenta que será usada no projeto. ### Google Stitch O Google Stitch possui suporte nativo ao formato. O próprio Google descreve o DESIGN.md como uma maneira de importar e exportar regras entre projetos e levar essa linguagem visual para outras plataformas. Para o fluxo específico de criação, importação e uso dentro da ferramenta, veja o guia [como usar DESIGN.md com Google Stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-google-stitch.md). ### Claude Code, Cursor e outros agentes Em agentes de codificação, mantenha o arquivo versionado junto ao projeto e configure as instruções do ambiente para que o DESIGN.md seja consultado quando uma tarefa envolver UI. A forma correta muda conforme a ferramenta: algumas possuem arquivos de instruções de projeto, outras permitem anexar explicitamente documentos ao contexto ou definir regras persistentes. Para não transformar este guia de criação em um manual de configuração de cada agente, esse fluxo fica separado no conteúdo sobre [DESIGN.md aplicado a agentes de IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-agentes-ia-ux.md). ## Como manter o DESIGN.md atualizado O DESIGN.md só funciona como fonte de contexto enquanto representa o produto real. Quando uma cor é alterada no sistema, um componente recebe uma nova regra ou a linguagem visual muda, o documento precisa acompanhar essa decisão. - Versione o arquivo junto ao projeto. - Revise mudanças relevantes em tokens e componentes. - Evite documentar comportamentos experimentais como regras permanentes. - Remova orientações que deixaram de existir no produto. - Valide novamente o arquivo depois de mudanças estruturais. - Mantenha texto e tokens coerentes entre si. Quando um token diz uma coisa e o texto orienta outra, o arquivo deixa de funcionar como fonte confiável de contexto. ## Erros comuns ao criar um DESIGN.md ### Copiar um template sem adaptar ao produto Templates aceleram o início, mas não devem transformar o produto em uma imitação visual da referência. Ajuste tokens, linguagem, componentes e restrições para refletir decisões reais. ### Documentar apenas valores Uma lista de cores e tamanhos não explica intenção. Use o Markdown para registrar como e por que essas decisões devem ser aplicadas. ### Escrever regras genéricas “Faça uma interface moderna” não cria um critério verificável. Explique hierarquia, densidade, contraste, comportamento dos componentes e situações que devem ser evitadas. ### Transformar o arquivo em documentação infinita O DESIGN.md não precisa carregar histórico da marca, atas de reunião, pesquisa completa ou toda a documentação técnica do Design System. Inclua o contexto necessário para preservar a linguagem visual e orientar decisões de interface. ### Inventar componentes que ainda não existem Quando o produto já possui um sistema, o documento deve reduzir divergência, não criar uma segunda biblioteca de UI. ### Não validar depois de editar Uma simples referência de token escrita incorretamente pode gerar inconsistência ou erro de validação. Use o linter oficial quando estiver trabalhando com a estrutura formal. ### Tratar a especificação como algo encerrado O repositório oficial ainda identifica o formato como **alpha**. Antes de construir integrações rígidas ou automações, confira a versão atual da especificação e do CLI. ## DESIGN.md substitui um Design System? Não. Um Design System pode envolver bibliotecas no Figma, componentes codificados, documentação, governança, processo de contribuição, versionamento, acessibilidade, padrões de interação e integração entre diferentes plataformas. O DESIGN.md resolve outro problema: **expressar a linguagem visual e parte das decisões estruturadas em um documento aberto que humanos e agentes conseguem consumir**. Em projetos pequenos, ele pode cobrir boa parte do contexto necessário para gerar interfaces consistentes. Em produtos complexos, funciona melhor como uma camada complementar ao sistema já existente. Essa distinção evita um erro comum: acreditar que documentar cores, tipografia e componentes em Markdown resolve governança, manutenção e qualidade de um Design System em escala. ## Checklist para revisar seu DESIGN.md - A direção visual está descrita de forma específica? - Os tokens representam valores realmente usados no produto? - As cores possuem papéis claros? - A hierarquia tipográfica está documentada? - Layout e espaçamento seguem uma lógica consistente? - A forma de comunicar profundidade está clara? - Os raios e formas seguem uma linguagem comum? - Os principais componentes possuem orientação suficiente? - Existem Do’s and Don’ts que eliminam ambiguidades? - Texto e tokens não se contradizem? - O arquivo foi validado quando utiliza a estrutura formal? - O agente utilizado no projeto foi configurado para receber esse contexto? Se essas respostas estiverem claras, o arquivo já possui uma base muito mais útil do que simplesmente uma coleção de estilos. ## Referências oficiais sobre DESIGN.md Como o formato ainda está evoluindo, priorize as fontes primárias para verificar detalhes técnicos: - [Google Labs: Stitch’s DESIGN.md format is now open-source](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/) - [Repositório oficial google-labs-code/design.md](https://github.com/google-labs-code/design.md) - [Especificação atual do formato DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) - [Design Tokens Format Module 2025.10](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) ## Conclusão: crie o arquivo a partir do sistema, não do prompt Um DESIGN.md útil começa pelas decisões reais do produto. O Markdown vem depois. Primeiro identifique a linguagem visual que precisa ser preservada. Depois organize tokens, contexto, componentes e restrições em uma estrutura que possa acompanhar o projeto. Quando bem mantido, o arquivo reduz a necessidade de explicar a mesma identidade visual em cada nova geração e cria uma referência compartilhada para diferentes fluxos com IA. Se você prefere começar a partir de uma referência já estruturada, explore a [biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). Para criar um arquivo automaticamente como ponto de partida, use também o [Gerador DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/gerador-design-md.md). Depois de criar o arquivo, o próximo passo é configurá-lo no ambiente em que você trabalha. Para Google Stitch, siga o guia de [DESIGN.md no Google Stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-google-stitch.md). Para agentes de codificação, continue pelo conteúdo sobre [DESIGN.md e agentes de IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-agentes-ia-ux.md). ### O que deve ter em um arquivo DESIGN.md? Um DESIGN.md pode combinar tokens estruturados em YAML com orientações em Markdown. A especificação atual organiza o corpo em Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components e Do’s and Don’ts. Seções que não forem relevantes podem ser omitidas. ### O YAML é obrigatório no DESIGN.md? Não. A especificação oficial define o YAML front matter como opcional. Ele é útil para registrar tokens e valores estruturados, enquanto o corpo em Markdown documenta contexto, intenção e regras de aplicação. ### Onde colocar o DESIGN.md no projeto? A especificação define o formato, não uma localização obrigatória. Em projetos versionados, manter o DESIGN.md na raiz do repositório facilita descoberta e manutenção. A forma como ele é carregado por um agente depende da ferramenta utilizada. ### Como validar um DESIGN.md? O projeto oficial disponibiliza o pacote @google/design.md. O comando npx @google/design.md lint DESIGN.md verifica a estrutura do arquivo de acordo com as regras implementadas na versão atual do CLI. ### DESIGN.md substitui um Design System? Não. DESIGN.md pode documentar parte da linguagem visual e dos tokens de um produto em um formato consumível por humanos e agentes de IA. Um Design System completo também pode incluir bibliotecas de componentes, código, governança, documentação, acessibilidade e processos de contribuição. ## Topics **Categorias:** [Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/design-systems.md) **Tags:** [claude code](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/claude-code.md), [cursor](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/cursor.md), [Design System](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-system.md), [design.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-md.md), [google stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/google-stitch.md), [IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/ia.md), [UX Design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/ux-design.md), [Vibe Coding](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/vibe-coding.md)