Pular para o conteúdo
Aula do menu Design

Diagramas de arquitetura e fluxo: o desenho que ninguém redesenha à mão

Ilustração editorial em índigo e azul-marinho: uma folha de código à esquerda se transforma, por uma seta fluida com filete rosa-carmim, num fluxograma de caixas conectadas à direita
O movimento da aula inteira numa cena: o texto plano da esquerda atravessa a seta e chega do outro lado como diagrama pronto, sem ninguém redesenhar caixa por caixa. Ilustração gerada por IA (Nano Banana) para esta aula.

O diagrama desenhado à mão numa ferramenta de slide custa pouco para nascer e caro para viver: cada mudança do sistema exige que alguém lembre de abrir o arquivo e redesenhar. O caminho contrário é o desenho descrito em texto e compilado a cada publicação, e cada decisão aqui vem com número e dono: o Mermaid chegou à versão 11.16 com nove tipos de diagrama além do fluxograma (releases oficiais, agosto de 2026); embarcar a biblioteca no navegador custa 3,4 MB sem compressão (medição sobre o pacote npm); o GitHub renderiza o código direto em issues, PRs e wikis enquanto o GitLab.com continua preso na versão 10; a régua entre Mermaid e D2 segue em uma dúzia de elementos; o texto do rótulo obedece aos 4,5:1 da WCAG 2.2 e as formas aos 3:1; e a IA que gera o diagrama passa por mermaid.parse() antes de qualquer render. A mesma matéria está em aula de vídeo e podcast logo abaixo, com transcrição para ler e copiar.

Guia do menu Design do portal, construído sobre pesquisa de fontes primárias com data de acesso 18/08/2026 e sobre o capítulo de diagramas, quadros brancos e grafos do curso Frontends com Vibecoding, de Alexandre Caramaschi. Ele compõe o menu com os guias de ícones, ilustrações, animação e geração de imagens e de menus, abas e paginação.

A aula, em vídeo e em podcast

O conteúdo deste guia virou uma aula gerada no NotebookLM a partir do dossiê de pesquisa, servida nos arquivos originais, sem recompressão. O vídeo apresenta o panorama em minutos; o podcast aprofunda a conversa para ouvir no deslocamento. Cada peça tem download, compartilhamento e a transcrição completa para ler e copiar.

Baixar o vídeo
Vídeo da aula: o panorama das decisões deste guia, com legenda em português.
Podcast da aula: diagramas de arquitetura e fluxo
Portal Leadlovers 2026 · menu Design
Baixar o podcast
Podcast da aula: a conversa aprofundada sobre as mesmas decisões.

Antes da biblioteca: quem monta o desenho?

A palavra "diagrama" esconde três famílias de figura com contratos de custo muito diferentes. A pergunta que as separa, na formulação do curso: quem monta o desenho, você ou quem usa o seu site?

Árvore de decisão: a pergunta quem monta o desenho separa as três famílias de ferramenta de diagrama Quem monta o desenho? você escreve quem usa arrasta a informação é a rede A máquina desenha Mermaid · D2 · Graphviz SVG compilado no build Quem usa arrasta as peças React Flow · tldraw Excalidraw funcionalidade de produto A informação é a rede Cytoscape.js · Sigma.js arranjo por simulação
A pergunta que separa as três famílias: quem monta o desenho decide a ferramenta e o contrato de custo.

1. Você escreve, a máquina desenha

O desenho vive como texto e a máquina calcula onde cada caixa fica. Serve para o diagrama de arquitetura do projeto, o fluxo de um processo no manual interno e o organograma no site da empresa. Ferramentas: Mermaid, D2 e Graphviz. A entrega é um SVG compilado no build.

2. Quem usa o produto arrasta as peças

O cliente conecta e apaga caixas na tela: o construtor de automação, o editor de fluxo de atendimento, a régua de aprovação que o próprio usuário monta. É funcionalidade de produto, com prazo, teste e suporte próprios. Ferramentas: React Flow, tldraw e Excalidraw.

3. A informação é a própria rede

Cadeia de fornecedores, quem indicou quem numa base de clientes, quais páginas linkam para quais. Milhares de nós se acomodam sozinhos por simulação, e o agrupamento que aparece é a resposta que uma tabela nunca daria. Ferramentas: Cytoscape.js e Sigma.js com Graphology.

