Pular para o conteúdo

Diagramas de arquitetura e fluxo

Como escolher a ferramenta, transformar texto em desenho e manter a figura legível.

Diagramas descritos em texto podem acompanhar as mudanças do sistema: o time revisa a fonte no repositório e a publicação gera o desenho. Mermaid e D2 atendem à documentação; um editor como React Flow permite que a pessoa monte o próprio fluxo; bibliotecas de grafos ajudam a explorar redes de dados. A escolha depende de quem monta a figura e da pergunta que ela precisa responder.

O catálogo reúne trinta e seis formatos com exemplos, código e descrição das relações. As seções técnicas comparam ferramentas, explicam a compilação para SVG e mostram como conferir sintaxe, lógica e contraste. Vídeo, podcast e transcrições preservam a aula que acompanha o guia.

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
Texto versionado convertido em diagrama. Ilustração gerada por IA para esta aula.

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.

A gravação preserva o recorte original da aula. O guia esclarece abaixo a convenção de doze elementos, a validação de sintaxe e o suporte atual do GitLab a Mermaid 11.

Baixar o vídeo
Vídeo da aula: o panorama das decisões deste guia, com legenda em português.
Ler a transcrição completa do vídeo
Transcrição do vídeo

Olá, time! É sensacional iniciar mais esta aula do nosso portal Leadlovers 2026. Hoje a gente vai mergulhar fundo num tema que, honestamente, muda por completo o jogo na hora de documentar processos no nosso dia a dia, diagramas de arquitetura e fluxo. A grande sacada desta nossa análise é deixar no passado de uma vez por todas aqueles desenhos frágeis feitos à mão em slides. Sabe aqueles que sempre quebram e ficam obsoletos assim que o sistema sofre a menor das atualizações? Pois o nosso caminho agora é abraçar a mentalidade de diagramas como código. Na prática, isso significa que o nosso texto vai se transformar quase que como mágica numa imagem final impecável, sem que ninguém da equipe precise arrastar uma setinha sequer de forma manual. Olhando bem rápido para nossa agenda de hoje, nós vamos cobrir seis passos essenciais. A pergunta de ouro, as ferramentas Mermaid e D2 agora em 2026, nosso processo de build com tokens, regras de WCAG, uso de inteligência artificial e por fim a fronteira do editor visual. Então, vamos começar pelo princípio. 1. A pergunta de ouro. Olha, o erro mais caro e doloroso em um projeto visual é escolher a família errada de ferramentas logo no pontapé inicial. Para a gente não jogar o orçamento e o nosso tempo pela janela, o diagnóstico inicial é surpreendentemente simples, que é esta pergunta. Quem é que realmente monta o desenho? É o nosso próprio time interno criando uma documentação estática para ser lida depois? Ou será que a pessoa que utiliza o produto final, arrastando caixas e conectando setas dinamicamente ali na tela? Dependendo dessa resposta, as ferramentas se dividem em três famílias bem diferentes. A primeira família funciona convertendo o texto em desenho, com ferramentas sensacionais como o Mermaid e D2. A segunda já engloba aqueles construtores visuais, onde as pessoas arrastam peças o que pede coisas como react flow. Já a terceira família é para lidar com redes massivas de dados usando bibliotecas pesadas tipo o Cytoscape. A gente precisa ter muito cuidado aqui. Confundir um diagrama focado em documentação textual com a construção de um editor visual interativo é a receita perfeita para transformar uma tarefinha de um dia num pesadelo que devora duas semanas de desenvolvimento. Ninguém quer isso, né? Avançando para parte 2, Mermaid e D, nesse nosso cenário atual, de 2026. A premissa central de tudo isso é manter o texto guardadinho e seguro lá no nosso repositório e deixar a máquina fazer todo o trabalho braçal do layout. E o número que nosso time precisa tatuar no braço, como padrão técnico interno, é o 11.16. Essa é a versão estável do Mermaid confirmada agora em agosto de 2026. Manter todo mundo operando exatamente sob essa versão é o que garante a paridade e tira qualquer surpresa desagradável na hora de compilar os recursos. E o que é absolutamente fantástico nessa versão é que o catálogo decolou para muito além de fluxogramas básicos. A sintaxe agora suporta diagramas de arquitetura de nuvem, layout em blocos, quadros kanban e gráficos de radar.

Mas olha, o detalhe mais incrível e crucial de todos é o suporte de primeira classe a acessibilidade. As tags de texto, como o accTitle e o accDescr, sobrevivem perfeitamente ao processo de compilação em SVG. Isso garante que os leitores de tela consigam interagir resultados sem perder nenhuma informação. É a acessibilidade de verdade. Agora surge a dúvida, como a gente decide exatamente entre usar o Mermaid ou pular pro D2? A melhor forma de resolver isso é usando a regra de uma dúzia. Para esquemas que têm até 12 elementos, o Mermaid é a escolha certa. Cumpre o papel de forma magistral. Mas se a complexidade aumentar e passar dessa marca, ou se a gente tiver aquelas estruturas complexas de contêineres dentro de contêineres, aí o D2 é indiscutivelmente a melhor pedida. O D2 foi pensado desde o início pra entender essas camadas aninhadas nativamente e desenhar as caixas de um jeito impecável ao redor dos grupos.

Ai, vale fazer um aceno rápido de respeito ao motor histórico por trás de tantas dessas ferramentas. O bom e velho Graphys. Longe de ser ultrapassado, ele continua vivíssimo e recebendo atualizações constantes neste ano de 2026, carregando nas costas vários ecossistemas legados e pipelines acadêmicos mais complexos. Chegando no nosso ponto 3. Build, SVG e Tokens. Como as coisas ganham vida? Na prática diária, o nosso pipeline de build precisa funcionar como um relógio, seguindo um fluxo muito bem amarrado. Primeiro, a gente escreve o texto direto no repositório. Depois, a automação entra em cena e compila isso na linha de comando, usando o Mermaid Clip. O terceiro passo é o nosso servidor disponibilizar o arquivo SVG purinho lá na web.

