Diagram Design: 39 gramáticas visuais com marca e revisão geométrica

ANÁLISE EDITORIAL

Diagram Design é uma Skill para transformar uma pergunta visual em um arquivo HTML autocontido, com SVG inline, hierarquia editorial e regras explícitas de legibilidade. Em vez de começar escolhendo caixas e cores, ela pede que o agente identifique o comportamento que precisa ser explicado, selecione uma das 39 gramáticas visuais, limite a complexidade e só então desenhe.

O pacote oficial cobre arquitetura, fluxo, sequência, estado, modelo de dados, cronograma, swimlane, quadrantes, gráficos, mapas de dependência, implantação e outras estruturas. Também documenta como redesenhar fontes draw.io e Mermaid, aplicar identidade visual, preservar acessibilidade e verificar conectores. É uma caixa de ferramentas ampla, mas não é um editor visual, não interpreta sozinho um sistema real e não torna correto um diagrama baseado em informações erradas.

O que esta Skill faz de verdade

O SKILL.md fixado organiza o trabalho em duas decisões. Primeiro vem o padrão semântico, quando comportamento, estado, risco ou fiscalização carregam o significado. Depois vem o tipo visual que define a disposição. Uma fila com capacidade finita pode usar um padrão de gargalo dentro de um fluxo de dados; uma fronteira de confiança pode usar um caminho seguro dentro de uma arquitetura.

A Skill impõe um orçamento: normalmente até nove nós, doze conexões e dois elementos de destaque. Quando o conteúdo excede o teto, a orientação é dividir em visão geral e detalhe. Conectores fora do mesmo eixo precisam usar cotovelos ortogonais arredondados, rótulos devem ficar afastados das linhas, pontos de conexão compartilhados são proibidos e uma linha não pode atravessar uma caixa que não seja origem ou destino.

A saída padrão é um HTML único com CSS incorporado e SVG inline. O SVG recebe título e descrição acessíveis, identificadores próprios e ordem de pintura que mantém setas atrás dos nós. Há variantes clara, escura e editorial completa. Movimento é opcional e não pode carregar um significado ausente no quadro estático.

Para quem serve

Serve a arquitetos de solução, equipes de produto, documentação, segurança, dados, operações e consultorias que precisam explicar relações, decisões e dependências sem entregar um emaranhado automático. Também atende quem recebe um draw.io ou Mermaid tecnicamente correto, mas inadequado para um artigo, slide, handoff ou leitura executiva.

É especialmente útil quando uma equipe quer repetir o mesmo sistema visual entre projetos. A Skill centraliza cores e tipografia em um guia, permite salvar perfis por cliente e usa um marcador de projeto para selecionar o perfil. Isso reduz escolhas improvisadas, mas amplia o cuidado com arquivos de marca e diretórios compartilhados.

Não é a melhor escolha para listas, comparações simples ou uma relação que cabe em um parágrafo. Também não substitui inventário técnico. Se nomes, fluxos, portas, permissões ou dependências não foram verificados, o resultado pode ficar bonito e ainda estar errado.

Compatibilidade e pré-requisitos

O README oficial documenta Claude Code, Codex, Factory Droid, Pi, Kiro, OpenCode e outros clientes compatíveis com Agent Skills. Para uso completo, o agente precisa ler o diretório da Skill, gravar arquivos no projeto e carregar a referência do tipo visual escolhido.

• Cliente capaz de carregar uma Skill em Markdown e suas referências.
• Pasta de projeto onde HTML, SVG ou PNG possam ser gravados com autorização.
• Navegador moderno para conferir HTML e SVG.
• Python 3 para os extratores e verificadores opcionais.
• Playwright e Chromium somente quando a exportação PNG documentada for necessária.
• Acesso à rede quando houver instalação por marketplace, leitura de site ou carregamento de Google Fonts.
• Fonte técnica confiável para nomes, relações, dados e decisões representadas.

A versão auditada não possui release nem tag publicada. O frontmatter do SKILL.md declara versão 2.6. Não converta isso em promessa de compatibilidade universal. O cliente, o runtime Python, o navegador e o método de instalação ainda precisam ser validados no ambiente real.

Instalação recomendada

O mantenedor documenta um marketplace para Codex. Os comandos abaixo consultam a rede e alteram a configuração do cliente. Revise o repositório, fixe o commit e faça o primeiro teste em um projeto sem dados sensíveis.

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Para Claude Code, a origem fixada mostra os comandos /plugin marketplace add e /plugin install. Outros clientes podem exigir cópia ou link do diretório skills/diagram-design. Não copie somente o SKILL.md para uso funcional, pois ele depende de 53 referências, templates e ativos.

