Adeus aos diagramas genéricos do Mermaid: diagram-design dá ao Claude Code um sistema de design (e sua paleta)
Você pede um diagrama de arquitetura ao Claude Code e já sabe exatamente o que volta: um bloco Mermaid que renderiza caixas arredondadas idênticas, setas que se cruzam na diagonal, uma paleta roxa sobre fundo escuro que ninguém escolheu e uma tipografia que não combina com mais nada que você publica. Dá pra entender. É também o equivalente visual de uma foto de stock — e se esse diagrama vai para sua documentação, seu README ou um post, você acaba abrindo Figma por trinta minutos ou simplesmente descartando o diagrama.
diagram-design é uma skill do Claude Code que ataca exatamente essa lacuna. Em vez de ensinar ao modelo uma sintaxe de diagramas, ele entrega um sistema de design: o que um diagrama pode conter, quantos elementos antes de deixar de comunicar, que cor vai onde e uma lista de coisas que nunca deve fazer. A saída não é Mermaid: é um arquivo HTML autocontido com SVG e CSS inline que você abre direto no navegador.
Publicado há dias por Cathryn Lavery (fundadora de BestSelf.co, escreve em littlemight.com), tem licença MIT e chegou ao posto #13 do trending diário do Trendshift em 9 de agosto de 2026. Hoje (verificado ao vivo em 12 de agosto de 2026) está em quase 10.000 estrelas — para um repo tão novo, isso é um sinal de tração forte, não um número de arredondamento.
O que realmente produz
A unidade de saída é um arquivo .html. Sem build step, sem JavaScript, sem imagens externas: o SVG vai inline, o CSS vai inline, e a única dependência externa é Google Fonts para as três tipografias. Você abre no navegador, tira um screenshot ou coloca em um site de docs.
Cada tipo vem em três variantes: minimal light, minimal dark e full-editorial (esta última adiciona cards de resumo ao redor do diagrama). O repo inclui uma galeria com abas em skills/diagram-design/assets/index.html onde você pode percorrer tudo antes de instalar nada — vale a pena abrir primeiro, porque é a forma mais rápida de decidir se a estética é sua.
Quantos tipos, exatamente
Aqui a documentação do próprio projeto se contradiz, e é bom saber antes de instalar:
- A galeria do README mostra 14 tipos com screenshots (architecture, flowchart, sequence, state machine, ER, timeline, swimlane, quadrant, nested, tree, org chart, Venn, layer stack, pyramid/funnel, mais um “consultant 2×2” especial).
- O
SKILL.mdque efetivamente se instala — o arquivo que Claude lê — lista um guia de seleção de 27 tipos. - A descrição do repositório no GitHub diz 29.
Os três números não são tanto uma contradição quanto a foto de um projeto que envia código mais rápido do que documenta. Os tipos que existem em SKILL.md mas não estão na galeria do README são os analíticos e de plataforma de dados: radar/spider, loop/flywheel, bar chart, line chart, Gantt, scatter plot, IT current-state, high-level data stack, process, medallion (armazenamento multi-camada com níveis de qualidade), data flow por função, topologia de integração de plataforma de dados e uma matriz de segurança por função. Se você julgasse a skill pelo README concluiria que não faz gráficos nem roadmaps. Faz.
Conseguência prática: leia skills/diagram-design/SKILL.md, não o README, para saber o que você pode pedir.
Instalação
Duas rotas, e a escolha importa mais do que parece.
Rota 1 — clone e symlink (recomendada se você vai personalizar):
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
Note que o symlink aponta para o diretório interno. A raiz do repo é um wrapper para que a mesma árvore funcione como plugin do Claude Code, plugin do Codex e skill standalone; a skill em si vive em skills/diagram-design/. Reinicie Claude Code e fica registrada como diagram-design.
Rota 2 — como plugin (mais rápida, mas a skill fica no cache do plugin, então edições manuais de references/style-guide.md não sobrevivem a uma atualização do plugin):
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
Em Claude Cowork: Customize → Directory → Plugins → + → cola cathrynlavery/diagram-design → Sync, e depois instala da lista Personal.
Em Codex:
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
Se você vai mexer no style guide manualmente — e a seção seguinte argumenta que deveria — tome a rota 1.
Seu primeiro diagrama
Não há comando para memorizar. A skill se ativa por intenção:
“Faz um diagrama de arquitetura da minha app: frontend, backend, PostgreSQL e um cache Redis.”
“Preciso de um quadrant dos projetos do Q2 por impacto vs. esforço.”
“Me dá um sequence diagram do handshake do OAuth.”
Claude escolhe o tipo, carrega apenas o arquivo de referência desse tipo, constrói o HTML e salva. Você também pode partir de um scaffold e editá-lo manualmente:
cp assets/template.html my-diagram.html # minimal light
cp assets/template-full.html my-diagram.html # editorial, com summary cards
A parte que faz parecer um seu projeto
Esta é a feature que justifica a instalação. De fábrica os diagramas renderizam com a paleta neutra da própria skill. Sessenta segundos de onboarding a substituem pela sua:
“onboard diagram-design to https://yoursite.com”
Claude faz fetch de sua homepage, extrai a paleta dominante e o font stack, e mapeia o que encontrou para funções semânticas em vez de valores hex crus:
| Detectado em seu site | Se converte em |
|---|---|
Fundo de <body> |
paper |
| Cor de texto principal | ink |
| Texto secundário / caption | muted |
| Cards ou containers | paper-2 |
| Cor de marca mais usado (CTA, link, heading) | accent |
Família tipográfica do <h1> |
|
Família tipográfica do <body> |
fonte node-name |
Fonte de <code> / <pre> |
fonte sublabel |
Mostra o diff proposto antes de escrever nada, e verifica contraste WCAG AA de ink sobre paper antes de confirmar. Essa verificação não é decorativa: os rótulos de um diagrama renderizam em 9–12px, e uma cor que passa como texto de corpo no seu site pode falhar nesse tamanho. Se falhar, o skill propõe um valor ajustado e explica por quê.
Tudo o que vem depois — os 27 tipos, o primitivo de anotação, a galeria — lê de references/style-guide.md e se refere a papéis (accent), nunca a hex. Você muda uma linha ali e todos os diagramas acompanham.
Também há um first-run gate para que você não envie acidentalmente diagramas com a paleta padrão para um projeto com marca: no primeiro diagrama de um projeto novo, se o guia de estilo continuar intacto, o skill para e oferece as opções (trazer de uma URL, extrair de um skill instalado, extrair de uma pasta local de design system, colar tokens manualmente, ou prosseguir com o default).
Um detalhe encontrado ao verificar esta nota: o gate decide se já foi personalizado comparando accent contra o valor literal #b5523a (o padrão “neutral stone + rust” que SKILL.md descreve), enquanto o README descreve o padrão instalado como “jet-black + atomic-tangerine” com outro accent. Se o accent da marca do seu projeto coincide com algum desses valores, ou se você edita a paleta sem tocar em accent, o gate pode ser lido como já-personalizado quando não está. É trivial contornar — você roda o onboarding explicitamente — mas é bom saber que é uma comparação de valor, não uma verificação real de “isso foi editado?”.
O sistema de design, condensado
As regras são o produto. Mesmo se você nunca instalar o skill, isso é um checklist usável:
- Uma única cor de accent, sobre no máximo dois elementos focais por diagrama. O accent diz ao leitor onde olhar primeiro; em todos os nós não diz nada.
- Três famílias tipográficas, cada uma com seu trabalho: uma serif para títulos e callouts em itálica, uma sans para nomes de nó, e uma mono estritamente para conteúdo técnico (portas, URLs, tipos de campo) — não como estética “dev” genérica.
- Bordas hairline de 1px, zero sombras, border radius no máximo de 10px.
- Cada coordenada, largura e gap divisível por 4. O guia de estilo é explícito que isso é o que evita que os diagramas pareçam gerados por IA.
- Densidade alvo 4/10: tecnicamente completo, sem precisar de legenda para entender. A filosofia declarada é que o diagrama não está pronto quando você adicionou tudo, mas quando já não se pode tirar nada.
E aplica complexity budgets duros, que é justamente a regra que falta à maioria dos prompts caseiros:
| Restrição | Limite |
|---|---|
| Nós por diagrama | 9 |
| Setas / transições | 12 |
| Elementos com accent | 2 |
| Linhas de sequence | 5 |
| Raias de swimlane | 5 |
| Itens em quadrant | 12 |
| Entidades ER | 8 |
| Profundidade de tree | 4 |
| Nós / profundidade de org chart | 12 / 4 |
| Camadas de layer stack | 6 |
| Círculos de Venn | 3 |
| Tarefas de Gantt | 12 |
| Pontos de scatter | 30 |
| Callouts de anotação | 2 |
A lista de anti-patterns vale roubar separadamente
SKILL.md traz uma lista explícita de coisas que nunca se deve fazer. Leia como diagnóstico de por que os diagramas gerados por IA parecem como parecem:
- dark mode com glow cyan/violeta
- uma monospace usada como estética “dev” transversal
- caixas idênticas para todos os nós
- uma legenda flutuando dentro da área do diagrama
- rótulos de seta sem retângulo de máscara
- texto vertical com
writing-modenas setas - três summary cards da mesma largura como layout padrão
- sombra em qualquer elemento
rounded-2xlnas caixas- accent em todos os nós “importantes”
- conectores diagonais entre nós fora do eixo
- um rótulo de seta tocando seu próprio conector
- dois conectores sobrepostos ou compartilhando traçado
- dois conectores compartilhando o mesmo ponto de ancoragem em uma caixa
- um conector roteado atrás de uma caixa que não é seu endpoint
Os conectores têm além disso regras obrigatórias próprias: traçados em ângulo reto arredondado, 6–10px de margem ao redor dos rótulos, e cada seta traçável de forma independente.
Dois primitivos
- Annotation callout — uma nota em serif itálica com linha guia Bézier pontilhada, para anotações editoriais à margem. Máximo de dois por diagrama.
- Sketchy filter — um filtro SVG de turbulence + displacement map que dá aspecto desenhado à mão. O skill o recomenda explicitamente para ensaios e o desaconselha para documentação técnica.
Quando não usá-lo
O skill documenta seus próprios limites, o que é mais raro do que deveria:
- Diagramas rápidos em unicode para um tweet ou saída de terminal → outra ferramenta mais leve.
- Uma lista de qualquer coisa → uma tabela ou bullets.
- Comparações antes/depois → uma tabela.
- Uma única caixa com um rótulo → escreva a frase e pronto.
Seu próprio encadramento antes de desenhar qualquer coisa: o leitor aprenderia mais disso do que de um parágrafo bem escrito? Se não, não desenhe.
Onde isso o deixa
O valor aqui não são os 27 tipos: é que alguém escreveu as restrições. A maioria de nós promptamos “me faça um diagrama de arquitetura bonito” e voltamos a discutir espaçamento, cor e densidade toda vez. Este skill converte isso em um arquivo: budgets que limitam a complexidade, uma lista de anti-patterns que nomeia os modos de falha, e uma camada de tokens que faz com que “sua marca” seja uma edição e não um search-and-replace em cada diagrama que você gerou na vida.
Instale por clone + symlink se vai tocar o guia de estilo, leia SKILL.md em vez do README para conhecer o catálogo real de tipos, e rode o onboarding antes do seu primeiro diagrama em qualquer projeto que tenha marca.
E você, desenha diagramas para sua documentação, ou pula porque deixá-los apresentáveis custa mais que escrever o parágrafo?