E a cereja do bolo é a injeção dos nossos tokens de design. É exatamente esse processo antecipado no momento do build que impede a nossa documentação de apodrecer e quebrar toda vez que o sistema recebe um deploy fresquinho. E tem um detalhe. Compilar antecipadamente não é só uma recomendação amigável. É uma obrigação técnica. Pensa bem, entregar a biblioteca inteira do Mermaid pro navegador de quem acessa o portal custa absurdos 3,4 megabytes. É, literalmente, usar uma bazuca pra matar um pernilongo. Quando a gente joga esse esforço lá pro servidor e entrega apenas o SVG compilado, o tamanho despenca pra meros 30 kilobytes. Nunca, jamais, faz sentido obrigar o usuário a baixar montanhas de JavaScript só pra renderizar uma imagem estática. E isso nos leva a uma regra de ouro que precisa ser defendida com unhas e dentes pela nossa equipe. Nunca escreva cor hexadecimal à mão, sempre injete tokens de cor do projeto no SVG. Se a gente colocar uma cor hexadecimal manualmente no código, aquele diagrama vai ficar praticamente invisível quando o dispositivo mudar de um tema claro pro dark mode, por exemplo. Usar tokens CSS é o que garante que o design vai fluir e se adaptar perfeitamente, não importa a tela ou tema.

Ponto 4. Contraste e a norma WCAG. Uma prioridade inegociável. Nenhuma figura, absolutamente nenhuma, deve subir pro ambiente de produção do Portal Leadlovers sem antes passar por este checklist de aprovação visual. Esses são números exatos e obrigatórios da norma WCAG, versão 2.2. Pra texto comum, a proporção mínima de contraste com o fundo tem que ser de 4,5 pra 1. Para as linhas e para os blocos, a exigência é de 3 pra 1 e qualquer alvo tocável na tela precisa ter no mínimo 24 por 24 pixels num padrão AA. Fica alerta para aquela praga invisível, rótulos com textos cinza sobre um fundo cinza que aparecem do nada quando o preenchimento falha ao herdar a cor base. A única solução segura é validar o contraste tanto no tema claro quanto no escuro. Ponto 5. Inteligência artificial, gerando diagramas a nossa realidade atual. A gente sabe que hoje ferramentas fantásticas como os artefatos do Claude, o Copilot Chat e o Mermaid AI estão acelerando demais a geração desses códigos de diagrama.

Esse fluxo cria coisas supervaliosas em questão de segundos, mas tem um grande porém. Modelos de IA são não determinísticos, ou seja, eles abrem um espaço enorme para imprecisões e para aquelas famosas invenções criativas na hora de escrever a sintaxe. A nossa principal vacina contra essas alucinações da inteligência artificial se chama Mermaid.parse. Essa função é uma maravilha. O único trabalho dela é bater o olho na estrutura gramatical que a IA sugeriu e validar se está tudo certo. Sempre precisa renderizar a imagem na tela. É uma barreira incrível que economiza recursos, mas que precisa sempre, sempre vir acompanhada de outra tática vital. Colar lá no prompt da IA a documentação exata da versão que a gente está usando no projeto. E para fechar, sessão 6, a fronteira do editor, até onde o texto resolve. É aqui que a gente traça uma linha bem grossa no chão separando que é documentação visual de um produto de software complexo. A pergunta que desimpata tudo a essa, existe a real necessidade de alguém salvar, editar dinamicamente ou repassar partes desse desenho ali pela própria interface da tela? Se a resposta for um sim para qualquer um desses pontos, a gente precisa abandonar um mermaid imediatamente. A natureza do projeto virou outra coisa completamente diferente. Quando a gente cruza a fronteira pro lado interativo, o terreno vira um campo minado, principalmente falando de licenciamento. Bibliotecas maravilhosas como o React Flow e o Excalidraw operam sob a licência MIT, super permissiva, todo tranquilo. Agora, achar que opções completas como o tldraw também são 100% livres para jogar em produção é uma cilada que custa caro. Hoje em dia, o tldraw exige uma licença comercial para uso em produção, então muita atenção para não comprometer o projeto logo no início. Para amarrar tudo que a gente desbravou nesta aula, vamos finalizar com uma reflexão poderosa que deve guiar as nossas decisões de agora em diante. Qual ferramenta vai poupar semanas de refação na nossa próxima sprint? Entender a real necessidade, escolher a ferramenta cirúrgica certa e blindar a nossa arquitetura visual é o que realmente traz eficiência para o orçamento e salva o nosso bem mais precioso, o tempo do time. Fica o forte convite para que essas métricas e processos sejam aplicados logo no próximo levantamento visual da equipe. Uma execução fantástica para todo mundo e até a nossa próxima análise.

Transcrição de reconhecimento de fala, com correções de grafia em nomes técnicos. A conversa original foi preservada. Versões e convenções mencionadas na gravação refletem o material da aula; consulte as notas técnicas do guia para os limites de cada recomendação.

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.
Ler a transcrição completa do podcast
Transcrição do podcast

Imagina a seguinte cena, é um dia inteiro de engenharia e marketing dedicado a montar o diagrama perfeito de um funil de conversão. Ah, o clássico painel infinito, chio de caixas perfeitamente alinhadas. Exato, tipo centenas de caixinhas, aquelas conexões milimétricas, cores impecáveis, aí o arquivo salvo, exportado como uma imagem linda e anexado com o maior orgulho na documentação da empresa. E a gente sabe bem o que acontece três dias depois, né? Nossa, sempre. Três dias depois, o líder de desenvolvimento muda a ordem de um web hook lá na esteira de integração ou o time de marketing decide colocar um e-mail extra de recuperação de carrinho. E assim, de forma totalmente silenciosa, aquele diagrama caríssimo, virou lixo eletrônico.

