--- title: "DESIGN.md e design tokens: como descrever um Design System para IA" date: 2026-10-02T12:30:00Z modified: 2026-09-23T17:21:24Z permalink: "https://camaraux.com.br/design-md-vs-design-tokens/" type: post status: publish excerpt: DESIGN.md e design tokens podem guardar as mesmas cores, fontes e medidas, mas ajudam em tarefas diferentes. Veja o mesmo sistema nos dois formatos e entenda onde manter os valores, como explicar as regras de uso e evitar informações conflitantes. wpid: 14222 categories: - UX & IA tags: - UX & IA - design system ia - design systems - design.md - inteligência artificial rank_math_title: "DESIGN.md e design tokens: diferenças e quando usar os dois" rank_math_description: Compare DESIGN.md e design tokens com exemplos. Saiba onde guardar valores e regras e como manter seu Design System consistente com IA. rank_math_focus_keyword: DESIGN.md,design tokens,DESIGN.md e design tokens featured_image: /wp-content/uploads/2026/09/DESIGN.md-e-design-tokens.png author: Lucas Camara timestamp: 2026-09-23T17:21:24Z --- **DESIGN.md e design tokens descrevem partes do mesmo sistema de design.** Tokens registram valores e referências que ferramentas podem transformar em código. O DESIGN.md reúne valores selecionados e explica a intenção, as regras de uso e os limites para pessoas e agentes de IA. Como ele também pode conter tokens e exportá-los, a decisão central é definir onde os valores são mantidos e como os outros artefatos serão atualizados. Imagine um botão azul com texto branco. O token informa a cor exata, a família tipográfica e o raio. A orientação de design explica em quais telas o botão aparece, qual ação ele representa e o que fazer quando há duas ações concorrentes. Neste artigo, você verá o mesmo exemplo nos dois formatos e um modo prático de evitar contradições. ## O que cada formato descreve **Design tokens** são decisões de design com nomes e tipos explícitos. Em vez de espalhar uma cor diretamente por dezenas de componentes, o time pode nomeá-la como `color.action.primary` e reutilizar sua referência. O [Design Tokens Format Module 2025.10](https://www.designtokens.org/tr/2025.10/format/), publicado pelo Design Tokens Community Group (DTCG), define um formato JSON para trocar esses dados entre ferramentas. A especificação permite descrições em `$description`, portanto tokens também podem carregar contexto curto. Ela não determina sozinha a composição de uma tela inteira. O relatório do grupo comunitário não é uma recomendação formal do W3C. **DESIGN.md** é um documento legível em Markdown. Na [especificação aberta do Google Labs](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), ele pode ter um cabeçalho YAML com tokens e um corpo que explica identidade visual, tipografia, layout, componentes e escolhas a evitar. A especificação trata os valores estruturados como referência normativa dentro do arquivo e a prosa como orientação de uso. O projeto está em estágio alpha, então esquema e ferramentas podem mudar. | Pergunta | Tokens em formato DTCG | DESIGN.md | | --- | --- | --- | | Qual é o valor? | Registra tipo, valor e referências entre tokens. | Pode registrar tokens no YAML ou apontar para a fonte existente. | | Por que usar? | Pode incluir uma descrição curta do token. | Explica intenção, hierarquia e restrições em texto. | | Quem consome? | Ferramentas, pipelines, aplicações e também pessoas ou agentes que leem JSON. | Pessoas e agentes aos quais o documento foi fornecido como contexto. | | Como chega à interface? | Depende da transformação e implementação. | Depende de o agente consultar e aplicar as orientações. | O [guia da CamaraUX sobre arquitetura de design tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-tokens-arquitetura-w3c.md) aprofunda nomes, tipos e referências. Para a visão mais ampla de bibliotecas, componentes e governança, consulte o [guia de Design System](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md). ## Onde há sobreposição entre DESIGN.md e tokens A sobreposição aparece quando ambos guardam a mesma cor, o mesmo nome de estilo ou a configuração de um componente. Isso não é um erro por si só. O problema surge quando cada arquivo pode ser editado de forma independente e ninguém sabe qual deles prevalece. Há pelo menos duas arquiteturas válidas. Um projeto pequeno pode manter os valores no YAML do DESIGN.md e usar a [ferramenta oficial de exportação](https://github.com/google-labs-code/design.md/blob/main/README.md) para gerar tokens DTCG ou CSS. Um sistema com tokens já integrados ao Figma, ao código e a várias plataformas pode manter o JSON ou outra fonte aprovada como canônica e gerar a seção correspondente do DESIGN.md a partir dela. Em ambos os casos, a regra é escolher **uma direção de atualização** para cada valor. Uma nuance útil: o token `action.primary` pode ter uma descrição como “cor da ação principal”. Essa frase ajuda a encontrar seu propósito, mas não resolve uma decisão contextual como “esta tela de confirmação não pode apresentar dois botões primários”. Essa orientação cabe na documentação do componente e, quando útil ao agente, no DESIGN.md. [![Diagrama de camadas de um token de cor, do valor hexadecimal ao token de componente para botão](https://miro.medium.com/1%2A_tVeFAkw1nXvNNTH8CpsNA.png) ](https://medium.com/@lea.seibel/color-tokens-as-an-interface-homogenization-tool-2ab46bee5a98)Camadas de nomeação de cor, do valor ao componente. Imagem: Léa Seibel, publicada no Medium. Exemplo externo de arquitetura de tokens; o exemplo do artigo abaixo é hipotético e independente.## Exemplo: o mesmo sistema nos dois formatos Considere um **produto hipotético** chamado Aurora. Seu botão principal usa azul `#174EA6`, texto branco, fonte Arial, corpo de 16 px e cantos de 8 px. O exemplo é didático: não representa um arquivo real da CamaraUX nem substitui validação de contraste, estados e acessibilidade no produto. ### 1. Valores no arquivo de tokens Em um JSON inspirado no formato DTCG 2025.10, os campos `$type` e `$value` dizem à ferramenta o que cada token representa. Uma descrição curta especifica o papel. Neste exemplo compacto, as cores usam os componentes sRGB correspondentes aos códigos hexadecimais; a tipografia e o raio aparecem como tipos próprios. ``` { "color": { "action-primary": { "$type": "color", "$value": {"colorSpace": "srgb", "components": [0.0902, 0.3059, 0.651], "hex": "#174EA6"}, "$description": "Fundo da ação principal." }, "on-action-primary": { "$type": "color", "$value": {"colorSpace": "srgb", "components": [1, 1, 1], "hex": "#FFFFFF"}, "$description": "Texto sobre a ação principal." } }, "font": { "body-family": {"$type": "fontFamily", "$value": "Arial"}, "body-size": {"$type": "dimension", "$value": {"value": 16, "unit": "px"}} }, "radius": { "button": {"$type": "dimension", "$value": {"value": 8, "unit": "px"}} } } ``` Esses valores são úteis para transformar tokens em variáveis de CSS, recursos de outras plataformas ou propriedades de componentes. O arquivo ainda não decide qual botão será a ação principal de uma tela específica. Também não garante que o componente implementado use os tokens corretamente. ### 2. Orientação no DESIGN.md O trecho abaixo segue a ideia de YAML e Markdown da especificação do Google Labs. Os nomes e valores foram mantidos equivalentes ao exemplo anterior, mas os esquemas não são idênticos: a sintaxe YAML do DESIGN.md não é o JSON DTCG copiado para outro arquivo. Em um fluxo real, a seção de valores deve ser derivada da fonte escolhida. ``` --- version: alpha name: Aurora colors: primary: "#174EA6" on-primary: "#FFFFFF" typography: body: fontFamily: Arial fontSize: 16px fontWeight: 400 lineHeight: 1.5 rounded: button: 8px components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" rounded: "{rounded.button}" typography: "{typography.body}" --- ## Overview Aurora usa uma interface clara e contida. A ação principal deve ser fácil de localizar sem disputar atenção com mensagens de erro. ## Colors Use primary somente para ações que avançam a tarefa principal. Use on-primary como texto sobre esse fundo. ## Typography O texto do botão deve ser legível em tamanhos de tela menores. Não reduza a fonte para acomodar rótulos longos; revise o rótulo ou o layout. ## Components O botão principal representa uma ação prioritária por região de decisão. Preserve estados de foco, carregamento e desabilitado conforme a biblioteca de componentes. ## Do's and Don'ts Não crie uma segunda cor azul para resolver uma exceção local. Registre a necessidade e revise os tokens com o time. ``` Agora o agente tem uma instrução sobre _quando_ aplicar os valores. Ainda assim, o documento não implementa sozinho os estados do botão. A biblioteca de componentes e os testes de interface continuam necessários. Para aprender a montar um arquivo completo, veja [como criar e aplicar um DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-aplicar-design-md-ia.md); este artigo se concentra na decisão entre as camadas. ## Como manter consistência entre os arquivos Antes de automatizar, registre uma decisão simples: **qual arquivo pode receber a edição original de cada valor?** Se a equipe já distribui tokens para várias plataformas, o arquivo de tokens ou sua fonte de origem pode continuar canônico. Se o projeto começa pelo DESIGN.md e usa sua exportação, seu YAML pode assumir esse papel. A escolha deve seguir o fluxo real de manutenção, não o nome do formato. 1. **Mapeie os proprietários:** valores de cor, tipografia e espaçamento têm uma origem; orientações de uso têm responsáveis pela revisão. 2. **Defina a direção:** gere a representação secundária quando possível. Se a cópia for manual, trate a comparação como etapa obrigatória da revisão. 3. **Valide referências:** confirme nomes, valores, aliases e ausência de referências quebradas. A CLI oficial do DESIGN.md oferece lint e exportação, mas sua saída deve ser conferida contra o pipeline do projeto. 4. **Teste a interface:** compare botão real, estados, contraste e comportamento com as regras. Um arquivo correto pode produzir uma interface ruim se for ignorado. 5. **Revise mudanças juntas:** se `primary` mudar, atualize a descrição, exemplos visuais e documentação afetada na mesma entrega. Para agentes de IA, inclua no fluxo uma instrução explícita para consultar o DESIGN.md e a biblioteca de componentes antes de gerar telas. A existência do arquivo no repositório, por si só, não garante sua leitura. O artigo [Design System para IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-para-ia.md) aprofunda o contexto e a governança; a [biblioteca DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/) reúne referências para explorar o formato. ## Quando usar os dois, e quando começar por um | Situação | Ponto de partida razoável | Cuidado principal | | --- | --- | --- | | Protótipo pequeno com IA e pouca infraestrutura | DESIGN.md com valores e regras; exportar tokens se o projeto precisar. | Verificar o que a exportação cobre e não confundir protótipo com governança pronta. | | Produto com biblioteca e pipeline de tokens existentes | Manter os tokens atuais e acrescentar um DESIGN.md conciso para explicar o uso aos agentes. | Gerar ou revisar valores espelhados para impedir divergência. | | Várias plataformas e temas | Fonte de tokens governada, com documentação de decisões no DESIGN.md e nos componentes. | Manter modo, plataforma e estado explícitos. Um resumo único pode omitir diferenças importantes. | O ponto de decisão é operacional: quem altera os valores, quem consome os arquivos e como uma mudança chega a uma interface testada. Se você precisa experimentar uma referência visual, o [gerador de DESIGN.md da CamaraUX](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/gerador-design-md.md) pode oferecer um ponto de partida. Revise os dados extraídos antes de tratá-los como regras do produto. ## Perguntas frequentes ### Posso converter DESIGN.md em tokens DTCG? A implementação oficial do Google Labs oferece exportação para o formato DTCG. Confira o resultado, pois regras em prosa e detalhes de componentes não viram automaticamente tokens equivalentes. ### O DESIGN.md é lido automaticamente por qualquer agente de IA? Não. O projeto precisa instruir a ferramenta a consultar o arquivo ou fornecê-lo como contexto. Teste se o agente usa as regras e os componentes esperados. ### Uma descrição no token substitui a documentação do componente? Uma descrição curta ajuda a explicar o papel do valor. Estados, comportamento, acessibilidade e critérios de escolha normalmente exigem documentação e implementação do componente. ## Fontes e especificações - [Google Labs: especificação DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), versão alpha consultada em setembro de 2026. - [Google Labs: documentação da CLI DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/README.md), comandos de lint e exportação consultados em setembro de 2026. - [Design Tokens Community Group: Format Module 2025.10](https://www.designtokens.org/tr/2025.10/format/), especificação de intercâmbio publicada em 2025. - [Google Labs: anúncio da abertura de DESIGN.md](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/), abril de 2026. ## Topics **Categorias:** [UX & IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/ux-e-ia.md) **Tags:** [design system ia](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-system-ia.md), [design systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-systems.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)