Design de Diagramas
Crie diagramas como arquivos HTML autônomos 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 — Portã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 entregue silenciosamente diagramas com skin padrão em um projeto com marca própria.
Primeiro, resolva qualquer marcador .diagram-design do projeto conforme references/profiles.md; um marcador resolvido com sucesso seleciona seu perfil e ignora este portão. Essa referência é responsável por falhas, o padrão protegido e o comportamento de salvamento.
Abra references/style-guide.md e verifique os tokens padrão. Se eles ainda forem os padrões enviados (papel #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 escolheu explicitamente o padrão), ignore este portão em execuções posteriores. Um cabeçalho de perfil principal nomeia o perfil ativo copiado. Sem um cabeçalho, qualquer valor de função semântica ou família tipográfica diferente dos padrões enviados significa personalizado-não salvo: ignore o portão e ofereça salvá-lo como um perfil. Tokens totalmente padrão sem marcador/cabeçalho acionam o portão. Após a integração, 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 é óbvio pelo layout, remova a linha.
- Coral é editorial, não uma bandeira. 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 que precise 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 unicode rápidos → uma ferramenta de texto simples separada, como wiretext. Esta skill não fornece uma.
- Listas de coisas → tabela ou marcadores.
- Antes/depois apenas de atributos → tabela; mudanças de topologia → Delta de arquitetura.
- "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, aplicação ou risco carrega o significado, primeiro carregue references/semantic-patterns.md e escolha um padrão primário. 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 → Fluxo de dados |
| Slots repetidos de Pergunta / Entrada / Governança / Saída entre estágios | Estrutura de estágios com slots semânticos → Processo |
| Conversa ou entrada solta se torna um artefato durável estruturado | Entrada não estruturada → artefato estruturado → Fluxo de dados |
| Duas trilhas de regras precisam de passagem/falha/pulado/não alcançado e primeira divergência | Trilhas pareadas de avaliação de política → Fluxograma |
| Limites de confiança mais caminhos de ingresso ou deploy permitidos/proibidos | Estrada segura pavimentada → Arquitetura |
| Controles agrupados por onde são aplicados | Catálogo de governança/controle → Pilha de camadas |
| Defesas compensam lacunas anteriores e o risco residual se propaga | Camadas de segurança compensatórias → Pilha de camadas |
| Decomposição hierárquica endereçável por ID, necessitando de E/S por bloco, restrições e um link de código | Decomposição de bloco rastreável → Árvore |
| Um sujeito progride através de fases, espera, tentativas, cancelamento e resultados terminais | Mapa de fase de ciclo de vida → Máquina de estados |
O padrão é dono dos primitivos semânticos e seu orçamento mais apertado; 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 aninhados de admin vs tráfego | Arquitetura | type-architecture.md |
| Mudança estrutural entre topologias sincronizadas Antes / Depois, com um registro de Mudanças | Delta de arquitetura | type-architecture-delta.md |
| Cenário de TI legado por fase ou departamento; mostra o estado anterior | Estado atual de TI | type-it-state.md |
| Lógica de decisão com ramificações | Fluxograma | type-flowchart.md |
| Mensagens ordenadas no tempo entre atores | Sequência | type-sequence.md |
| Estados + transições + guardas | Máquina de estados | type-state.md |
| Entidades + campos + relacionamentos | ER / modelo de dados | type-er.md |
| Eventos posicionados no tempo | Linha do tempo | type-timeline.md |
| Processo multifuncional com handoffs | Raia | type-swimlane.md |
| Posicionamento / priorização em dois eixos | Quadrante | type-quadrant.md |
| Múltiplas entidades pontuadas em 3–5 critérios quantitativos | Radar / Aranha | type-radar.md |
| Uma série quantitativa em categorias cíclicas; ângulo=categoria, raio=magnitude | Gráfico polar | 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 | Aninhado | type-nested.md |
| Relacionamentos Pai → filhos | Árvore | type-tree.md |
| Propriedade humana/agente/equipe, reporte, roteamento, escalada | Organograma | type-org-chart.md |
| Níveis de abstração empilhados | Pilha de camadas | type-layers.md |
| Partes de um objeto separadas ao longo de um eixo: uma desmontagem, uma unboxing, ordem de montagem | Axonométrica explodida | type-exploded.md |
| Um andar ou local visto de cima em um ângulo: salas com móveis, edifícios por fase | Planta axonométrica | type-axonometric-plan.md |
| Sobreposição entre conjuntos | Venn | type-venn.md |
| Hierarquia classificada ou queda de conversão | Pirâmide / funil | type-pyramid.md |
| Comparação quantitativa entre categorias | Gráfico de barras | type-bar.md |
| Um total inicial conectado a um total final por contribuições sinalizadas (ponte orçamentária, deltas de headcount) | Cascata | type-waterfall.md |
| Parte-do-todo onde os tamanhos relativos são a história | Treemap | type-treemap.md |
| Dados tabulados cruzados; preenchimento codifica valor por célula | Mapa de calor | type-heatmap.md |
| Tendências contínuas ao longo do tempo, mudança entre exatamente dois estados (gráfico de declive), uma distribuição por série (ridgeline) ou movimento de classificação em vários instantâneos (bump) | Gráfico de linhas | type-line.md |
| Tarefas e fases em uma linha do tempo | Gantt | type-gantt.md |
| Correlação ou distribuição de duas variáveis; variantes bolha (três variáveis) e beeswarm (uma variável, ponto por item) | Gráfico de dispersão | type-scatter.md |
| Pilha de dados ponta a ponta em um cluster de contêineres | Alto nível | type-high-level.md |
| Processo sequencial multi-ator com handoffs de dados | Processo | type-process.md |
| Armazenamento de dados em múltiplas camadas com níveis de qualidade e políticas de acesso | Medalhão | type-medallion.md |
| Fluxo de dados com escopo de função: quem faz o quê em cada etapa do pipeline | Fluxo de dados | type-data-flow.md |
| Topologia de integração de uma plataforma de dados — fontes → núcleo → consumidores | Integração DP | type-dp-integration.md |
| Matriz de permissões de acesso por função / por componente | Matriz de segurança DP | type-dp-security-matrix.md |
| Uma quantidade se dividindo e mesclando através de estágios, largura da banda = quantidade | Sankey | type-sankey.md |
| Causas de um efeito observado, agrupadas por categoria (análise de causa raiz) | Espinha de peixe | type-fishbone.md |
| Cadeia de valor contra evolução — o que construir, comprar e o que está mudando | Mapa de Wardley | type-wardley.md |
| Trabalho em andamento por estado, com limites WIP e itens bloqueados | Kanban | type-kanban.md |
| O que uma pessoa faz através dos estágios de uma experiência e como se sente | Jornada do usuário | type-journey.md |
| O que o cliente faz vs o que o serviço esconde, através de estágios, com uma linha de visibilidade | Blueprint de serviço | type-service-blueprint.md |
| Onde o software é executado — zonas, hosts, artefatos, réplicas, portas | Implantação | type-deployment.md |
| O que depende do que, com fan-in e ciclos que uma árvore não pode expressar | Grafo de dependência | type-dependency.md |
| Classes com operações, herança, composição (outros diagramas UML em outro lugar) | Classe UML | type-uml-class.md |
| Espinha dorsal narrativa fatiada em releases, com a linha de corte | Mapa de história | type-story-map.md |
| Tabelas físicas: tipos SQL, restrições, índices, FKs no nível de coluna | Esquema de banco de dados | 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 do tipo escolhido vinculada no guia antes de desenhar. Quando roteado acima, carregue também semantic-patterns.md; quando a animação for escolhida, carregue animation.md.
Confirme antes de desenhar
Antes de renderizar, declare o plano em uma mensagem curta: o tipo visual escolhido (e padrão semântico, se roteado), a predefinição de tamanho e qualquer coisa que o orçamento de complexidade (§7) forçará a sair. Se o usuário estiver acessível, deixe-o redirecionar antes de desenhar; caso contrário, prossiga e anote as suposições ao lado da entrega. Pule a pausa apenas quando a solicitação já fixa exatamente tipo, tamanho e conteúdo.
4. Anti-padrões Universais
Estes marcam esquemas "AI slop" de qualquer tipo:
| Anti-padrão | Por que falha |
|---|---|
| Modo escuro + brilho ciano/roxo | Parece "técnico" sem decisões de design |
| JetBrains Mono como fonte genérica de "dev" | 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 |
Modo de escrita vertical writing-mode em setas | Ileggível |
| 3 cartões de resumo de largura igual como padrão | Grade genérica — varie as 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 do §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 que não é o ponto final |
Anti-padrõ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 de 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 mencionam "tinta", "destaque", "suave", 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 em uma opacidade, e {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout} para fontes. Resolva cada placeholder contra 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 principal / traço |
muted, soft | Texto secundário, setas padrão, sub-rótulos |
accent | Destaque editorial (1–2 nós) |
link | Links clicáveis |
success, warning, error, info | Estados de validação ou status |
line | Traço de conector padrão |
grid | Linhas de grade (quadrantes, gráficos) |
font-ui, font-mono | Famílias tipográficas |
Regras de Conector
- Ângulos de 90° ou 0°. Sem inclinações diagonais.
- Rótulos nunca tocam seu traço. Use um retângulo de máscara com preenchimento
paper. - As máscaras devem estar na frente de todos os traços, não cortadas por um nó posterior.
- Caminhos não se sobrepõem. Use curvas ou desvio.
- Cada conector tem seu próprio ponto de anexação. Não compartilhe pontos.
- Nunca transite atrás de uma caixa que não seja o ponto final.
6. Orçamento de Complexidade
| Limiar | Ação |
|---|---|
| ≤ 9 nós | Diagrama único |
| 10–15 nós | Dividir em visão geral + detalhe ou usar um tipo mais abstrato |
| > 15 nós | Deve ser dividido em múltiplos diagramas |
7. Saída
Gere um arquivo HTML autônomo com SVG inline. O arquivo deve:
- Conter todos os estilos inline (não dependa de CSS externo)
- Ser visualizável em qualquer navegador moderno
- Ter uma tag
<title>descritiva - Incluir um metadado
<meta>com a data de geração e a versão da skill
Formatos de saída adicionais (PNG, SVG) podem ser gerados sob demanda.
8. Importação
Suporta importação de:
.drawio(diagrams.net).excalidraw(Excalidraw)- Mermaid (código mermaid)
A importação converte o layout original no sistema de design editorial, aplicando o guia de estilo ativo. O layout original é usado como referência, não uma réplica exata.
9. Manutenção e Perfis
- Os perfis são armazenados em
references/profiles.md. - Para salvar um perfil, use o comando
save-profilecom um nome. - Para carregar um perfil, use o comando
load-profile. - Para listar perfis, use
list-profiles.
10. Referências
references/style-guide.md— Guia de estilo e tokensreferences/profiles.md— Gerenciamento de perfisreferences/onboarding.md— Fluxo de integraçãoreferences/semantic-patterns.md— Padrões semânticosreferences/animation.md— Animaçãoreferences/type-*.md— Referências de tipo visual
Última atualização: 2025