Virou uma mentira visual, porque absolutamente ninguém, tipo ninguém, lembra de abrir o sórter de desenho para atualizar aquela figura manualmente depois que o código muda. Esse é o custo oculto do desenvolvimento moderno. É muito raro o problema estar em escrever o código que processa a ação, sabe? O buraco negro do orçamento é manter as representações visuais em sincronia com a realidade da operação. Sim, porque o código do sistema é orgânico, ele flui, mas a documentação tradicional é totalmente ingessada. E essa simetria acaba corroendo a confiança entre os departamentos. A documentação passa a ser vista não como um mapa real do território, mas tipo como um registro arqueológico estático de como as coisas deveriam ser.

E não como elas realmente são. É por isso que o alvo do nosso mergulho profundo de hoje é exatamente o antídoto para esse abismo de desatualização. Um material excelente por sinal. Muito. A gente vai dissecar o dossier aprofundado do portal Leadlovers 2026, mais especificamente os módulos do curso Frontends com VibeCoding. Que foca exatamente no alinhamento crítico entre essas esteiras de marketing e os times de engenharia. É. A missão das fontes hoje é clara, a transição para diagramas de arquitetura e fluxo definidos estritamente como código, ou seja, um texto contínuo que orienta a máquina a se desenhar sozinha a cada nova publicação. Liquidando o problema da obsolescência de uma vez por todas.

Mas olha, antes do dossier mergulhar nessa sopa de letrinhas e bibliotecas, ele bate numa tecla metodológica bem brutal. Ah, armadilha da palavra diagrama, né? Isso. O material expõe que essa palavra mascara três categorias mecânicas radicalmente diferentes. E tratar as três como o mesmo problema é… hum, a receita perfeita para queimar orçamentos inteiros. Uma falácia de categorização. Assumir que qualquer bloco visual conectado por setas funciona com a mesma premissa técnica é criar uma dívida arquitetural monstruosa. Com certeza. O material propõe uma divisão rigorosa em três famílias, baseada numa pergunta muito simples. Quem, no final das contas, faz o trabalho braçal de calcular a posição de cada elemento na tela.

Boa. Então, se a resposta for… hum, o analista escreve um roteiro em texto e a máquina deduz o posicionamento das peças por conta própria, a gente cai direto na família 1. Exatamente. Que é o foco pesado das nossas fontes de hoje. Linguagens puramente textuais de modelagem, como o D2 e o gigante ecossistema do Mermaid. E a engenharia por trás dessa família 1 é totalmente baseada em delegar o microgerenciamento. Sim, o operador abre mão conscientemente do controle fino sobre os pixels. Você dá as instruções lógicas, tipo o nó A manda informação pro nó B. E o motor de renderização faz os cálculos pesados pra evitar que as linhas se cruzem. É como escrever o roteiro de uma peça de teatro para os atores seguirem em vez de arrumar o palco.

Você insere uma etapa nova de faturamento e a máquina empurra o resto sozinho. Mas claro, depender desse motor esbarra numa restrição. Se o produto exige que um cliente ou um coordenador clique nas etapas do funil, arraste a caixa com o mouse e mude a ordem ligando fios na tela. Aí já mudamos de cenário. Completamente. Aí estamos na família 2. Território de construtores modulares, onde o dociente destaca o react flow como espinha dorsal. Entendi. E tem a família 3 também, certo? Sim. Só pra fechar taxonomia, a família 3 é sobre física computacional em tempo real. Pense em bibliotecas como Cytoscape.js. Aquelas redes gigantes de dados. Isso. Dezenas de milhares de nozes olados que se atraem ou se repelem na tela.

O formato da nuvem é a própria informação. Útil pra monitorar servidores macícios globais. Mas peraí, vamos fazer um teste prático aqui. Se as ferramentas da família 2 entregam liberdade total na ponta da linha pra arrastar e montar painéis, por que não usar o react flow pra tudo? Porque o preço dessa liberdade astronômico, financeiramente falando. Nossa, o clássico erro de orçamento documentado no curso? Sim. Orçar a implementação de um canvas da família 2 pra resolver um problema de simples leitura da família 1 é o que faz um misprinte de desenvolvimento entrar em colapso. Porque se você deixa as pessoas arrastarem coisas, o sistema tem que gerenciar coordenadas de banco de dados, calcular colisão na tela, habilitar zoom...

Salva tudo no servidor depois. Vira um software de design gigante embutido no projeto só pra exibir um texto. A regra do dossier é clara. Se quem loga no sistema precisa interagir com a geometria e salvar aquilo, não é mermaid. Passou da fronteira de diagramação e invadiu o desenvolvimento avançado de produto. Exato. Um dia de trabalho vira duas semanas de dor de cabeça se você errar a família. Então beleza, ficando na família 1, onde nós escrevemos texto pra máquina desenhar, o curso joga um holofote imenso nas opções de mercado atuais, em pleno 2026. E o mermaid reina absoluto. O domínio deles é inegável, especialmente agora no release 11.16.1. Muito além daqueles fluxogramas burocráticos de antigamente, né?

O dossier lista suporte pra arquitetura de nuvem, componentes circulares pra radar, quatro scambam de marketing. Sim, até pacotes densos de rede, a expansão foi agressiva demais. Só que essa velocidade toda gerou umas fissuras na estrutura deles. Como assim? O motor central do mermaid nasceu pra grafos bem lineares. Com tanta coisa nova, muitas topologias ainda vivem de atributos marcados como o beta. Ele é ótimo em linha reta. Mas quando você precisar grupar componentes complexos em caixas fechadas... Ao calcanhar de Aquiles do agrupamento. É aí que entra a régua de medição do curso, a disputa entre mermaid e D2. A famosa regra das 12 caixas. Sim, o material traça a linha justamente aí. Fluxo rápido até 12 componentes, mermaid a escolha certa.

