Diagram Design: uma skill de agente com um sistema de design de verdade

Todo diagrama gerado por IA é igual. Você conhece o visual: caixas de cantos arredondados, um degradê de roxo para azul em algum lugar, sombra em tudo, setas que terminam um pouco antes da borda da caixa e uma fonte que grita «padrão». É o equivalente visual de um press release. Tecnicamente, comunica. Ninguém quer ler.

Diagram Design, uma skill de agente de Cathryn Lavery, ataca esse visual de frente. O slogan é incomumente direto para um README: um único arquivo HTML com SVG embutido, na sua marca, 45 tipos de diagrama, sem sombras, sem a gambiarra do Mermaid.

Essa última frase é a tese. O projeto não tenta deixar a geração de diagramas mais inteligente. Tenta fazer o resultado parecer obra de alguém com repertório.

O que ele produz de fato

Você descreve o diagrama, o agente escreve um único arquivo HTML com SVG inline e você dá dois cliques. Sem etapa de build, sem pipeline de renderização, sem dependência de serviço. O arquivo abre offline e vai parecer o mesmo daqui a cinco anos.

A biblioteca cobre um espectro realmente amplo: diagramas de arquitetura e de delta de arquitetura, deploy, grafos de dependência, classes UML, schema de banco de dados, fluxogramas, diagramas de sequência, máquinas de estado, raias, fluxo de dados, além de uma pilha inteira de gráficos (barras, linhas, dispersão, treemap, radar, polar, cascata, heatmap, sankey) e formas estruturais (árvores, organogramas, pilhas de camadas, Venn, pirâmides, medalhões). Em estratégia e planejamento há quadrantes, mapas de Wardley, Gantt, linhas do tempo, kanban, story maps e jornadas de usuário. Tem até uma axonometria explodida para trabalho espacial.

Cada tipo vem em três variantes estáticas: minimal clara, minimal escura e um tratamento editorial completo. Uma pequena inconsistência que vale registrar: o título do repositório diz 44 tipos, o corpo do texto diz 45 e a galeria vai de 01 a 44. Um projeto tão obsessivo com a própria grade tem um erro de digitação. Acontece.

A parte que faz funcionar: as regras

O esforço foi para o sistema de design, e ele é enunciado em números, não em adjetivos.

Uma cor de destaque por diagrama. O destaque serve para puxar a atenção para um ou dois elementos. Todo o resto é tinta, papel e cinza contido. Essa única regra elimina a maior parte do ruído visual que faz diagramas de IA parecerem um dashboard de 2016.

Três famílias tipográficas, cada uma com uma função. Instrument Serif para títulos e anotações em itálico. Geist sans para nomes de nós. Geist Mono para sub-rótulos técnicos: portas, URLs, tipos de campo. Reservar a monoespaçada para o detalhe técnico é o tipo de coisa que um designer em atividade faz por instinto e que um gerador nunca faz.

Uma grade de 4 pixels. Toda coordenada, largura, espaçamento e padding precisa ser divisível por quatro. A autora chama isso de chave para o resultado não parecer gerado por IA. Ela está certa, e o motivo é sutil: o desalinhamento é a denúncia. Você não percebe que uma caixa tem 137 pixels de largura. Você percebe que algo está estranho, e não sabe dizer o quê.

Filetes, sem sombras, raio limitado a 10px. As bordas fazem o trabalho que as sombras costumam fazer, e fazem sem fingir que o diagrama é um objeto físico apoiado numa superfície.

Densidade de informação alvo: 4 de 10. É a regra que a maioria dos times vai resistir a adotar e pela qual a maioria dos leitores vai agradecer. O princípio declarado: o movimento de maior qualidade costuma ser apagar.

Acessibilidade também não é item de última hora. A saída SVG carrega role="img", aria-labelledby e elementos title/description; preferências de movimento reduzido são respeitadas; o contraste WCAG AA (4.5:1 para texto, 3:1 para marcas-chave) é verificado na CI. A paleta padrão é preto profundo e tangerina sobre papel branco esfumaçado.

O onboarding de marca é o recurso escondido

Você passa a URL do seu site. Ele extrai as cores e as fontes e as mapeia em papéis semânticos: paper, ink, muted, accent, link. Depois entrega um recibo de fidelidade dizendo o que inferiu e onde chutou.

