Design de Diagramas
Se a solicitação for em coreano, todos os textos dentro do diagrama (título, rótulos, descrições auxiliares, legendas) devem ser escritos em coreano. Rótulos auxiliares em inglês devem ser mantidos apenas para nomes próprios essenciais. Se o estilo da marca for solicitado e o usuário não tiver definido um, prossiga com o estilo padrão imediatamente. (Versão em coreano: 방구석프로 bangpro.ai.kr · Original: github.com/cathrynlavery/diagram-design, MIT License)
Crie diagramas como arquivos HTML independentes 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 — porteiro do guia de estilo
Antes de gerar o primeiro diagrama em um novo projeto, verifique se o guia de estilo foi personalizado.
Não publique diagramas com o estilo padrão silenciosamente em um projeto com marca definida.
Primeiro, resolva qualquer marcador .diagram-design do projeto conforme references/profiles.md; um marcador resolvido com sucesso seleciona seu perfil e ignora este porteiro. Essa referência gerencia 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 fornecidos (papel #f5f5f5, tinta #2d3142, destaque #bf4520), pause e pergunte ao usuário:
"Este é o 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 tiver sido personalizado (ou o usuário tiver escolhido explicitamente o padrão), pule este porteiro nas execuções posteriores. Um cabeçalho de perfil principal nomeia o perfil ativo copiado. Sem cabeçalho, qualquer valor de papel semântico ou família tipográfica diferente dos padrões fornecidos significa personalizado-não-salvo: pule o porteiro e ofereça salvá-lo como perfil. Tokens totalmente padrão sem marcador/cabeçalho acionam o porteiro. Após a integração, ofereça salvar como um perfil de cliente nomeado conforme references/profiles.md.
1. Filosofia
A melhor ação geralmente é a exclusão.
Aplicado a esquemas:
- Cada nó representa uma ideia distinta. Dois nós que sempre viajam juntos são um nó.
- Cada conexão carrega informação. Se a relação for óbvia 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 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, tabela ou lista com marcadores.
Não use para:
- Diagramas unicode rápidos → uma ferramenta de texto simples separada, como wiretext. Esta skill não inclui uma.
- Listas de coisas → tabela ou marcadores.
- Antes/depois de atributos apenas → 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 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 → Fluxo de dados |
| Slots de Pergunta / Entrada / Governança / Saída repetidos entre estágios | Estrutura de estágio 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 passou/falhou/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/implantuação permitidos/proibidos | Estrada pavimentada segura → 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 que precisa de E/S por bloco, restrições e um link de código | Decomposição de bloco rastreável → Árvore |
| Um assunto progride por fases, espera, tentativas, cancelamento e resultados finais | Mapa de fases do ciclo de vida → Máquina de estados |
O padrão possui primitivas semânticas e seu orçamento mais restrito; o tipo possui a 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 uma visão geral; escopos aninhados de admin vs. tráfego | Arquitetura | type-architecture.md |
| Mudança estrutural entre topologias sincronizadas Antes / Depois, com um razão 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 transferências | 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 / Teia | 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, relatórios, roteamento, escalonamento | 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: desmontagem, unboxing, ordem de montagem | Axonométrica explodida | type-exploded.md |
| Um andar ou local visto de cima em ângulo: salas com móveis, edifícios por fase | Planta axonométrica | type-axonometric-plan.md |
| Sobreposição entre conjuntos | Diagrama de 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 vinculado a um total final por contribuições assinadas (ponte orçamentária, deltas de headcount) | Cascata | type-waterfall.md |
| Parte-de-um-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 inclinação), uma distribuição por série (cume), ou movimento de classificação em vários instantâneos (solavanco) | 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 enxame de abelhas (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 transferências de dados | Processo | type-process.md |
| Armazenamento de dados em várias 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 entre 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 versus evolução — o que construir, comprar e o que está mudando | Mapa de Wardley | type-wardley.md |
| Trabalho em andamento por estado, com limites de WIP e itens bloqueados | Kanban | type-kanban.md |
| O que uma pessoa faz nos estágios de uma experiência e como se sente | Jornada do usuário | type-journey.md |
| O que o cliente faz versus o que o serviço esconde, entre 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 quê, com fan-in e ciclos que uma árvore não pode expressar | Grafo de dependências | type-dependency.md |
| Classes com operações, herança, composição (outros caminhos UML em outro lugar) | Classe UML | type-uml-class.md |
| Espinha dorsal narrativa dividida em versões, 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 parecerem úteis, escolha o eixo dominante; um padrão semântico pode adicionar primitivas específicas 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 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 o padrão semântico, se roteado), o predefinição 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 anote as suposições ao lado da entrega. 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 destaques 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 §6 | Falha automática: inclinações diagonais, rótulos tocando seu traço, máscaras recortadas por um nó posterior, caminhos sobrepostos, pontos de fixação compartilhados, trânsito atrás de uma caixa que não é de ponto final |
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 papéis semânticos (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 "ink", "accent", "muted", etc., procure o valor hex atual em
style-guide.md.
Trechos de referência de tipo escrevem papéis como espaços reservados: {ink}, {ink @ 0.40} para um papel em uma opacidade, e {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout} para fontes. Resolva cada espaço reservado contra style-guide.md antes de emitir.
…
[truncado para tradução]