Mas se o diagrama exige camadas dentro de camadas, tipo uma nuvem com redes virtuais isoladas, contendo clusters cubermets, rodando dezenas de microserviços, aí o D2 toma a frente. Porque a matemática do D2 pra grupar coisas é diferente, né? O motor é o que é deles. Exatamente. No D2, o agrupamento não é uma gambiarra sintática, é um conceito de primeira classe. O compilador projeta o tamanho da caixa externa, baseado no volume do que tem lá dentro sem quebrar a imagem. Mas... Uma dúvida que doce levanta, se o D2 é tão mais inteligente pra grupar, porque a gente simplesmente não usa o D2 pra todo e bane o Mermaid da empresa. Evita até retrabalho no futuro. A resposta é fricção cognitiva. Aprender D2 tem um pedaço alto.

A sintaxe obriga o programador a declarar escopos espaciais antes mesmo de desenhar as setas. É muito burocrático. Você imagina exigir isso de um analista só pra desenhar um fluxo de 5 e meios de marketing. Exato. Mato o raciocínio. O Mermaid só pede quatro linhas simples pra entregar o mesmo resultado. Se a ferramenta exige muita ginástica, o time desiste e volta pras planilhas desenhadas à mão. Sem contar que o Mermaid tem aquele monopólio de suporte nos editores de código, mas a gente já fala dessa roleta de plataformas. Tem uma etapa crítica antes disso. Como essa imagem gerada pelo texto chega na tela de quem vai ler? Nossa, a parte do carregamento, as fontes dão puxão de orelha enorme naquele erro de principiante.

E como dão? A mania terrível de embutir o motor inteiro do Mermaid na página web do cliente. Carregar 3,4 megabytes brutos de JavaScript na versão completa da 11.16.1. E mandar isso pro navegador de quem tá acessando o portal da empresa. É um absurdo arquitetural. Você manda uma carga gigantesca para um celular com internet ruim, engasga a memória principal do navegador, faz ele calcular a geometria algébrica de setinhas. Tudo isso só para a moção diagrama. Pronto. O dossier usa uma analogia que eu achei fantástica, que é tipo convidar alguém pra comer um bolo. Em vez de dar fatia, entregar farinha, o forno e os ovos na casa da pessoa e mandá-la assar. Por isso, a solução metodológica do curso é inverter essa polaridade agressivamente.

Compilar no momento do building. O famoso build time, salva vidas e economiza muito plano de dados. Sim. Usando ferramentas acíncronas no servidor, como o Mermaid CLI ou a cadeia do rehype Mermaid. Enquanto o site corporativo tá sendo publicado nos bastidores, um servidor gigante faz todo o processamento geométrico. E aí a página só recebe um formato SVG, leve, estático, minificado. Sem nenhum script atrelado. É uma elegância gigantesca em engenharia. O desenho vive como texto no repositório, mantendo histórico de versão. Mas a entrega final na tela é uma pena. E a entregar rápido é ótimo. Mas de que adianta carregar instantaneamente se as pessoas não conseguem enxergar o que tá escrito ali.

O abismo da acessibilidade. Outro ponto fortíssimo do dossier. É muito sério. A gente cai na norma mundial do WC AG. O material mostra que por padrão as ferramentas geram um cinza claro sobre um fundo claro. A relação de contraste fica em 2 para 1, o que é horrível. Essa densidade ótica garante a iligibilidade total. Dependendo do ângulo do monitor, ou se tiver uma janela refletindo na tela do coordenador de marketing, acabou. O dado desaparece. E a norma exige proporções exatas, né? 4,5 para 1 em textos normais e 3 para 1 no delineamento das formas. Exato. E como se resolve isso em um vetor gerado no servidor, sem embutir códigos hexadecimais ingessados. Injetando cores puramente para o variável CSS, os tokens universais de design da empresa.

Sim. O SVG vira uma esponja. Em vez de declarar que a caixa é cinza, ele diz que a caixa usa a variável de cor principal do sistema. Se a pessoa acessa pelo celular no modo escuro, no meio da noite, o vetor absorve essa mudança instantaneamente e gira o contraste, garantindo a conformidade visual sempre. Tudo devidamente ancorado, na regra de preenchimento explícito e fontes nunca inferiores a 14 pixels. Isso é incrível, mas mesmo com contraste perfeito e SVG super leve, a gente ainda esbarra na plataforma onde isso vai abrir no dia a dia. A famigerada roleta dos ecossistemas. Exato. A gente tem essa ilusão de que código é código e vai abrir igual em todo lugar. O GitHub e o VS Code são exemplos maravilhosos.

Sim. Suporte nativo isolado, sensacional. O VS Code até abraçou a renderização nativa em chates e arquivos markdown de pré-visualização, desde aquele update de janeiro de 2026. Lindo. Mas aí o dossier joga um balde de água fria com o GitLab. O material aponta que a renderização corporativa do GitLab ficou paralisada em ferramentas arcaicas, tipo a versão 10 do Mermaid. É um desastre logístico interno. Imagine o cenário. O desenvolvedor escreve usando uma sintaxe moderna da versão 11, checa no monitor local dele, vê que está perfeito e aprova. Aí o gelente vai abrir o repositório no GitLab da empresa para ler o funil e o motor legado lá de dentro não reconhece o código. Exibe um bloco vermelho gigantesco de erro de sintaxe.

