# Diagramas: instruções para agentes de IA

- Página: Diagramas de arquitetura e fluxo: do texto ao desenho pronto (https://brasilgeo.ai/leadlovers2026/design/diagramas/)
- Revisado em: 2026-11-16
- JSON com o mesmo conteúdo: https://brasilgeo.ai/leadlovers2026/design/diagramas/agentes.json
- Índice dos guias de Design para agentes: https://brasilgeo.ai/leadlovers2026/design/llms.txt
- Esquema: design-guia-para-agentes/v1

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.

## Quando consultar

- 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

- **DIA-01** (obrigatória). 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. Por quê: Errar a família transforma um dia de trabalho em duas semanas.
- **DIA-02** (obrigatória). 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). Por quê: Teste das três condições do curso: um sim em qualquer uma tira o caso do texto.
- **DIA-03** (obrigatória). Compile o diagrama no build e sirva SVG puro. Nunca embarque o runtime do Mermaid na página de leitura. Por quê: mermaid.min.js 11.16.1 pesa 3,4 MiB sem compressão; o SVG compilado fica perto de 30 KB.
- **DIA-04** (recomendada). Comece com Mermaid até cerca de 12 elementos; acima disso, ou com camadas aninhadas, compare com D2. Por quê: Convenção didática do curso, sem limite técnico; Mermaid também agrupa e aceita layout ELK.
- **DIA-05** (obrigatória). Fixe a versão do Mermaid no package.json e gere o código pela documentação dessa versão. Por quê: Exemplos usam a série 11 (11.16.1); a doc atual já mostra a 12 e a IA inventa sintaxe.
- **DIA-06** (obrigatória). 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". Por quê: parse() só confere sintaxe; não detecta condição omitida nem sanitiza. strict codifica HTML e desabilita cliques.
- **DIA-07** (obrigatória). Toda seta que sai de uma decisão leva a condição escrita, e o caminho de retorno existe. Por quê: Caixas ligadas sem condição escondem a decisão.
- **DIA-08** (obrigatória). 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. Por quê: Como img, o title interno não é exposto; PNG descarta os atributos.
- **DIA-09** (obrigatória). Nunca escreva hex solto no diagrama publicado. Injete tokens do projeto com reserva: var(--token, #hex). Por quê: Hex fixo some ao trocar de tema.
- **DIA-10** (obrigatória). 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. Por quê: Como img, o SVG é documento isolado e var(--text) resolve para nada.
- **DIA-11** (obrigatória). No Mermaid, themeVariables aceita só hexadecimal: use uma paleta por tema no compilador ou aplique var() no SVG inline no pós-processo. Por quê: var(--token) passado ao motor não substitui a configuração.
- **DIA-12** (obrigatória). Dê fill explícito a cada text do SVG, sem herança do grupo. Por quê: Rótulo cinza sobre fundo cinza surge quando o preenchimento falha ao herdar.
- **DIA-13** (obrigatória). 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. Por quê: WCAG 2.2, critérios 1.4.3 e 1.4.11; a amostra cinza-claro do guia fica perto de 2:1.
- **DIA-14** (obrigatória). 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. Por quê: Fonte 15 em viewBox 1200 chega a 4,9 px no celular. O 14 px é referência do curso, não norma.
- **DIA-15** (recomendada). 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. Por quê: Sem -I, todo SVG sai com id my-svg e dois diagramas colidem.
- **DIA-16** (recomendada). Uma figura responde uma pergunta só. No C4, um nível por figura (contexto, contêiner, componente, código), começando pelo contexto. Por quê: Contêiner e componente no mesmo quadro produzem desenho que ninguém lê inteiro.
- **DIA-17** (recomendada). 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. Por quê: Acima disso divida a figura ou troque de tipo (catálogo de 36 tipos).
- **DIA-18** (obrigatória). Antes de padronizar um tipo novo ou -beta do Mermaid, confira onde ele precisa renderizar (GitHub, GitLab, VS Code, Obsidian, Notion). Por quê: A versão embarcada de cada plataforma decide o que funciona.
- **DIA-19** (obrigatória). tldraw exige license key em produção; React Flow e Excalidraw são MIT. Confira a licença antes de orçar editor. Por quê: Quem orçou tldraw como MIT precisa refazer a conta.
- **DIA-20** (recomendada). 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. Por quê: Evita apagar o desenho aberto e laço infinito na busca.

## Decisões rápidas

| Situação | Escolha | Evite |
| --- | --- | --- |
| Time escreve documentação e o leitor só lê | Texto compilado no build (Mermaid, D2 ou Graphviz), saída em SVG. | Biblioteca de diagrama no navegador do leitor. |
| Usuário do produto arrasta, conecta e salva caixas | Editor de fluxo: React Flow ou Excalidraw (MIT). | Mermaid; tldraw sem license key. |
| Milhares de nós e o agrupamento é a resposta | Cytoscape.js (layout cose) ou Sigma.js com Graphology em WebGL. | Grafo de força com menos de 20 nós. |
| Fluxo simples, até cerca de 12 elementos | Mermaid, com poucas linhas e suporte nativo nas plataformas. |  |
| Contêineres dentro de contêineres, ou muitos elementos | D2 (agrupamento nativo) com layout ELK; compare com Mermaid. | Subgraphs profundos no Mermaid. |
| Raias horizontais fiéis ou mais de 5 raias | D2 ou Graphviz com clusters. | Mermaid subgraph. |
| Processo com decisão e retorno | Fluxograma com condição na seta. | Sequência (só ordem) e esteira (fila reta). |
| Situações e transições com volta | stateDiagram-v2. | Fluxograma quando o processo é linear sem volta. |
| Causas em paralelo, mais de uma por porquê | Espinha de peixe (flowchart RL com subgraphs). | Árvore de cinco causas, de uma resposta por degrau. |
| Figura vai para e-mail, slide ou download | SVG autocontido: fundo, cores, font-family, xmlns, title e desc; uma versão por tema. | var() sem reserva; id e class da página de origem. |

## Números de referência

| Valor | Para quê | Fonte |
| --- | --- | --- |
| 4,5:1 | Contraste mínimo do texto normal nos dois temas. | WCAG 2.2, 1.4.3 (AA) |
| 3:1 | Contraste mínimo de linhas e formas necessárias à compreensão. | WCAG 2.2, 1.4.11 |
| 14 px | Referência do curso para rótulos na dimensão exibida. | Convenção do curso, não norma |
| 12 px a 390 px | Piso da letra efetiva no celular. | Oficina de SVG legível |
| 12 elementos | Ponto para comparar Mermaid com D2. | Convenção didática do curso |
| 3,4 MiB | Peso do mermaid.min.js 11.16.1 sem compressão (medido em 10/09/2026). | Medição do guia |
| cerca de 30 KB | Peso do SVG compilado. | Guia da aula |
| Mermaid 11.16.1 | Versão de referência (4 de agosto de 2026); mermaid-cli 11.16.0. | Releases do GitHub |

## Erros comuns e a correção

- 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.

## Padrões de código

### Fluxograma Mermaid acessível

Fluxo com decisão, até cerca de 12 elementos.

```mermaid
flowchart TD
  accTitle: Pedido de orçamento
  accDescr: Fluxo do pedido com a decisão sobre o CNPJ
  A([Lead pede orçamento]) --> B{Tem CNPJ no cadastro?}
  B -- sim --> C[Robô responde o preço]
  B -- não --> D[Pede o CNPJ antes do preço]
  D --> C
  C --> E[Cartão entra no CRM]
```

### Contêineres aninhados em D2

Camadas dentro de camadas; acima de 12 elementos.

```d2
cliente: Navegador
servidor: Servidor {
  api: API
  cache: Cache
}
banco: Banco de dados
cliente -> servidor.api: pede dados
servidor.api -> servidor.cache: consulta
servidor.api -> banco: grava
```

### Validação no build

Script de CI antes de compilar com mmdc.

```js
import mermaid from "mermaid";

mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
try {
  await mermaid.parse(fonte); // Promise: use await
} catch (erro) {
  throw new Error(`Sintaxe recusada: ${erro.message}`);
}
// Depois: mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura
// Pós-processo: cores por var(--token, reserva) e fill em cada text.
```

### SVG autocontido e acessível

Figura que vai a e-mail, slide ou download.

```html
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 100" role="img"
     aria-labelledby="t d">
  <title id="t">Do rascunho à versão aprovada</title>
  <desc id="d">Rascunho segue para revisão.</desc>
  <style>
    .fundo { fill: var(--fundo, #ffffff); }
    .caixa { fill: var(--caixa, #edf3f8); stroke: var(--linha, #14589c); stroke-width: 2; }
    text { fill: var(--texto, #182b3c); font-family: system-ui, sans-serif; font-size: 18px; }
  </style>
  <rect class="fundo" width="360" height="100"/>
  <rect class="caixa" x="30" y="17" width="300" height="66" rx="8"/>
  <text x="180" y="58" text-anchor="middle">Rascunho</text>
</svg>
```

## Checklist antes de entregar

- [ ] 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 citadas

- **Mermaid 11.16.1**: Fluxo, sequência, estados, C4, Gantt, quadrantChart, mindmap, gitGraph.
- **@mermaid-js/mermaid-cli 11.16.0 (mmdc)**: Compila .mmd em SVG no build; flags -I, -c e -p.
- **D2 v0.7.1**: Contêineres aninhados; layouts dagre, ELK e TALA (proprietário, marca-d'água sem licença).
- **Graphviz 16.0.0**: Motor DOT em manutenção ativa; clusters para raias.
- **React Flow (@xyflow/react 12.11)**: Editor de fluxo MIT; isValidConnection; toObject() serializa o estado.
- **Cytoscape.js 3.34, Sigma.js, Graphology**: Grafos de rede; Sigma usa WebGL.

## Onde aprofundar na página

- [As três famílias, teste de fronteira e modelo C4](https://brasilgeo.ai/leadlovers2026/design/diagramas/#familias)
- [Fluxograma de decisão em Mermaid](https://brasilgeo.ai/leadlovers2026/design/diagramas/#gd-fluxograma)
- [Tipos novos do Mermaid, accTitle, parse e mmdc](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid)
- [Plataformas que renderizam Mermaid](https://brasilgeo.ai/leadlovers2026/design/diagramas/#plataformas)
- [Mermaid, D2 e Graphviz](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid-d2)
- [Contraste e letra nos dois temas](https://brasilgeo.ai/leadlovers2026/design/diagramas/#temas)
- [IA gerando diagramas e validação](https://brasilgeo.ai/leadlovers2026/design/diagramas/#ia)
- [Oficina de SVG legível no celular e no escuro](https://brasilgeo.ai/leadlovers2026/design/diagramas/#oficina-diagrama-legivel)

## Guias relacionados

- [Gráficos](https://brasilgeo.ai/leadlovers2026/design/graficos/): Quando a figura precisa mostrar quantidade ou priorização. Instruções: https://brasilgeo.ai/leadlovers2026/design/graficos/agentes.md
- [Ícones](https://brasilgeo.ai/leadlovers2026/design/icones/): Ícones dentro de nós e legendas. Instruções: https://brasilgeo.ai/leadlovers2026/design/icones/agentes.md
- [Tailwind e tokens](https://brasilgeo.ai/leadlovers2026/design/tailwind/): Tokens de cor e tema claro e escuro que o SVG herda. Instruções: https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md
- [React](https://brasilgeo.ai/leadlovers2026/design/react/): Editor de fluxo com React Flow. Instruções: https://brasilgeo.ai/leadlovers2026/design/react/agentes.md

## Fontes primárias

- [Mermaid: uso e versões](https://mermaid.js.org/config/usage.html)
- [Mermaid: função parse](https://mermaid.js.org/config/setup/mermaid/interfaces/Mermaid.html#parse)
- [Mermaid: acessibilidade](https://mermaid.js.org/config/accessibility.html)
- [D2: contêineres](https://d2lang.com/tour/containers/)
- [WCAG 2.2: contraste de texto](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
