{
  "esquema": "design-guia-para-agentes/v1",
  "guia": "diagramas",
  "nome": "Diagramas",
  "titulo": "Diagramas de arquitetura e fluxo: do texto ao desenho pronto",
  "descricao": "Aula de diagramas para o time, com vídeo e podcast: as três famílias de figura, Mermaid 11, a régua entre Mermaid e D2 e o contraste da WCAG 2.2.",
  "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/",
  "arquivos": {
    "markdown": "https://brasilgeo.ai/leadlovers2026/design/diagramas/agentes.md",
    "json": "https://brasilgeo.ai/leadlovers2026/design/diagramas/agentes.json",
    "indice": "https://brasilgeo.ai/leadlovers2026/design/llms.txt"
  },
  "revisadoEm": "2026-11-16",
  "idioma": "pt-BR",
  "resumo": "Diagrama nasce como texto versionado no repositório e vira SVG no build, nunca no navegador do leitor. A primeira pergunta é quem monta o desenho: quem escreve (Mermaid, D2, Graphviz), quem usa o produto (editor de fluxo) ou a própria rede de dados (grafo). O resultado é uma figura legível nos dois temas, com nome acessível e sem biblioteca na página.",
  "quandoUsar": [
    "Pedido de fluxograma, sequência, estados, C4, organograma, matriz 2x2 ou outro diagrama de documentação.",
    "Escolha entre Mermaid, D2 e Graphviz para um diagrama de arquitetura.",
    "Tela em que o usuário arrasta caixas e salva o fluxo (editor tipo React Flow).",
    "Diagrama gerado por IA que precisa de validação antes de entrar no repositório.",
    "SVG exibido no celular, no tema escuro, em e-mail, slide ou arquivo baixado."
  ],
  "regras": [
    {
      "id": "DIA-01",
      "nivel": "obrigatória",
      "regra": "Antes de escolher ferramenta, responda: quem monta o desenho? Quem escreve usa texto compilado; quem usa o produto precisa de editor de fluxo; rede com milhares de nós usa grafo.",
      "porque": "Errar a família transforma um dia de trabalho em duas semanas."
    },
    {
      "id": "DIA-02",
      "nivel": "obrigatória",
      "regra": "Se quem olha precisa salvar o que montou, voltar para editar ou enviar a outra pessoa mexer, abandone Mermaid e trate como funcionalidade de produto (React Flow, Excalidraw).",
      "porque": "Teste das três condições do curso: um sim em qualquer uma tira o caso do texto."
    },
    {
      "id": "DIA-03",
      "nivel": "obrigatória",
      "regra": "Compile o diagrama no build e sirva SVG puro. Nunca embarque o runtime do Mermaid na página de leitura.",
      "porque": "mermaid.min.js 11.16.1 pesa 3,4 MiB sem compressão; o SVG compilado fica perto de 30 KB."
    },
    {
      "id": "DIA-04",
      "nivel": "recomendada",
      "regra": "Comece com Mermaid até cerca de 12 elementos; acima disso, ou com camadas aninhadas, compare com D2.",
      "porque": "Convenção didática do curso, sem limite técnico; Mermaid também agrupa e aceita layout ELK."
    },
    {
      "id": "DIA-05",
      "nivel": "obrigatória",
      "regra": "Fixe a versão do Mermaid no package.json e gere o código pela documentação dessa versão.",
      "porque": "Exemplos usam a série 11 (11.16.1); a doc atual já mostra a 12 e a IA inventa sintaxe."
    },
    {
      "id": "DIA-06",
      "nivel": "obrigatória",
      "regra": "Valide todo código Mermaid com await mermaid.parse() e trate a rejeição antes de renderizar. Depois confira atores, condições, saídas, retornos e exceções contra o processo real. Para definição vinda de fora, mantenha securityLevel: \"strict\".",
      "porque": "parse() só confere sintaxe; não detecta condição omitida nem sanitiza. strict codifica HTML e desabilita cliques."
    },
    {
      "id": "DIA-07",
      "nivel": "obrigatória",
      "regra": "Toda seta que sai de uma decisão leva a condição escrita, e o caminho de retorno existe.",
      "porque": "Caixas ligadas sem condição escondem a decisão."
    },
    {
      "id": "DIA-08",
      "nivel": "obrigatória",
      "regra": "Use accTitle e accDescr em todo Mermaid; em SVG manual, title, desc, role=\"img\" e aria-labelledby. Se o SVG for usado como img, escreva o alt com origem, condição e destino.",
      "porque": "Como img, o title interno não é exposto; PNG descarta os atributos."
    },
    {
      "id": "DIA-09",
      "nivel": "obrigatória",
      "regra": "Nunca escreva hex solto no diagrama publicado. Injete tokens do projeto com reserva: var(--token, #hex).",
      "porque": "Hex fixo some ao trocar de tema."
    },
    {
      "id": "DIA-10",
      "nivel": "obrigatória",
      "regra": "Token só alcança SVG inline. Para SVG chamado por img, grave as cores no arquivo ou compile uma versão clara e outra escura e sirva por picture com prefers-color-scheme.",
      "porque": "Como img, o SVG é documento isolado e var(--text) resolve para nada."
    },
    {
      "id": "DIA-11",
      "nivel": "obrigatória",
      "regra": "No Mermaid, themeVariables aceita só hexadecimal: use uma paleta por tema no compilador ou aplique var() no SVG inline no pós-processo.",
      "porque": "var(--token) passado ao motor não substitui a configuração."
    },
    {
      "id": "DIA-12",
      "nivel": "obrigatória",
      "regra": "Dê fill explícito a cada text do SVG, sem herança do grupo.",
      "porque": "Rótulo cinza sobre fundo cinza surge quando o preenchimento falha ao herdar."
    },
    {
      "id": "DIA-13",
      "nivel": "obrigatória",
      "regra": "Contraste nos dois temas: 4,5:1 no texto normal e 3:1 em linhas e formas necessárias à compreensão, medido sobre o fundo real.",
      "porque": "WCAG 2.2, critérios 1.4.3 e 1.4.11; a amostra cinza-claro do guia fica perto de 2:1."
    },
    {
      "id": "DIA-14",
      "nivel": "obrigatória",
      "regra": "Rótulo com 14 px ou mais na dimensão exibida e nunca abaixo de 12 px a 390 px. Conta: fonte x largura exibida / largura do viewBox. Todo SVG tem viewBox.",
      "porque": "Fonte 15 em viewBox 1200 chega a 4,9 px no celular. O 14 px é referência do curso, não norma."
    },
    {
      "id": "DIA-15",
      "nivel": "recomendada",
      "regra": "Compile com mmdc usando -I (id único), -c (JSON de configuração) e -p (Puppeteer, sandbox em CI Linux): mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura.",
      "porque": "Sem -I, todo SVG sai com id my-svg e dois diagramas colidem."
    },
    {
      "id": "DIA-16",
      "nivel": "recomendada",
      "regra": "Uma figura responde uma pergunta só. No C4, um nível por figura (contexto, contêiner, componente, código), começando pelo contexto.",
      "porque": "Contêiner e componente no mesmo quadro produzem desenho que ninguém lê inteiro."
    },
    {
      "id": "DIA-17",
      "nivel": "recomendada",
      "regra": "Respeite o limite do tipo: fluxograma até 15 caixas, raias até 5, sequência até 8 mensagens, organograma até 4 níveis, árvore de decisão até 3, ER até 15 tabelas; grafo de força só com 20 nós ou mais.",
      "porque": "Acima disso divida a figura ou troque de tipo (catálogo de 36 tipos)."
    },
    {
      "id": "DIA-18",
      "nivel": "obrigatória",
      "regra": "Antes de padronizar um tipo novo ou -beta do Mermaid, confira onde ele precisa renderizar (GitHub, GitLab, VS Code, Obsidian, Notion).",
      "porque": "A versão embarcada de cada plataforma decide o que funciona."
    },
    {
      "id": "DIA-19",
      "nivel": "obrigatória",
      "regra": "tldraw exige license key em produção; React Flow e Excalidraw são MIT. Confira a licença antes de orçar editor.",
      "porque": "Quem orçou tldraw como MIT precisa refazer a conta."
    },
    {
      "id": "DIA-20",
      "nivel": "recomendada",
      "regra": "No editor de fluxo, recuse conexão inválida com motivo escrito (nó ausente, autoligação, tipo proibido, duplicata, ciclo), valide o arquivo importado inteiro antes de trocar o estado e exporte com schemaVersion.",
      "porque": "Evita apagar o desenho aberto e laço infinito na busca."
    }
  ],
  "decisoes": [
    {
      "situacao": "Time escreve documentação e o leitor só lê",
      "escolha": "Texto compilado no build (Mermaid, D2 ou Graphviz), saída em SVG.",
      "evitar": "Biblioteca de diagrama no navegador do leitor."
    },
    {
      "situacao": "Usuário do produto arrasta, conecta e salva caixas",
      "escolha": "Editor de fluxo: React Flow ou Excalidraw (MIT).",
      "evitar": "Mermaid; tldraw sem license key."
    },
    {
      "situacao": "Milhares de nós e o agrupamento é a resposta",
      "escolha": "Cytoscape.js (layout cose) ou Sigma.js com Graphology em WebGL.",
      "evitar": "Grafo de força com menos de 20 nós."
    },
    {
      "situacao": "Fluxo simples, até cerca de 12 elementos",
      "escolha": "Mermaid, com poucas linhas e suporte nativo nas plataformas."
    },
    {
      "situacao": "Contêineres dentro de contêineres, ou muitos elementos",
      "escolha": "D2 (agrupamento nativo) com layout ELK; compare com Mermaid.",
      "evitar": "Subgraphs profundos no Mermaid."
    },
    {
      "situacao": "Raias horizontais fiéis ou mais de 5 raias",
      "escolha": "D2 ou Graphviz com clusters.",
      "evitar": "Mermaid subgraph."
    },
    {
      "situacao": "Processo com decisão e retorno",
      "escolha": "Fluxograma com condição na seta.",
      "evitar": "Sequência (só ordem) e esteira (fila reta)."
    },
    {
      "situacao": "Situações e transições com volta",
      "escolha": "stateDiagram-v2.",
      "evitar": "Fluxograma quando o processo é linear sem volta."
    },
    {
      "situacao": "Causas em paralelo, mais de uma por porquê",
      "escolha": "Espinha de peixe (flowchart RL com subgraphs).",
      "evitar": "Árvore de cinco causas, de uma resposta por degrau."
    },
    {
      "situacao": "Figura vai para e-mail, slide ou download",
      "escolha": "SVG autocontido: fundo, cores, font-family, xmlns, title e desc; uma versão por tema.",
      "evitar": "var() sem reserva; id e class da página de origem."
    }
  ],
  "numeros": [
    {
      "valor": "4,5:1",
      "uso": "Contraste mínimo do texto normal nos dois temas.",
      "fonte": "WCAG 2.2, 1.4.3 (AA)"
    },
    {
      "valor": "3:1",
      "uso": "Contraste mínimo de linhas e formas necessárias à compreensão.",
      "fonte": "WCAG 2.2, 1.4.11"
    },
    {
      "valor": "14 px",
      "uso": "Referência do curso para rótulos na dimensão exibida.",
      "fonte": "Convenção do curso, não norma"
    },
    {
      "valor": "12 px a 390 px",
      "uso": "Piso da letra efetiva no celular.",
      "fonte": "Oficina de SVG legível"
    },
    {
      "valor": "12 elementos",
      "uso": "Ponto para comparar Mermaid com D2.",
      "fonte": "Convenção didática do curso"
    },
    {
      "valor": "3,4 MiB",
      "uso": "Peso do mermaid.min.js 11.16.1 sem compressão (medido em 10/09/2026).",
      "fonte": "Medição do guia"
    },
    {
      "valor": "cerca de 30 KB",
      "uso": "Peso do SVG compilado.",
      "fonte": "Guia da aula"
    },
    {
      "valor": "Mermaid 11.16.1",
      "uso": "Versão de referência (4 de agosto de 2026); mermaid-cli 11.16.0.",
      "fonte": "Releases do GitHub"
    }
  ],
  "evitar": [
    {
      "erro": "Embarcar o motor do Mermaid na página de leitura.",
      "corrija": "Compilar no build com mermaid-cli e servir SVG."
    },
    {
      "erro": "Confiar no código de IA porque o desenho renderizou.",
      "corrija": "parse() mais revisão do processo contra a descrição."
    },
    {
      "erro": "Fluxo só com caixas, setas sem condição.",
      "corrija": "Nomear cada saída de decisão e o retorno."
    },
    {
      "erro": "Mermaid exportado com htmlLabels (foreignObject), que some fora do navegador.",
      "corrija": "Gerar com htmlLabels: false para os rótulos virarem text."
    },
    {
      "erro": "Ampliar a letra sem ampliar a caixa.",
      "corrija": "Aumentar as caixas junto ou quebrar o rótulo em tspan."
    },
    {
      "erro": "Usar área de círculo ou faixa como quantidade.",
      "corrija": "Avisar na legenda ou trocar por gráfico."
    }
  ],
  "padroes": [
    {
      "nome": "Fluxograma Mermaid acessível",
      "quando": "Fluxo com decisão, até cerca de 12 elementos.",
      "linguagem": "mermaid",
      "codigo": "flowchart TD\n  accTitle: Pedido de orçamento\n  accDescr: Fluxo do pedido com a decisão sobre o CNPJ\n  A([Lead pede orçamento]) --> B{Tem CNPJ no cadastro?}\n  B -- sim --> C[Robô responde o preço]\n  B -- não --> D[Pede o CNPJ antes do preço]\n  D --> C\n  C --> E[Cartão entra no CRM]"
    },
    {
      "nome": "Contêineres aninhados em D2",
      "quando": "Camadas dentro de camadas; acima de 12 elementos.",
      "linguagem": "d2",
      "codigo": "cliente: Navegador\nservidor: Servidor {\n  api: API\n  cache: Cache\n}\nbanco: Banco de dados\ncliente -> servidor.api: pede dados\nservidor.api -> servidor.cache: consulta\nservidor.api -> banco: grava"
    },
    {
      "nome": "Validação no build",
      "quando": "Script de CI antes de compilar com mmdc.",
      "linguagem": "js",
      "codigo": "import mermaid from \"mermaid\";\n\nmermaid.initialize({ startOnLoad: false, securityLevel: \"strict\" });\ntry {\n  await mermaid.parse(fonte); // Promise: use await\n} catch (erro) {\n  throw new Error(`Sintaxe recusada: ${erro.message}`);\n}\n// Depois: mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura\n// Pós-processo: cores por var(--token, reserva) e fill em cada text."
    },
    {
      "nome": "SVG autocontido e acessível",
      "quando": "Figura que vai a e-mail, slide ou download.",
      "linguagem": "html",
      "codigo": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 360 100\" role=\"img\"\n     aria-labelledby=\"t d\">\n  <title id=\"t\">Do rascunho à versão aprovada</title>\n  <desc id=\"d\">Rascunho segue para revisão.</desc>\n  <style>\n    .fundo { fill: var(--fundo, #ffffff); }\n    .caixa { fill: var(--caixa, #edf3f8); stroke: var(--linha, #14589c); stroke-width: 2; }\n    text { fill: var(--texto, #182b3c); font-family: system-ui, sans-serif; font-size: 18px; }\n  </style>\n  <rect class=\"fundo\" width=\"360\" height=\"100\"/>\n  <rect class=\"caixa\" x=\"30\" y=\"17\" width=\"300\" height=\"66\" rx=\"8\"/>\n  <text x=\"180\" y=\"58\" text-anchor=\"middle\">Rascunho</text>\n</svg>"
    }
  ],
  "checklist": [
    "A pergunta do desenho está escrita e a família (texto, editor ou grafo) saiu dela.",
    "A fonte do diagrama está versionada e o SVG é compilado no build.",
    "A versão do Mermaid está fixada e mermaid.parse() passou.",
    "Condições, saídas, retornos e exceções conferem com o processo real.",
    "Cores vêm de tokens com reserva; nenhum hex solto.",
    "Cada text tem fill explícito e fonte de 14 px ou mais (12 px a 390 px no mínimo).",
    "Contraste medido nos dois temas: 4,5:1 no texto e 3:1 em linhas e formas.",
    "O SVG tem viewBox, title, desc, role=\"img\" e aria-labelledby; como img, tem alt com as relações.",
    "O destino real foi aberto: celular a 390 px, tema escuro, e-mail ou arquivo baixado.",
    "Tipos novos ou -beta testados nas plataformas de leitura."
  ],
  "ferramentas": [
    {
      "nome": "Mermaid 11.16.1",
      "uso": "Fluxo, sequência, estados, C4, Gantt, quadrantChart, mindmap, gitGraph."
    },
    {
      "nome": "@mermaid-js/mermaid-cli 11.16.0 (mmdc)",
      "uso": "Compila .mmd em SVG no build; flags -I, -c e -p."
    },
    {
      "nome": "D2 v0.7.1",
      "uso": "Contêineres aninhados; layouts dagre, ELK e TALA (proprietário, marca-d'água sem licença)."
    },
    {
      "nome": "Graphviz 16.0.0",
      "uso": "Motor DOT em manutenção ativa; clusters para raias."
    },
    {
      "nome": "React Flow (@xyflow/react 12.11)",
      "uso": "Editor de fluxo MIT; isValidConnection; toObject() serializa o estado."
    },
    {
      "nome": "Cytoscape.js 3.34, Sigma.js, Graphology",
      "uso": "Grafos de rede; Sigma usa WebGL."
    }
  ],
  "ondeAprofundar": [
    {
      "tema": "As três famílias, teste de fronteira e modelo C4",
      "ancora": "#familias",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#familias"
    },
    {
      "tema": "Fluxograma de decisão em Mermaid",
      "ancora": "#gd-fluxograma",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#gd-fluxograma"
    },
    {
      "tema": "Tipos novos do Mermaid, accTitle, parse e mmdc",
      "ancora": "#mermaid",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid"
    },
    {
      "tema": "Plataformas que renderizam Mermaid",
      "ancora": "#plataformas",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#plataformas"
    },
    {
      "tema": "Mermaid, D2 e Graphviz",
      "ancora": "#mermaid-d2",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid-d2"
    },
    {
      "tema": "Contraste e letra nos dois temas",
      "ancora": "#temas",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#temas"
    },
    {
      "tema": "IA gerando diagramas e validação",
      "ancora": "#ia",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#ia"
    },
    {
      "tema": "Oficina de SVG legível no celular e no escuro",
      "ancora": "#oficina-diagrama-legivel",
      "url": "https://brasilgeo.ai/leadlovers2026/design/diagramas/#oficina-diagrama-legivel"
    }
  ],
  "relacionados": [
    {
      "guia": "graficos",
      "motivo": "Quando a figura precisa mostrar quantidade ou priorização.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/graficos/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/graficos/agentes.md"
    },
    {
      "guia": "icones",
      "motivo": "Ícones dentro de nós e legendas.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/icones/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/icones/agentes.md"
    },
    {
      "guia": "tailwind",
      "motivo": "Tokens de cor e tema claro e escuro que o SVG herda.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md"
    },
    {
      "guia": "react",
      "motivo": "Editor de fluxo com React Flow.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/react/agentes.md"
    }
  ],
  "fontes": [
    {
      "titulo": "Mermaid: uso e versões",
      "url": "https://mermaid.js.org/config/usage.html"
    },
    {
      "titulo": "Mermaid: função parse",
      "url": "https://mermaid.js.org/config/setup/mermaid/interfaces/Mermaid.html#parse"
    },
    {
      "titulo": "Mermaid: acessibilidade",
      "url": "https://mermaid.js.org/config/accessibility.html"
    },
    {
      "titulo": "D2: contêineres",
      "url": "https://d2lang.com/tour/containers/"
    },
    {
      "titulo": "WCAG 2.2: contraste de texto",
      "url": "https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html"
    }
  ]
}
