Design de Diagramas
Crie diagramas como arquivos HTML auto-contidos com SVG inline e um sistema de design editorial.
Quarenta e cinco tipos visuais. Padrões semânticos descrevem comportamento; referências de tipo descrevem layout.
0. Configuração inicial — verificação do guia de estilo
Antes de gerar seu primeiro diagrama em um novo projeto, verifique se o guia de estilo foi personalizado.
Não envie diagramas com a skin padrão silenciosamente em um projeto com marca.
Primeiro, resolva qualquer marcador .diagram-design do projeto conforme references/profiles.md. Um marcador resolvido com sucesso seleciona seu perfil e ignora esta verificação. Essa referência é responsável por falhas, pelo padrão protegido e pelo comportamento de salvamento.
Abra references/style-guide.md e verifique os tokens padrão. Se ainda forem os padrões fornecidos (fundo #f5f5f5, tinta #2d3142, destaque #bf4520), pause e pergunte ao usuário:
"Este é seu primeiro diagrama neste projeto e o guia de estilo ainda é o padrão. Personalizar agora? Opções: (a) URL do site, (b) skill instalada, (c) pasta local/sistema de design, (d) colar tokens, (e) manter padrão, (f) carregar perfil salvo."
Em seguida, siga a seção correspondente de references/onboarding.md; para (f), siga references/profiles.md.
Depois que o guia de estilo for personalizado (ou o usuário escolher explicitamente o padrão), ignore esta verificação em execuções posteriores. Um cabeçalho de perfil principal nomeia o perfil ativo copiado. Sem cabeçalho, qualquer valor de função semântica ou família tipográfica diferente dos padrões fornecidos significa personalizado-não-salvo: ignore a verificação e ofereça salvá-lo como perfil. Tokens totalmente padrão sem marcador/cabeçalho acionam a verificação. Após o onboarding, ofereça salvar como um perfil de cliente nomeado conforme references/profiles.md.
1. Filosofia
O movimento de maior qualidade geralmente é a exclusão.
Aplicado a esquemas:
- Cada nó representa uma ideia distinta. Dois nós que sempre andam juntos são um nó.
- Cada conexão carrega informação. Se o relacionamento for óbvio pelo layout, remova a linha.
- Coral é editorial, não um sinalizador. 1–2 nós focais por diagrama. Usá-lo em 5 nós apaga o sinal.
- O esquema não está pronto quando tudo é adicionado. Está pronto quando nada pode ser removido.
Densidade alvo: 4/10. Suficiente para ser tecnicamente completo. Não tão denso a ponto de precisar de um guia. Acima de 9 nós, provavelmente são dois diagramas.
2. Quando Usar
Use para qualquer um dos 45 tipos visuais (§3) quando um leitor aprender mais com um visual do que com prosa, uma tabela ou uma lista com marcadores.
Não use para:
- Diagramas rápidos em unicode → uma ferramenta separada de texto simples, como
wiretext. Esta skill não inclui uma. - Listas de coisas → tabela ou marcadores.
- Antes/depois apenas com atributos → tabela; mudanças de topologia → Architecture delta.
- "Diagramas" de uma forma → apenas escreva a frase.
Antes de desenhar, pergunte: O leitor aprenderia mais com isso do que com um parágrafo bem escrito? Se não, não desenhe.
3. Seleção: padrão semântico, depois tipo visual
Quando comportamento, estado, imposição ou risco carregam o significado, primeiro carregue references/semantic-patterns.md e escolha um padrão principal. Em seguida, escolha o tipo visual mais próximo para o layout. Se nenhum padrão corresponder, escolha o tipo diretamente.
| Gatilho comportamental | Padrão semântico → tipo mais próximo |
|---|---|
| Fan-in, profundidade de fila, capacidade finita, gargalo | Fila Fan-in / Gargalo → Data flow |
| Slots repetidos de Pergunta / Entrada / Governança / Saída entre estágios | Framework de estágios com slots semânticos → Process |
| Conversa ou entrada solta se torna um artefato durável estruturado | Entrada não estruturada → artefato estruturado → Data flow |
| Duas trilhas de regras precisam de aprovado/reprovado/pulado/não-alcançado e primeira divergência | Trilhas pareadas de avaliação de política → Flowchart |
| Limites de confiança mais caminhos de ingresso ou implantação permitidos/proibidos | Caminho pavimentado seguro → Architecture |
| Controles agrupados por onde são aplicados | Catálogo de governança / controle → Layer stack |
| Defesas compensam lacunas anteriores e o risco residual se propaga | Camadas de segurança compensatórias → Layer stack |
| Decomposição hierárquica endereçável por ID, precisando de E/S, restrições e link de código por bloco | Decomposição de bloco rastreável → Tree |
| Um sujeito progride por fases, espera, tentativas, cancelamento e resultados terminais | Mapa de fases do ciclo de vida → State Machine |
O padrão é dono dos primitivos semânticos e de seu orçamento mais restrito; o tipo é dono da gramática de layout. Use references/animation.md apenas quando movimento for solicitado ou esclarecer materialmente uma mudança ordenada; estático permanece o padrão.
Guia de tipos visuais (45)
| Se você está mostrando… | Use | Referência |
|---|---|---|
| Componentes + conexões em um instantâneo; escopos administrativo vs. tráfego aninhados | Architecture | type-architecture.md |
| Mudança estrutural entre topologias sincronizadas Antes / Depois, com um livro-razão de Mudanças | Architecture delta | type-architecture-delta.md |
| Cenário de TI legado por fase ou departamento; mostra o estado antes | IT current-state | type-it-state.md |
| Lógica de decisão com ramificações | Flowchart | type-flowchart.md |
| Mensagens ordenadas no tempo entre atores | Sequence | type-sequence.md |
| Estados + transições + guardas | State machine | type-state.md |
| Entidades + campos + relacionamentos | ER / data model | type-er.md |
| Eventos posicionados no tempo | Timeline | type-timeline.md |
| Processo multifuncional com transferências | Swimlane | type-swimlane.md |
| Posicionamento / priorização em dois eixos | Quadrant | type-quadrant.md |
| Múltiplas entidades pontuadas em 3–5 critérios quantitativos | Radar / Spider | type-radar.md |
| Uma série quantitativa entre categorias cíclicas; ângulo=categoria, raio=magnitude | Polar chart | type-polar.md |
| Ciclo de reforço; a última etapa alimenta a primeira e um hub acumula estado | Loop | type-loop.md |
| Hierarquia por contenção / escopo | Nested | type-nested.md |
| Relacionamentos Pai → filhos | Tree | type-tree.md |
| Propriedade humana/agente/equipe, reporte, roteamento, escalação | Org chart | type-org-chart.md |
| Níveis de abstração empilhados | Layer stack | type-layers.md |
| Partes de um objeto separadas ao longo de um eixo: desmontagem, unboxing, ordem de montagem | Exploded axonometric | type-exploded.md |
| Um andar ou local visto de cima em um ângulo: salas com móveis, edifícios por fase | Axonometric plan | type-axonometric-plan.md |
| Sobreposição entre conjuntos | Venn | type-venn.md |
| Hierarquia classificada ou queda de conversão | Pyramid / funnel | type-pyramid.md |
| Comparação quantitativa entre categorias | Bar chart | type-bar.md |
| Um total inicial conectado a um total final por contribuições assinadas (ponte orçamentária, deltas de headcount) | Waterfall | type-waterfall.md |
| Parte-de-todo onde os tamanhos relativos são a história | Treemap | type-treemap.md |
| Dados tabulados cruzados; preenchimento codifica valor por célula | Heatmap | type-heatmap.md |
| Tendências contínuas ao longo do tempo, mudança entre exatamente dois estados (slopegraph), uma distribuição por série (ridgeline) ou movimento de classificação em vários instantâneos (bump) | Line chart | type-line.md |
| Tarefas e fases em uma linha do tempo | Gantt | type-gantt.md |
| Correlação ou distribuição de duas variáveis; bolha (três variáveis), beeswarm (uma variável, ponto por item) e box plot (sumário de cinco números por grupo) variantes | Scatter plot | type-scatter.md |
| Pilha de dados ponta a ponta em um cluster de contêineres | High-Level | type-high-level.md |
| Processo sequencial multi-ator com transferências de dados | Process | type-process.md |
| Armazenamento de dados em várias camadas com níveis de qualidade e políticas de acesso | Medallion | type-medallion.md |
| Fluxo de dados com escopo de função: quem faz o quê em cada etapa do pipeline | Data flow | type-data-flow.md |
| Topologia de integração de uma plataforma de dados — fontes → núcleo → consumidores | DP integration | type-dp-integration.md |
| Matriz de permissões de acesso por função / componente | DP security matrix | type-dp-security-matrix.md |
| Uma quantidade se dividindo e mesclando entre estágios, largura da banda = quantidade | Sankey | type-sankey.md |
| Causas de um efeito observado, agrupadas por categoria (análise de causa raiz) | Fishbone | type-fishbone.md |
| Cadeia de valor contra evolução — o que construir, comprar e o que está mudando | Wardley map | type-wardley.md |
| Trabalho em andamento por estado, com limites de WIP e itens bloqueados | Kanban | type-kanban.md |
| O que uma pessoa faz nas etapas de uma experiência e como se sente | User journey | type-journey.md |
| O que o cliente faz vs. o que o serviço esconde, entre estágios, com uma linha de visibilidade | Service blueprint | type-service-blueprint.md |
| Onde o software é executado — zonas, hosts, artefatos, réplicas, portas | Deployment | type-deployment.md |
| O que depende do quê, com fan-in e ciclos que uma árvore não pode expressar | Dependency graph | type-dependency.md |
| Classes com operações, herança, composição (outros caminhos UML em outro lugar) | UML class | type-uml-class.md |
| Espinha dorsal narrativa dividida em releases, com a linha de corte | Story map | type-story-map.md |
| Tabelas físicas: tipos SQL, restrições, índices, chaves estrangeiras em nível de coluna | Database schema | type-db-schema.md |
Regras práticas:
- Se uma tabela de 3 colunas comunica a mesma coisa, escolha a tabela.
- Se dois tipos parecem úteis, escolha o eixo dominante; um padrão semântico pode adicionar primitivos específicos de comportamento, não uma segunda gramática de layout.
- Se você ultrapassou o orçamento de complexidade (§7), divida em uma visão geral + detalhe.
Sempre carregue a referência de tipo escolhida vinculada no guia antes de desenhar. Quando roteado acima, carregue também semantic-patterns.md; quando animação for escolhida, carregue animation.md.
Confirmar antes de desenhar
Antes de renderizar, declare o plano em uma mensagem curta: o tipo visual escolhido (e padrão semântico, se roteado), o preset de tamanho e qualquer coisa que o orçamento de complexidade (§7) forçará para fora. Se o usuário estiver acessível, deixe-o redirecionar antes de você desenhar; se não, prossiga e observe as suposições ao lado do entregável. Pule a pausa apenas quando a solicitação já definir tipo, tamanho e conteúdo exatamente.
4. Antipadrões Universais
Estes marcam esquemas "AI slop" de qualquer tipo:
| Antipadrão | Por que falha |
|---|---|
| Modo escuro + brilho ciano/roxo | Parece "técnico" sem decisões de design |
| JetBrains Mono como fonte "dev" genérica | Mono é para conteúdo técnico — portas, comandos, URLs. Nomes vão em Geist sans. |
| Caixas idênticas para cada nó | Apaga a hierarquia |
| Legenda flutuando dentro da área do diagrama | Colide com nós |
| Rótulos de seta sem retângulo de máscara | Sangra através da linha |
Texto vertical writing-mode em setas | Ilegível |
| 3 cartões de resumo de largura igual como padrão | Grade genérica — varie larguras |
| Sombra em qualquer elemento | Sombras estão fora. Bordas estão dentro. |
rounded-2xl em caixas | Raio máximo 6–10px ou nenhum |
| Coral em cada nó "importante" | Coral é 1–2 acentos editoriais, não um sistema de sinalização |
| Reproduzir o layout do renderizador do Mermaid | Importa espaçamento e roteamento automáticos em vez de fazer um layout editorial |
| Qualquer violação das seis regras de conector da §6 | Falha automática: inclinações diagonais, rótulos tocando seu traço, máscaras cortadas por um nó posterior, caminhos sobrepostos, pontos de anexação compartilhados, trânsito atrás de uma caixa não terminal |
Antipadrões específicos de tipo vivem em cada referência de tipo vinculada no guia.
5. Sistema de Design
O sistema de design é personalizável. references/style-guide.md é a fonte única da verdade para cores, tipografia, tokens e a paleta padrão; este arquivo nomeia funções semânticas (paper, ink, muted, accent, link, …). Para aplicar uma marca, edite style-guide.md ou execute o fluxo baseado em URL em references/onboarding.md.
Quando as especificações abaixo ou nas referências de tipo mencionarem "tinta", "destaque", "sutil", etc., procure o valor hexadecimal atual em
style-guide.md.
Trechos de referência de tipo escrevem funções como placeholders: {ink}, {ink @ 0.40} para uma função com opacidade, e {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout} para fontes. Resolva cada place holder em style-guide.md antes de emitir.
Funções semânticas (de relance)
| Função | Propósito |
|---|---|
paper, paper-2 | Fundo da página e fundo do contêiner |
ink | Texto / traço principal |
muted, soft | Segundo plano |
6. Regras de Conector
Todo conector deve seguir estas seis regras:
- Sem inclinações diagonais. Ângulos de 90° apenas. Curvas Bezier são permitidas quando a alternativa seria um emaranhado.
- Rótulos não tocam seu traço. Um retângulo de máscara (fill: papel, 2px de padding) separa o texto da linha.
- Máscaras não são cortadas por nós posteriores. Ordem Z: conector → máscara → nós.
- Caminhos não se sobrepõem. Se dois conectores compartilham um segmento, afaste um ou agrupe.
- Cada extremidade anexa a um ponto de anexação único. Nenhum ponto compartilhado.
- Trânsito não passa atrás de uma caixa que não seja seu destino. Roteie ao redor.
Violar qualquer uma é falha automática.
7. Orçamento de Complexidade
Um diagrama não deve exigir mais de 5 segundos para ser compreendido. Use estas diretrizes:
| Métrica | Limite |
|---|---|
| Nós | 9 máx. (acima disso, dividir) |
| Conexões | 1,5× nós (aprox.) |
| Rótulos | Todos devem ser legíveis no tamanho final |
| Cores | Máx. 4 funções semânticas ativas (papel, tinta, 1–2 destaques) |
Acima de 9 nós, crie um diagrama de visão geral e um de detalhe.
8. Saída
Sempre HTML auto-contido com SVG inline. Opções:
- HTML (.html) — padrão, visualizável em qualquer navegador
- SVG (.svg) — extraído do HTML, para incorporação
- PNG (.png) — rasterizado, para documentos
Use a extensão correta: diagram-name.html, diagram-name.svg, diagram-name.png.
9. Importação
Suporta importação de:
- .drawio — diagramas do draw.io
- Mermaid — sintaxe Mermaid (
mermaid ...) - .excalidraw — arquivos Excalidraw
Após a importação, aplique o sistema de design editorial e limpe quaisquer antipadrões.
10. Referências
references/style-guide.mdreferences/onboarding.mdreferences/profiles.mdreferences/semantic-patterns.mdreferences/animation.md- Tipo:
type-architecture.md - Tipo:
type-flowchart.md - Tipo:
type-sequence.md - Tipo:
type-state.md - Tipo:
type-er.md - Tipo:
type-timeline.md - Tipo:
type-swimlane.md - Tipo:
type-quadrant.md - Tipo:
type-radar.md - Tipo:
type-polar.md - Tipo:
type-loop.md - Tipo:
type-nested.md - Tipo:
type-tree.md - Tipo:
type-org-chart.md - Tipo:
type-layers.md - Tipo:
type-exploded.md - Tipo:
type-axonometric-plan.md - Tipo:
type-venn.md - Tipo:
type-pyramid.md - Tipo:
type-bar.md - Tipo:
type-waterfall.md - Tipo:
type-treemap.md - Tipo:
type-heatmap.md - Tipo:
type-line.md - Tipo:
type-gantt.md - Tipo:
type-scatter.md - Tipo:
type-high-level.md - Tipo:
type-process.md - Tipo:
type-medallion.md - Tipo:
type-data-flow.md - Tipo:
type-dp-integration.md - Tipo:
type-dp-security-matrix.md - Tipo:
type-sankey.md - Tipo:
type-fishbone.md - Tipo:
type-wardley.md - Tipo:
type-kanban.md - Tipo:
type-journey.md - Tipo:
type-service-blueprint.md - Tipo:
type-deployment.md - Tipo:
type-dependency.md - Tipo:
type-uml-class.md - Tipo:
type-story-map.md - Tipo:
type-db-schema.md