--- title: "Como avaliar um DESIGN.md: auditoria de qualidade, acessibilidade e consistência" date: 2026-08-20T13:04:00Z modified: 2026-08-20T13:05:31Z permalink: "https://camaraux.com.br/como-avaliar-design-md/" type: post status: publish excerpt: Aprenda a avaliar um DESIGN.md com um método prático de auditoria que analisa estrutura, tokens, componentes, acessibilidade, responsividade e uso por agentes de IA. wpid: 12411 categories: - Design Systems tags: - Design Systems - Acessibilidade - agentes de IA - Design System - Design Tokens - design.md - inteligência artificial - UX Design rank_math_title: "Como avaliar um DESIGN.md: checklist de qualidade" rank_math_description: Aprenda a avaliar um DESIGN.md com critérios de estrutura, tokens, componentes, acessibilidade, responsividade e uso por agentes de IA. rank_math_focus_keyword: DESIGN.md,avaliar um DESIGN.md,como avaliar um DESIGN.md,checklist DESIGN.md,validar DESIGN.md,auditoria DESIGN.md,qualidade DESIGN.md,DESIGN.md acessibilidade,DESIGN.md design system featured_image: /wp-content/uploads/2026/08/Como-avaliar-um-DESIGN-md.png featured_image_alt: Pessoa observando painel com blocos que representam elementos de um design system author: Lucas Camara timestamp: 2026-08-20T13:05:31Z --- Um `DESIGN.md` pode passar em todas as validações técnicas do linter oficial e ainda ser um arquivo ruim. A validação técnica consegue encontrar problemas importantes, como referências quebradas, inconsistências estruturais e combinações de cor que não atendem ao contraste mínimo configurado no linter. Mas ela não consegue responder sozinha se o documento representa o produto real, explica a intenção do design, cobre estados importantes, orienta comportamento responsivo ou reduz as ambiguidades que fazem um agente de IA improvisar. Por isso, avaliar um DESIGN.md exige olhar para três níveis diferentes: **validade, qualidade e resultado**. Primeiro verificamos se o arquivo pode ser interpretado de forma confiável. Depois, se as decisões documentadas são coerentes e suficientes. Por fim, testamos se um agente que recebe esse contexto consegue produzir interfaces sem reconstruir o design system por conta própria. Este guia apresenta um método de auditoria criado pela CamaraUX para fazer essa avaliação. O **Score CamaraUX de Qualidade do DESIGN.md** organiza dez dimensões em uma pontuação de 0 a 100. Ele não faz parte da especificação oficial do Google e não pretende substituir o linter. A função é complementar a validação técnica com critérios de design, UX, acessibilidade, documentação e uso real por agentes. Se você ainda está conhecendo o formato, comece pelo [guia e biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). Se ainda não criou o arquivo, veja primeiro [como criar um DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-aplicar-design-md-ia.md). Aqui partimos de outra pergunta: **o arquivo já existe, mas ele está realmente bom?** ## O que significa ter um DESIGN.md de qualidade? Um bom DESIGN.md não é o arquivo com mais linhas, mais tokens ou mais componentes descritos. Ele é o arquivo que **preserva decisões reais do produto e reduz o espaço de interpretação do agente sem transformar a documentação em uma especificação infinita**. A especificação oficial define o DESIGN.md como uma representação em texto de um design system, combinando tokens legíveis por máquina com racional e orientação em Markdown. No [repositório oficial do Google Labs](https://github.com/google-labs-code/design.md), o formato continua identificado como **alpha** e está em desenvolvimento ativo. Isso significa que qualquer auditoria precisa separar duas coisas: aderência ao formato atual e qualidade do conteúdo que foi colocado dentro dele. Essa distinção é ainda mais importante porque a própria [filosofia do projeto DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md) enfatiza o papel da prosa. Valores exatos ajudam o agente, mas não substituem uma descrição clara da intenção, dos limites e das relações entre decisões. | Nível | Pergunta | Exemplo de evidência | | --- | --- | --- | | **Validade** | O arquivo está estruturalmente correto? | Lint, referências, schema, ordem e sintaxe. | | **Qualidade** | O documento representa bem o sistema? | Fidelidade, semântica, componentes, estados, restrições e acessibilidade. | | **Resultado** | O agente consegue aplicar esse contexto? | Teste controlado de geração, comparação visual e análise do que foi inventado. | ## O linter oficial é o primeiro teste, não a auditoria inteira O projeto oficial disponibiliza o pacote `@google/design.md`. Antes de discutir qualidade editorial ou consistência visual, vale começar por ele porque problemas estruturais podem invalidar qualquer avaliação posterior. ``` npx @google/design.md lint DESIGN.md ``` O conjunto de verificações evolui junto com a especificação, mas atualmente inclui sinais como referências de token que não resolvem, ausência de tokens importantes, contraste em pares de cor de componentes, tokens não utilizados e problemas na organização do arquivo. Como o formato permanece em alpha, consulte o [arquivo de configuração atual da especificação e do linter](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.yaml) quando uma integração depender de detalhes exatos. Também é possível comparar versões: ``` npx @google/design.md diff DESIGN-anterior.md DESIGN.md ``` Ou exportar os tokens para o formato do Design Tokens Community Group: ``` npx @google/design.md export --format dtcg DESIGN.md > tokens.json ``` Esses testes são valiosos porque removem erros objetivos. O problema aparece quando usamos o resultado como selo de qualidade. Um arquivo pode não ter referência quebrada e ainda dizer apenas que a interface deve ser “moderna, limpa e premium”. Pode possuir uma paleta válida e não explicar quando cada cor deve ser usada. Pode ter um botão primário documentado e omitir foco, loading, erro, disabled e comportamento em telas menores. > **Passar no lint significa que parte da estrutura está consistente. Não significa que o agente recebeu contexto suficiente para tomar boas decisões.** ## Antes de pontuar, defina qual é a fonte de verdade A primeira pergunta da auditoria não está dentro do Markdown. Está fora dele: **de onde vieram as decisões documentadas?** Em um produto existente, o DESIGN.md deveria refletir o sistema que já está sendo utilizado. Isso pode envolver componentes em produção, bibliotecas no Figma, variables, design tokens, documentação técnica e regras que a equipe já aplica. Se o arquivo inventa uma segunda paleta, novos raios ou componentes que não existem, ele pode ser bem escrito e mesmo assim funcionar como uma fonte de divergência. Em projetos sem design system formal, a auditoria muda. Nesse caso, não existe uma base madura para comparar, mas ainda precisamos identificar quais decisões são deliberadas e quais foram apenas inferidas a partir de uma tela, template ou geração anterior. Quando o objetivo é documentar um sistema existente, veja também o processo para [documentar o Design System de um site sem começar do zero](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/documentar-design-system-site-existente.md). ## Score CamaraUX de Qualidade do DESIGN.md: 100 pontos O score abaixo é uma metodologia de auditoria da CamaraUX, não uma extensão oficial da especificação. Ele serve para tornar a revisão comparável ao longo do tempo e evitar que a avaliação termine em opiniões vagas como “parece completo”. | Critério | Peso | O que precisa ser demonstrado | | --- | --- | --- | | **1. Fidelidade à fonte de verdade** | 15 | Tokens, componentes e regras correspondem ao produto ou ao sistema deliberadamente definido. | | **2. Validade técnica e estrutural** | 10 | O arquivo é interpretável, passa pelas verificações aplicáveis e não contém referências quebradas. | | **3. Tokens semânticos e coerentes** | 10 | Os nomes carregam função, escalas são consistentes e valores evitam duplicação arbitrária. | | **4. Intenção, racional e restrições** | 15 | A prosa explica como decidir quando um token isolado não é suficiente. | | **5. Componentes, variantes e estados** | 15 | Componentes críticos possuem regras de uso, variantes e estados relevantes. | | **6. Acessibilidade** | 15 | Regras importantes são verificáveis e não tratam acessibilidade apenas como uma frase genérica. | | **7. Responsividade e edge cases** | 8 | O agente sabe como adaptar layout, conteúdo longo, estados vazios, erro e diferentes tamanhos. | | **8. Guardrails e anti-patterns** | 5 | O documento registra decisões que não devem ser reinventadas. | | **9. Operação por agentes** | 4 | Existe uma forma real e verificável de o agente receber o arquivo como contexto. | | **10. Manutenção e versionamento** | 3 | O arquivo possui dono, histórico e rotina de revisão compatível com o produto. | | **Total** | **100** | | Uma forma simples de pontuar cada dimensão é conceder 0%, 50% ou 100% do peso. Use valores intermediários apenas quando houver evidência suficiente para justificar a diferença. O objetivo não é fabricar precisão matemática, mas tornar visíveis as lacunas. - **90 a 100:** robusto. O arquivo pode funcionar como uma fonte confiável de contexto, desde que os gates críticos também estejam aprovados. - **75 a 89:** bom, com lacunas controladas. É utilizável, mas ainda existe espaço relevante de interpretação. - **60 a 74:** precisa de revisão antes de ser tratado como fonte confiável. - **Abaixo de 60:** alto risco de o agente preencher decisões por conta própria. ## 1. Fidelidade à fonte de verdade: 15 pontos Este é o critério mais importante porque um documento consistente, mas inconsistente com o produto, apenas formaliza o erro. Escolha uma amostra de decisões que possam ser verificadas fora do arquivo. Compare cores, tipografia, spacing, raios e pelo menos três componentes críticos com a implementação ou biblioteca utilizada pela equipe. Não procure apenas valores iguais. Verifique também se o papel semântico continua o mesmo. | Pergunta | Evidência esperada | | --- | --- | | As cores vêm do sistema real? | Comparação com tokens, CSS, variables ou biblioteca oficial do produto. | | A tipografia representa a hierarquia existente? | Famílias, pesos, tamanhos e papéis coerentes com o produto. | | Os componentes citados existem? | Correspondência com Figma, código ou documentação. | | O arquivo cria exceções novas? | Nenhum valor ou comportamento relevante aparece apenas no DESIGN.md sem justificativa. | Se você extraiu o arquivo automaticamente de um site, trate a extração como evidência inicial, não como verdade final. CSS de produção pode conter legado, experimentos, componentes de terceiros e exceções locais. A auditoria precisa distinguir o que é padrão do que é ruído. ## 2. Validade técnica e estrutural: 10 pontos Depois da fidelidade, verifique se a estrutura pode ser consumida de forma previsível. Execute o linter, corrija referências quebradas e revise warnings relevantes antes de continuar. Também confira a [especificação atual do formato](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md). Como o projeto está em evolução, evitar uma cópia antiga da spec é especialmente importante quando você usa automações, parsers ou CI. Um arquivo pode receber os 10 pontos quando não possui erros estruturais conhecidos, utiliza referências válidas e não depende de sintaxe que a ferramenta de consumo ignora silenciosamente. ## 3. Tokens semânticos e coerentes: 10 pontos Tokens de qualidade não são apenas variáveis com nomes bonitos. Eles representam decisões reutilizáveis de forma que o consumidor entenda a função, não apenas o valor. Design systems maduros seguem essa lógica. O [Carbon Design System](https://carbondesignsystem.com/elements/color/tokens/), por exemplo, organiza tokens de cor por papéis como background, layer, field, border, text, link, support e focus. O [Atlassian Design System](https://atlassian.design/tokens/design-tokens) também trata tokens como fonte de verdade para decisões repetíveis. A [Adobe Spectrum](https://spectrum.adobe.com/page/design-tokens/) diferencia tokens globais, aliases e tokens específicos de componente. Isso não significa copiar a arquitetura dessas empresas. O ponto é avaliar se seu arquivo possui uma lógica própria que continue compreensível quando os valores mudarem. ``` # Fraco colors: blue-1: "#165DFF" blue-2: "#0F4ED8" # Mais semântico colors: action-primary: "#165DFF" action-primary-hover: "#0F4ED8" text-primary: "#171821" surface-default: "#FFFFFF" ``` Nem todo sistema precisa usar esse modelo de nomenclatura, mas o avaliador precisa conseguir responder: **se o hexadecimal mudar amanhã, o nome do token ainda explica por que ele existe?** Quando a arquitetura de tokens for parte central do problema, aprofunde no guia sobre [design tokens e interoperabilidade](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-tokens-arquitetura-w3c.md). O [Design Tokens Format Module](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) é uma referência importante para intercâmbio de tokens entre ferramentas, mas deve ser descrito corretamente como uma especificação do Community Group, não como uma Recomendação W3C. ## 4. Intenção, racional e restrições em prosa: 15 pontos Esta dimensão separa um arquivo que apenas armazena valores de um arquivo que realmente orienta decisões. Compare estas duas instruções: ``` Interface moderna, premium e minimalista. ``` A frase transmite uma preferência estética, mas quase nenhuma regra operacional. Um agente ainda precisa decidir o que significa premium, quanto espaço é minimalista, onde usar cor, quando elevar um card e que tipo de hierarquia é esperado. ``` A interface deve priorizar leitura e tarefas operacionais. Use superfícies neutras como base e reserve a cor de ação para decisões interativas. Evite competir com o conteúdo usando grandes áreas coloridas ou múltiplos acentos. ``` A segunda versão continua permitindo variações, mas cria critérios. É isso que deve ser avaliado: **a prosa ajuda alguém a decidir quando não existe uma regra exata?** Procure principalmente: - qual sensação o produto deve transmitir e por quê; - qual é a hierarquia entre conteúdo, navegação e ações; - quando um token pode e não pode ser usado; - quais decisões são obrigatórias e quais admitem interpretação; - quais exceções existem e por que elas existem. ## 5. Componentes, variantes e estados: 15 pontos Tokens resolvem parte do problema. Interfaces reais são compostas por elementos que mudam de estado, recebem conteúdo variável e precisam funcionar em tarefas diferentes. Para os componentes mais importantes, verifique se o arquivo deixa claro: | Camada | O que avaliar | | --- | --- | | **Função** | Quando o componente deve ser usado e qual problema resolve. | | **Variantes** | Primário, secundário, destrutivo, compacto ou outras variantes reais do sistema. | | **Estados** | Default, hover, focus, active, disabled, loading, error ou estados aplicáveis. | | **Conteúdo** | Labels, limites de texto, ajuda e comportamento com conteúdo longo. | | **Comportamento** | O que acontece na interação, inclusive quando a ação falha. | Não é necessário reproduzir todo o Storybook dentro do DESIGN.md. Em sistemas grandes, uma orientação melhor pode ser explicar o papel do componente e apontar para a fonte apropriada. A qualidade está em oferecer contexto suficiente para impedir que o agente invente uma variante nova quando o sistema já possui uma solução. Se o arquivo começou a virar uma cópia integral de toda a documentação técnica, revise a arquitetura. Um [Design System completo](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md) pode incluir código, bibliotecas, governança, processos de contribuição e documentação mais profunda. DESIGN.md é uma camada de contexto para agentes, não um substituto de todas essas estruturas. ## 6. Acessibilidade e critérios testáveis: 15 pontos “A interface deve ser acessível” vale pouco como instrução porque não diz o que o agente precisa preservar. A auditoria deve procurar critérios verificáveis. Para conteúdo web, a [WCAG 2.2](https://www.w3.org/TR/WCAG22/) é a referência normativa atual. Entre os pontos que podem aparecer na documentação de um sistema estão contraste de texto, contraste não textual, foco visível, elementos não totalmente encobertos quando recebem foco e tamanho mínimo de alvos em contextos aplicáveis. O linter do DESIGN.md ajuda em parte desse trabalho ao avaliar combinações de `backgroundColor` e `textColor` que estão representadas de forma estruturada. Isso não significa que o arquivo ou o produto inteiro está em conformidade. Um contraste válido não verifica ordem de foco, labels, semântica, teclado, mensagens de erro, nomes acessíveis ou a implementação real do componente. | Regra fraca | Regra auditável | | --- | --- | | Garanta acessibilidade. | Texto de corpo deve manter contraste mínimo AA; não use apenas cor para comunicar estado. | | Botões devem ser acessíveis. | Todo botão interativo precisa de estado de foco visível e nome compreensível. | | Erros devem ser claros. | Mensagem de erro deve identificar o problema e orientar correção sem depender apenas de cor. | Também vale cruzar essas orientações com a documentação de [acessibilidade em Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/acessibilidade-design-systems-inclusao-wcag.md). A regra de auditoria é simples: quanto mais importante a recomendação, mais testável ela deve ser. ## 7. Responsividade e edge cases: 8 pontos Um arquivo pode produzir uma tela de demonstração impecável e falhar quando o produto encontra conteúdo real. Por isso, a auditoria precisa buscar decisões para situações como: - redução de colunas em telas menores; - conteúdo longo em títulos, botões e tabelas; - estados vazios, loading e erro; - informação crítica que não pode desaparecer no mobile; - componentes fixos que podem encobrir conteúdo; - densidade e espaçamento em diferentes breakpoints; - variações de idioma e expansão de texto quando o produto é internacional. Não é necessário transformar o documento em uma folha de estilos responsiva. O objetivo é registrar o comportamento que precisa permanecer consistente quando o agente reorganiza uma interface. ## 8. Guardrails e anti-patterns: 5 pontos A seção de Do’s and Don’ts existe para registrar decisões que seriam difíceis de deduzir apenas olhando valores. Um bom guardrail descreve uma condição específica. “Não crie UI genérica” é subjetivo. “Não introduza uma nova cor de ação quando o token de ação existente atender ao estado” é verificável. Também vale registrar erros recorrentes observados no trabalho com agentes. Se o modelo insiste em transformar toda seção em card, criar múltiplos CTAs primários ou adicionar gradientes que não existem na marca, essas ocorrências podem virar restrições explícitas quando realmente representam uma decisão do sistema. ## 9. Operação por agentes: 4 pontos Um DESIGN.md excelente que nunca chega ao contexto do agente vale pouco. Não assuma que qualquer ferramenta encontrará e aplicará o arquivo automaticamente apenas porque ele está na raiz do repositório. A forma de descoberta e inclusão de contexto varia. Uma prática mais defensável é tornar a relação explícita no arquivo de instruções da ferramenta ou do projeto. Para configurações específicas, veja [como usar DESIGN.md com Claude Code, Cursor e outros agentes](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-agentes-ia-ux.md). Se o fluxo está no Stitch, use o guia de [DESIGN.md no Google Stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-google-stitch.md). Durante a auditoria, teste a operação em vez de confiar na configuração: peça ao agente para resumir as principais restrições visuais que recebeu antes de gerar uma interface. Se ele não consegue recuperar regras centrais do documento, o problema pode estar na forma como o contexto foi fornecido. ## 10. Manutenção e versionamento: 3 pontos DESIGN.md deve ser tratado como documentação viva. Um arquivo perfeito no dia da criação se torna uma fonte de erro quando o produto muda e ele não acompanha. Verifique três coisas: - quem é responsável por revisar mudanças relevantes; - como alterações ficam registradas no versionamento; - em quais eventos o arquivo precisa ser revisto, como mudança de tokens, novos componentes ou alteração de direção visual. O comando `diff` do CLI oficial ajuda a comparar versões, mas a revisão humana continua necessária quando a mudança envolve intenção ou comportamento, não apenas valores. ## Gates críticos: quando o arquivo deve ser reprovado mesmo com uma boa nota Uma média pode esconder problemas graves. Por isso, o Score CamaraUX utiliza gates críticos. Se qualquer condição abaixo ocorrer, o arquivo deve ser tratado como **não aprovado** até a correção, independentemente da soma final. - **Erro estrutural ou referência quebrada:** o consumidor não consegue interpretar parte relevante do sistema de forma confiável. - **Contradição com o produto:** o DESIGN.md orienta valores, componentes ou comportamentos diferentes da fonte de verdade sem justificativa. - **Falha de acessibilidade documentada:** uma combinação ou regra essencial já nasce incompatível com os critérios adotados pelo produto. - **Contexto não entregue:** a ferramenta usada no projeto não recebe o arquivo quando executa tarefas de UI. - **Instruções conflitantes:** duas partes do documento orientam decisões incompatíveis para o mesmo contexto. ## Como fazer a auditoria na prática Você não precisa ler cada linha com o mesmo nível de atenção desde o início. Uma auditoria eficiente pode funcionar em cinco passagens. ### Passagem 1: valide a estrutura Execute o linter, revise a especificação usada pelo projeto e corrija erros objetivos. Não comece discutindo estética enquanto existem referências que não resolvem ou valores que o parser não interpreta como esperado. ### Passagem 2: compare com a fonte de verdade Selecione uma amostra representativa do sistema. Compare tokens, tipografia, componentes e comportamentos com código, Figma ou documentação real. Registre qualquer divergência e identifique se ela é erro, legado ou decisão consciente. ### Passagem 3: procure o que o agente ainda precisa adivinhar Leia o arquivo como alguém que não conhece o produto. Depois de cada seção, pergunte: “qual decisão importante ainda depende de gosto pessoal ou de inferência?”. Esse exercício costuma revelar frases aspiracionais, componentes sem estados e tokens sem papel semântico. ### Passagem 4: aplique o score e os gates Pontue as dez dimensões usando evidências. Uma nota menor com problemas bem identificados é mais útil do que uma nota alta baseada em impressão geral. ### Passagem 5: teste uma geração controlada Escolha uma tela ou componente que ainda não esteja literalmente documentado. Peça ao agente para criar a solução utilizando apenas o contexto do projeto e o DESIGN.md. O objetivo não é avaliar se a tela ficou “bonita”. É descobrir **quais decisões o agente precisou inventar**. > **Teste sugerido:** gere uma nova tela que use pelo menos um formulário, uma ação principal, uma ação secundária, um estado de erro e uma adaptação mobile. Depois compare cores, tipografia, spacing, componentes, estados, foco, conteúdo e comportamento com o sistema esperado. Se o agente acerta os valores, mas inventa o comportamento do erro, o problema provavelmente não está nos tokens. Se usa componentes corretos, mas cria um CTA primário extra, falta uma regra de hierarquia. Se o mobile colapsa sem prioridade, faltam orientações responsivas. ## Assista a um fluxo real com DESIGN.md no ecossistema do Google O vídeo abaixo, publicado pelo Google Cloud Tech, mostra um fluxo com Stitch, restrições de design por DESIGN.md e integração com ferramentas de desenvolvimento. Ele é útil para visualizar por que o arquivo precisa carregar decisões operacionais, não apenas uma paleta. ## Exemplo de pontuação: um arquivo tecnicamente válido, mas incompleto Imagine um DESIGN.md que passa no lint, reproduz corretamente a paleta e a tipografia do produto, mas possui componentes descritos apenas no estado padrão. A prosa usa termos genéricos, acessibilidade aparece em uma frase ampla e não existe orientação responsiva. | Critério | Pontos | Leitura | | --- | --- | --- | | Fidelidade | 15/15 | Valores conferidos com a fonte de verdade. | | Validade técnica | 10/10 | Sem erros estruturais relevantes. | | Tokens semânticos | 8/10 | Boa base, alguns nomes ainda são puramente visuais. | | Intenção e racional | 7/15 | Prosa genérica em decisões importantes. | | Componentes e estados | 7/15 | Estados interativos e erro ausentes. | | Acessibilidade | 6/15 | Contraste verificado, outros critérios não documentados. | | Responsividade | 2/8 | Pouca orientação. | | Guardrails | 3/5 | Alguns anti-patterns úteis. | | Operação por agentes | 4/4 | Contexto carregado explicitamente. | | Manutenção | 2/3 | Versionado, sem rotina de revisão definida. | | **Total** | **64/100** | **Precisa de revisão.** | Perceba que o problema não é “falta de tokens”. A estrutura técnica está boa. O risco está justamente nas decisões que o agente ainda precisa completar sozinho. ## Checklist final para revisar seu DESIGN.md - O arquivo representa o produto ou sistema que realmente existe? - O linter está sem erros estruturais relevantes? - As referências entre tokens resolvem corretamente? - Os nomes de tokens comunicam papel e intenção? - As escalas de spacing, tipografia e raios são coerentes? - A prosa oferece critérios quando um valor isolado não basta? - Componentes críticos possuem variantes e estados relevantes? - Regras de acessibilidade importantes são testáveis? - Existe orientação para mobile, conteúdo longo, loading, vazio e erro? - Os Do’s and Don’ts reduzem erros recorrentes em vez de repetir frases genéricas? - A ferramenta utilizada no projeto realmente recebe o DESIGN.md como contexto? - O arquivo é versionado e revisado quando o sistema muda? - Uma geração controlada reproduz o sistema sem inventar decisões centrais? ## O que fazer quando a auditoria encontra lacunas Não tente corrigir a nota adicionando texto por volume. Corrija a causa da ambiguidade. Se o problema está em tokens, revise a arquitetura e sua relação com o sistema real. Se está em componentes, documente estados e regras de uso. Se a falha aparece em acessibilidade, transforme princípios genéricos em critérios verificáveis. Se o agente não recebe o contexto, ajuste a configuração antes de reescrever o documento inteiro. Depois da revisão, execute novamente o lint e o teste controlado. A comparação entre versões ajuda a mostrar o que mudou, mas a melhoria real aparece quando o agente deixa de improvisar decisões que deveriam pertencer ao sistema. Se você concluiu a auditoria e percebeu que o arquivo precisa ser reestruturado, volte ao guia de [como criar um DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-aplicar-design-md-ia.md). Para escolher um ponto de partida diferente, explore a [biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). ## Referências - [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/) - [Google Labs – repositório oficial google-labs-code/design.md](https://github.com/google-labs-code/design.md) - [Google Labs – especificação do formato DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) - [Google Labs – filosofia do DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md) - [Design Tokens Community Group – Design Tokens Format Module 2025.10](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) - [W3C – Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) - [Carbon Design System – Color Tokens](https://carbondesignsystem.com/elements/color/tokens/) - [Atlassian Design System – Design Tokens](https://atlassian.design/tokens/design-tokens) - [Adobe Spectrum – Design Tokens](https://spectrum.adobe.com/page/design-tokens/) ## Perguntas frequentes sobre avaliação de DESIGN.md ### Como saber se meu DESIGN.md está bem feito? Um bom DESIGN.md precisa ser tecnicamente válido, representar a fonte de verdade do produto, usar tokens coerentes, explicar intenção e restrições, cobrir componentes e estados importantes, incluir critérios de acessibilidade e chegar de fato ao contexto do agente. O teste final é verificar o que o agente ainda precisa inventar quando gera uma interface nova. ### Passar no linter oficial significa que o DESIGN.md está bom? Não. O linter encontra problemas estruturais e verificações objetivas, mas não consegue provar que a prosa é clara, que o arquivo representa o produto real, que componentes possuem estados suficientes ou que o agente produzirá uma interface coerente. Lint é um gate técnico, não uma avaliação completa de qualidade. ### O que é o Score CamaraUX de Qualidade do DESIGN.md? É uma metodologia editorial da CamaraUX que organiza a auditoria em dez dimensões e 100 pontos: fidelidade, validade técnica, tokens, intenção, componentes, acessibilidade, responsividade, guardrails, operação por agentes e manutenção. Não faz parte da especificação oficial do Google. ### DESIGN.md substitui um Design System? Não. DESIGN.md pode traduzir parte da linguagem visual, dos tokens e das regras para um formato consumível por agentes. Um Design System completo também pode envolver bibliotecas de componentes, código, documentação detalhada, governança, processos de contribuição, testes e infraestrutura entre plataformas. ### Preciso testar o DESIGN.md com um agente depois do lint? Sim, se o objetivo é avaliar o uso real. Gere uma tela ou componente que não esteja literalmente descrito no arquivo e observe quais decisões o agente precisou inventar. Isso revela lacunas de intenção, componentes, estados, responsividade e guardrails que a validação estrutural não detecta. ### Com que frequência devo revisar um DESIGN.md? Revise quando houver mudanças relevantes em tokens, componentes, direção visual, acessibilidade ou comportamento responsivo, e também quando agentes começarem a repetir erros que deveriam estar cobertos pelo sistema. Versionar o arquivo e comparar mudanças ajuda a manter histórico e rastreabilidade. ## Conclusão: avalie o que o arquivo impede o agente de precisar adivinhar O melhor DESIGN.md não é o mais longo. É o que preserva as decisões importantes do sistema com clareza suficiente para que humanos e agentes saibam o que manter, onde existe liberdade e quais limites não devem ser ultrapassados. Comece pela validade técnica, mas não pare nela. Compare o documento com o produto, avalie a semântica dos tokens, revise componentes e estados, transforme acessibilidade em critérios verificáveis e teste uma geração que force o agente a tomar decisões. Quando o arquivo deixa de ser uma coleção de estilos e passa a funcionar como contexto confiável para decisões, ele começa a cumprir seu papel. ## Topics **Categorias:** [Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/design-systems.md) **Tags:** [Acessibilidade](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/acessibilidade.md), [agentes de IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/agentes-de-ia.md), [Design System](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-system.md), [Design Tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-tokens.md), [design.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-md.md), [inteligência artificial](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/inteligencia-artificial.md), [UX Design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/ux-design.md)