O diagrama sobreviveu à estera toda, mas quebrou no último quilômetro. Validar as coisas só na sua máquina é um silo alienado, né? Totalmente. E falando em sintaxe que pode quebrar, a gente precisa tocar no assunto da inteligência artificial. Tentação de terceirizar tudo. Já que é só texto, porque eu vou escrever manualmente, se eu posso pedir para o Claude ou para o Copilot gerarem 100 caixas de diagrama em dois segundos. É, é o reflexo instintivo de 2026, fugir da fadiga operacional. O problema é que o dossier detalha como isso alimenta a armadilha da alucinação confiante. Alucinação confiante. Isso é muito perigoso, porque a IA cospe um código em milissegundos super complexo, visualmente impecável na estrutura de texto.

E a equipe confia cegamente. Só que esses modelos são geradores não determinísticos. Eles inventam propriedades que não existem na versão específica que a empresa está usando. Fundem atributos imaginários. E se você joga isso direto na esteira de publicação automática que a gente montou? O compilador barra a publicação. Quebra o deploy do portal corporativo inteiro. Para evitar esse colapso, o manual ensina a blindar o processo com um passo bem rápido de segurança. A função mermaid.parse. O famoso segurança de balada. Como ele funciona mesmo na prática? Ele desenha o vetor antes. Não, aí é que está a sacada de performance. Ele não tenta calcular pixel, renderizar geometria, nada. Ele atua puramente na verificação da árvore de sintásseis abstrata, ou AST.

Ah, então ele só leu léxico. Exato. Ele checa se aquela gramática é válida. É acíncrono e ultra rápido. Ele barra e é mentirosa de entrar na festa antes que o compilador tenha o trabalho de tentar desenhar e falhar miserabilmente. E o curso também ensina a ancorar o prompt da IA, exigindo que ela olhe as versões exatas das bibliotecas registradas no arquivo package.json da empresa para não inventar moda. Ajudando a domar a alucinação direto na fonte. Perfeito. Então a gente validou, compilou, publicou leve e garantiu contraste. Mas chega um dia em que o diagrama não é mais só para a leitura. O texto puro não basta mais. E aqui a gente volta para o começo da conversa, atravessando a fronteira em direção ao abismo legal, o momento em que as famílias se cruzam.

É o cenário da recepcionista da clínica. Se ela precisa arrastar um bloco na tela para mudar um fluxo de confirmação direto na plataforma, o Mermaid morre na praia. A gente entra de cabeça no mundo dos editores interativos, a família 2. E quando a engenharia cruza essa linha, a habilidade mais urgente não é ler código, é ler licença de software. Puxa, esse aviso do doce é vital. A gente tem opções seguras de código aberto. O React Flow é uma saída blindada, licença emiti para sempre. O Excalidrol continua na mesma linha, super livre e permissivo. Mas a grande surpresa, e o alerta vermelho do material, foi a mudança nas regras do TL Drol. Isso assustou muita gente. A biblioteca não é mais puramente de código aberto, permissivo para produção comercial.

Deixou de ser, se a sua empresa embarca o tldraw, sistematicamente agora, sem pagar a licença comercial dedicada. A punição é uma visualização compulsória de marca d'água, enraizada na tela dos clientes ou barreiras jurídicas ativas. Imagina você construir o recurso interno no sprint, achando que é grátis e na hora do lançamento, o jurídico manda desligar tudo. Pois é. A arma de lhe orçamentária mais cara que tem é por causa de coisas assim que um dia de planejamento se arrasta por duas semanas. Falta de clareza sobre o limite técnico e as amarras de licença da ferramenta. É de tirar o fôlego a quantidade de variáveis. Mas consolidando as grandes lições no nosso dossier hoje, a gente precisa saber separar a família textual da interativa, delegar o peso da renderização para o build e não para o navegador, respeitar as normas cegas do WCAG, usar parsers para não ser enganado pelas IAS e nunca implementar um motor arrastável sem ler o contrato.

Exato. No fim das contas, o que tudo isso significa, significa parar de tratar a documentação de software como uma pintura a óleo que ninguém pode tocar. Significa ter uma documentação que finalmente sobrevive ao choque com a realidade do código. E sabe o que é fascinante nisso tudo? Uma reflexão final para a gente fechar. Manda. Já que a documentação agora é baseada em texto perfeitamente validada e compilada em milissegundos, o que impede a gente de imaginar um futuro superpróximo onde o próprio código da aplicação se auto analisa. Como assim? O código muda na esteira, detecta os próprios webhooks, reescreve ativamente o diagrama em mermaid sem intervenção humana e publica imagem nova automaticamente.

Uma arquitetura de software que literalmente desenha e explica-se mesmo em tempo real. Nossa, a documentação ganhando vida própria, fechando definitivamente o abismo entre o que a máquina faz escondida e o espelho visual do que a gente enxerga na tela. Que pensamento maravilhoso para encerrar a análise. Obrigada pela companhia nesse mergulho profundo. Foi excelente. Até a próxima.

Transcrição de reconhecimento de fala, com correções de grafia em nomes técnicos. A conversa original foi preservada. Versões e convenções mencionadas na gravação refletem o material da aula; consulte as notas técnicas do guia para os limites de cada recomendação.

Exemplo comentado

Qual desenho explica o processo que você precisa ensinar?

Uma pessoa quer descobrir quem aprova uma entrega; outra quer montar um fluxo arrastando peças. A imagem pode parecer semelhante, mas as tarefas exigem experiências diferentes. A escolha começa pelo que o leitor precisa fazer.

Leitura: seguir uma aprovação. Decisão: aprovado ou revisar?. Edição: montar o próprio fluxo.
Leitura: seguir uma aprovação · Decisão: aprovado ou revisar? · Edição: montar o próprio fluxo. Baixar a ilustração
Ler os dois casos e suas decisões comentadas

As saídas estão nomeadas

O fluxo apresenta pedido, revisão, critério de aprovação e retorno com correção. As setas trazem o significado de cada saída.

Decisão: a condição foi atendida. A condição e o retorno permitem percorrer uma aprovação e uma revisão.