O erro mais caro da área é montar a segunda família com a ferramenta da primeira. O Mermaid desenha o que você escreveu; ele nunca entrega ao seu cliente uma tela onde ele monte alguma coisa. Descobrir isso na metade do trabalho custa a semana inteira. O teste do curso cabe em três condições, ditas em voz alta sobre a figura: quem olha precisa salvar o que montou; precisa voltar depois e editar; precisa mandar para outra pessoa mexer. Um sim em qualquer uma tira o caso do texto e o coloca na família do editor de fluxo.

Mermaid em 2026: bem mais que fluxograma

A biblioteca chegou à versão 11.16.1 em 4 de agosto de 2026 (releases oficiais no GitHub), com a série 10 ainda recebendo patches de segurança. O catálogo foi muito além do fluxograma, do diagrama de sequência e do Gantt que o time já conhece; a doc oficial confirma os tipos recentes reunidos abaixo.

Pictograma de fluxograma: caixas e um losango de decisão ligados por setas
Fluxograma
Pictograma de diagrama de sequência: duas linhas de vida trocando mensagens
Sequência
Pictograma de Gantt: barras horizontais escalonadas no tempo
Gantt
Pictograma de arquitetura de nuvem: dois serviços conectados dentro de um grupo tracejado
Arquitetura
architecture-beta
beta
Pictograma de diagrama de blocos: blocos de larguras variadas em posição manual
Blocos
block
Pictograma de pacote de rede: barra segmentada em campos de bits
Pacote de rede
packet
Pictograma de quadro kanban: três colunas com cartões
Kanban
kanban
Pictograma de radar: teia pentagonal com área de dados
Radar
radar-beta
beta
Pictograma de treemap: retângulo dividido em células aninhadas
Treemap
treemap-beta
beta
Pictograma de gráfico de barras e linhas sobre eixos
Barras e linhas
xychart
Pictograma de sankey: fluxos que se ramificam entre origem e destino
Sankey
experimental
O catálogo do Mermaid 11.16.1 pela doc oficial: o selo marca a sintaxe ainda beta ou experimental.

Nos tipos novos, a doc detalha o alcance: a arquitetura de nuvem (architecture-beta, desde a v11.1.0) relaciona serviços e recursos de deploys de nuvem e CI/CD, o diagrama de blocos (block) traz controle manual de posição e o xychart cobre gráficos de barras e linhas. O sufixo -beta em vários deles é o aviso honesto da própria equipe: catálogo em expansão, sintaxe ainda assentando.

Dois recursos merecem lugar fixo no fluxo do time. O primeiro é a dupla accTitle e accDescr, que insere <title> e <desc> no SVG com os atributos ARIA correspondentes, disponível para todos os tipos de diagrama (documentação do Mermaid): a figura ganha nome e descrição para leitor de tela sem uma linha de CSS. O benefício sobrevive apenas onde o SVG é preservado; rasterizar para PNG descarta os atributos. O segundo é a função mermaid.parse(), que valida a definição sem renderizar: o portão barato para qualquer código de diagrama que chegue de fora, inclusive o gerado por IA.

O peso que ninguém orça: o mermaid.min.js da 11.16.1 tem 3,4 MB sem compressão (medição sobre o pacote npm, 18/08/2026). O entry ESM moderno tem cerca de 30 KB e carrega cada tipo de diagrama sob demanda, e a equipe distribui um "Tiny Mermaid" com metade do tamanho da versão completa. Para página de leitura, a conta continua favorecendo o build: compilar uma vez e servir SVG puro entrega a figura sem nenhum desses kilobytes.

No build, o compilador oficial é o @mermaid-js/mermaid-cli (11.16.0), que renderiza com um Chromium headless via Puppeteer. Três flags resolvem os atritos clássicos:

-I
Id único por SVG
Sem ela, todo arquivo sai com id my-svg e dois diagramas na mesma página colidem.
-c
JSON de configuração
Onde entram themeVariables e htmlLabels.
-p
Configura o Puppeteer
O lugar do ajuste de sandbox em CI Linux.
As três flags do mermaid-cli que desarmam os atritos clássicos do build.

Para diagramas grandes existe o renderer ELK (@mermaid-js/layout-elk), experimental e recomendado pela doc para os casos complexos; ele é pacote separado, e as plataformas hospedadas só o têm se o instalarem.

Onde o código renderiza sozinho, e onde trava

O mesmo texto que gera a figura do site documenta a arquitetura no repositório, e a versão embarcada por cada plataforma decide quais tipos de diagrama funcionam. O retrato de agosto de 2026, pelas documentações oficiais:

GitHub · renderiza
GitLab.com · versão 10
VS Code · nativo na 1.121
Obsidian · nativo
Notion · atalho /mermaid
O retrato de agosto de 2026 num olhar: a letra miúda de cada plataforma segue na tabela.
PlataformaO que renderizaA letra miúda
GitHubBlocos mermaid em issues, discussions, pull requests, wikis e arquivos MarkdownA versão embarcada é a que o GitHub escolhe; plugins de terceiros podem conflitar
GitLab.comBlocos mermaid no MarkdownA doc declara suporte à versão 10: os diagramas novos da série 11 (arquitetura, kanban, radar, treemap) ficam de fora
VS CodePreview de Markdown, células de notebook e chat, com pan, zoom e cópia do fonteNativo desde a 1.121 (extensão embutida "Mermaid Markdown Features"); o chat renderiza desde a 1.109
ObsidianBlocos mermaid nas notasVersão embarcada sem declaração na doc
NotionBloco de código Mermaid pelo atalho /mermaidAtalho documentado na release de agosto de 2022

Documentações oficiais de GitHub, GitLab, VS Code, Obsidian e Notion, acesso em 18/08/2026.

A consequência prática: antes de padronizar um tipo novo de diagrama no time, confira onde ele precisa renderizar. Um architecture-beta lindo no VS Code aparece como bloco de texto cru num merge request do GitLab.com.

Mermaid, D2 e o Graphviz que segue vivo

O D2, da Terrastruct, trata agrupamento como conceito de primeira classe: você escreve servidor: { api; cache } e a caixa em volta aparece. A versão estável é a v0.7.1, de agosto de 2025, com contêineres aninhados, temas prontos, sketch mode, imports, variáveis e exportação para SVG, PNG, PDF, PPTX, GIF e até ASCII (documentação do D2). São três motores de layout: dagre (padrão, baseado no algoritmo DOT do Graphviz), ELK e TALA.

TALA tem preço. O motor de layout desenhado para arquitetura de software é proprietário e de código fechado, instalado à parte do D2 (que permanece inteiramente open source): a avaliação é gratuita, e sem licença o desenho sai com marca-d'água; uso comercial exige licença paga (README oficial do TALA). Vale o mesmo cuidado com a comparação pública em text-to-diagram.com: o site é mantido pelo próprio projeto D2, útil com viés estrutural declarado.

O Graphviz, avô da família, segue em manutenção ativa: release 16.0.0 em 14 de agosto de 2026, com cadência quase mensal (GitLab oficial do projeto). Continua o motor por trás de toolchains como o doxygen, e a linhagem de onde o dagre veio. Para quem precisa de muitas linguagens num serviço só, o Kroki oferece uma API unificada para cerca de 28 ferramentas de diagrama, D2, Mermaid, PlantUML e Graphviz incluídos, com self-host via Docker (documentação do Kroki).

A régua do curso, com o cenário de 2026: para até uma dúzia de elementos, Mermaid; acima disso, ou com camadas dentro de camadas, D2. O motivo segue cabendo numa linha: o D2 desenha o agrupamento e o Mermaid espalha as caixas. O que mudou na margem: o diagrama de blocos devolve ao Mermaid o controle manual de posição, e o renderer ELK melhora os diagramas grandes, mas ambos carregam status beta ou experimental, enquanto contêiner aninhado é o núcleo estável do D2 desde o início.

Compilado ao publicar: a figura que se refaz sozinha

A dica central do curso permanece: gerar o SVG no momento de publicar, com as cores do projeto injetadas por token, em vez de embarcar o runtime na página do leitor. O texto versionado no repositório ganha histórico, autor e revisor, e a figura acompanha o sistema. O ecossistema de 2026 se dividiu em três campos, pelas documentações oficiais:

O roteiro da casa, do zero à figura publicada, cabe em quatro estações, lidas da esquerda para a direita:

Pipeline de build: arquivo ponto mmd versionado no repositório, compilador mmdc com Chromium headless via Puppeteer, SVG com tokens do projeto na pasta pública e página do leitor sem biblioteca nenhuma. Arquivo .mmd versionado no repositório mmdc Chromium headless via Puppeteer SVG com tokens do projeto, na pasta pública Página do leitor sem biblioteca nenhuma
O pipeline da casa: o texto versionado compila para SVG no build e o leitor recebe a figura pronta, sem runtime.

No script de build, o comando é mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura; a injeção das cores por token acontece no pós-processo; cada <text> sai conferido com fill explícito e fonte de 14 px para cima; e o resultado abre nos dois temas antes do commit. Quando a arquitetura mudar, muda-se o texto e o build refaz o resto.

Legível nos dois temas: os números da norma