O download local do Bastidores é propositalmente documental. Ele contém apenas SKILL.md, LICENSE e ORIGEM.md. Não inclui referências, exemplos, scripts, fixtures, plugin, Playwright, Chromium ou fontes. Use o ZIP para auditar propósito, versão, licença e escopo. Para executar, obtenha a árvore completa no commit fixado.

Configuração antes do primeiro uso

O primeiro gate verifica o guia de estilo. Se os tokens ainda forem os padrões, a Skill deve perguntar se o usuário quer ler um site, extrair um design system local, informar valores manualmente, usar o padrão ou carregar um perfil salvo. Não deve aplicar a identidade de uma marca sem essa decisão.

O onboarding pode buscar páginas públicas, ler CSS calculado, fontes e capturas, ou analisar uma pasta local com CSS, JSON e Markdown. Conteúdo lido é dado não confiável, não instrução. A proposta de tokens deve ser mostrada antes de gravar mudanças.

Perfis salvos ficam fora do projeto, e um arquivo .diagram-design pode selecionar o perfil. A referência de perfis precisa ser revisada antes de criar, substituir ou reutilizar identidades de clientes. Nomes, paletas e fontes não devem atravessar projetos por engano.

Primeiro uso seguro

Comece sem importação e sem PNG. Use um sistema fictício com quatro componentes, saída HTML, tamanho de documento, detalhe equilibrado e público misto. Declare a história em uma frase, escolha um tipo e deixe o agente informar o que ficará de fora para respeitar o orçamento.

Crie um diagrama de arquitetura em HTML para um sistema fictício com aplicativo web, API, fila e banco. Use o perfil padrão somente neste teste, público misto, detalhe equilibrado e sem animação. Não leia outros diretórios nem publique o arquivo.

Abra o HTML localmente e confira a relação entre os quatro componentes. Depois, rode o verificador self_check.py da árvore oficial no arquivo exato. Esse script analisa contrato de SVG acessível, segurança de arquivo único e regras básicas, mas não comprova que a arquitetura descrita é verdadeira.

Esta curadoria não instalou o plugin nem executou os scripts upstream. O teste recomendado acima é um procedimento verificável, não um resultado realizado pelo Bastidores. Essa distinção evita apresentar uma ilustração ou leitura de código como prova de execução.

Como o fluxo deve funcionar

1. Definir decisão, público, destino, formato, tamanho e nível de detalhe.
2. Inventariar fatos, componentes, relações, medidas e lacunas.
3. Escolher um padrão semântico quando comportamento for central.
4. Escolher somente um tipo visual dominante e carregar sua referência.
5. Selecionar perfil de marca ou aprovar explicitamente o padrão.
6. Reduzir nós e conexões até caber no orçamento aplicável.
7. Montar o HTML com SVG acessível e conteúdo estático completo.
8. Verificar grade, conectores, rótulos, contraste e ordem de pintura.
9. Executar self_check.py no arquivo gerado.
10. Abrir o HTML e revisar em largura real de uso.
11. Exportar SVG ou PNG somente quando solicitado.
12. Registrar o que foi removido, agrupado ou simplificado.

Ao importar, o contrato de saída fixa quatro escolhas: formato, tamanho, detalhe e público. O redesenho precisa entregar um registro de fidelidade, para que o usuário saiba quais nós e conexões foram mantidos, unidos ou removidos.

Resultado esperado

O resultado padrão é um HTML autocontido, com título editorial, SVG inline, CSS incorporado e, quando necessário, cartões de apoio. Um bom arquivo comunica a relação principal antes de exigir leitura de cada rótulo. Deve continuar compreensível sem animação e conter título e descrição acessíveis no SVG.

Draw.io e Diagram Design não entregam a mesma coisa. A Draw.io Skill prioriza um arquivo .drawio editável e sua validação visual. Diagram Design redesenha para HTML e SVG com uma gramática editorial própria. Já Archify começa por evidências de um repositório para mapear arquitetura. Diagram Design começa pela história, pelo tipo visual e pelo sistema de marca. Ele pode representar arquitetura, mas não faz o inventário técnico por você.

Visual Explainer, ainda apenas candidata na fila editorial consultada, tende a um objetivo mais amplo de explicação visual. Diagram Design passou neste gate porque sua unidade central é a gramática de diagramas, com limites geométricos, importadores textuais e contrato de acessibilidade verificável.