A figura está pronta para o teste de leitura; a descrição textual continua necessária.

O desenho só tem caixas

As caixas estão conectadas, mas as setas que saem da revisão não dizem quando seguir ou voltar.

Decisão: falta conferir ou corrigir. A aparência de fluxo esconde uma decisão que ainda não foi escrita.

Nomeie a condição de cada seta e teste o caminho de retorno.

Consultar as seis etapas do desenho
A pessoa consegue seguir os dois ramos e explicar o motivo de cada saída?
EtapaO que conferirAção
Escrever a perguntaDiga qual dúvida o desenho deve resolver antes de escolher a biblioteca.Complete: a pessoa precisa entender ou fazer o quê?
Definir a interaçãoDistingua ler uma sequência de editar um processo. Ler pode usar uma figura estática com explicação.Registre se os elementos precisam ser editáveis.
Testar o desenhoO leitor deve localizar entrada, critério de decisão e destino de cada ramo sem depender da cor.Peça que percorra uma situação com o desenho.
Se atendida: Entregar a figuraSe a leitura funciona, publique a figura com legenda, descrição textual e relação entre os nós.Mantenha o texto fonte junto do desenho.
Se pendente: Reorganizar a lógicaUm ramo sem condição ou uma seta sem destino pede revisão do processo representado.Nomeie a decisão e confira cada saída antes de estilizar.
Repetir com uma exceçãoUma figura didática deve mostrar o que acontece quando o caminho principal não pode continuar.Confira o percurso de revisão com outra pessoa.

Esboço com pergunta, entrada, decisão, saídas nomeadas e exceção descrita.

Acrescentar animação a uma seta ambígua torna a ambiguidade mais visível; escreva a condição primeiro.

Os casos são ilustrativos. A escolha da família do diagrama depende da interação descrita em cada caso.

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.

O modelo C4: o que entra em cada figura

A família escolhida resolve como o desenho nasce e deixa em aberto o que cabe dentro de cada quadro. A convenção C4, de Simon Brown, organiza essa segunda resposta em quatro níveis: contexto, contêiner, componente e código. O contexto mostra o sistema inteiro e quem conversa com ele; o contêiner abre esse sistema nas peças que rodam separadas; o componente entra dentro de uma dessas peças; o código desce ao detalhe da implementação. A régua de ferramentas desta aula responde como a figura é produzida, e o C4 responde o que ela mostra.

Um nível por figura. Contêiner e componente no mesmo quadro produzem o desenho que ninguém lê inteiro. E a figura de contexto vem antes de qualquer outra, porque ela é a que situa quem chega: sem ela, o segundo desenho já abre cobrando um conhecimento que o leitor ainda vai formar.

Mermaid na aula: formatos além do fluxograma

Os exemplos desta aula usam a série 11. A documentação atual já apresenta a série 12; fixe a versão no projeto e confira a compatibilidade antes de atualizar. Recursos e limites descritos a seguir pertencem ao recorte da aula.

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 MiB 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 · Mermaid 11
VS Code · nativo na 1.121
Obsidian · nativo
Notion · atalho /mermaid
Compatibilidade das plataformas: recursos e condições de uso na tabela. GitLab revisto em setembro de 2026.
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 documentação atual informa Mermaid 11. Confira o tipo de diagrama e a versão da instância antes de padronizar o uso
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. Pesquisa inicial em 18/08/2026; suporte do GitLab conferido novamente em 10/09/2026.

A consequência prática: antes de padronizar um tipo novo de diagrama no time, confira onde ele precisa renderizar. O mesmo código pode ter resultados diferentes conforme a versão do renderizador e os recursos habilitados em cada instância.

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 v0.7.1, usada como referência na pesquisa da aula, foi publicada em 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: até uma dúzia de elementos, começar com Mermaid; acima disso, ou com camadas aninhadas, comparar o resultado com D2. Essa é uma convenção didática, sem limite técnico de doze nós. O Mermaid também aceita agrupamentos e o layout ELK. A decisão deve considerar cruzamento de setas, legibilidade dos rótulos, controle de posição e manutenção do código. O D2 oferece contêineres aninhados como parte da linguagem.

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.

No Mermaid, themeVariables recebe cores hexadecimais. Use uma paleta por tema no compilador ou aplique as variáveis CSS ao SVG inline no pós-processamento. Passar var(--token) diretamente ao motor não substitui essa configuração.

O token só alcança o SVG que mora dentro da página. A figura chamada por <img src="diagrama.svg"> abre num documento próprio, isolado do CSS de quem a exibe: as variáveis desta página ficam fora do alcance dela, var(--text) lá dentro resolve para nada e o rótulo cai no valor de fábrica ou some. A injeção de tokens que esta seção ensina pede uma de duas saídas. Ou o SVG entra inline no HTML, colado no corpo da página, e passa a enxergar as mesmas variáveis do tema. Ou o build compila duas versões da mesma figura, uma clara e uma escura, e a página serve a que corresponde ao tema ativo. Quem seguir o roteiro mantendo a chamada por img vai ver a figura quebrar no tema escuro, com o pipeline verde e o commit aprovado.

A regressão visual que o CI pega antes do merge

Compilar no build resolve o frescor da figura e abre um ponto cego. O texto-fonte muda uma linha, o motor de layout reposiciona metade das caixas e ninguém percebe, porque a revisão do pull request lê o diff do texto sem abrir o desenho. O conserto reaproveita o passo de compilação que a seção já descreve: o CI gera o SVG do branch, compara com o SVG da base e leva a diferença para dentro da própria revisão.

