Atlassian publica DESIGN.md — lições aprendidas ao testar contexto de design portátil na prática

• Um formato Markdown portátil para resolver o problema de "slop", em que UIs geradas por IA se tornam genéricas e sem identidade de marca, reunindo os elementos centrais de um design system em um único arquivo para incluí-lo no prompt
• O DESIGN.md é composto por duas partes: tokens de design legíveis por máquina e racional de design (rationale) legível por pessoas e agentes; ele captura a intenção (intent), não a especificação técnica completa do sistema
• Ao ser aplicado na geração de um dashboard com Figma Make na demonstração da keynote do Team '26, cores, espaçamento, formas e tipografia ficaram alinhados ao sistema da Atlassian, com bom desempenho em prototipagem one-shot
• Porém, em uma base de código de produção, consumiu cerca de 92% mais tokens que o uso do próprio servidor MCP e skills, aumentou o tempo de geração e apresentou variação de aproximadamente 2,7x no consumo de tokens entre execuções, reduzindo a eficiência
• Seus pontos fortes exclusivos — portabilidade e concisão — têm valor em portabilidade entre plataformas, temas personalizados por clientes e prototipagem em novos ambientes, posicionando-se como complemento, não substituto, de ferramentas ricas de design system

---

Contexto — o problema de "slop" em UIs de IA

• Quando a IA gera UIs, os resultados tendem a ficar parecidos: botões com gradiente, títulos em maiúsculas, layouts genéricos de cards, animações de hover desnecessárias etc.; a funcionalidade funciona, mas falta identidade visual
• A comunidade de design chama esses resultados de "slop": saídas funcionais, mas sem decisões de design intencionais
• A causa é a falta de contexto sobre marca, componentes e padrões; a IA usa como padrão a média dos dados de treinamento → "Generic in, generic out"
• A equipe do Atlassian Design System está construindo um mecanismo de contexto para a era da IA e fornece contexto de design rico aos agentes por meio do servidor ADS MCP e de skills detalhadas de IA
  • Com isso, confirmou redução de custo de tokens de IA e melhora na precisão e qualidade dos resultados gerados por milhares de builders de produto

Visão geral do DESIGN.md

• Um formato Markdown open source criado pelo Google para sua ferramenta de design Stitch, funcionando como um snapshot portátil da marca e dos padrões de UI de uma equipe
• O princípio de funcionamento é simples: ao incluí-lo em um arquivo e inseri-lo no prompt, os resultados gerados começam a parecer com o produto da própria empresa

• O que é (What it is)

  • Um arquivo Markdown portátil que descreve apenas os elementos essenciais de um design system
  • A primeira parte lista tokens de design em formato legível por máquina
  • A segunda parte descreve o racional de design — cores, espaçamento, layout, elevation, componentes etc. — em formato legível por pessoas e agentes