O defeito mais comum desta área é o rótulo invisível. Cada texto dentro de uma figura gerada carrega a própria cor, e o valor de fábrica de muitas ferramentas é um cinza-claro sobre fundo claro, perto de 2:1. A régua tem dono e número: a WCAG 2.2 exige 4,5:1 para texto de tamanho normal (critério 1.4.3, nível AA) e 3:1 para os objetos gráficos, as linhas e formas do diagrama (critério 1.4.11).

Amostra reprovada: rótulo em cinza-claro sobre fundo claro, contraste perto de 2 para 1 Rótulo
Texto perto de 2:1
reprovado
Amostra aprovada: rótulo em cinza forte sobre fundo claro, contraste de 4,5 para 1 Rótulo
Texto forte, 4,5:1
aprovado
Amostra reprovada: linha fina em cinza-claro, contraste abaixo de 3 para 1
Linha abaixo de 3:1
reprovada
Amostra aprovada: forma com traço em contraste de 3 para 1
Forma com 3:1
aprovada
O mesmo rótulo em quatro amostras sobre fundo claro: as razões da WCAG 2.2 decidem o que passa. As cores das amostras são fixas de propósito, para a demonstração valer nos dois temas.

No tema escuro fica pior. Depois de gerar qualquer figura, abra nos dois temas e rode o auditor de contraste do navegador antes de considerar pronto.

IA gerando diagramas: o que é real e como validar

A geração por IA saiu da promessa e entrou na documentação oficial das plataformas. O claude.ai cria artifacts do tipo "mermaid diagrams" (central de ajuda da Anthropic), e há um conector oficial da Mermaid Chart no diretório do Claude que valida a sintaxe e renderiza SVG dentro da conversa. O cookbook oficial do GitHub ensina a pedir diagramas Mermaid ao Copilot Chat para colar em qualquer superfície Markdown, com um aviso literal que vale emoldurar: as respostas são não determinísticas.

Fluxo de validação: o agente de IA gera código Mermaid e mermaid.parse() valida sem renderizar; aprovado, o código segue para o render no build; reprovado, o erro volta para o agente, que fica ancorado na documentação da versão do package.json. Agente de IA gera código Mermaid mermaid.parse() valida sem renderizar aprovado Render no build figura publicada reprovado: o erro volta para o agente âncora do agente: a documentação da versão do package.json
O portão barato antes do render: mermaid.parse() valida o código gerado e devolve o erro ao agente quando reprova.

A empresa por trás do Mermaid vende o Mermaid AI (descreva, envie um documento ou cole uma transcrição e receba o diagrama), com servidor MCP para Claude, VS Code e Cursor. Do lado do ChatGPT, a OpenAI documenta renderização nenhuma: o comportamento varia entre superfícies, e o que existe de oficial é um GPT da Mermaid Chart na loja.

A armadilha continua real, e o antídoto tem nome de função. O modelo escreve com a mesma segurança sobre a propriedade que existe e sobre a que mudou de nome duas versões atrás. Antes de renderizar qualquer código gerado, rode mermaid.parse(), que valida sem desenhar (doc oficial do Mermaid), e ancore o agente na documentação da versão que está no seu package.json. Instruir o modelo a usar apenas a informação dos documentos fornecidos é a recomendação da própria Anthropic para reduzir alucinação, no guia oficial da plataforma.

Quando o caso sai do texto: editores e grafos em 2026

Ilustração editorial dividida em dois mundos: à esquerda uma mão escreve linhas de texto com uma caneta; à direita outra mão arrasta uma peça rosa-carmim de fluxograma numa tela azul-marinho
A fronteira em imagem: de um lado a mão que escreve o diagrama como texto; do outro, a mão de quem arrasta caixas na tela (o mundo da recepcionista da clínica). Ilustração gerada por IA (Nano Banana) para esta aula.

A cena que fixa a fronteira, no curso: a recepcionista da clínica que desenha e salva o próprio fluxo de confirmação de consulta. Ela nunca vai escrever texto; ela arrasta caixas.

Fluxograma das três condições da fronteira: qualquer sim leva ao editor de fluxo e nenhum sim devolve o caso ao texto compilado no build Salvar o que montou? Voltar depois e editar? Mandar outra pessoa mexer? algum sim? qualquer sim nenhum sim Editor de fluxo produto com prazo, teste e suporte O caso fica no texto SVG compilado no build
As três condições ditas em voz alta sobre a figura: um sim em qualquer uma coloca o caso na família do editor de fluxo; nenhum sim mantém a figura como texto compilado no build.