Para comparar por conta da casa, o pixelmatch num passo de CI recebe as duas imagens e devolve a máscara dos pixels que mudaram, com um limiar por cima para segurar o ruído de antialiasing. Para terceirizar a hospedagem das imagens e o botão de aprovar, Percy e Chromatic entregam a mesma comparação com histórico por pull request. Em qualquer das duas rotas o ganho é o mesmo: a mudança de layout aparece na revisão, e quem aprova decide se ela foi pedida ou se é efeito colateral de uma linha de texto.

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

O contraste depende da cor do rótulo e do fundo real. A WCAG 2.2 exige 4,5:1 para texto de tamanho normal (critério 1.4.3, nível AA). Para partes de objetos gráficos necessárias à compreensão, como linhas e formas do diagrama, o critério 1.4.11 pede 3:1 contra as cores adjacentes. As amostras abaixo mostram valores aprovados e reprovados.

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.

A mudança de tema pode alterar o contraste. Confira texto, linhas e formas nos fundos em que realmente aparecem, incluindo os estados de foco e seleção dos controles.

O curso adota 14 px como referência local para rótulos, medida na dimensão em que o desenho é exibido. A WCAG não estabelece esse tamanho como mínimo universal: contraste, ampliação e legibilidade também precisam ser conferidos. Um SVG com fonte de 14 px que encolhe pela metade exibe um rótulo de aproximadamente sete pixels.

IA gerando diagramas: o que é real e como validar

Assistentes de IA podem gerar o código de um diagrama a partir de uma descrição. O Claude documenta diagramas Mermaid em seus artifacts; o cookbook do GitHub apresenta exemplos com Copilot Chat e alerta que as respostas são não determinísticas. O código gerado precisa passar pela mesma revisão aplicada a uma alteração escrita pelo time.

Da descrição do processo ao diagrama revisado A descrição orienta o código. O parser confere a sintaxe. A revisão do processo confere ramos e exceções. A figura passa por renderização e conferência de contraste. Falhas de sintaxe, lógica ou leitura retornam ao código e à descrição antes da publicação. Descriçãoatores e condiçõesCódigoversão documentadaSintaxemermaid.parse()Lógicaramos e exceçõesFigurarender e contraste Falha de sintaxe, lógica ou leitura: revisar antes de publicar
O parser verifica a sintaxe. A revisão humana confere se o desenho preserva o processo, e a inspeção visual verifica a figura renderizada.

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. No ChatGPT e em outros assistentes, confira a superfície usada para exibir o resultado. Gerar código, renderizar uma prévia e exportar SVG são capacidades diferentes; valide a entrega no destino escolhido.

Validar sintaxe e conferir significado são etapas diferentes. Use mermaid.parse() antes de renderizar e consulte a documentação da versão registrada no package.json. Depois confira se o desenho conserva atores, entradas, condições, saídas, retornos e exceções do processo. O parser não detecta uma condição omitida nem comprova que uma ligação existe no sistema. Renderize o código aprovado e confira rótulos, contraste e cortes nos dois temas.

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.

Um editor de fluxo acrescenta persistência, estados de edição, testes e suporte ao escopo do produto. As ferramentas a seguir atendem a essa tarefa com modelos de licença diferentes:

React Flow (xyflow)

Licença MIT MIT

A série 12.11 consultada usa licença MIT. A assinatura Pro oferece exemplos avançados e suporte. 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.

Há colaboração em tempo real, e é ela que separa esse quadro do desenho estático: o pacote aceita integração de sincronização, Yjs entre elas, para várias pessoas editarem a mesma tela. Na conta frente ao tldraw, esse ponto soma do lado da licença, já que a edição a várias mãos chega sem license key em produção.

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.

Esse teto de WebGL citado para os dois já tem um degrau seguinte à vista, o WebGPU. O deck.gl explora renderização em WebGPU na série 9.4, marcada como alpha na documentação consultada em 02/09/2026, e o estágio decide o uso: serve para prova de conceito e para medir ganho no seu volume de nós. Para o grafo que vai ao ar neste semestre, o WebGL segue como o caminho de produção, com o experimento em WebGPU rodando ao lado e data de reavaliação marcada no calendário do time.

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. Adote a referência do curso de
  14px na dimensão exibida e confira ampliação e legibilidade.
- 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
   as partes gráficas necessárias à compreensão passam 3:1 (WCAG 2.2, critérios 1.4.3 e 1.4.11).
3. Compare Mermaid e D2 se o desenho ficar denso ou exigir grupos aninhados.
   A regra de 12 nós é uma convenção deste curso, não um limite técnico.
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 de sintaxe.
   Confira separadamente entradas, condições, retornos e destinos: o parser
   não verifica se o processo descrito corresponde à realidade.
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. Confira o fill calculado de cada <text>, inclusive quando herdado,
   e marque fontes menores que 14px na dimensão exibida (convenção da aula).