• O que não é (What it isn't)

  • Não é a especificação técnica completa de como um design system funciona em produção, nem todos os detalhes completos do sistema
  • Não inclui bibliotecas de código existentes, linters para manter padrões de codificação, nem especificações detalhadas de design do Figma
  • A especificação define esse formato como uma forma de capturar a intenção (intent), não todos os detalhes do sistema

Construindo o próprio DESIGN.md

• A Atlassian já vinha preparando seu design system para consumo por IA por meio do servidor MCP, de um pipeline de conteúdo estruturado e de diversas skills de agentes
• Gerou seu próprio DESIGN.md a partir do mesmo pipeline de conteúdo estruturado que alimenta o MCP e as skills de agentes
• Testou o formato em ferramentas comuns de vibe coding e adicionou orientações mais rigorosas para erros frequentes que não estavam nos guias existentes

Teste no Team '26

• A demonstração da keynote do Team '26, encerrada há um mês em Anaheim, foi usada como um caso de teste adequado
• Em uma das demonstrações da keynote, o Figma Make usou o Teamwork Graph para gerar um dashboard personalizado, com o objetivo de alinhar a linguagem de design de uma só vez, sem depender de servidor MCP ou ferramentas internas
• Com a aplicação do DESIGN.md, o resultado passou de um "slop" genérico para algo reconhecivelmente Atlassian, usando valores esperados de cor, espaçamento, forma e tipografia, além de aplicar elevation alinhada ao sistema nos componentes
• As diretrizes e especificações de alto nível do arquivo são adequadas para gerar uma UI do zero ao customizar bibliotecas comuns como Tailwind e Shadcn

Trade-offs na aplicação em produção

• Uma base de código de produção é muito diferente de um ambiente isolado criado do zero: ela já possui tokens e bibliotecas de componentes existentes, regras rígidas de lint e checagem de tipos
• Em uma tarefa simples, como uma tela de login de usuário, usar o DESIGN.md como único guia de design consumiu cerca de 92% mais tokens, levou mais tempo para gerar e registrou variação de aproximadamente 2,7x no consumo de tokens entre execuções
  • A observação deixa claro que esse resultado não é determinístico e pode variar conforme modelo, prompt, design system, ambiente e qualidade do contexto

• Limitação 1 — o contexto é entregue de uma vez, não sob demanda

  • O servidor MCP busca sob demanda, por meio de tool calls como ads_plan, apenas as instruções para componentes específicos
  • Isso evita carregar itens desnecessários em partes pesadas, como centenas de ícones e uma grande quantidade de tokens semânticos de design
  • O DESIGN.md carrega tudo integralmente a cada vez, causando custo alto e respostas lentas desde o início; em poucos turnos, pode haver corte de contexto, reduzindo a precisão

• Limitação 2 — manter o arquivo curto causa perda de contexto

  • Um design system é um objeto complexo que comprime a linguagem compartilhada de milhares de telas, arquivos Figma e componentes de frontend
  • O MCP e as skills sob demanda condensam cerca de 2,5 MB de instruções; como o DESIGN.md é carregado de uma vez, ele precisa ser reduzido muito mais
  • O arquivo resultante tem 80 KB, cerca de 19.800 tokens de LLM (aproximadamente 10.700 sem o frontmatter), o que é grande em comparação com exemplos da comunidade
  • Para chegar a esse tamanho, foram removidas partes consideráveis das orientações de uso de mais de 50 componentes, as diretrizes básicas foram muito reduzidas e alguns tokens de design pouco usados foram excluídos
  • Observou-se que, com a falta de contexto, agentes que buscam qualidade de produção tendem a ficar menos precisos ou a coletar contexto por conta própria, lendo diretamente implementações de componentes para encontrar orientações de uso não especificadas

• Limitação 3 — a especificação expõe o interior do design system

  • O DESIGN.md é um snapshot portátil que reescreve o design system em prosa, com o objetivo de fornecer princípios, especificações e diretrizes para reimplementar o sistema do zero
  • Em ambientes de produção já estabelecidos, essa informação pode ser desnecessária ou levar agentes a criar dívida técnica (tech debt), especialmente em componentes
  • Em vez de ler e interpretar todos os detalhes de estilização de um botão (backgroundColor, textColor, borderColor etc.), é preferível importar e usar o componente existente
    • Ex.: import Button from '@atlaskit/button'; seguido de <Button appearance="primary" spacing="compact" />
  • O uso de componentes compartilhados é essencial para manutenção: alterar um botão em um só lugar se propaga por toda a base de código e facilita code review e manutenção
  • Como o DESIGN.md exclui intencionalmente orientações de código e fornece apenas especificações de reimplementação, nos testes ele tendeu mais a recriar componentes do que a usar o sistema existente
  • O servidor MCP e as skills oferecem um nível melhor de abstração com base na fundação técnica, funcionando como manual de uso do sistema existente, não como guia de reimplementação
  • Combinado a regras de lint que impõem padrões de codificação sem consumir tokens, isso cria um ciclo de feedback positivo para os agentes

Quando o DESIGN.md é mais útil

• Direção artística de alto nível (High-level artistic direction)

  • O DESIGN.md mais simples se concentra na direção visual e no feeling do sistema; se isso ainda não foi documentado, é um artefato útil
  • Porém, o frontmatter duplica informações que já existem na base de código

• Prototipagem rápida em ambientes desconhecidos

  • Em prototipagem blue-sky ou testes de novas ferramentas, ajuda a gerar UIs on-brand sem o peso de configurar toda a stack técnica nem as restrições dos componentes existentes

• Interoperabilidade com ferramentas de design (Interoperability)

  • Algumas ferramentas de IA montam UIs customizando componentes pré-criados alinhados a uma linguagem de design; o DESIGN.md fornece instruções no nível adequado para essas ferramentas

• Temas personalizados por clientes para UI adaptativa (Customer theming)

  • Em produtos que precisam gerar interfaces dinâmicas, como relatórios, gráficos e dashboards, ajuda clientes a descreverem facilmente sua própria marca, fazendo com que a saída da IA pareça pertencer à marca do cliente
  • Pode ser concebido como uma opção que administradores ou equipes de marca enviam para ferramentas de trabalho
• O ponto comum entre esses casos é o escopo de UIs geradas por agentes em ambientes nos quais a saída do design system existente não está disponível ou não é prática

Como começar e contribuir para o padrão

• A Atlassian publicou seu arquivo DESIGN.md em atlassian.design/DESIGN.md para ajudar a moldar o padrão, em vez de apenas reagir a ele
• O arquivo da empresa hoje tem algumas diferenças em relação ao padrão, incluindo atributos não padronizados para renderização de componentes; como o padrão não dá suporte a theming, ela oferece uma variação separada para modo escuro
• Feedback foi compartilhado no GitHub, algumas sugestões já foram incorporadas à especificação, e a participação de todo o setor é incentivada

Conclusão

• O DESIGN.md é um formato portátil útil como snapshot de um design system, mas não substitui ferramentas mais ricas de design system
• Quando agentes dão suporte a MCP ou skills, eles oferecem resultados melhores a um custo menor
• Em portabilidade entre plataformas, temas personalizados por clientes e prototipagem blue-sky, um DESIGN.md bem estruturado oferece melhorias significativas
• Quando design systems se tornam legíveis por IA, todo o ecossistema se beneficia