O caso pertence ao editor de fluxo, que é produto com prazo, teste e suporte, e o sinal de erro da escolha errada é o dia orçado que vira duas semanas. O retrato 2026 das ferramentas dessa fronteira, pelas fontes oficiais:

React Flow (xyflow)

Licença MIT MIT

Série 12.11, MIT declarado permanente na página Pro ("open-source MIT-licensed software, and it will be forever"). A assinatura Pro paga exemplos avançados e suporte; recurso travado na biblioteca não existe. Persistência oficial: toObject() serializa nós, arestas e viewport em JSON.

tldraw

Licença própria: exige license key em produção license key

Deixou de ser open source permissivo: a licença própria exige license key em produção, e sob a licença hobby a marca "made with tldraw" deve aparecer no canvas (licença e site oficiais). Quem orçou tldraw como MIT precisa refazer a conta.

Excalidraw

Licença MIT MIT

MIT, sem marca e sem chave, inclusive como componente React embutível (@excalidraw/excalidraw). O quadro branco de traço à mão que permanece livre para embarcar.

Na terceira família, o Cytoscape.js (3.34) roda headless em Node para calcular o arranjo do grafo antes de publicar e servir as posições prontas (documentação oficial); o Sigma.js desenha via WebGL grafos de milhares de nós, com o Graphology guardando o dado. E os alvos de toque do editor de fluxo têm número de norma: 24×24 px CSS no nível AA da WCAG 2.2 e 44×44 no AAA, a régua para os pontos de conexão que o dedo precisa acertar.

Prompts prontos

Diagrama de arquitetura compilado na publicação

Descreva a arquitetura deste repositório e gere o diagrama em D2 com
contêineres por camada (cliente, servidor, dados, integrações externas).

Requisitos:
- Compile o D2 para SVG no passo de build (nunca no navegador do leitor).
- Injete os tokens de cor do projeto (var(--accent), var(--text),
  var(--border)) no SVG gerado; nada de cores hardcoded.
- Todo <text> com fill EXPLÍCITO e font-size >= 14px.
- Use layout ELK; agrupe por camada com contêineres aninhados.

Critérios de aceite:
1. O SVG final não referencia nenhuma lib em runtime.
2. Rodei o auditor de contraste e todo texto passa AA (4,5:1) e
   toda forma passa 3:1 (WCAG 2.2, critérios 1.4.3 e 1.4.11).
3. Se o sistema tiver mais de 12 nós, você justificou D2 sobre Mermaid.
4. As setas têm rótulo quando o tipo de chamada não é óbvio.

Código Mermaid gerado por IA, validado antes do render

Gere o fluxograma em Mermaid (flowchart TD) para o processo descrito
abaixo, usando APENAS a sintaxe documentada na versão que está no meu
package.json (mermaid 11.x). Não use propriedade, tipo de diagrama ou
atalho que não esteja nessa documentação.

Critérios de aceite:
1. O código passa em mermaid.parse() sem erro.
2. Cada nó tem rótulo em português, sem abreviação inventada.
3. Se você não tiver certeza de uma sintaxe, diga que não tem,
   em vez de arriscar.

Auditoria de uma figura antes de publicar

Audite o SVG anexo nos dois temas do site (claro e escuro):
1. Liste todo <text> sem fill explícito ou com fonte menor que 14px.
2. Meça o contraste de cada rótulo contra o fundo real e aponte o que
   fica abaixo de 4,5:1; meça linhas e bordas contra 3:1 (WCAG 2.2).
3. Confirme a presença de <title> e <desc> acessíveis.
4. Devolva a lista de correções em ordem de impacto, sem reescrever
   o arquivo inteiro.
Infográfico da aula: as três famílias de figura (você escreve com Mermaid ou D2, o usuário arrasta com React Flow, os dados formam a rede com Cytoscape), a régua de uma dúzia entre Mermaid e D2, o pipeline de compilar no build (versão em texto, gera SVG no build, serve sem bibliotecas) e o contraste WCAG de 4,5:1 conferido nos temas claro e escuro.
A aula inteira num quadro: as três famílias, a régua de uma dúzia, o pipeline de build e o contraste nos dois temas. Infográfico gerado no NotebookLM a partir do dossiê da aula.

Por onde começar

Assista à aula, escolha o processo que o time mais explica em reunião e escreva-o em quatro linhas de flowchart TD. Compile para SVG no build, valide com mermaid.parse() se o código veio de um agente, abra nos dois temas e rode o auditor de contraste antes de mostrar a alguém. O menu Design continua nos guias de ícones, ilustrações, animação e geração de imagens e de menus, abas e paginação, e o restante do portal no glossário.