2. Meça o contraste de cada rótulo contra o fundo real e aponte o que
   fica abaixo de 4,5:1; confira 3:1 nas partes gráficas necessárias
   à compreensão (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.
Guias para postar

Dois guias prontos para o LinkedIn e o Instagram

Cada cartão abaixo foi desenhado para sair como imagem: escolha o formato, abra a tela de print, capture a área do cartão e publique com a legenda que o botão copia. O conteúdo resume o método desta página, então o post leva o leitor de volta para cá.

Design · Diagramas como códigoLeadlovers 2026

O diagrama nasce em texto e compila no build

O leitor recebe o SVG pronto, sem nenhuma biblioteca de desenho na página.
  1. Versione o arquivo do diagrama no repositório. O desenho ganha histórico, autor e revisor.
  2. Compile no momento de publicar. A flag de identificador único evita colisão entre figuras.
  3. Injete os tokens de cor no pós-processo. A mesma figura serve o tema claro e o escuro.
  4. Sirva o SVG da pasta pública. Mudou a arquitetura, muda o texto e o build refaz o resto.
brasilgeo.ai/leadlovers2026Guia 1 de 2
Legenda sugerida para LinkedIn e Instagram
Diagrama desenhado em ferramenta de slide envelhece no dia seguinte à publicação.

Tratar diagrama como código muda o contrato. O desenho vive como texto no repositório, ganha histórico, autor e revisor, e vira SVG no momento de publicar. O compilador oficial do Mermaid roda no build com identificador único por figura, os tokens de cor entram no pós-processo e a página do leitor recebe o desenho pronto, sem runtime nenhum.

Quando a arquitetura mudar, você muda o texto e o build refaz o resto.

Salve o cartão e aplique no próximo diagrama de arquitetura do seu repositório.

Guia completo: brasilgeo.ai/leadlovers2026/design/diagramas/

#Leadlovers #Diagramas #Mermaid #Documentacao
Design · Diagramas como códigoLeadlovers 2026

Nenhum rótulo da figura pode sumir na tela

Confira rótulos e linhas contra o fundo real nos temas claro e escuro.
  • Declare a cor de preenchimento em cada texto. Confira o preenchimento calculado de cada rótulo, inclusive quando herdado do grupo.
  • Puxe as cores dos tokens do projeto. A figura acompanha o tema claro e o escuro.
  • Fixe a fonte em 14 pixels para cima em todo rótulo, inclusive nos das setas.
  • Escreva o título e a descrição acessíveis. A figura passa a ter nome no leitor de tela.
  • Meça o contraste nos dois temas. A WCAG 2.2 pede 4,5:1 no texto e 3:1 nas partes gráficas necessárias à compreensão.
brasilgeo.ai/leadlovers2026Guia 2 de 2
Legenda sugerida para LinkedIn e Instagram
Um rótulo cinza-claro sobre fundo claro pode ficar ilegível. A revisão precisa conferir as cores reais nos dois temas.

A auditoria tem cinco pontos e cabe em minutos: cor de preenchimento declarada em cada texto do SVG, cores puxadas dos tokens do projeto, referência do curso de 14 pixels na dimensão exibida, título e descrição acessíveis em toda figura, e o contraste medido nos dois temas. A WCAG 2.2 pede 4,5:1 no texto de tamanho normal e 3:1 nas partes gráficas necessárias à compreensão.

Abra a figura no tema claro e no escuro antes de considerar o trabalho pronto.

Guia completo: brasilgeo.ai/leadlovers2026/design/diagramas/

#Leadlovers #Acessibilidade #Diagramas #WCAG

Perguntas frequentes

O que significa tratar diagrama como código?

O desenho vive como texto no repositório, em ferramentas como Mermaid e D2, e é compilado em figura a cada publicação. O texto versionado ganha histórico, autor e revisor, e a figura acompanha o sistema: quando a arquitetura muda, muda-se o texto e o build refaz o resto, sem ninguém redesenhar caixa por caixa numa ferramenta de slide.

Quando usar Mermaid e quando usar D2?

A régua do curso usa doze elementos como referência didática, sem impor um limite técnico ao Mermaid. Comece com Mermaid para fluxos simples e compare D2 quando houver grupos aninhados ou dificuldade de leitura. Considere cruzamento de setas, rótulos e manutenção do código; Mermaid também aceita agrupamentos e o layout ELK.

Por que compilar o diagrama no build em vez de renderizar no navegador?

Embarcar o mermaid.min.js da versão 11.16.1 custa 3,4 MiB sem compressão no navegador de quem lê. Compilar no build com o @mermaid-js/mermaid-cli e servir o SVG puro entrega a mesma figura sem esse peso, com as cores do projeto injetadas por token no pós-processo, o que mantém o diagrama legível nos temas claro e escuro.

Como validar um código Mermaid gerado por IA antes de publicar?

Use mermaid.parse() para conferir a sintaxe e consulte a documentação da versão registrada no package.json. Depois revise o significado: entrada, condições, saídas, retornos e exceções. Um código pode passar no parser e ainda representar um processo errado. A validação do SVG e do contraste completa a revisão visual.

Qual contraste a WCAG 2.2 exige em um diagrama?

O texto de tamanho normal precisa de 4,5:1 contra o fundo (critério 1.4.3, nível AA) e as partes gráficas necessárias à compreensão, de 3:1 (critério 1.4.11). A amostra cinza-claro deste guia fica perto de 2:1. Abra a figura nos dois temas e rode o auditor de contraste do navegador antes de considerar pronta.

Quando o projeto precisa de um editor de fluxo em vez do Mermaid?

Quando quem usa o produto arrasta, edita e salva o próprio desenho na tela, o caso vira funcionalidade de produto, com prazo, teste e suporte próprios. Nessa fronteira, React Flow e Excalidraw seguem sob licença MIT; o tldraw deixou de ser open source permissivo e exige license key em produção, então quem o orçou como MIT precisa refazer a conta.

Do texto à publicação

A publicação do diagrama reúne fonte versionada, validação da sintaxe, revisão do processo e conferência do SVG nos dois temas. As descrições e os exemplos deste guia permitem consultar cada etapa. A coleção continua nos guias de ícones, ilustrações, animação e imagens, de menus, abas e paginação e no glossário.

Fontes e notas da aula

O guia reúne a pesquisa da aula iniciada em 18 de agosto de 2026 e o capítulo de diagramas do curso Frontends com Vibecoding, de Alexandre Caramaschi. Versões, tamanhos de pacotes e suporte das plataformas são retratos das verificações datadas no texto. A referência de doze elementos é uma convenção do curso. Os exemplos do catálogo são hipotéticos.

Medição de distribuição, 10/09/2026: o arquivo mermaid@11.16.1/dist/mermaid.min.js tem 3.566.058 bytes sem compressão HTTP, aproximadamente 3,4 MiB. Esse tamanho pertence ao arquivo completo citado, não a toda instalação ou carregamento modular.

Consultar a documentação citada