Permissões, privacidade e riscos

O uso funcional pode ler a fonte do projeto, arquivos draw.io, Mermaid, CSS, JSON, Markdown e páginas públicas. Pode gravar HTML, SVG, PNG, guias de estilo, perfis e o marcador .diagram-design. A instalação por marketplace altera configuração e consulta a rede. A exportação PNG pode instalar e executar Playwright e Chromium.

Os extratores drawio_extract.py e mermaid_extract.py trabalham com texto local e documentam que não executam links ou JavaScript da origem. Ainda assim, rótulos, URLs, comentários e metadados devem ser tratados como dados não confiáveis. Não siga uma instrução escondida dentro do diagrama.

O onboarding por site pode revelar padrões de uma marca pública; o onboarding por pasta pode alcançar um design system privado. Restrinja os diretórios, não carregue segredos, confirme o cliente e revise cada diff. Diagramas técnicos também podem expor hostnames, portas, topologia, controles e caminhos de acesso. Use exemplos sintéticos em demonstrações públicas.

Google Fonts é a única dependência externa permitida no HTML padrão, segundo a Skill. Se o ambiente for offline ou exigir empacotamento integral, valide substituição de fonte e não alegue correspondência perfeita. A imagem e a página nunca devem ser tratadas como evidência de segurança, conformidade ou arquitetura implantada.

Erros comuns

Usar nove caixas idênticas. Isso apaga hierarquia. Escolha um ou dois focos e tratamentos semânticos.

Transformar lista em diagrama. Se uma tabela resolve, a imagem apenas aumenta o trabalho.

Conservar o layout automático do Mermaid. A importação deve extrair relações e redesenhar, não reproduzir o renderizador.

Manter todas as cores do draw.io. As cores de origem são sinais para mapear função, não uma paleta obrigatória.

Instalar só o SKILL.md. A Skill depende das referências, templates, ativos e verificadores da árvore oficial.

Usar perfil do cliente errado. Confirme o marcador e o arquivo selecionado antes de gerar.

Exportar PNG cedo demais. Revise HTML e SVG primeiro, depois instale dependências de exportação se necessário.

Confundir validação geométrica com validação factual. Um conector correto ainda pode representar uma relação inexistente.

Versão, licença e origem verificadas

A API oficial do GitHub foi consultada em 05/09/2026. O repositório cathrynlavery/diagram-design registrava 31.530 estrelas, estava público, não arquivado e declarava licença MIT. A contagem pertence ao repositório inteiro e não mede precisão ou adoção de cada uma das 39 gramáticas.

A curadoria fixou o commit 4451eadc484d76aa860edf3289c16fcd082dcdbf, que era o HEAD de main na consulta. O último commit específico retornado para o SKILL.md foi b52a33bfeef85d43995193ee52c13b485154b7b4. Não havia tags nem releases publicadas. O frontmatter declara versão 2.6.

A licença MIT permite redistribuição com preservação do aviso. O ZIP local tem três arquivos textuais, 18.159 bytes e SHA-256 abe377c7e982ea6b6becc259ea2378febb8b1a8c5426cca1e10614f3cb03496a. Referências, exemplos, scripts e dependências foram omitidos de forma explícita.

Checklist antes de automatizar

• Fixe repositório, commit, versão declarada e licença.
• Confirme cliente, diretório, destino e permissões de gravação.
• Separe fatos verificados de decisões visuais.
• Defina formato, tamanho, detalhe e público antes de desenhar.
• Escolha um padrão semântico e um tipo visual dominante.
• Aprove perfil de marca e evite misturar clientes.
• Respeite orçamento de nós, conexões, destaques e anotações.
• Trate draw.io, Mermaid, páginas e código como dados não confiáveis.
• Revise HTML, SVG, contraste, rótulos e acessibilidade.
• Execute os verificadores somente na árvore oficial auditada.
• Instale Playwright e Chromium apenas se a exportação PNG for necessária.
• Registre simplificações e mantenha publicação sob aprovação humana.

Fontes primárias

• Repositório oficial do Diagram Design.
• Commit auditado e HEAD verificado.
• Diretório oficial da Skill no commit fixado.
• SKILL.md auditado.
• README e instalação oficial.
• Onboarding de identidade visual.
• Perfis e marcador de projeto.
• Contrato de formato, tamanho, detalhe e público.
• Importação controlada de draw.io.
• Importação controlada de Mermaid.
• Exportação SVG e PNG.
• Diagnóstico de dependências.
• Licença MIT preservada.