Diagramas de arquitetura e fluxo: o desenho que ninguém redesenha à mão
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.
Olá, time! É sensacional iniciar mais esta aula do nosso portal Lead Lovers 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 Lead Lovers 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 gerada localmente por reconhecimento de fala sobre o áudio original e revisada nos termos técnicos; pequenos desvios de grafia podem permanecer.
Portal Leadlovers 2026 · menu Design
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 mormade 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 mormade 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 mormade 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 mormade 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 mormade CLI ou a cadeia do rehype mormade. 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 Vesh Code são exemplos maravilhosos.
Sim. Suporte nativo isolado, sensacional. O Vesh 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 Jason 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 TEL de Drol, 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 gerada localmente por reconhecimento de fala sobre o áudio original e revisada nos termos técnicos; pequenos desvios de grafia podem permanecer.
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?
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.
architecture-betablockpacketkanbanradar-betatreemap-betaxychartNos 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:
-Imy-svg e dois diagramas na mesma página colidem.-cthemeVariables e htmlLabels.-pPara 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:
/mermaid
| Plataforma | O que renderiza | A letra miúda |
|---|---|---|
| GitHub | Blocos mermaid em issues, discussions, pull requests, wikis e arquivos Markdown | A versão embarcada é a que o GitHub escolhe; plugins de terceiros podem conflitar |
| GitLab.com | Blocos mermaid no Markdown | A doc declara suporte à versão 10: os diagramas novos da série 11 (arquitetura, kanban, radar, treemap) ficam de fora |
| VS Code | Preview de Markdown, células de notebook e chat, com pan, zoom e cópia do fonte | Nativo desde a 1.121 (extensão embutida "Mermaid Markdown Features"); o chat renderiza desde a 1.109 |
| Obsidian | Blocos mermaid nas notas | Versão embarcada sem declaração na doc |
| Notion | Bloco de código Mermaid pelo atalho /mermaid | Atalho 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:
- Build de verdade: o
rehype-mermaidrenderiza no build usando Playwright, com quatro estratégias de saída (img-png,img-svg,inline-svg,pre-mermaid). É o caminho para pipelines unified, Astro e Next. - Cliente: o Material for MkDocs inicializa o runtime JavaScript quando a página tem bloco
mermaid; o Hugo só tem GoAT nativo em build e manda carregar Mermaid via JS; o Docusaurus habilita pelo tema oficial sem declarar onde renderiza. - Sem navegador nenhum: o
beautiful-mermaid(Luki Labs, MIT) reimplementa o render em TypeScript puro, sem DOM, cobrindo seis tipos de diagrama. Promissor para CI sem Chromium, com a ressalva de ser projeto de terceiro, jovem, sem paridade garantida com o Mermaid oficial.
O roteiro da casa, do zero à figura publicada, cabe em quatro estações, lidas da esquerda para a direita:
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).
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.
- Todo
<text>do SVG comfillexplícito, cor própria declarada em cada rótulo, sem herança. - Cor por token do projeto (
var(--accent),var(--text),var(--border)), para a mesma figura servir o tema claro e o escuro. - Tamanho de fonte igual ou maior que 14 pixels em todo rótulo.
accTitleeaccDescrem cada figura: nome e descrição acessíveis sem custo.- Contraste conferido nos dois temas: 4,5:1 no texto, 3:1 nas formas (WCAG 2.2).
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.
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
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.
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)
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
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
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.
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.