Essa segunda parte importa muito mais do que a extração. Ferramentas de extração de marca costumam te entregar uma paleta e ficar quietas. Mostrar a inferência é o que permite corrigir antes de produzir quarenta diagramas no laranja errado.

Há também um caminho de importação: aponte para um arquivo Mermaid, draw.io ou Excalidraw e ele redesenha o diagrama no sistema de design, com quatro controles — formato, tamanho, detalhe, público — e um livro de fidelidade. Migrar um wiki cheio de gráficos Mermaid é exatamente o caso de uso para o qual isso foi feito.

Onde encaixa e onde não encaixa

A instalação é deliberadamente entediante. npx skills add cathrynlavery/diagram-design para qualquer coisa que leia Agent Skills; comandos do marketplace de plugins para Claude Code, Codex, GitHub Copilot e Factory Droid; symlinks ou importação de subdiretório para Cursor, Cline, Gemini CLI, Windsurf, Amp, Zed, Kiro e OpenCode. Existem slash commands para exportar, importar, fazer profiling e uma checagem doctor.

A autora é refrescantemente clara sobre os limites, e são os limites certos.

A qualidade depende do modelo. O mesmo prompt pode produzir dois layouts diferentes, porque o que você recebe é geometria gerada, não preenchimento de template. Não existe fonte editável: nem canvas para arrastar, nem texto que dê para comparar num diff de pull request. Para documentação que muda toda semana, ela recomenda Mermaid: dá para fazer diff, o GitHub renderiza nativamente, e isso vale mais do que beleza.

Ela também faz uma pergunta que mais autores de ferramentas deveriam fazer: o leitor vai tirar mais desse diagrama do que de um parágrafo? Se o «diagrama» é uma caixa com rótulo, escreva a frase. Se está comparando duas listas, use uma tabela. Se quer arte ASCII para um terminal, essa não é a ferramenta.

A saída é um arquivo, não um serviço

Há uma decisão de design aqui que vai parecer mais inteligente a cada ano: o entregável é um único arquivo HTML com SVG inline, e ele abre offline. Sem conta, sem script embutido, sem dependência de um fornecedor que talvez reajuste o preço da API no próximo trimestre. Coloque num repositório, anexe a um ticket, imprima, mande por e-mail para um cliente que usa um notebook bloqueado.

Para quem já viu um SaaS de diagramas ser adquirido e depois degradar, isso não é recurso pequeno. É a diferença entre um artefato e uma assinatura.

O trade-off é que você não consegue editá-lo como editaria um canvas. Sem arrastar e soltar, sem painel de camadas, sem pilha de desfazer. Se o layout está errado, você regenera ou ajusta as coordenadas na mão — e como tudo está sobre uma grade de 4px, a edição manual é sobrevivível de um jeito que não seria num documento de formato livre.

Como julgar uma skill de diagramas em dez minutos

Peça algo de forma incômoda: um sistema com um nó obviamente importante, três serviços de apoio e um banco de dados que todo mundo esquece. Uma boa saída usa o único destaque para marcar o nó importante e deixa o resto recuar. Uma saída ruim colore tudo, porque colorir tudo é o que geradores fazem quando não têm prioridades.

Depois peça o mesmo diagrama duas vezes. Saída idêntica significa que você está olhando um template. Saída diferente significa que você está olhando geração, o que é mais honesto e também é o motivo pelo qual o modelo importa.

Por fim, olhe os números. Conte os espaçamentos. Se não forem múltiplos de quatro, as restrições estão sendo ignoradas, e o resto do sistema de design provavelmente também.

O argumento de verdade

Existe uma versão deste projeto que teria sido só um prompt de estilo. «Deixe editorial, sem sombras, minimalista.» Essa versão produziria lixo inconsistente, porque prompt não sobrevive ao contato com um diagrama de arquitetura de quarenta nós.

O que torna o Diagram Design interessante é que ele codifica bom gosto como restrições que uma máquina consegue checar: divisível por quatro, um destaque, três fontes, razão de contraste, sem sombra. A estética não está no modelo. Está na especificação.

É uma ideia mais portátil do que a própria skill. Seja o que for que você use para gerar visuais — diagramas, slides, capas, thumbnails —, a diferença entre uma saída que parece desenhada e uma que parece gerada costuma ser uma lista curta de regras que alguém teve o trabalho de escrever.