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.
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.
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
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. Baixar a ilustraçãoLer 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?
Etapa
O que conferir
Ação
Escrever a pergunta
Diga qual dúvida o desenho deve resolver antes de escolher a biblioteca.
Complete: a pessoa precisa entender ou fazer o quê?
Definir a interação
Distingua 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 desenho
O 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 figura
Se 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ógica
Um 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ção
Uma 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.
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?
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.
Catálogo: trinta e seis tipos de diagrama, cada um com a pergunta que responde
Escolha o formato pela pergunta: acompanhar um processo, entender uma estrutura, organizar uma hierarquia ou explorar relações. Cada exemplo traz o uso indicado, o risco de interpretação e a descrição dos elementos e ligações em “Como construir”. Os exemplos são ilustrativos e usam situações do portal, como aprovação de orçamento, automação de e-mail e organização do CRM.
Sobre os exemplos: os nomes, as etapas e as ligações das trinta e seis figuras foram montados para ilustrar a forma, e a legenda de cada uma repete o aviso. Nenhuma descreve a arquitetura real de um cliente; ao reutilizar um formato, troque os elementos pelos seus e confira os dois caminhos de cada decisão. Para código Mermaid, use mermaid.parse() para verificar a sintaxe; outros formatos exigem seu próprio validador.
Fluxo e processo
Quando a pergunta é o que acontece depois, o desenho tem começo, setas e fim. Quase tudo aqui é texto compilado no build; a exceção é o fluxo que o cliente monta sozinho, que muda de família e de orçamento.
1. Fluxograma de decisão
Responde: por onde o pedido de orçamento passa e em que ponto o atendimento bifurca. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com mais de quinze caixas ou três decisões encadeadas: divida em duas figuras por etapa.
O pedido de orçamento com uma decisão: se o CNPJ já está no cadastro, o robô responde o preço; se não está, pede o CNPJ primeiro. Os dois caminhos terminam no mesmo cartão do CRM. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma forma por tipo de passo (retângulo para ação, losango para decisão, cantos arredondados para início e fim) e a resposta da decisão escrita na seta. Leia em voz alta do começo ao fim: se travar em algum ponto, falta uma seta ou sobra uma caixa.
Receita em Mermaid:
flowchart TD
accTitle: Pedido de orçamento
accDescr: Fluxo do pedido de orçamento com a decisão sobre o CNPJ
A([Lead pede orçamento]) --> B{Tem CNPJ no cadastro?}
B -- sim --> C[Robô responde o preço como pessoa]
B -- não --> D[Pede o CNPJ antes do preço]
D --> C
C --> E[Cartão entra no CRM na coluna Orçado]
De
Relação
Para
Lead pede orçamento
segue para
Tem CNPJ no cadastro?
Tem CNPJ?
sim
Robô responde o preço
Tem CNPJ?
não
Pede o CNPJ antes do preço
Pede o CNPJ
segue para
Robô responde o preço
Robô responde o preço
segue para
Cartão entra no CRM
2. Fluxo de automação (gatilho, espera, condição)
Responde: o que a régua de e-mail faz com o lead depois que ele baixou o e-book, passo a passo, com as esperas. Família: editor de fluxo dentro do produto (React Flow, tldraw, Excalidraw); quem monta é quem usa. Quando evitar: para documentação interna de um fluxo fixo: aí é fluxograma compilado, sem editor.
Uma régua de boas-vindas: gatilho, primeiro e-mail, espera de dois dias, condição de abertura e reenvio com outro assunto. É o desenho que o cliente monta no construtor, peça por peça. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
É funcionalidade de produto: cada tipo de peça (gatilho, ação, espera, condição) é um nó com entradas e saídas definidas, e o usuário conecta as portas. O estado do fluxo é salvo como JSON de nós e arestas, e é esse JSON que o motor executa.
Responde: quem faz cada passo do atendimento: a mesma sequência do fluxograma, separada por responsável. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com mais de cinco raias ou setas cruzando duas raias de uma vez: o desenho vira tabuleiro.
Três raias: o lead pergunta, o robô responde com a faixa de preço e pergunta se ele quer proposta, o comercial recebe o cartão pronto e devolve a proposta em 24 horas. A raia diz de quem é cada passo. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
No Mermaid, cada raia é um subgraph e a ordem dos subgraphs define a ordem das faixas. Para raias horizontais de verdade, com o processo fluindo da esquerda para a direita, o D2 e o Graphviz com clusters saem mais fiéis.
Receita em Mermaid:
flowchart LR
subgraph Lead
A[Pergunta o preço no chat] --> B[Nada de resposta em 1 h]
F[Recebe a proposta em 24 h]
end
subgraph Robô
C[Responde com faixa de preço] --> D[Pergunta se quer proposta]
end
subgraph Comercial
E[Recebe o cartão pronto]
end
B --> C
D --> E --> F
Raia
Passo
Vai para
Lead
Pergunta o preço no chat
Nada de resposta em 1 h
Robô
Responde com faixa de preço
Pergunta se quer proposta
Comercial
Recebe o cartão pronto
Lead recebe a proposta em 24 h
4. Diagrama de sequência
Responde: em que ordem os sistemas conversam quando um visitante manda o formulário, e quem responde a quem. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para fluxo com decisão e laço: a sequência mostra ordem, e a bifurcação fica ilegível nela.
Quatro participantes e cinco mensagens: o formulário cria o cartão no CRM, o CRM dispara o robô, o robô responde ao visitante em 40 segundos e registra a resposta. A seta tracejada é a resposta. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um participante por coluna, tempo de cima para baixo, seta cheia para a chamada e tracejada para a resposta. Escreva na seta o que vai na mensagem, e limite a oito mensagens por figura.
Receita em Mermaid:
sequenceDiagram
accTitle: Formulário ao robô
participant V as Visitante
participant F as Formulário
participant C as CRM
participant R as Robô
V->>F: envia nome e WhatsApp
F->>C: cria o cartão
C->>R: dispara: cartão novo
R-->>V: responde em 40 s
R->>C: registra a resposta
Ordem
De
Para
Mensagem
1
Visitante
Formulário
envia nome e WhatsApp
2
Formulário
CRM
cria o cartão
3
CRM
Robô
dispara: cartão novo
4
Robô
Visitante
responde em 40 s (resposta)
5
Robô
CRM
registra a resposta
5. Máquina de estados
Responde: em que situações um cartão do CRM pode estar e o que o faz mudar de uma para outra. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para processo linear sem volta: aí é fluxograma, e a máquina de estados só acrescenta jargão.
Os estados de um cartão: novo, em conversa, orçado e cliente. As setas de volta (sem resposta em sete dias, reabriu) são o que a máquina de estados mostra e o fluxograma esconde. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um estado por elipse, uma transição por seta com o evento escrito nela, e um ponto cheio para o início. Todo estado precisa de pelo menos uma saída, exceto o final; se sobrar estado sem saída, é sinal de cartão que fica preso.
Receita em Mermaid:
stateDiagram-v2
[*] --> Novo
Novo --> EmConversa : respondeu
EmConversa --> Orçado : pediu proposta
EmConversa --> Novo : sem resposta em 7 dias
Orçado --> EmConversa : reabriu
Orçado --> Cliente : fechou
Cliente --> [*]
De
Evento
Para
início
Novo
Novo
respondeu
Em conversa
Em conversa
pediu proposta
Orçado
Em conversa
sem resposta em 7 dias
Novo
Orçado
reabriu
Em conversa
Orçado
fechou
Cliente
6. Jornada do usuário
Responde: como o cliente se sente em cada etapa até fechar, e onde a experiência afunda. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: sem pesquisa por trás das notas: a jornada com humor inventado vira ficção com aparência de dado.
Seis etapas do cliente de uma clínica, com a nota de satisfação de um a cinco em cada uma. O vale é a espera sem resposta em uma hora, e é ele que justifica o robô. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma coluna por etapa, uma nota por etapa e a ação do cliente escrita embaixo. No Mermaid, o tipo journey desenha tudo a partir de uma linha por tarefa com a nota e o ator.
Receita em Mermaid:
journey
title Jornada do paciente até fechar
section Antes
Vê o post: 3: Paciente
Pergunta ao assistente: 4: Paciente
Abre o guia do segmento: 4: Paciente
section Contato
Pede orçamento: 2: Paciente
Sem resposta em 1 h: 1: Paciente
section Fechamento
Recebe a proposta: 5: Paciente, Comercial
Etapa
Ação
Nota (1 a 5)
Descobre
vê o post
3
Pesquisa
pergunta ao assistente
4
Compara
abre o guia do segmento
4
Decide
pede orçamento
2
Espera
sem resposta em 1 h
1
Fecha
recebe a proposta
5
7. Casos de uso
Responde: o que cada tipo de pessoa faz com o sistema, sem dizer ainda como o sistema faz. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: como substituto de requisitos: o desenho lista intenções, e a regra de cada uma fica fora dele.
Três atores e quatro casos de uso do portal. O time comercial lê e assiste; o dono do negócio assiste e copia o prompt; o editor publica. O retângulo é a fronteira do sistema. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um boneco por papel fora da caixa do sistema, uma elipse por ação dentro, e uma linha ligando quem faz o quê. O Mermaid não tem o tipo nativo; o flowchart com nós em elipse resolve, e o PlantUML tem o tipo pronto.
Receita em Mermaid:
flowchart LR
TC([Time comercial]) --- U1((Ler o guia do segmento))
TC --- U2((Assistir à aula))
DN([Dono do negócio]) --- U2
DN --- U3((Copiar o prompt pronto))
ED([Editor do portal]) --- U4((Publicar guia novo))
subgraph Portal Leadlovers
U1
U2
U3
U4
end
Ator
Caso de uso
Time comercial
Ler o guia do segmento
Time comercial
Assistir à aula
Dono do negócio
Assistir à aula
Dono do negócio
Copiar o prompt pronto
Editor do portal
Publicar guia novo
8. Linha do tempo
Responde: o que foi publicado e quando, em ordem, para situar quem chega no meio da história. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para prazos com duração e dependência: isso é Gantt; a linha do tempo só marca instantes.
Cinco marcos do portal, de maio a setembro, alternando acima e abaixo da linha para os rótulos não se encostarem. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um eixo, um ponto por marco e o rótulo alternando de lado. No Mermaid, o tipo timeline monta a partir de uma linha por período com os eventos separados por dois-pontos.
Receita em Mermaid:
timeline
title Publicações do portal
mai : Menu Segmentos no ar
jun : Aulas em vídeo e podcast
jul : Hub de comércio eletrônico aberto
ago : Roteiros de recepção
set : Catálogo de gráficos
Quando
Marco
mai
Menu Segmentos no ar
jun
Aulas em vídeo e podcast
jul
Hub de comércio eletrônico aberto
ago
Roteiros de recepção
set
Catálogo de gráficos
9. Cronograma (Gantt)
Responde: quanto dura cada frente do plano de 90 dias, o que já foi feito e o que depende do quê. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para plano que muda toda semana: o Gantt em texto é barato de manter, mas o desenho publicado envelhece em dias.
Cinco frentes em nove semanas: duas concluídas, uma andando e duas previstas, com a linha do hoje. O que está à esquerda do hoje sem estar concluído é atraso. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma linha por tarefa com início e duração; o Mermaid calcula as datas e desenha a barra, e a palavra-chave after encadeia a dependência sem digitar data.
Receita em Mermaid:
gantt
title Plano de 90 dias
dateFormat YYYY-MM-DD
axisFormat S%U
section Base
Fonte única de dados :done, a1, 2026-07-06, 14d
Régua de reativação :done, a2, after a1, 14d
section Atendimento
Robô que responde preço :active, b1, 2026-07-20, 21d
Segmentos no CRM : b2, after b1, 21d
section Medição
Painel de uma página : c1, after b2, 21d
Frente
Início
Fim
Situação
Fonte única de dados
S1
S2
feito
Régua de reativação
S2
S3
feito
Robô que responde preço
S3
S5
andando
Segmentos no CRM
S5
S7
previsto
Painel de uma página
S7
S9
previsto
10. Quadro Kanban
Responde: em que etapa está cada entrega do portal e onde o trabalho acumula. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Para o quadro que o time move de verdade, é ferramenta de gestão, e o desenho é só o retrato. Quando evitar: como quadro vivo publicado numa página: ele fica velho na primeira movimentação.
Quatro colunas e oito cartões do fluxo editorial do portal. A coluna com mais cartões é onde o trabalho acumula, e o número no título diz isso sem contar. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma coluna por etapa, um cartão por item, e o total de cartões no título da coluna. No Mermaid, o tipo kanban desenha a partir de colunas com itens indentados.
Receita em Mermaid:
kanban
A fazer
Guia de escolas
Aula de ilustração
FAQ do glossário
Fazendo
Catálogo de diagramas
Roteiros de recepção
Revisão
Guia de dentistas
Publicado
Catálogo de gráficos
Menu Segmentos
Coluna
Cartões
A fazer
Guia de escolas; Aula de ilustração; FAQ do glossário
Fazendo
Catálogo de diagramas; Roteiros de recepção
Revisão
Guia de dentistas
Publicado
Catálogo de gráficos; Menu Segmentos
Estrutura e arquitetura
Aqui a pergunta é o que existe e como se encaixa. O modelo C4 diz o que entra em cada nível; estes tipos mostram como cada nível se desenha. Um nível por figura, e a figura de contexto vem antes de todas.
11. C4 nível 1: contexto
Responde: o que é o sistema, quem o usa e com que sistemas externos ele conversa, numa figura que situa quem chega. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com detalhe interno do sistema: qualquer caixa de dentro pertence ao nível de contêiner.
O portal no centro, duas pessoas que o usam e dois sistemas externos com que ele conversa. É a primeira figura de qualquer documentação, porque situa sem cobrar conhecimento prévio. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa para o sistema, uma por pessoa, uma por sistema externo, e setas com verbo. O Mermaid tem a sintaxe C4Context; o Structurizr gera os quatro níveis a partir de um único modelo.
Receita em Mermaid:
C4Context
title Contexto do Portal Leadlovers
Person(comercial, "Time comercial", "Lê guias e aulas")
Person(dono, "Dono de negócio", "Copia prompts prontos")
System(portal, "Portal Leadlovers", "Guias, aulas e prompts por segmento")
System_Ext(nblm, "NotebookLM", "Gera vídeo e podcast")
System_Ext(cf, "Cloudflare", "Publica o site")
Rel(comercial, portal, "lê")
Rel(dono, portal, "copia prompts")
Rel(portal, nblm, "gera aula")
Rel(portal, cf, "publica")
Elemento
Tipo
Relação
Time comercial
pessoa
lê guias e aulas do portal
Dono de negócio
pessoa
copia prompts do portal
Portal Leadlovers
sistema
NotebookLM
externo
gera a aula para o portal
Cloudflare
externo
publica o portal
12. C4 nível 2: contêiner
Responde: de que peças o sistema é feito, o que roda separado e o que conversa com o quê. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: misturando com componente: se aparece uma classe ou um módulo, o nível já mudou.
As seis peças do portal: site estático, worker, mídia, gerador, conteúdo por slug e aulas. Cada caixa é algo que roda ou é armazenado em separado; a tecnologia vai entre colchetes. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por coisa que roda ou armazena separadamente, com a tecnologia entre colchetes, dentro da moldura do sistema. Setas com verbo curto. Se a figura passar de dez caixas, abra um sub-sistema por figura.
Receita em Mermaid:
C4Container
title Contêineres do Portal Leadlovers
System_Boundary(p, "Portal Leadlovers") {
Container(site, "Site estático", "HTML + SVG", "Páginas compiladas")
Container(worker, "Worker", "Cloudflare", "Serve e redireciona")
ContainerDb(r2, "Mídia", "R2", "Vídeo e áudio das aulas")
Container(gen, "Gerador de páginas", "Node", "Monta as páginas a partir do JSON")
ContainerDb(json, "Conteúdo", "JSON por slug", "Fonte única dos guias")
Container(aulas, "Aulas", "NotebookLM", "Vídeo e podcast")
}
Rel(worker, site, "serve")
Rel(worker, r2, "aponta")
Rel(json, gen, "lê")
Rel(gen, site, "gera")
Contêiner
Tecnologia
Relação
Site estático
HTML + SVG
gerado pelo gerador; servido pelo worker
Worker
Cloudflare
serve o site e aponta para a mídia
Mídia
R2
guarda vídeo e áudio
Gerador de páginas
Node
lê o conteúdo e gera o site
Conteúdo
JSON por slug
fonte única
Aulas
NotebookLM
transcritas para o conteúdo; enviadas à mídia
13. C4 nível 3: componentes
Responde: como um contêiner é organizado por dentro, módulo a módulo, e a ordem em que eles se chamam. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para quem não vai mexer no código: leitor de negócio para no nível de contêiner.
Seis módulos do gerador: leitor de JSON, molde, inliner de SVG, escritor, gerador do llms.txt e lint. As setas seguem a ordem de execução, e o lint valida antes do escritor. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por módulo com responsabilidade única, dentro da moldura do contêiner. Só desenhe o que existe no código; componente imaginado é dívida de documentação.
Receita em Mermaid:
C4Component
title Componentes do gerador de páginas
Container_Boundary(g, "Gerador de páginas") {
Component(leitor, "Leitor de JSON", "Node", "Carrega o conteúdo por slug")
Component(molde, "Molde de página", "Template", "Monta o HTML")
Component(svg, "Inliner de SVG", "Node", "Embute figuras e troca infinite pelo token")
Component(lint, "Lint editorial", "Node", "Reprova voz de máquina e acento faltando")
Component(llms, "Gerador de llms.txt", "Node", "Variantes v1 e v2")
Component(disco, "Escritor em disco", "Node", "Grava as páginas")
}
Rel(leitor, molde, "entrega")
Rel(molde, svg, "chama")
Rel(svg, disco, "grava")
Rel(disco, llms, "regenera")
Rel(lint, leitor, "valida antes")
Componente
Chama
Leitor de JSON
Molde de página
Molde de página
Inliner de SVG
Inliner de SVG
Escritor em disco
Escritor em disco
Gerador de llms.txt
Gerador de llms.txt
Lint editorial
Lint editorial
Leitor de JSON (valida antes)
14. Arquitetura de nuvem
Responde: em que serviço de qual provedor cada peça roda, e por onde o deploy passa. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: como substituto do contêiner C4: aqui a caixa é o serviço contratado, e a peça lógica fica no outro nível.
Dois grupos, Cloudflare e GitHub, com os serviços de cada um e o caminho do deploy: o repositório dispara o Actions, que publica no worker, que lê a mídia no R2. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um grupo por provedor, um serviço por caixa com o tipo entre parênteses e setas com o verbo. No Mermaid, a sintaxe architecture-beta traz grupos e ícones; o D2 faz o mesmo com ícones e sai mais estável.
Receita em Mermaid:
architecture-beta
group cf(cloud)[Cloudflare]
group gh(cloud)[GitHub]
service worker(server)[Worker] in cf
service r2(disk)[R2] in cf
service dns(internet)[DNS] in cf
service cache(database)[Cache] in cf
service actions(server)[Actions] in gh
service repo(database)[Repositório] in gh
worker:R --> L:r2
dns:T --> B:worker
repo:T --> B:actions
actions:L --> R:worker
Serviço
Provedor
Relação
Worker
Cloudflare
lê o R2; recebe o deploy do Actions
R2
Cloudflare
guarda a mídia
DNS
Cloudflare
aponta para o worker
Cache
Cloudflare
na frente do worker
Actions
GitHub
publica no worker
Repositório
GitHub
dispara o Actions
15. Diagrama de blocos
Responde: como os módulos de um produto se encaixam numa grade fixa, quando a posição de cada bloco importa mais que a seta. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: quando o desenho precisa de laços e decisões: a grade prende o fluxo, e o fluxograma libera.
Os módulos de uma automação numa grade de quatro colunas: captura, régua, CRM na linha de cima; robô e painel embaixo. A posição é escolhida, e a seta é secundária. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Declare o número de colunas e a ordem dos blocos, com espaços vazios onde a grade pede. É o tipo do Mermaid com controle manual de posição, útil quando o leitor já conhece a disposição física ou lógica.
Receita em Mermaid:
block-beta
columns 4
form["Formulário do site"] cap["Captura de lead"] regua["Régua de e-mail"] crm["CRM"]
space robo["Robô de WhatsApp"] painel["Painel de uma página"] space
form --> cap
cap --> regua
regua --> crm
robo --> cap
crm --> painel
Bloco
Linha, coluna
Liga a
Formulário do site
1, 1
Captura de lead
Captura de lead
1, 2
Régua de e-mail
Régua de e-mail
1, 3
CRM
CRM
1, 4
Painel de uma página
Robô de WhatsApp
2, 2
Captura de lead; CRM
Painel de uma página
2, 3
16. Topologia de rede
Responde: por onde um pedido do navegador passa até chegar ao arquivo, e onde cada domínio resolve. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para quem não opera a infra: leitor de negócio não precisa saber onde a borda termina.
O caminho do pedido: internet, borda da Cloudflare, worker, mídia no R2; a origem estática só é lida no deploy, e o DNS resolve o domínio na borda. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Um nó por equipamento ou serviço, linhas para as conexões e o nome do domínio onde ele resolve. O D2 tem ícones e formas de nuvem prontos e sai mais fiel que o flowchart do Mermaid.
Receita em D2:
internet: Internet { shape: circle }
cf: Cloudflare (borda) { shape: hexagon }
worker: Worker
r2: R2 (mídia) { shape: cylinder }
origem: Origem estática (build) { shape: page }
dns: DNS brasilgeo.ai
internet -> cf -> worker -> r2
cf -> dns: resolve
worker -> origem: lê no deploy { style.stroke-dash: 4 }
De
Para
Nota
Internet
Cloudflare (borda)
Cloudflare
Worker
Worker
R2 (mídia)
vídeo e áudio
Cloudflare
DNS
resolve brasilgeo.ai
Worker
Origem estática
lida no deploy
17. Diagrama de classes
Responde: de que dados e ações cada entidade do código é feita, e como uma referencia a outra. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: em página para leigo: a figura fala com quem escreve código, e só com essa pessoa.
Três classes do domínio: Lead, Cartão e Mensagem, com atributos acima do traço e métodos abaixo. A cardinalidade nas setas diz que um lead gera um cartão e um cartão tem muitas mensagens. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por classe, com atributos e métodos separados por um traço, e a relação escrita na seta com a cardinalidade nas pontas. Só as classes que importam para o leitor daquela figura.
Receita em Mermaid:
classDiagram
class Lead {
+String nome
+String whatsapp
+String segmento
+String origem
+responder()
+moverPara(coluna)
}
class Cartao {
+String coluna
+String dono
+Date criadoEm
+mover()
}
class Mensagem {
+String canal
+String texto
+Date enviadaEm
+registrar()
}
Lead "1" --> "1" Cartao : gera
Cartao "1" --> "*" Mensagem : tem
Classe
Atributos
Métodos
Relação
Lead
nome, whatsapp, segmento, origem
responder(), moverPara()
gera 1 Cartão
Cartao
coluna, dono, criadoEm
mover()
tem muitas Mensagens
Mensagem
canal, texto, enviadaEm
registrar()
18. Entidade-relacionamento
Responde: que tabelas existem, que chaves ligam uma à outra e qual lado é o muitos. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para modelo com mais de quinze tabelas numa figura: divida por domínio, uma figura por grupo.
Três tabelas: segmento, lead e conversa. Um segmento tem muitos leads e um lead tem muitas conversas; a chave estrangeira aponta para a chave primária, e o pé de galinha marca o lado do muitos. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por tabela com as colunas, a chave primária marcada e a relação com a cardinalidade nas pontas. O Mermaid desenha a partir das relações escritas como frases: SEGMENTO possui LEAD.
Receita em Mermaid:
erDiagram
SEGMENTO ||--o{ LEAD : possui
LEAD ||--o{ CONVERSA : inicia
SEGMENTO {
int id PK
string nome
string familia
}
LEAD {
int id PK
int segmento_id FK
string nome
string origem
}
CONVERSA {
int id PK
int lead_id FK
string canal
datetime iniciada_em
}
Tabela
Colunas
Relação
SEGMENTO
id, nome, familia
possui muitos LEAD
LEAD
id, segmento_id, nome, origem
inicia muitas CONVERSA
CONVERSA
id, lead_id, canal, iniciada_em
19. Fluxo de dados (DFD)
Responde: por onde o dado entra, que processo o transforma, em que depósito fica e para onde sai. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: quando a pergunta é a ordem no tempo: o DFD não tem sequência, tem transformação.
O lead bruto entra pelo formulário, o processo 1 valida consultando a base de duplicados, o processo 2 roteia pelas regras do segmento e o cartão sai para o CRM. Retângulo é externo, círculo é processo, linhas paralelas são depósito. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Três formas fixas: retângulo para entidade externa, círculo para processo numerado, par de linhas para depósito de dados. A seta carrega o nome do dado, e nunca um verbo. O Mermaid não tem o tipo; o flowchart com essas formas resolve.
Receita em Mermaid:
flowchart LR
F[Formulário do site] -- lead bruto --> P1((1 Validar e limpar))
P1 -- lead válido --> P2((2 Rotear por segmento))
P2 -- cartão --> CRM[CRM]
D1[(D1 Base de duplicados)]
D2[(D2 Regras por segmento)]
P1 -. consulta .-> D1
P2 -. grava .-> D2
Origem
Dado
Destino
Formulário do site
lead bruto
1 Validar e limpar
1 Validar e limpar
consulta
D1 Base de duplicados
1 Validar e limpar
lead válido
2 Rotear por segmento
2 Rotear por segmento
grava
D2 Regras por segmento
2 Rotear por segmento
cartão
CRM
20. Esteira (pipeline)
Responde: por que etapas o conteúdo passa até publicar e em qual delas o deploy parou. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para processo com bifurcação: a esteira é uma fila reta, e a decisão pede fluxograma.
As seis etapas do deploy do portal, da fonte em JSON ao deploy, com o estado de cada uma. A esteira reta diz onde parou sem que ninguém abra o log. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma seta-chevron por etapa, na ordem, com a cor pelo estado. Em Mermaid é um flowchart de esquerda para a direita com classes por estado; o desenho de chevron sai melhor em SVG à mão ou no D2.
Responde: como duas branches nasceram da master e voltaram para ela, e em que ordem os merges entraram. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para histórico com dezenas de commits: mostre só a forma dos ramos, e deixe o log para a ferramenta.
A master com duas branches de funcionalidade que nasceram em pontos diferentes e voltaram por merge. A figura explica ao time por que o llms.txt conflitou. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma linha por branch e um ponto por commit, com os merges como pontos de volta. O Mermaid tem o tipo gitGraph que desenha a partir dos comandos commit, branch, checkout e merge.
Quando a informação tem pai e filho, o desenho é uma árvore, e a árvore se lê de cima para baixo ou do centro para fora. Todos estes tipos são texto compilado; o que muda é a direção e o que cada nível significa.
22. Organograma
Responde: quem responde a quem, e onde o robô de atendimento entra na estrutura. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com mais de quatro níveis: o desenho sai da tela; abra um organograma por diretoria.
Direção no topo, três áreas e cinco times. O robô aparece como time do atendimento, com dono humano acima dele, que é a regra do guia de dentistas. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por cargo ou time, ligada ao superior por linha sem seta, de cima para baixo. No Mermaid é um flowchart TD com traços simples; o D2 respeita melhor a simetria dos níveis.
Receita em Mermaid:
flowchart TD
D[Direção] --- M[Marketing]
D --- C[Comercial]
D --- A[Atendimento]
M --- M1[Conteúdo]
M --- M2[Mídia paga]
C --- C1[Pré-venda]
A --- A1[Recepção]
A --- A2[Robô]
Time
Responde a
Marketing
Direção
Comercial
Direção
Atendimento
Direção
Conteúdo
Marketing
Mídia paga
Marketing
Pré-venda
Comercial
Recepção
Atendimento
Robô
Atendimento
23. Árvore de decisão
Responde: que resposta o robô dá para cada combinação de perguntas do lead, sem laço e sem volta. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com mais de três níveis de pergunta: a árvore dobra a cada nível e vira tabela de regras.
Duas perguntas encadeadas e quatro respostas do robô: preço com ou sem CNPJ, horário com agenda ou repasse para a recepção. Cada folha é uma resposta e cada caminho é uma regra. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Losango por pergunta, folhas por resposta, e as respostas escritas nas setas. Leia cada caminho da raiz à folha como uma frase; se alguma folha estiver vazia, falta regra.
Receita em Mermaid:
flowchart LR
Q1{Lead pediu preço?}
Q1 -- sim --> Q2{Tem CNPJ?}
Q2 -- sim --> R1[Robô responde a faixa]
Q2 -- não --> R2[Pede o CNPJ primeiro]
Q1 -- não --> Q3{Perguntou horário?}
Q3 -- sim --> R3[Envia a agenda do dia]
Q3 -- não --> R4[Passa para a recepção]
Pediu preço?
Tem CNPJ?
Perguntou horário?
Resposta
sim
sim
Robô responde a faixa
sim
não
Pede o CNPJ primeiro
não
sim
Envia a agenda do dia
não
não
Passa para a recepção
24. Mapa mental
Responde: de que assuntos um guia é feito antes de virar texto, com o tema no centro e os ramos ao redor. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: como entrega final: o mapa mental é ferramenta de rascunho, e o leitor precisa do texto ordenado.
O guia de dentistas no centro e os quatro ramos que viraram seções: perfis de paciente, primeiro contato, objeções e cadências, cada um com as folhas que viraram subtítulos. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Tema no centro, um ramo por assunto, folhas por subassunto, e nada de setas. O Mermaid desenha a partir da indentação; a ordem dos ramos é a do texto.
Receita em Mermaid:
mindmap
root((Guia de dentistas))
Perfis de paciente
Urgência
Estética
Plano
Primeiro contato
WhatsApp
Instagram
Objeções
Preço
Medo
Tempo
Cadências
24 h
7 dias
30 dias
Ramo
Folhas
Perfis de paciente
Urgência, Estética, Plano
Primeiro contato
WhatsApp, Instagram
Objeções
Preço, Medo, Tempo
Cadências
24 h, 7 dias, 30 dias
25. Mapa do site
Responde: como as páginas se organizam em ramos e quantas existem em cada um, antes de mexer no menu. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: listando todas as páginas: acima de trinta folhas, mostre a contagem por ramo e link para a lista.
A raiz do portal e cinco ramos: segmentos, design, artigos, playlist e glossário, com a contagem de páginas em cada um. É o desenho que precede qualquer discussão de menu. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Raiz no topo, um nó por diretório, folhas de exemplo e a contagem no lugar da lista completa. No Mermaid é um flowchart TD; o sitemap.xml pode gerar o código por script, para a figura nunca ficar velha.
Receita em Mermaid:
flowchart TD
R[/leadlovers2026/] --- S[segmentos/ 26]
R --- D[design/ 6]
R --- A[artigos/ 30]
R --- P[playlist/ 109]
R --- G[glossario/ 276 termos]
S --- S1[dentistas/]
S --- S2[restaurantes/]
D --- D1[graficos/]
D --- D2[diagramas/]
Ramo
Páginas
Exemplos
segmentos/
26
dentistas/, restaurantes/
design/
6
graficos/, diagramas/
artigos/
30
playlist/
109
glossario/
1 (276 termos)
26. Árvore de cinco causas
Responde: qual é a causa raiz por trás de um sintoma, perguntando por quê cinco vezes até chegar numa decisão. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: quando cada por quê tem mais de uma resposta: aí é espinha de peixe, com as causas em paralelo.
Do sintoma (lead sem resposta em uma hora) até a causa raiz (o dono decide preço caso a caso), em cinco por quês. O último degrau é uma decisão, e é ela que o plano ataca. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma caixa por resposta, em degrau, com a pergunta escrita na seta. Pare quando a resposta for uma decisão que alguém pode tomar; se for a natureza humana, voltou um degrau demais.
Receita em Mermaid:
flowchart TD
E[Leads sem resposta em 1 h] -- por quê? --> C1[Recepção ocupada no balcão]
C1 -- por quê? --> C2[Só uma pessoa atende o WhatsApp]
C2 -- por quê? --> C3[Ninguém sabe a faixa de preço]
C3 -- por quê? --> C4[Tabela de preço não existe por escrito]
C4 -- por quê? --> C5[Dono decide preço caso a caso]
style E fill:#F7EED9,stroke:#8A6516
style C5 fill:#1E2365,color:#fff
Nível
Resposta
0
Leads sem resposta em 1 h
1
Recepção ocupada no balcão
2
Só uma pessoa atende o WhatsApp
3
Ninguém sabe a faixa de preço
4
Tabela de preço não existe por escrito
5
Dono decide preço caso a caso
27. Espinha de peixe (Ishikawa)
Responde: que famílias de causa concorrem para um mesmo problema, com as causas em paralelo e agrupadas. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: sem priorização depois: a espinha lista tudo, e o Pareto do guia de gráficos diz o que atacar primeiro.
O carrinho abandonado na cabeça do peixe e seis famílias de causa nas espinhas: preço, página, pessoas, processo, produto e promessa, com duas causas em cada uma. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma seta central até o problema, uma espinha por família de causa e as causas como traços em cada espinha. Não há tipo nativo no Mermaid; um flowchart RL com subgraphs por família dá a mesma leitura, e o desenho clássico sai em SVG à mão.
Receita em Mermaid:
flowchart RL
P[Carrinho abandonado]
subgraph Preço
p1[frete alto] --- p2[sem Pix]
end
subgraph Página
g1[erro no checkout] --- g2[lenta no celular]
end
subgraph Pessoas
s1[sem chat] --- s2[sem retorno]
end
Preço --> P
Página --> P
Pessoas --> P
Família
Causas
Preço
frete alto, sem Pix
Página
erro no checkout, lenta no celular
Pessoas
sem chat, sem retorno
Processo
cadastro longo, prazo incerto
Produto
sem foto, sem medida
Promessa
prazo mudou, cupom falhou
28. Ciclo
Responde: que etapas se repetem sem fim, e em que ordem, quando o processo não tem saída e sim retorno. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: quando o processo termina: laço desenhado onde há fim engana o leitor sobre o que acontece depois.
As quatro fases do ciclo de experimentação do portal: planejar, fazer, checar e agir, num laço de 90 dias. A seta que volta é o que distingue o ciclo da esteira. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Quatro arcos com seta, uma fase por arco e o nome do ciclo no centro. O Mermaid desenha o laço como flowchart com uma seta de volta; o círculo de verdade sai em SVG à mão.
Receita em Mermaid:
flowchart LR
P[Planejar: meta e hipótese] --> F[Fazer: rodar o teste]
F --> C[Checar: ler o painel]
C --> A[Agir: manter ou reverter]
A --> P
Fase
O que acontece
Segue para
Planejar
meta e hipótese
Fazer
Fazer
rodar o teste
Checar
Checar
ler o painel
Agir
Agir
manter ou reverter
Planejar
29. Pirâmide de níveis
Responde: em que degrau uma operação está numa escada de maturidade, e o que o degrau seguinte pede. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para mostrar proporção: a área de cada faixa é geometria, e o leitor a lê como quantidade.
A escada de maturidade do glossário em cinco faixas, do nível zero (sem cadastro de lead) ao dez (IA roteia e responde com dono humano). Cada faixa diz o que caracteriza o degrau. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Faixas trapezoidais empilhadas, com o nível mais alto no topo e o nome mais a descrição em cada faixa. Não é gráfico: a largura não codifica nada, e a legenda deve dizer isso.
Aqui os elementos se definem uns pelos outros: em que quadrante caem, o que compartilham, quem liga com quem. Os três últimos tipos são a família dos grafos, em que a máquina calcula a posição e o agrupamento que aparece é a resposta.
30. Matriz 2×2 (quadrantes)
Responde: o que fazer primeiro: cada iniciativa posicionada por impacto e esforço, com o quadrante certo destacado. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com notas inventadas na hora: a posição parece medida, e a discussão vira sobre o ponto e não sobre a iniciativa.
Seis iniciativas do plano de 90 dias por impacto e esforço. As duas do quadrante de alto impacto e baixo esforço, em destaque, são as primeiras da fila. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Dois eixos, quatro quadrantes com nome e um ponto por item com coordenadas de zero a um. O Mermaid tem o tipo quadrantChart que desenha a partir das coordenadas.
Receita em Mermaid:
quadrantChart
title Impacto por esforço
x-axis Baixo esforço --> Alto esforço
y-axis Baixo impacto --> Alto impacto
quadrant-1 Planejar com calma
quadrant-2 Fazer primeiro
quadrant-3 Deixar para depois
quadrant-4 Evitar
Robô responde preço: [0.18, 0.82]
Régua de reativação: [0.32, 0.72]
CRM por segmento: [0.72, 0.86]
Painel de uma página: [0.84, 0.76]
Assinatura de e-mail: [0.14, 0.28]
Reforma do site: [0.88, 0.22]
Iniciativa
Esforço
Impacto
Quadrante
Robô responde preço
baixo
alto
fazer primeiro
Régua de reativação
baixo
alto
fazer primeiro
CRM por segmento
alto
alto
planejar
Painel de uma página
alto
alto
planejar
Assinatura de e-mail
baixo
baixo
depois
Reforma do site
alto
baixo
evitar
31. Diagrama de Venn
Responde: o que dois conjuntos têm em comum: quais assistentes citam o portal, quais citam a marca e quais citam os dois. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: com mais de três conjuntos ou para mostrar quantidade: a área do círculo não é proporcional e o leitor a lê como se fosse.
Dois conjuntos: assistentes que citam o portal e assistentes que citam a marca. O Perplexity está na interseção, e o Copilot fora dos dois círculos. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Dois ou três círculos sobrepostos com transparência, o nome de cada conjunto fora e os elementos dentro da região certa. Não há tipo no Mermaid; o desenho é SVG à mão com três círculos no máximo.
Responde: em que canal o cliente está em cada etapa, e onde não há ninguém para atendê-lo. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: sem pesquisa com clientes: a grade preenchida por palpite parece dado.
Cinco etapas nas colunas, cinco canais nas linhas e uma marca onde o canal participa da etapa. A coluna de decidir tem dois canais; a de voltar tem um só, o e-mail. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Uma tabela HTML com a etapa na coluna e o canal na linha é a versão mais acessível; o SVG entra quando a figura precisa ir para slide ou PDF com o mesmo visual.
Responde: o que está no centro do território do portal, o que é adjacente e o que fica de fora, num único olhar. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Quando evitar: para hierarquia com pai e filho: círculo dentro de círculo sugere pertencimento, e o organograma diz mais.
O raio semântico do glossário em três anéis: núcleo (automação de marketing), adjacente (CRM, atendimento, medição) e vizinhança (tráfego, redes, e-mail). O que está fora, fica fora do portal. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Três círculos com o mesmo centro e raios crescentes, o núcleo mais escuro e o anel externo mais claro, com o nome de cada anel. SVG à mão; não há tipo pronto que valha o esforço.
Responde: quem cita quem no ecossistema, e que grupos se formam sozinhos quando a simulação acomoda os nós. Família: grafo calculado por simulação (Cytoscape.js, Sigma.js); a informação é a própria rede. Quando evitar: com menos de vinte nós: o grafo de força é exagero; um flowchart escrito à mão lê melhor.
Dez marcas ligadas por citações mútuas. O tamanho do nó é o número de citações recebidas, e a posição foi calculada por simulação: os dois grupos que aparecem são a aliança e o bloco concorrente. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Nós e arestas em JSON, layout por força calculado pela biblioteca, tamanho do nó por grau. O Cytoscape.js entrega isso com o layout cose; para milhares de nós, o Sigma.js com Graphology em WebGL.
Responde: que páginas apontam para o guia e para onde ele aponta de volta, no desenho da arquitetura hub-satélite do glossário. Família: texto compilado no build (Mermaid, D2 ou Graphviz); quem monta é quem escreve. Acima de cem páginas, muda para a família dos grafos. Quando evitar: para o site inteiro: o desenho é por hub, uma figura por tema.
O guia de dentistas como hub e seis satélites em mão dupla: dois artigos, a aula, um termo do glossário, o guia vizinho e um episódio da playlist. Link só de ida é seta só de ida, e aparece. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Hub no centro, satélites ao redor e uma seta por link, com a mão dupla desenhada como duas setas. O código pode ser gerado a partir do rastreio dos links da página, e a figura fica sempre atual.
Receita em Mermaid:
flowchart TB
H((Guia de dentistas))
A1[Artigo: robô responde preço] <--> H
A2[Artigo: CRM move o cartão] <--> H
V[Aula em vídeo] <--> H
G[Glossário: dono da métrica] <--> H
C[Guia de clínicas] <--> H
P[Playlist: episódio 41] <--> H
Página
Aponta para o hub
Hub aponta de volta
Artigo: robô responde preço
sim
sim
Aula em vídeo
sim
sim
Glossário: dono da métrica
sim
sim
Artigo: CRM move o cartão
sim
sim
Guia de clínicas
sim
sim
Playlist: episódio 41
sim
sim
36. Esboço de tela (wireframe)
Responde: onde cada bloco fica na página antes de qualquer cor ou texto final, para discutir estrutura sem discutir estilo. Família: quadro branco (Excalidraw ou tldraw) quando o time desenha junto; SVG à mão quando vai para o guia. Quando evitar: com cor e texto final: o esboço bonito trava a conversa no estilo, que é a última decisão.
A página de guia em baixa fidelidade: cabeçalho, hero com título e cápsula, vídeo da aula ao lado das ações, rodapé. O X no retângulo é a convenção para imagem ou vídeo. Exemplo hipotético, montado para mostrar o formato.Como construir e os elementos da figura
Retângulos cinza, um X onde vai mídia, texto de rótulo em vez de texto final e nenhuma cor além de um destaque para a ação principal. No Excalidraw, o time desenha ao vivo e exporta SVG; no guia, o SVG à mão com meia dúzia de retângulos basta.
Regra da casa: escolha o grupo pela pergunta e o tipo pela forma mais simples que a responde; se dois tipos empatam, vence o que cabe em menos caixas. Uma figura responde a uma pergunta só, e o C4 manda um nível por figura. E todo diagrama publicado sai com o título, a descrição e a lista de elementos por perto, porque é isso que o leitor de tela lê e o revisor confere.
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.
Fluxograma
Sequência
Gantt
Arquitetura
architecture-beta
beta
Blocos
block
Pacote de rede
packet
Kanban
kanban
Radar
radar-beta
beta
Treemap
treemap-beta
beta
Barras e linhas
xychart
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 assíncrona mermaid.parse(), que valida a definição sem renderizar. Aguarde sua conclusão com await e trate o erro de sintaxe. Essa validação não sanitiza conteúdo nem autoriza interações. Para definições recebidas de fora, mantenha securityLevel: "strict", que codifica HTML e desabilita cliques; avalie "sandbox" quando precisar de isolamento em iframe.
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.
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 documentação atual informa Mermaid 11. Confira o tipo de diagrama e a versão da instância antes de padronizar o uso
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. 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:
Build de verdade: o rehype-mermaid renderiza 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:
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.
Texto perto de 2:1
reprovado
Texto forte, 4,5:1
aprovado
Linha abaixo de 3:1
reprovada
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.
Todo <text> do SVG com fill explí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.
accTitle e accDescr em cada figura: nome e descrição acessíveis sem custo.
Contraste conferido nos dois temas: 4,5:1 no texto, 3:1 nas partes gráficas necessárias à compreensão (WCAG 2.2).
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.
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. Aguarde mermaid.parse() antes de renderizar e trate sua rejeição; a API retorna uma Promise. 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 uma ligação no sistema. Renderize o código aprovado com a configuração de segurança definida e confira rótulos, contraste e cortes nos dois temas.
Quando o caso sai do texto: editores e grafos em 2026
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.
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)
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
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.
A colaboração em tempo real existe no aplicativo Excalidraw, mas não vem implementada no componente npm. A FAQ oficial explica que a aplicação hospedeira usa as APIs expostas para construir essa integração. Sincronização, persistência e autorização precisam entrar no escopo do produto; inserir um botão de colaboração não entrega essas funções.
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.
Editar um fluxo que sabe recusar uma conexão
O desenho parece correto até alguém importar uma conexão para uma etapa que não existe. Este editor conserva o trabalho atual quando o arquivo é inválido e explica a recusa. Você pode renomear os nós, remover relações, criar outras e exportar o resultado. Todas as ações funcionam por formulário e teclado, sem depender de arraste.
O cenário é autoral e didático: um material passa por rascunho, revisão, aprovação e publicação simulada. Escolhemos um processo acíclico para esta oficina: a saída encerra o percurso e a entrada não recebe conexões. Outros fluxos podem incluir retornos explícitos. O editor é JavaScript nativo, executado localmente; não carrega React Flow nem publica conteúdo em qualquer serviço.
Cenário
Quem
Marina, coordenadora de conteúdo do portal de cursos, e dois revisores que trabalham em dias alternados.
Tarefa
Desenhar o fluxo de aprovação das apostilas (rascunho, revisão, aprovação, publicação) e trocar o arquivo do fluxo entre as três pessoas por e-mail.
Falha vista
Um revisor colou um arquivo com uma conexão para a etapa "Jurídico", que ninguém tinha criado, e o editor antigo apagou o desenho inteiro ao tentar carregar. Na semana seguinte, outro ligou Aprovação de volta a Revisão e o validador de percurso ficou rodando sem fim.
Resultado esperado
Um editor que recusa cada conexão inválida com motivo escrito, mantém o desenho aberto quando o arquivo recebido falha e exporta um documento com número de versão que a importação sabe conferir.
O coração da oficina é uma função pequena que recebe o grafo atual e a conexão pedida e devolve o motivo da recusa ou uma string vazia. Os testes correm numa ordem fixa, do mais barato ao mais caro: existência dos dois nós, origem diferente do destino, tipos permitidos (a publicação encerra, o rascunho só começa), duplicata e, por último, a busca em profundidade (percurso que segue cada saída até o fim antes de voltar) para descobrir se o destino já alcança a origem. Quando alcança, a nova conexão fecharia um ciclo.
Mapa da oficina. O pedido de conexão atravessa a cadeia de testes à direita antes de tocar o grafo à esquerda; o caminho tracejado é a volta de Aprovação para Revisão, recusada por fechar ciclo.
A pessoa escolhe Aprovação como origem e Revisão como destino nos dois selects e envia o formulário. O grafo atual tem quatro nós em linha.
Os testes baratos correm primeiro: os dois nós existem, são diferentes, a origem não é a publicação, o destino não é o rascunho e a conexão ainda não está na lista.
A busca em profundidade parte do destino (Revisão) e segue as saídas: Revisão leva a Aprovação, que é a origem do pedido.
Como o destino já alcança a origem, a conexão fecharia um ciclo. O editor escreve o motivo na área de status e deixa o grafo como estava.
Se a busca terminasse sem encontrar a origem, a conexão entraria na lista e a figura, os selects e as relações seriam redesenhados a partir do estado.
Exportar serializa o estado com schemaVersion 1 e dispara o download por Blob (objeto de arquivo em memória) e URL temporária.
Importar valida o texto inteiro, nó por nó e conexão por conexão, com a mesma função de recusa; só depois substitui o estado. Qualquer erro deixa o desenho aberto intacto.
Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.
Demonstrar no editor
Observe três lugares enquanto age: a área de status logo abaixo deste parágrafo, que recebe cada motivo de recusa em texto; a lista de relações, que só muda quando a conexão passa; e o foco do teclado, que volta ao campo útil depois de cada ação (o rótulo após renomear, o select de origem após remover). O status tem role="status", então o leitor de tela anuncia o motivo sem mover o cursor.
O validador de percurso é um segundo mecanismo, separado do teste de conexão. Ele parte do rascunho, marca os nós alcançados e compara com a lista completa; depois procura nós sem saída que não sejam a publicação. Uma conexão válida pode deixar o processo incompleto, e é esse o caso que a terceira etapa do roteiro reproduz.
Dados de exercício. O exemplo inicial tem quatro nós com identificadores fixos e três conexões. Use os pedidos da tabela para provocar cada resposta do editor.
Pedidos de conexão e resposta esperada
Origem
Destino
Resposta
Aprovação
Revisão
Recusada: criaria um ciclo
Rascunho
Revisão
Recusada: já existe
Revisão
Revisão
Recusada: nó aponta para si mesmo
Publicação simulada
Rascunho
Recusada: tipos de saída e entrada
Rascunho
Aprovação
Aceita: atalho válido, percurso continua completo
Selecione um nó para renomeá-lo ou escolha origem e destino. O JavaScript precisa estar ativo para editar.
Rascunho
Revisão
Aprovação
Publicação simulada
Relações do documento
Rascunho para Revisão
Revisão para Aprovação
Aprovação para Publicação simulada
Restaurar um JSON ou testar um arquivo inválido
A importação aceita os quatro identificadores e tipos deste exercício. Campos desconhecidos não são incorporados. O limite local de 16.000 caracteres contém o tamanho do exercício; não é limite técnico do formato JSON.
Uma conexão válida ainda pode compor um processo incompleto
Remova Revisão para Aprovação e valide. A interface deve identificar o trecho sem saída e os nós que ficaram inalcançáveis. Reponha a ligação.
Escolha Aprovação como origem e Revisão como destino. A relação fecharia um ciclo e deve ser recusada. Tente também repetir uma conexão existente e ligar um nó a si mesmo.
Renomeie Revisão para Revisão editorial, baixe o JSON e guarde o texto. Prepare o arquivo inválido, tente restaurar e confirme que o desenho anterior permanece. Cole o JSON válido para recuperar o rótulo.
A validação acontece antes de substituir o estado. Isso permite corrigir um documento recebido sem perder o desenho aberto. O teste de conexão verifica uma ligação; a verificação de percurso examina o conjunto. Nenhuma das duas confirma se as regras de aprovação representam o trabalho da equipe. A revisão do significado continua necessária, mesmo quando o JSON passa.
Investigar as falhas
Cada linha abaixo reproduz um defeito que aparece em editores de fluxo feitos às pressas, inclusive nos gerados por agente de IA. A coluna de confirmação descreve o que fazer no navegador para ver o sintoma com os próprios olhos antes de corrigir.
Falhas que esta oficina reproduz
Sintoma
Causa provável
Como confirmar
Correção
O desenho some ao colar um arquivo com erro
O estado foi substituído pelo JSON recebido antes de qualquer validação; o erro aparece só na hora de desenhar.
Acione "Preparar arquivo inválido" e depois "Restaurar JSON". Aqui o status explica a recusa e a lista de relações continua igual. Num editor com a falha, a lista fica vazia ou o console mostra um erro de propriedade indefinida.
Validar num objeto limpo e só atribuir ao estado quando a função devolver sem lançar erro (bloco documento-fluxo.js).
Validar percurso trava a aba ou estoura a pilha
A busca não guarda os nós já visitados e um ciclo faz a recursão voltar ao mesmo nó para sempre.
Abra o console (F12) e, num editor sem a proteção, crie um retorno entre dois nós e valide: aparece RangeError: Maximum call stack size exceeded. Aqui o ciclo nem chega a entrar.
Conjunto vistos na busca em profundidade e recusa do ciclo na hora de conectar; a validação de percurso usa o mesmo conjunto.
A mesma conexão aparece duas vezes na lista
O teste de duplicata compara objetos por referência, ou a importação não passou pela função de recusa.
Tente adicionar Rascunho para Revisão de novo. O status deve dizer que já existe. Em seguida cole um JSON com a conexão repetida e restaure: a importação também recusa.
Comparar origem e destino como strings, na criação e na importação, pela mesma função.
Depois de renomear, as relações mostram o nome antigo
A lista de relações foi escrita com o rótulo copiado no momento da conexão, e não com o identificador.
Renomeie Revisão para Revisão editorial. As três listas (nós, selects e relações) precisam mudar juntas, porque render() lê sempre o grafo.
Guardar só identificadores nas conexões e resolver o rótulo na hora de desenhar.
Quem usa teclado perde o lugar após remover uma conexão
O botão removido era o elemento focado; ao sumir, o foco cai no body.
Com Tab, chegue a "Remover conexão" e pressione Enter. O foco deve ir para o select de origem; com leitor de tela, ouve-se o status "Conexão removida".
Chamar focus() num controle estável depois de redesenhar e anunciar pelo role="status".
Um arquivo de outra versão entra sem aviso
O documento exportado não carrega número de versão, então a importação aceita qualquer formato parecido.
No textarea, troque "schemaVersion": 1 por 2 e restaure. O status deve recusar por versão não reconhecida.
Gravar schemaVersion na exportação e conferir na importação; migrar versões antigas de propósito, com função própria.
Código de referência
Os dois primeiros blocos são a versão do editor desta página escrita como módulos reaproveitáveis: a função de recusa com a busca em profundidade e o documento versionado com exportação e importação. O terceiro adapta o contrato para React Flow, biblioteca de grafos para React cujo isValidConnection aceita a mesma função.
// Regras que uma conexão precisa passar antes de entrar no grafo.
// Devolve uma string vazia quando a conexão é válida, ou o motivo da recusa.
export function motivoDaRecusa(grafo, conexao) {
const origem = grafo.nodes.find((n) => n.id === conexao.source);
const destino = grafo.nodes.find((n) => n.id === conexao.target);
if (!origem || !destino) return "A conexão aponta para um nó ausente.";
if (origem.id === destino.id) return "Um nó não pode apontar para si mesmo.";
if (origem.type === "end" || destino.type === "start") {
return "A publicação encerra o processo e o rascunho é a entrada.";
}
const repetida = grafo.edges.some(
(e) => e.source === conexao.source && e.target === conexao.target
);
if (repetida) return "Esta conexão já existe.";
// Se o destino já alcança a origem, a nova aresta fecharia um ciclo.
if (alcanca(grafo, destino.id, origem.id)) {
return "Esta conexão criaria um ciclo; o processo é acíclico.";
}
return "";
}
// Busca em profundidade: partindo de `de`, algum caminho chega a `ate`?
// O conjunto `vistos` impede revisitar nós e garante que a busca termina
// mesmo num grafo que já tivesse um ciclo por outro motivo.
export function alcanca(grafo, de, ate, vistos = new Set()) {
if (de === ate) return true;
if (vistos.has(de)) return false;
vistos.add(de);
return grafo.edges
.filter((e) => e.source === de)
.some((e) => alcanca(grafo, e.target, ate, vistos));
}
// Percurso completo: todos os nós alcançáveis a partir da entrada e
// nenhum nó sem saída além do final.
export function percursoIncompleto(grafo, entrada = "inicio", saida = "fim") {
const vistos = new Set();
const visitar = (id) => {
if (vistos.has(id)) return;
vistos.add(id);
grafo.edges.filter((e) => e.source === id).forEach((e) => visitar(e.target));
};
visitar(entrada);
const inalcancaveis = grafo.nodes.filter((n) => !vistos.has(n.id));
const semSaida = grafo.nodes.filter(
(n) => n.id !== saida && !grafo.edges.some((e) => e.source === n.id)
);
return { inalcancaveis, semSaida };
}
import { motivoDaRecusa } from "./validar-conexao.js";
// Documento versionado: o número permite recusar formatos desconhecidos
// e migrar formatos antigos de propósito, com função própria.
const VERSAO = 1;
const LIMITE = 16000; // caracteres aceitos no campo de importação
export function exportar(grafo) {
const texto = JSON.stringify({ schemaVersion: VERSAO, ...grafo }, null, 2);
const url = URL.createObjectURL(
new Blob([texto], { type: "application/json;charset=utf-8" })
);
const a = Object.assign(document.createElement("a"), {
href: url, download: `fluxo-v${VERSAO}.json`
});
document.body.append(a); a.click(); a.remove();
setTimeout(() => URL.revokeObjectURL(url), 1000);
return texto;
}
// Valida um texto recebido e devolve um grafo limpo. Lança erro com motivo
// legível; quem chama só troca o estado depois que a função devolve.
export function importar(texto, modelo) {
if (texto.length > LIMITE) throw new Error("Arquivo maior que o limite.");
const bruto = JSON.parse(texto); // SyntaxError sobe para quem chama
if (!bruto || bruto.schemaVersion !== VERSAO) {
throw new Error("Versão não reconhecida. Use schemaVersion 1.");
}
if (!Array.isArray(bruto.nodes) || !Array.isArray(bruto.edges)) {
throw new Error("Faltam nós ou conexões.");
}
const limpo = { nodes: [], edges: [] };
for (const esperado of modelo.nodes) {
const achados = bruto.nodes.filter((n) => n && n.id === esperado.id);
const rotulo = achados.length === 1 ? String(achados[0].label || "").trim() : "";
if (!rotulo || rotulo.length > 60 || achados[0].type !== esperado.type) {
throw new Error(`Nó ${esperado.id} inválido.`);
}
// Campos desconhecidos ficam de fora: só entra o que o modelo conhece.
limpo.nodes.push({ ...esperado, label: rotulo });
}
for (const c of bruto.edges) {
if (!c || typeof c.source !== "string" || typeof c.target !== "string") {
throw new Error("Conexão sem origem ou destino válido.");
}
const motivo = motivoDaRecusa(limpo, c); // a mesma regra da criação
if (motivo) throw new Error(motivo);
limpo.edges.push({ source: c.source, target: c.target });
}
return limpo;
}
// Uso: try { grafo = importar(campo.value, modelo); desenhar(); }
// catch (e) { status.textContent = `Importação recusada; desenho preservado. ${e.message}`; }
Para implementar esse contrato em outro projeto React, adapte o fragmento abaixo. Instale a versão escolhida de @xyflow/react, registre-a no lockfile e prepare um contêiner com altura definida. Os nós padrão já têm pontos de conexão; em nós personalizados, declare Handle, papéis, rótulos e instruções. Use a mesma validação na importação e na criação de arestas.
import { useCallback, useState } from "react";
import { ReactFlow, getOutgoers, addEdge, applyNodeChanges, applyEdgeChanges } from "@xyflow/react";
import "@xyflow/react/dist/style.css";
// A mesma busca em profundidade da oficina, com os utilitários do React Flow.
function conexaoValida(conexao, nodes, edges) {
if (conexao.source === conexao.target) return false;
const destino = nodes.find((n) => n.id === conexao.target);
if (!destino) return false;
const vistos = new Set();
const alcancaOrigem = (no) => {
if (no.id === conexao.source) return true;
if (vistos.has(no.id)) return false;
vistos.add(no.id);
return getOutgoers(no, nodes, edges).some(alcancaOrigem);
};
return !alcancaOrigem(destino);
}
export function FluxoAprovacao({ inicial }) {
const [nodes, setNodes] = useState(inicial.nodes);
const [edges, setEdges] = useState(inicial.edges);
const onConnect = useCallback(
(conexao) => setEdges((atuais) => addEdge(conexao, atuais)),
[]
);
return (
<div style={{ height: 480 }}>
<ReactFlow
nodes={nodes}
edges={edges}
onNodesChange={(mud) => setNodes((n) => applyNodeChanges(mud, n))}
onEdgesChange={(mud) => setEdges((e) => applyEdgeChanges(mud, e))}
onConnect={onConnect}
isValidConnection={(c) => conexaoValida(c, nodes, edges)}
onInit={(instancia) => {
// toObject() inclui viewport; grave { schemaVersion: 1, flow: ... }
// e valide esse documento antes de setNodes, setEdges e setViewport.
window.__fluxo = instancia;
}}
fitView
/>
</div>
);
}
O fragmento mostra a recusa de ciclos; o starter do seu produto ainda precisa das regras de tipos, salvamento e tratamento de erro. O JSON nativo desta oficina não inclui viewport porque o editor não tem câmera nem zoom. Não o entregue diretamente ao React Flow sem conversão. Baixar o editor nativo executado nesta página.
Critérios de aceite
Levar para o projeto
Em React ou Next, mantenha motivoDaRecusa fora dos componentes e use-a tanto em isValidConnection quanto na importação; em Astro ou HTML puro, o editor desta página já serve como está, com os ids trocados pelos seus. Em produção, meça a proporção de importações recusadas por motivo (versão, nó ausente, ciclo) e o tempo até a primeira conexão válida de quem chega pela primeira vez; os dois números dizem se o documento exportado está claro para quem o recebe.
Levar o diagrama para fora da página sem perder os rótulos
Você baixa uma figura que estava legível no portal e encontra texto claro sobre fundo branco. A exportação levou a geometria, mas deixou a paleta na folha de estilo original. Esta oficina grava cor, fundo e rótulos no SVG; a mesma figura aparece inline e como imagem externa criada localmente, e pode ser aberta fora do site.
O processo autoral de demonstração tem três etapas: receber um rascunho, revisar e liberar a versão aprovada. A tabela da demonstração explicita as relações. O seletor muda a paleta do arquivo, independentemente do tema do portal, para você comparar o destino claro e o escuro.
Cenário
Quem
Paulo, analista de marketing que mantém o catálogo de materiais do portal e monta o e-mail mensal da equipe de vendas.
Tarefa
Reaproveitar o diagrama "Do rascunho à versão aprovada", que está perfeito na página do catálogo, em três destinos: o corpo do e-mail (como imagem), o slide da reunião (arquivo anexado) e a própria página (inline).
Falha vista
No e-mail, as caixas apareceram sem texto: a cor do rótulo vinha de var(--text), que só existe no CSS do portal, e o cliente de e-mail pintou tudo de preto sobre fundo escuro. No slide, a fonte trocou para uma serifada e dois rótulos saíram da caixa.
Resultado esperado
Um único arquivo SVG que carrega fundo, cores, fonte nomeada, título e descrição, e que se lê igual nos três destinos, com uma versão para fundo claro e outra para fundo escuro.
O mecanismo é simples de enunciar e fácil de esquecer: um SVG inline faz parte do documento, então herda variáveis CSS, fonte, cor do texto e fundo da página, e seu <title> é lido pelo leitor de tela. O mesmo código servido como <img> vira um documento isolado: as variáveis da página não chegam, a fonte só existe se for nomeada dentro do arquivo, o fundo fica transparente e o leitor de tela lê o alt, nunca o <title>. O arquivo baixado perde ainda o contexto do navegador: a fonte passa a ser a do sistema de quem abre.
Mapa da oficina. O mesmo SVG chega a três destinos; o que cada um perde está anotado na caixa, e a coluna da direita mostra o que a oficina grava no arquivo para nada se perder.
Inline, o SVG é parte do documento: recebe as variáveis CSS, a fonte do corpo, a cor do texto e o fundo da página, e o leitor de tela lê o title pelo aria-labelledby.
O mesmo código servido como img vira um documento separado: var() da página não existe lá, a fonte só aparece se estiver nomeada no arquivo, o fundo fica transparente e o leitor de tela lê o atributo alt.
O arquivo baixado leva só o que está escrito no XML; quem abre no visualizador do sistema vê a fonte padrão da máquina.
A função render() da oficina escreve fundo, preenchimento e traço como atributos de cada elemento, segundo a paleta escolhida, e nomeia a família da fonte nos textos.
Uma cópia sem id e sem class é serializada por XMLSerializer; o texto vira URL data: para a imagem e Blob com URL temporária para o download, revogada logo depois.
A conferência acontece no destino real: alt na imagem, contraste medido sobre o fundo de verdade e o arquivo aberto fora do site.
Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.
Demonstrar a exportação
Troque a paleta no seletor e observe as duas figuras lado a lado: a inline recebe os atributos novos no DOM, e a imagem externa é recriada a partir da serialização. Como as cores estão gravadas em cada elemento, as duas ficam idênticas; é a prova de que o arquivo já carrega o que precisa. Depois baixe o SVG e abra no navegador ou no visualizador do sistema.
Na aba Elementos do DevTools (F12), selecione o <img> e leia o atributo src: começa com data:image/svg+xml, seguido do XML codificado. Esse endereço é o arquivo inteiro, e cada byte dele precisa valer sozinho. A tabela ao lado das figuras oferece as relações em texto, para quem não enxerga a figura ou para quando a imagem falha em carregar.
Dados de exercício. Duas paletas, uma por fundo. Os valores abaixo são os que render() grava nos atributos do arquivo.
Paletas gravadas no arquivo
Papel
Paleta clara
Paleta escura
Fundo
#ffffff
#162536
Texto
#182b3c
#f3f7fc
Caixa
#edf3f8
#22374d
Linha e seta
#14589c
#aed5ff
A figura inline e a tabela estão disponíveis. Ative o JavaScript para gerar a imagem externa e baixar o arquivo.
SVG inline no documento
O mesmo SVG como imagem externa
Relações que a figura precisa preservar
Origem
Condição
Destino
Rascunho
Enviar para conferir
Revisão
Revisão
Conteúdo aprovado
Versão aprovada
Confira o arquivo no destino em que será usado
Troque a paleta e compare as duas figuras. O modo inline recebe estilos do documento; a imagem é um recurso separado. Nesta amostra, as cores explícitas tornam os dois resultados equivalentes.
Baixe o SVG, abra fora do portal e confira os rótulos. O arquivo contém fundo, preenchimentos, fonte de sistema e descrições, sem buscar uma biblioteca de diagrama em runtime.
Reduza a largura da janela e percorra a figura pelo teclado. A oficina conserva a dimensão dos rótulos e permite rolagem local; a tabela oferece outra leitura. No seu produto, compare isso com um arranjo que caiba na largura disponível.
Para reproduzir a falha num projeto de teste, exporte um SVG cujo fill dependa de var(--text) definido apenas na página hospedeira. Abra o arquivo como imagem separada e observe a ausência desse contexto. Corrija gravando valores de cor no artefato ou preparando versões autocontidas por tema. A cor aplicada precisa ser conferida no fundo real, incluindo estados de seleção e foco.
Investigar as falhas
As perdas da tabela seguem o mapa: cada destino descarta um pedaço do contexto da página, e o sintoma aparece sempre no lugar que ninguém conferiu. A coluna de confirmação diz onde olhar.
Falhas que esta oficina reproduz
Sintoma
Causa provável
Como confirmar
Correção
No e-mail ou no slide, as caixas aparecem vazias
O texto usa fill="var(--text)" ou currentColor; fora da página a variável não existe e a cor cai para preto, invisível sobre fundo escuro, ou some num tema que define color igual ao fundo.
Edite o SVG inline no DevTools trocando um fill por var(--text) e mude a paleta: a imagem externa gerada mostra o texto preto ou ausente enquanto a inline continua certa.
Gravar valores de cor nos atributos ou numa <style> dentro do próprio SVG, como faz render().
A fonte muda e os rótulos saem da caixa
O <text> herdava font-family do body; isolado, cai na fonte padrão do visualizador, mais larga.
Baixe o arquivo e abra no visualizador do sistema ou numa aba nova; compare a largura de "Versão aprovada" com a da figura inline.
Nomear font-family="system-ui,sans-serif" em cada texto e deixar folga de largura nas caixas; para fonte própria, converter o texto em caminho ou incorporar a fonte.
A figura escura fica sem fundo no destino
O fundo vinha da página; o SVG isolado é transparente e o visualizador pinta branco por trás do texto claro.
Na aba Elementos, remova o rect com data-od-background e troque a paleta para escura: a imagem externa mostra texto quase branco sobre branco.
Primeiro elemento do SVG é um rect de fundo com a cor da paleta; manter uma versão por tema.
O leitor de tela diz só "imagem"
Como <img>, o <title> interno do SVG não é exposto; vale apenas o alt, que ficou vazio.
Com NVDA ou VoiceOver, navegue até a imagem externa desta oficina: o anúncio é o texto do alt. Apague o alt no DevTools e repita.
Escrever o alt com as relações da figura (origem, condição, destino) e manter <title> e <desc> para o uso inline.
A imagem externa nunca aparece
A política de segurança de conteúdo (CSP) do site bloqueia data: em img-src, ou o XML serializado veio sem xmlns.
Aba Console: a mensagem cita a diretiva img-src. Aba Rede: a entrada data: aparece com erro. A oficina troca o status pela mensagem de falha ao disparar o evento error da imagem.
Liberar data: em img-src ou servir o arquivo por URL; garantir o namespace no elemento raiz.
O download leva ids repetidos para dentro da página de destino
O arquivo preservou id e class da página de origem; colado inline em outra página, colide com ids existentes e recebe CSS alheio.
Abra o arquivo baixado no editor de texto: a raiz não tem id nem class, porque a cópia os remove antes de serializar. Compare com uma exportação direta do DOM.
Serializar uma cópia limpa; quando a figura for reinserida inline, prefixar ids como faz o ampliador desta página.
Código de referência
O primeiro bloco é a exportação desta demonstração reescrita como módulo; o segundo é um modelo de SVG autocontido, com fundo, fonte nomeada, título e descrição; o terceiro mostra como incorporar o mesmo arquivo com uma versão por tema usando <picture> e a consulta prefers-color-scheme, que o navegador avalia sem JavaScript.
// Grava a paleta no próprio SVG e produz as três saídas: inline (já está
// na página), <img> com URL data: e arquivo para download.
const PALETAS = {
light: { fundo: "#ffffff", texto: "#182b3c", caixa: "#edf3f8", linha: "#14589c" },
dark: { fundo: "#162536", texto: "#f3f7fc", caixa: "#22374d", linha: "#aed5ff" }
};
export function gravarPaleta(svg, nome) {
const p = PALETAS[nome];
svg.querySelector("[data-od-background]").setAttribute("fill", p.fundo);
svg.querySelectorAll("[data-od-box]").forEach((el) => {
el.setAttribute("fill", p.caixa);
el.setAttribute("stroke", p.linha);
});
svg.querySelectorAll("text").forEach((el) => {
el.setAttribute("fill", p.texto);
// Fora da página não há herança: a família precisa estar no elemento.
if (!el.getAttribute("font-family")) el.setAttribute("font-family", "system-ui,sans-serif");
});
svg.querySelectorAll("[data-od-line]").forEach((el) => el.setAttribute("stroke", p.linha));
svg.querySelectorAll("[data-od-arrow]").forEach((el) => el.setAttribute("fill", p.linha));
}
// Serializa uma cópia sem id nem class: fora da página esses ganchos só
// serviriam ao CSS que o destino não tem, e colidiriam ao reinserir inline.
export function serializar(svg) {
const copia = svg.cloneNode(true);
copia.removeAttribute("id");
copia.removeAttribute("class");
if (!copia.getAttribute("xmlns")) copia.setAttribute("xmlns", "http://www.w3.org/2000/svg");
return new XMLSerializer().serializeToString(copia);
}
export function comoImagem(img, texto) {
img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(texto);
}
export function baixar(texto, nome) {
const url = URL.createObjectURL(new Blob([texto], { type: "image/svg+xml;charset=utf-8" }));
const a = Object.assign(document.createElement("a"), { href: url, download: nome });
document.body.append(a); a.click(); a.remove();
setTimeout(() => URL.revokeObjectURL(url), 1000); // libera a memória
}
// Uso: gravarPaleta(svg, select.value); const xml = serializar(svg);
// comoImagem(img, xml); botao.onclick = () => baixar(xml, `processo-${select.value}.svg`);
<!-- Modelo autocontido: tudo o que o destino precisa está dentro do arquivo. -->
<svg xmlns="http://www.w3.org/2000/svg" width="360" height="340" viewBox="0 0 360 340"
role="img" aria-labelledby="t d">
<!-- Nome e descrição: lidos quando o SVG estiver inline; como <img>, escreva o alt. -->
<title id="t">Do rascunho à versão aprovada</title>
<desc id="d">Rascunho segue para revisão. A revisão libera a versão aprovada.</desc>
<!-- Estilo dentro do arquivo: vale em qualquer destino. O var() tem valor
de reserva, então funciona mesmo onde a variável não existe. -->
<style>
.fundo { fill: var(--fundo, #ffffff); }
.caixa { fill: var(--caixa, #edf3f8); stroke: var(--linha, #14589c); stroke-width: 2; }
.linha { fill: none; stroke: var(--linha, #14589c); stroke-width: 3; }
.seta { fill: var(--linha, #14589c); }
text { fill: var(--texto, #182b3c); font-family: system-ui, sans-serif; font-size: 18px; }
</style>
<rect class="fundo" width="360" height="340"/>
<rect class="caixa" x="30" y="24" width="300" height="66" rx="8"/>
<text x="180" y="65" text-anchor="middle">Rascunho</text>
<path class="linha" d="M180 90 V122"/><path class="seta" d="M174 116 L180 126 L186 116 Z"/>
<rect class="caixa" x="30" y="126" width="300" height="66" rx="8"/>
<text x="180" y="167" text-anchor="middle">Revisão</text>
<path class="linha" d="M180 192 V224"/><path class="seta" d="M174 218 L180 228 L186 218 Z"/>
<rect class="caixa" x="30" y="228" width="300" height="66" rx="8"/>
<text x="180" y="269" text-anchor="middle">Versão aprovada</text>
</svg>
<!-- 1. Inline: o SVG entra no DOM e as variáveis do tema valem.
Defina --fundo, --texto, --caixa e --linha no CSS da página. -->
<figure>
<!-- cole aqui o conteúdo de processo-claro.svg -->
<figcaption>Fluxo de aprovação das apostilas</figcaption>
</figure>
<!-- 2. Como imagem, com uma versão por tema. O navegador escolhe a fonte
pela consulta de mídia, sem JavaScript; o alt carrega as relações. -->
<picture>
<source srcset="/media/processo-dark.svg" media="(prefers-color-scheme: dark)">
<img src="/media/processo-light.svg" width="360" height="340"
alt="Rascunho segue para Revisão, que libera a Versão aprovada.">
</picture>
<!-- 3. Quando o tema é trocado por atributo no html (data-theme), a consulta
de mídia não acompanha: troque o src pelo JavaScript do seu interruptor. -->
<script>
const img = document.querySelector("img[data-tema]");
new MutationObserver(() => {
const escuro = document.documentElement.dataset.theme === "dark";
img.src = escuro ? "/media/processo-dark.svg" : "/media/processo-light.svg";
}).observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
</script>
A imagem desta página usa uma URL data: local, compatível com a política de imagens do portal; não é um arquivo remoto nem exige upload. O download produz o arquivo SVG real. Mermaid e D2 são alternativas para gerar diagramas maiores a partir de texto, sem mudar a obrigação de conferir o resultado exportado. Baixar o código desta demonstração.
Critérios de aceite
Levar para o projeto
Em React ou Next, gere as duas versões do arquivo no build (uma função pura que recebe a paleta e devolve a string) e sirva por <picture>; em Astro, um componente .astro pode emitir o SVG inline com as variáveis do tema e o mesmo arquivo em public/ para download; em HTML puro, o módulo acima basta. Em produção, acompanhe a taxa de erro de carregamento das imagens SVG (evento error enviado ao analytics) e, no e-mail, a proporção de cliques na versão em texto da figura, sinal de que a imagem chegou ilegível.
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.
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.
Versione o arquivo do diagrama no repositório. O desenho ganha histórico, autor e revisor.
Compile no momento de publicar. A flag de identificador único evita colisão entre figuras.
Injete os tokens de cor no pós-processo. A mesma figura serve o tema claro e o escuro.
Sirva o SVG da pasta pública. Mudou a arquitetura, muda o texto e o build refaz o resto.
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.
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
Diagrama que se lê no celular e no tema escuro
Quando um agente de IA gera um diagrama, o arquivo costuma sair em SVG, um formato de imagem escrito em texto que encolhe sem perder nitidez. Encolher é justamente o risco: a figura desenhada para 1200 pixels de largura cabe inteira num celular de 390, e a letra diminui na mesma proporção, até virar um risco ilegível.
Há mais dois defeitos comuns. As cores chegam fixas dentro do arquivo, então um texto azul-escuro some quando o leitor liga o tema escuro do site. E as setas não têm texto para leitor de tela, o programa que lê a página em voz alta: quem não enxerga a figura recebe só a palavra imagem, sem saber o que liga a quê.
Três regras práticas antes de publicar
Letra nunca abaixo de 12 pixels na largura do celular. Faça a conta: tamanho da letra vezes a largura exibida, dividido pela largura do viewBox, que é a área de desenho interna do SVG. Se der menos de 12, aumente a letra ou desenhe uma versão mais estreita. Para rótulo de leitura confortável, o curso segue com a referência de 14 pixels.
Cores pelos tokens do tema, nunca fixas no SVG. Tokens são as variáveis de cor que o site troca entre claro e escuro. No arquivo, use currentColor ou var(--nome-do-token) no lugar de valores como #1e2365; assim a figura acompanha o tema escolhido pela pessoa.
Título e descrição acessíveis em toda figura. Coloque <title> e <desc> logo depois da etiqueta <svg>, com role="img" e aria-labelledby apontando para os dois. A descrição conta em uma ou duas frases o que as setas ligam.
Para pedir isso ao agente, duas ou três linhas bastam. Cole o pedido abaixo junto com a descrição do processo; ele cobre as três regras e deixa claro em que largura a figura será vista, que é o dado que o agente nunca adivinha sozinho.
Gere o diagrama em SVG para exibir a 390 px de largura: nenhum texto
abaixo de 12 px nessa largura, cores só com currentColor ou var(--token)
do tema, e <title>, <desc>, role="img" e aria-labelledby no <svg>.
Para conferir depois de publicar, o detector da skill Impeccable 4.5.0, um conjunto de instruções de design para agentes de código, mede na página no ar a letra pequena (a regra tiny-text) e o contraste entre texto e fundo, com o comando npx impeccable detect e a opção --viewport 390x844 para simular o celular. Ele não usa modelo de linguagem: lê a página renderizada.
Cenário
Quem
Lívia, analista de CRM, que pede ao agente de IA os diagramas da página de vendas do curso de automação.
Tarefa
Publicar o fluxo "o lead entra pelo formulário, recebe a sequência de e-mails e chega à conversa com vendas" no topo da página, que recebe a maior parte das visitas pelo celular.
Falha vista
No computador a figura estava ótima. No celular, os três rótulos viraram riscos de 4,9 pixels; com o tema escuro ligado, o azul-marinho do texto sumiu no fundo; e o leitor de tela anunciou apenas "imagem".
Resultado esperado
O mesmo SVG, analisado a 390 pixels, com letras em 12 pixels ou mais, cores ligadas aos tokens do tema com valor de reserva, e título, descrição, role="img" e aria-labelledby na raiz.
A oficina abaixo é um analisador que roda inteiro no navegador. Ele lê o código colado com DOMParser (leitor de XML que devolve uma árvore sem executar nada), remove script, foreignObject, mídia embutida e atributos de evento, e só então faz três conferências independentes: a conta da letra em cada <text>, o inventário das cores fixas e a presença do nome acessível. Com um título preenchido, ele gera a versão corrigida e a mostra como imagem sobre o fundo que você escolher.
Mapa da oficina. O código colado passa pela limpeza, pelas três conferências a 390 pixels e pela correção; os valores são os do exemplo que o botão "Usar exemplo" carrega.
O código colado é lido pelo DOMParser como XML. Antes de qualquer prévia, a oficina remove script, foreignObject, mídia embutida, atributos on* e endereços externos. A largura marcada no formulário (390 por padrão) entra na conta.
Para cada text, a letra efetiva é o tamanho declarado vezes 390 dividido pela largura do viewBox. No exemplo, 15 vira 4,9 pixels e a nota de rodapé de 12 vira 3,9; o fator sugerido parte da menor letra: 12 dividido por 3,9, arredondado para 3,08.
Cada fill, stroke e cor em atributo, em style ou na folha interna entra no inventário quando é um valor fixo; currentColor, var() e none ficam de fora. O exemplo traz cinco valores distintos.
A raiz é conferida: title e desc como filhos diretos, role="img" e aria-labelledby apontando para ids que existem. O exemplo falha nos quatro itens.
Com o título preenchido, corrigir() multiplica cada letra pelo fator (gravado em style, com prioridade sobre o atributo), troca cada cor fixa por var(--diagrama-cor-n, cor original) e insere title, desc, role e aria-labelledby; sem viewBox, cria um a partir de width e height.
A versão corrigida vira uma imagem por URL data: na largura escolhida, sobre o fundo claro ou escuro do seletor, com o SVG e o mapa de cores prontos para copiar.
Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.
Demonstrar o analisador
Acione "Usar exemplo" e leia o resultado de cima para baixo: a tabela de letras ordenada da menor para a maior, com a conta usada escrita por extenso; o inventário de cores com a contagem de usos; a lista de quatro itens do nome acessível; e a versão corrigida. Depois troque a largura para 1280 e veja a mesma figura passar na conta da letra sem mudar uma linha do código, porque a conferência depende de onde a figura será vista.
Marque "Trocar cores fixas por variáveis" e analise de novo. Na prévia, mude o fundo para escuro: o texto ainda aparece, porque cada variável leva a cor original como reserva; o mapa de cores gerado é o ponto de partida para ligar cada variável ao token do seu tema. O status no topo resume a análise e é anunciado pelo leitor de tela.
Dados de exercício. O exemplo embutido é o fluxo do lead com três caixas, duas setas e uma nota de rodapé. Os números abaixo são os que a análise a 390 pixels devolve.
O exemplo antes e depois da correção, a 390 pixels
Item
Antes
Depois
Rótulos das caixas
15 px declarados, 4,9 px na tela
46,2 px declarados, 15,0 px na tela
Nota de rodapé
12 px declarados, 3,9 px na tela
37 px declarados, 12,0 px na tela
Cores fixas
5 valores em 15 usos
5 variáveis com valor de reserva
Nome acessível
Sem title, desc, role e aria-labelledby
Os quatro presentes, ids gerados a partir do título
Oficina: conferir um SVG antes de publicar
Esta oficina precisa de JavaScript para analisar o código. Sem ele, confira à mão: procure font-size em cada <text> e faça a conta com a largura do viewBox; procure valores como #333 em fill e stroke; e veja se há <title> e <desc> logo depois de <svg>.
A análise aparece aqui depois que o JavaScript carregar.
O exemplo traz os três problemas de propósito: letra de 15 pixels num desenho de 1200 de largura, que chega a menos de 5 pixels no celular, cores fixas que somem no fundo escuro da prévia e nenhum título acessível. Troque a largura, ligue a troca de cores e compare a prévia nos dois fundos. Baixar o código desta oficina.
Investigar as falhas
Os sintomas abaixo aparecem em figuras geradas por agente, exportadas da Mermaid ou desenhadas no draw.io. Para cada um, a coluna de confirmação usa o próprio analisador ou o DevTools; a correção aponta para o bloco de código correspondente.
Falhas que esta oficina reproduz
Sintoma
Causa provável
Como confirmar
Correção
Rótulos viram riscos no celular
O viewBox é largo (1200) e a letra foi escolhida olhando o monitor; a 390 pixels ela encolhe para menos de um terço.
No analisador, use o exemplo a 390: tabela com 4,9 px e 3,9 px. No DevTools, Ctrl+Shift+M com 390 de largura e inspecione um <text>: o tamanho calculado aparece na aba Computed.
Multiplicar as letras pelo fator sugerido ou redesenhar num viewBox mais estreito para o celular (medir-letra.js).
Depois de ampliar a letra, o rótulo sai da caixa
O fator foi aplicado só ao texto; as caixas continuam do tamanho antigo.
Na prévia corrigida, o rótulo "Lead entra pelo formulário" ultrapassa a caixa de 300 de largura. Role a prévia para os lados e compare com o original.
Aumentar as caixas junto ou quebrar o rótulo em dois tspan; para fluxos longos, uma versão vertical para o celular.
O texto some no tema escuro
Cores fixas em fill e stroke, escolhidas para fundo branco.
Analise o exemplo sem a troca de cores e mude o fundo da prévia para escuro: o azul-marinho desaparece. Ligue a troca e repita.
Cor em style com var(--token, reserva); atributo de apresentação não aceita var() (cores-por-token.js).
A oficina diz que não há nenhum <text>
A Mermaid exportou os rótulos em foreignObject com HTML dentro, que a limpeza remove e que some fora do navegador.
A nota ao fim do resultado lista "foreignObject" entre os removidos. No arquivo, procure <foreignObject.
Gerar de novo com htmlLabels: false na configuração da Mermaid, para os rótulos virarem <text>.
O leitor de tela lê cada pedaço da figura ou só "imagem"
Sem role="img", alguns leitores entram em cada elemento; sem <title>, anunciam o genérico.
Lista "3. Nome e descrição" do analisador com itens em Não. Com NVDA ou VoiceOver, navegue até a figura inline e ouça o anúncio.
<title> e <desc> como primeiros filhos, role="img" e aria-labelledby com os dois ids (fluxo-lead.svg).
A figura não encolhe com a tela
O SVG tem width e height fixos e nenhum viewBox; o navegador mantém o tamanho em pixels e corta.
O analisador avisa "viewBox acrescentado" e usa a largura do atributo na conta. No DevTools, a figura ultrapassa a largura do contêiner a 390.
Gravar viewBox="0 0 largura altura" e deixar width: 100%; height: auto no CSS.
Código de referência
Os dois módulos reproduzem as conferências do analisador, prontos para um script de build que recuse figuras ilegíveis antes do deploy; o terceiro bloco é o exemplo da oficina já corrigido, para servir de modelo ao pedido feito ao agente.
// Letra efetiva: tamanho declarado × largura exibida ÷ largura do viewBox.
// Roda no navegador ou no Node com um DOM (jsdom, linkedom).
const PISO = 12;
export function larguraBase(svg) {
const vb = (svg.getAttribute("viewBox") || "").trim().split(/[\s,]+/).map(Number);
if (vb.length === 4 && vb.every(Number.isFinite) && vb[2] > 0) return vb[2];
const w = parseFloat(svg.getAttribute("width") || "");
return Number.isFinite(w) && w > 0 ? w : null; // sem viewBox, vale o width
}
// Tamanho declarado: atributo, style ou herança do pai, em px.
function tamanhoDeclarado(no) {
for (let n = no; n && n.nodeType === 1; n = n.parentNode) {
const style = n.getAttribute("style") || "";
const m = style.match(/font-size\s*:\s*([\d.]+)(px)?/i);
if (m) return parseFloat(m[1]);
const attr = parseFloat(n.getAttribute("font-size") || "");
if (Number.isFinite(attr)) return attr;
}
return 16; // padrão do navegador quando nada foi declarado
}
export function medir(svg, exibida = 390) {
const base = larguraBase(svg);
const linhas = [];
for (const t of svg.querySelectorAll("text")) {
if (!t.textContent.trim()) continue;
const declarado = tamanhoDeclarado(t);
const efetivo = base ? (declarado * exibida) / base : null;
linhas.push({ texto: t.textContent.trim(), declarado, efetivo });
}
linhas.sort((a, b) => a.efetivo - b.efetivo);
const menor = linhas[0] ? linhas[0].efetivo : null;
// Fator que leva a menor letra ao piso de 12 px, arredondado para cima.
const fator = menor !== null && menor < PISO ? Math.ceil((PISO / menor) * 100) / 100 : 1;
return { base, linhas, menor, fator, abaixo: linhas.filter((l) => l.efetivo < PISO).length };
}
// Uso num gate de build: const r = medir(svg, 390);
// if (r.abaixo) throw new Error(`${r.abaixo} texto(s) abaixo de 12 px; fator ${r.fator}`);
// Troca cada cor fixa por var(--diagrama-cor-n, cor original).
// A cor original fica de reserva: fora da página, nada se perde.
const PROPS = ["fill", "stroke", "stop-color", "flood-color", "lighting-color", "color"];
function fixa(v) {
const s = (v || "").trim().toLowerCase();
if (!s || ["none", "transparent", "inherit", "currentcolor"].includes(s)) return false;
return !s.startsWith("var(") && !s.startsWith("url(");
}
export function coresPorToken(svg) {
const nomes = new Map(); // valor → nome da variável
const nome = (v) => {
const k = v.toLowerCase();
if (!nomes.has(k)) nomes.set(k, `--diagrama-cor-${nomes.size + 1}`);
return nomes.get(k);
};
for (const n of [svg, ...svg.querySelectorAll("*")]) {
for (const p of PROPS) {
const v = n.getAttribute(p);
if (!fixa(v)) continue;
// Atributo de apresentação não aceita var(): a cor passa para o style,
// que tem prioridade sobre o atributo.
n.removeAttribute(p);
const st = (n.getAttribute("style") || "").trim();
n.setAttribute("style", `${st ? st.replace(/;?\s*$/, ";") : ""}${p}:var(${nome(v)}, ${v.trim()})`);
}
}
// Mapa para o CSS da página: ligue cada variável ao token do seu tema.
const css = [":root {", ...[...nomes].map(([v, n]) => ` ${n}: var(--color-text); /* era ${v} */`), "}",
':root[data-theme="dark"] {', " /* redefina aqui só o que muda no tema escuro */", "}"].join("\n");
return { svg, css, total: nomes.size };
}
<!-- O exemplo da oficina depois da correção, para exibir a 390 px.
Letras × 3,08; cores por variável com reserva; nome acessível na raiz. -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 360" role="img"
aria-labelledby="fluxo-lead-titulo fluxo-lead-descricao">
<title id="fluxo-lead-titulo">Fluxo do lead até a conversa com vendas</title>
<desc id="fluxo-lead-descricao">O lead entra pelo formulário, recebe a sequência
de e-mails e chega à conversa com vendas. Setas ligam as três etapas na ordem.</desc>
<style>
.fundo { fill: var(--diagrama-fundo, #ffffff); }
.caixa { fill: var(--diagrama-caixa, #f1f3f8); stroke: var(--diagrama-cor-1, #1e2365); stroke-width: 3; }
.seta { stroke: var(--diagrama-cor-2, #999999); fill: var(--diagrama-cor-2, #999999); stroke-width: 3; }
text { fill: var(--diagrama-cor-1, #1e2365); font-family: Arial, sans-serif; font-size: 46.2px; }
.nota { fill: var(--diagrama-cor-3, #6b6b6b); font-size: 37px; }
</style>
<rect class="fundo" width="1200" height="360"/>
<rect class="caixa" x="40" y="120" width="330" height="110" rx="12"/>
<text x="205" y="190" text-anchor="middle">Lead entra</text>
<path class="seta" d="M370 175 H440"/><path class="seta" d="M430 165 L450 175 L430 185 Z"/>
<rect class="caixa" x="450" y="120" width="300" height="110" rx="12"/>
<text x="600" y="190" text-anchor="middle">E-mails</text>
<path class="seta" d="M750 175 H820"/><path class="seta" d="M810 165 L830 175 L810 185 Z"/>
<rect class="caixa" x="830" y="120" width="330" height="110" rx="12"/>
<text x="995" y="190" text-anchor="middle">Vendas</text>
<text class="nota" x="600" y="320" text-anchor="middle">Exemplo didático</text>
</svg>
<!-- Na página: :root { --diagrama-cor-1: var(--color-text); --diagrama-cor-2: var(--color-muted); }
e, no tema escuro, só o que muda. O cinza #bbbbbb da nota original reprovaria no
contraste sobre branco; o modelo usa #6b6b6b de reserva. -->
Critérios de aceite
Levar para o projeto
Em React ou Next, rode medir() e coresPorToken() num script de build sobre os SVGs de public/, com jsdom, e falhe o build quando houver letra abaixo do piso; em Astro, o mesmo script cabe numa integração que percorre os arquivos antes de copiar; em HTML puro, cole o analisador desta página numa rota interna. Em produção, meça a proporção de visitas ao celular que ampliam a figura (evento do botão "Ampliar diagrama") e o resultado do npx impeccable detect --viewport 390x844 a cada publicação; os dois caem quando a letra passa a caber.
Interfaces amplas que se leem sem esforço: UX de 2026 para muita página, menu e link
Um portal como este tem centenas de páginas, dezenas de menus e milhares de links. O roadmap de execução passa de 400 mil palavras e 160 tabelas numa página só. Quem chega sem senioridade técnica precisa achar a resposta em poucos cliques, entender o que está vendo e saber qual é a próxima ação. Esta seção reúne um benchmark feito em 21 de outubro de 2026, com o geo-orchestrator varrendo documentação de navegadores, estudos de usabilidade e sites de referência, e o transforma num roteiro para pedir ao agente de código.
A ideia central é organizar a página em três camadas: uma síntese que cabe numa tela, um roteiro que conduz de seção em seção e a fonte completa para quem precisa do detalhe. Cada camada tem elementos visuais próprios, e a maior parte deles hoje sai do navegador sem biblioteca: índice que acompanha a rolagem, paleta de comandos, acordeão exclusivo, popover ancorado, barra de leitura, cartões com entrada escalonada e tabela com cabeçalho fixo.
Regra dos dois cliques e das três camadas. Qualquer informação ou ação do portal precisa ficar a no máximo dois cliques de onde a pessoa está, e cada seção longa precisa oferecer a síntese antes do detalhe. O detalhe continua disponível, numa camada abaixo, para quem precisa dele. O agente de código cumpre a regra quando o pedido diz onde a pessoa começa, o que ela procura e quantos passos pode dar. Os dois cliques são meta de projeto, e o critério de aprovação é a tarefa real: a NN/g mostrou em 2019 (Laubheimer, "The 3-Click Rule for Navigation Is False") que o número de cliques importa menos do que a clareza de cada escolha, e o teste de árvore (tree testing, NN/g, 2023) confere a organização das categorias antes de desenhar a tela.
Como um portal amplo se organiza em camadas
O mapa abaixo mostra a mesma página vista pelas três camadas. A pessoa entra pela síntese, escolhe uma trilha pelo seu papel e desce até a fonte quando precisa. Todo ponto do mapa tem uma volta marcada, e o ponto pulsante indica onde a pessoa está, que é o sinal mais barato e mais eficaz de orientação num conteúdo grande.
As três camadas convivem na mesma página. A camada de síntese nunca substitui a fonte: ela aponta para ela.
Benchmark 1: padrões de navegação que funcionam para quem chega sem prática
A tabela compara os padrões mais usados em portais de documentação e produtos amplos em 2025 e 2026. A coluna de evidência cita o estudo ou a diretriz que sustenta a recomendação, com o ano. Role a tabela: o cabeçalho fica fixo, que é o primeiro padrão da lista aplicado nela mesma.
Padrão
Quando usar
Quando evitar
Evidência e referência
Quem usa bem em 2026
Índice da página que acompanha a rolagem (scroll-spy)
Página com 6 seções ou mais e leitura de cima a baixo; marca a seção atual e serve de "você está aqui".
Página curta ou com seções de tamanhos muito desiguais, em que o marcador pula.
NN/g, "Table of Contents", Wang e Brown, outubro de 2023, estudo qualitativo: parte das pessoas não percebe um índice fixo discreto, por isso a seção atual precisa de destaque. Smashing Magazine, Friedman, maio de 2023: navegação fixa compensa quando a pessoa compara e age ao longo da página. Nenhum dos dois mede ganho de tempo.
Documentação da Stripe, MDN, docs da Vercel.
Menu lateral em árvore recolhível
Portal com mais de 30 páginas agrupadas por tema; mostra só o ramo aberto.
Celular, onde a árvore vira uma gaveta; e portais com menos de 10 páginas.
Nielsen, "Progressive Disclosure", NN/g, 2006: esconder o que é raro deixa o sistema mais fácil de aprender e com menos erro.
Trilha de navegação (breadcrumb) com "você está aqui"
Sempre que a página fica dois níveis ou mais abaixo da raiz.
Site raso, em que a trilha repete o menu.
Diretriz 2.4.8 da WCAG (Location, nível AAA) descreve a localização dentro do conjunto de páginas como ajuda de orientação.
Este portal, lojas grandes, documentação da Microsoft.
Paleta de comandos (Ctrl+K)
Portal com muitas páginas e pessoas que voltam com frequência; vira a busca e o atalho de ação.
Público que entra uma vez e sai, sem hábito de teclado; nesse caso a busca visível basta.
Padrão popularizado por Linear, Notion e Vercel desde 2021; no benchmark de 21/10/2026 ele aparece como atalho de ação, nunca como única navegação.
Linear, Notion, Raycast, Vercel.
Divulgação progressiva com details e summary
Perguntas frequentes, detalhes técnicos, exceções e notas longas.
Conteúdo que a pessoa precisa comparar lado a lado; acordeão esconde o que deveria estar junto.
Nielsen, NN/g, 2006; GOV.UK Design System, componente accordion, revisado em 2024, com guia de quando usar e quando usar details.
GOV.UK, MDN, lojas com perguntas por produto.
Menu escondido atrás de ícone (hambúrguer) no computador
Só quando a largura obriga; no celular com os 3 a 5 itens principais visíveis.
No computador, por padrão.
Pernice e Budiu, "Hamburger Menus and Hidden Navigation Hurt UX Metrics", NN/g, 2016, com 179 participantes em seis sites: no computador, a navegação escondida foi usada em 27% das tarefas, contra 48% com o menu visível. Em 2025 a NN/g mediu que o ícone é mais reconhecido, sem medir tempo nem sucesso; o rótulo "Menu" ao lado ajuda quem tem menos prática.
Sites que mostram os itens principais e escondem o resto.
Barra de progresso de leitura
Artigo e guia longo, lido de ponta a ponta; mostra quanto falta.
Páginas de consulta, lidas por partes; a barra engana.
Recurso nativo com animation-timeline: scroll() no Chrome desde 2023 e no Safari 26, setembro de 2025; Firefox ainda atrás de preferência em junho de 2026 (Firefox 152).
Blogs técnicos, este portal nas aulas longas.
Próximo passo ao fim de cada seção
Guia com ordem recomendada; evita o fim morto.
Página de referência sem ordem.
GOV.UK Design System, padrão "step by step navigation", 2018, revisado em 2023, criado para jornadas com várias páginas.
GOV.UK, cursos, roadmap deste portal.
Trilhas por papel
Mesmo conteúdo lido por gestor, operador e técnico; cada papel vê a ordem e o tempo dele.
Conteúdo que serve a um papel só.
Aplicado no roadmap deste portal em 22/10/2026, com barra fixa e a escolha guardada no navegador.
Documentação da AWS e do Google Cloud por papel.
Mapa do portal visual
Portal com 50 páginas ou mais, para quem quer ver o todo antes de entrar.
Site pequeno.
Este portal tem o mapa em /leadlovers2026/mapa-do-portal/ e o diagrama de arquitetura do catálogo acima.
Portais de governo e universidades.
Cabeçalho que encolhe ao rolar
Celular, para ganhar espaço sem perder a busca.
Formulários longos no celular, onde qualquer barra fixa rouba espaço.
Smashing Magazine, maio de 2023: barra fixa prejudica quando sobra pouco espaço, caso dos formulários no celular.
Apps de notícias, lojas.
Transição entre páginas (View Transitions)
Portal em que a pessoa navega entre páginas irmãs; a transição mostra que o contexto foi mantido.
Navegação rara ou público com movimento reduzido ligado.
Chrome, estudo de caso do Modo IA do Google com view transitions, 2025, usado como melhoria progressiva: sem suporte, só não anima.
Google Modo IA, Astro, sites em Chrome e Safari.
Benchmark 2: o que o navegador faz sozinho em outubro de 2026
Em 2026, a maior parte dos elementos dinâmicos de um portal sai do próprio navegador. A coluna de suporte registra o retrato de 21 de outubro de 2026 a partir das notas de lançamento do Chrome, do Firefox e do Safari e dos resumos mensais do web.dev. "Baseline" quer dizer que os três motores principais entregam o recurso sem bandeira. Peça ao agente os recursos marcados como Baseline sem medo; para os demais, peça sempre a reserva, que é o comportamento sem o recurso.
Recurso
Serve para
Suporte em 21/10/2026
Como pedir ao agente
details com name
Acordeão em que abrir um item fecha os outros, sem JavaScript.
Baseline: Chrome 120, Safari 17.2, Firefox 130.
"Acordeão exclusivo com details name, sem JS; summary com 44 px de altura."
Popover API
Glossário, menu e aviso que abrem na camada de cima e fecham com Esc ou clique fora.
Baseline: Chrome 114, Safari 17, Firefox 125.
"Use popover auto para o glossário e popover manual para o aviso de ação; sem suporte, use details."
Anchor Positioning
Prender o popover ao termo, com virada automática quando falta espaço.
Baseline desde janeiro de 2026, com Firefox 147.
"position-anchor e position-area, com position-try-fallbacks: flip-block; se não houver suporte, posicione abaixo do termo."
dialog nativo
Paleta de comandos e janelas modais com foco preso e Esc.
Baseline desde 2022.
"Paleta de comandos num dialog com showModal, input com role combobox e lista com role listbox."
@starting-style e transition-behavior: allow-discrete
Animar a entrada de um elemento que acabou de aparecer, inclusive popover e dialog.
Baseline: Chrome 117, Safari 17.5, Firefox 129.
"Entrada com @starting-style, 300 ms, e sem animação com prefers-reduced-motion."
Container queries e :has()
Componente que muda de forma pelo espaço que tem, e estilo que depende do que há dentro.
Baseline desde 2023; consultas só por nome chegaram ao Firefox 149 e ao Safari 26.4 em março de 2026.
"O cartão reempilha com @container (max-width: 640px); não use media query para isso."
text-wrap: balance e scrollbar-gutter
Título sem palavra órfã e layout que não pula quando a barra de rolagem aparece.
Baseline desde 2024.
"text-wrap: balance nos títulos e scrollbar-gutter: stable nos rolos."
light-dark() e color-scheme
Cor que troca sozinha entre tema claro e escuro.
Baseline desde 2024; imagens dentro de light-dark() viraram Baseline em setembro de 2026 com Safari 27.
"Cores só por token; cada token com light-dark()."
contrast-color()
Texto preto ou branco escolhido pelo navegador sobre qualquer fundo.
Baseline desde abril de 2026, com Chrome 147.
"Rótulo de selo com color: contrast-color(var(--fundo))."
field-sizing: content
Caixa de texto que cresce com o que a pessoa digita.
Baseline desde junho de 2026.
"textarea com field-sizing: content e max-height."
overflow-anchor
A página não pula quando conteúdo carrega acima do que está sendo lido.
Baseline desde setembro de 2026, com Safari 27.
"Mantenha overflow-anchor: auto; nunca desligue em lista longa."
View Transitions na mesma página
Trocar de aba, reordenar lista e expandir cartão com continuidade visual.
Baseline desde o Firefox 144, outubro de 2025.
"document.startViewTransition ao trocar a aba; sem suporte, troca direta."
View Transitions entre páginas
Transição ao navegar de uma página a outra do portal.
Parcial: Chrome 126 e Safari 18.2; Firefox em desenvolvimento.
"@view-transition { navigation: auto } nas duas páginas; é melhoria progressiva."
Scroll-driven animations (animation-timeline)
Barra de leitura e revelação ao rolar sem JavaScript.
Parcial: Chrome 115 e Safari 26; Firefox atrás de preferência até Firefox 152, junho de 2026.
"Barra com animation-timeline: scroll() dentro de @supports; reserva em JS com scroll passivo."
Scroll-triggered animations e trigger-scope
Disparar uma animação quando um ponto da rolagem é atingido.
Só Chrome, desde o Chrome 146, março de 2026.
"Ainda não peça; use IntersectionObserver."
interpolate-size e calc-size()
Animar height: auto, caso do acordeão que abre suave.
Parcial: Chrome 129; Safari só na Technology Preview 254, de 8 de outubro de 2026; Firefox sem suporte.
"interpolate-size: allow-keywords no details; sem suporte, abre sem animar."
select personalizável (appearance: base-select)
Caixa de seleção com ícones e estilo próprio.
Parcial: Chrome 135 e Safari 27, setembro de 2026; Firefox sem suporte.
"Só com reserva no select padrão."
View Transitions por elemento (element.startViewTransition)
Várias transições ao mesmo tempo em partes diferentes da tela.
Só Chrome, desde o Chrome 147, abril de 2026.
"Ainda não peça."
ariaNotify()
Avisar o leitor de tela de uma ação sem depender de região viva.
Baseline com Chrome 141, Firefox 150 e Safari 27.
"Status por aria-live e, quando houver, ariaNotify."
Benchmark 3: bibliotecas de movimento, só quando o navegador não basta
A regra de 2026 é começar pelo CSS e pela Web Animations API, e só trazer biblioteca quando o movimento tem estrutura: linha do tempo com etapas, rolagem presa (scrub) ou morfologia de SVG. Os pesos abaixo foram medidos pela Prismetic Group em 26 de julho de 2026, com esbuild 0.25.0, na menor importação que funciona, minificada e comprimida com gzip; o Bundlephobia, que mede o pacote inteiro, dá números maiores (GSAP core 26,7 KB na 3.15.0, Anime.js 39,3 KB na 4.5.0), e por isso o método precisa constar ao lado de todo peso citado. Entre as bibliotecas de componentes, as acessíveis por padrão (Radix, Base UI, React Aria, Ark UI) saem corretas do agente com mais frequência do que o componente escrito do zero.
Opção
Peso gzip (jul. 2026)
Licença
Use quando
O que costuma sair errado do agente
CSS e Web Animations API
0 KB
Nativo
Hover, foco, entrada, acordeão, barra de leitura, revelação ao rolar.
Esquecer prefers-reduced-motion e animar height sem interpolate-size.
motion/mini
3,4 KB
MIT
Sequência simples sobre a Web Animations API, fora do React.
Pedir spring e layout animation, que só existem no pacote completo.
Anime.js v4 (animate)
13,2 KB; 19,1 KB com timeline e scroll
MIT
Linha do tempo e SVG leves sem framework.
Copiar exemplo da v3: o objeto global anime sumiu em abril de 2025.
Motion (animate híbrido)
24,7 KB; 43,9 KB em motion/react
MIT
Interface em React com entrada, saída e layout.
Animar lista sem key estável, perdendo a identidade do item.
GSAP core e ScrollTrigger
28,2 KB; 46,1 KB com ScrollTrigger
Gratuito desde a 3.13, 30/04/2025, com cláusula contra ferramentas sem código concorrentes do Webflow
Rolagem presa, pin, linha do tempo com rótulos, MorphSVG.
Não limpar o ScrollTrigger ao desmontar; scrub acima de 1 segundo.
Lottie e Rive
Lottie-web perto de 60 KB; runtime Rive menor, variável por recurso
MIT (lottie-web); Rive com runtime aberto e editor próprio
Ilustração animada e personagem com máquina de estados.
Arquivo JSON pesado em cima da dobra; sem imagem de reserva.
cmdk e Sonner
17,1 KB (cmdk 1.1.1); 9,2 KB (Sonner 2.0.8)
MIT
Paleta de comandos e avisos de ação em React quando o dialog e o popover nativos não bastam.
Trazer cmdk para uma lista de 8 itens que um dialog nativo resolve.
auto-animate
perto de 2 KB (3,2 KB na 0.9.0 pelo Bundlephobia)
MIT
Lista que reordena e some com um atributo só.
Aplicar em lista virtualizada, que troca nós o tempo todo.
Cognição e acessibilidade para quem chega sem senioridade
Quatro leis antigas e uma norma recente explicam por que os padrões acima funcionam. Os cartões seguem o formato de síntese do roadmap: tese, pontos, decisão e cuidado.
Lei de Hick (1952)
O tempo de escolha cresce com o número de opções visíveis.
Menus com 5 a 7 itens de primeiro nível.
O resto entra por divulgação progressiva.
Decidir: quais 5 ações entram na barra. Cuidado: esconder demais vira o problema do hambúrguer.
Lei de Fitts (1954)
Alvo maior e mais perto é mais rápido e mais seguro de acertar.
Alvos de 44 px no toque e 24 px no mínimo da WCAG 2.2 (critério 2.5.8, outubro de 2023).
Ação principal perto do conteúdo que ela afeta.
Decidir: o tamanho mínimo de botão do projeto. Cuidado: ícone sem rótulo quebra a regra para quem chega sem prática.
Carga cognitiva (Sweller, 1988)
A memória de trabalho segura pouca coisa; a página precisa mostrar o essencial e guardar o resto num clique.
Síntese antes do detalhe.
Uma família de ícones, uma escala de cor.
Decidir: o que cabe na primeira tela. Cuidado: animação que não comunica estado soma carga.
Divulgação progressiva (Nielsen, 2006)
Mostrar primeiro o mais usado e deixar o raro numa camada abaixo melhora aprendizado e reduz erro.
details, abas e gaveta lateral.
Sempre com pista do que está escondido.
Decidir: o que é raro de verdade, com dados de uso. Cuidado: comparação lado a lado não pode ficar em acordeão.
WCAG 2.2 (W3C, outubro de 2023)
Três critérios novos pesam direto em portais amplos.
2.4.11: o foco do teclado nunca fica escondido atrás de barra fixa.
2.5.7: tudo que se arrasta tem alternativa por clique.
2.5.8: alvo com 24 por 24 px no mínimo.
Decidir: a altura da barra fixa e o scroll-margin das seções. Cuidado: cabeçalho fixo que cobre o foco reprova o 2.4.11.
Movimento reduzido e linguagem simples
Quem pede menos movimento no sistema recebe o estado final; quem chega sem senioridade recebe glosa breve no primeiro termo técnico.
prefers-reduced-motion em toda animação.
Termo técnico com explicação entre parênteses na primeira vez.
Decidir: o glossário do projeto. Cuidado: animação de 2 segundos em cima da dobra atrasa quem quer ler.
Oficina: um mini-portal com todos os elementos
O quadro abaixo junta num espaço só os elementos do benchmark, todos nativos: barra de leitura com scroll-driven animation e reserva em JavaScript, índice que acompanha a rolagem, trilha com "você está aqui", paleta de comandos num dialog (Ctrl+K ou o botão Buscar), cartões com esqueleto de carregamento e entrada escalonada, acordeão exclusivo com details name, glossário em popover ancorado ao termo, tabela com resumo em cima, cabeçalho fixo e mostrar mais, próximo passo ao fim da seção e aviso de ação com desfazer. Os dados são de exercício. Baixar o código desta oficina e o CSS.
Esta oficina precisa de JavaScript para o índice que acompanha a rolagem, a paleta de comandos e o aviso de ação. Sem ele, o acordeão, a tabela com cabeçalho fixo e o glossário continuam funcionando, porque são nativos do navegador.
Portal de exercício
Início
Plano 2027
Visão executiva
Visão geral
Leitura de 1 minuto
O plano de 2027 tem três frentes: reativar quem parou, reter a segunda parcela e abrir dois segmentos novos. Cada frente tem uma dona, um número que a mede e uma data de releitura. O termo aparece em todas as frentes, por isso vem explicado aqui no primeiro uso.
Taxa de retenção: parte das pessoas que continuam clientes depois de um período. Se 100 começaram e 80 seguem após 90 dias, a taxa é de 80%.
A dona da frente, com a data já marcada no calendário do plano. A decisão fica registrada na própria seção, com o estado "pendente", "decidido" ou "adiado".
O que acontece se o número da semana cair?
A frente entra em alerta e o próximo passo muda: em vez de avançar, a dona revisa a hipótese e registra o motivo antes da releitura seguinte.
Como a pessoa nova encontra a fonte de um número?
Todo número tem a fonte embaixo do cartão e um link para a tabela de origem. A paleta de comandos leva até lá com duas teclas.
Próximo passo: ver as campanhas que sustentam os números.Ir para a tabela
Tabela de campanhas
Consulta, sem ordem de leitura
10 campanhas4 em alertamelhor: Reativação B
Campanha
Estado
Respostas
Reativação B
no ar
41
Reativação A
alerta
12
Segunda parcela P2
no ar
23
Segunda parcela P3
alerta
9
Segmento moda
rascunho
0
Segmento artesanato
rascunho
0
Boas-vindas
no ar
15
Carrinho parado
alerta
6
Indicação
no ar
4
Pesquisa de saída
alerta
2
Fim do roteiro. Marque o plano como revisado.
O que conferir na oficina: o índice marca a seção visível ao rolar; a paleta responde a Ctrl+K só quando a oficina está na tela; abrir uma pergunta fecha as outras; o glossário abre colado ao termo e vira para cima quando falta espaço embaixo; a tabela mantém o cabeçalho ao rolar; e o aviso de ação oferece desfazer por 6 segundos. Com movimento reduzido ligado no sistema, os cartões aparecem prontos, sem esqueleto nem entrada escalonada.
Passo a passo para pedir tudo isso ao agente de código
O agente acerta quando o pedido traz o contrato: quem usa, de onde parte, quantos passos pode dar, o que acontece sem JavaScript e sem movimento, e como medir. Os sete pedidos abaixo seguem essa ordem e podem ir um por vez, cada um com o anterior já no ar.
Contrato de navegação. Antes de qualquer componente, peça o mapa: lista de páginas, o agrupamento em até 7 itens de primeiro nível e a prova dos dois cliques para as 10 tarefas mais comuns.
Leia o site/ e liste as páginas por grupo. Proponha um menu com no máximo 7 itens
de primeiro nível e mostre, para estas 10 tarefas [lista], o caminho em até 2 cliques
a partir da home. Onde passar de 2, proponha atalho. Nenhum código ainda.
Índice que acompanha a rolagem. Peça o índice nativo com IntersectionObserver, aria-current="location" no link da seção visível e scroll-margin-top igual à altura da barra fixa, para o foco nunca ficar escondido (WCAG 2.4.11).
Crie um índice lateral fixo para as seções h2 desta página. Marque a seção visível
com aria-current="location" usando IntersectionObserver, sem biblioteca. Defina
scroll-margin-top igual à altura do cabeçalho fixo. No celular, o índice vira uma
linha de chips acima do conteúdo. Com prefers-reduced-motion, a rolagem é imediata.
Paleta de comandos. Peça um dialog nativo com input combobox, lista listbox, setas, Enter e Esc, e deixe claro que ela soma à busca visível, sem substituí-la.
Adicione uma paleta de comandos em <dialog> aberta por Ctrl+K e por um botão
"Buscar ou agir" visível no cabeçalho. Input com role="combobox", lista com
role="listbox", navegação por setas, Enter executa, Esc fecha, foco volta ao botão.
Itens: as 8 seções e estas 4 ações [lista]. Busca ignora acento e caixa.
Divulgação progressiva. Peça details com name para acordeão exclusivo, popover para glossário e a regra de que comparação lado a lado nunca fica escondida.
Transforme as perguntas frequentes em <details name="faq"> (um aberto por vez),
summary com 44 px de altura e seta que gira. Termos técnicos viram botão que abre
um popover="auto" ancorado ao termo com position-anchor e position-try-fallbacks;
sem suporte, o popover abre abaixo do termo. Tabelas comparativas ficam visíveis.
Tabela longa e números com fonte. Peça resumo em cima, cabeçalho fixo com position: sticky, "mostrar mais" a partir de 12 linhas e a fonte embaixo de cada número.
Para toda tabela com mais de 12 linhas: resumo com total e destaque acima, cabeçalho
com position: sticky dentro de um rolo com max-height e scrollbar-gutter: stable,
e botão "Mostrar as outras N linhas" com aria-expanded. Todo número em cartão de
destaque recebe a fonte e a data embaixo, em texto pequeno.
Movimento que comunica estado. Peça entrada com @starting-style, esqueleto de carregamento, aviso de ação com desfazer e a barra de leitura em scroll-driven animation com reserva, tudo com prefers-reduced-motion.
Cartões de número: esqueleto enquanto carregam e entrada escalonada de 70 ms por
cartão com @starting-style. Ações concluídas mostram um popover="manual" com
"Desfazer" por 6 segundos. Barra de leitura com animation-timeline: scroll() dentro
de @supports e reserva em JS com scroll passivo. Com prefers-reduced-motion, tudo
aparece no estado final sem transição. Nenhuma biblioteca de animação.
Revisão antes de publicar. Peça a conferência na página servida, em duas larguras, com o detector da Impeccable e o teste de teclado, e registre o que mudou no PR.
Rode npx impeccable detect --json na URL de preview em 1280 e em 390 px. Corrija
texto abaixo de 12 px e contraste abaixo de 4,5:1. Percorra a página só com Tab:
o foco nunca pode ficar atrás da barra fixa. Liste no PR o peso somado dos arquivos
novos e os eventos de medição criados.
Erros que os agentes mais cometem nesses pedidos
Esconder a navegação para "limpar" a tela. O agente troca o menu por um ícone no computador. Peça os itens principais visíveis e cite o estudo de Pernice e Budiu (NN/g, 2016) no pedido.
Animar sem reserva. Sai animation-timeline sem @supports, interpolate-size sem fallback e nenhum prefers-reduced-motion. Peça a reserva em cada recurso parcial da tabela acima.
Trazer biblioteca pesada para uma transição. O agente instala Motion ou GSAP para um fade. Diga "nenhuma biblioteca de animação" quando o CSS resolve.
Copiar exemplo velho. Anime.js v3, Framer Motion com nome antigo e GSAP com aviso de licença paga. Peça a versão e a data no comentário do arquivo.
Acessibilidade de fachada. role="button" em div, aria-label sem texto visível, foco que some no modal. Peça elementos nativos (button, dialog, details, popover) e o teste só com teclado.
Barra fixa que cobre o foco e o alvo das âncoras. Peça scroll-margin-top igual à barra e teste o link do índice no celular.
Cabeçalho fixo que gruda no rolo errado. Com overflow nos dois eixos, o sticky do cabeçalho da tabela prende ao rolo interno e some ao rolar a página; peça overflow: auto clip ou um contêiner de eixo único (Chrome, "Single-axis scroll containers", setembro de 2026).
Skip link que não move o foco. Em 15 sites gerados por IA avaliados pela AudioEye em setembro de 2026, 12 tinham o link "pular para o conteúdo" e nenhum levava o foco ao destino; todos falharam no nível A. Peça o alvo com tabindex="-1" e foco programático.
Seletor gravado no elemento raiz. Gravar um atributo de modo no html e depois varrer "[data-modo]" apanha a raiz inteira; em 21/10/2026 isso apagou uma página deste portal durante a construção. Peça seletores qualificados por tag.
O que é seguro pedir solto e o que exige revisão humana. Saem corretos do agente, quase sempre, os elementos nativos: details, dialog, trilha de navegação, foco visível e popover. Exigem plano, o padrão WAI-ARIA citado no pedido e teste manual de teclado: combobox, árvore de menu, tabela virtualizada e qualquer componente escrito do zero. E só se confirmam no navegador ou com leitor de tela: INP em campo, contraste real nos dois temas e a ordem de leitura. O WebAIM Million de fevereiro de 2026 achou falha em 95,9% das páginas, e o axe-core detecta 57% do volume de problemas (Deque, novembro de 2025); o resto é teste manual.
Checklist antes de publicar uma página ampla
Marque cada item depois de conferir na página servida. A marcação fica guardada só neste navegador.
Medir depois: o que diz se a página ficou mais fácil
A página ampla melhora por medição, nunca por gosto. Três leituras bastam para a primeira releitura, duas semanas depois da publicação: eventos de uso no GA4 para índice, paleta, acordeão e mostrar mais, com o nome da seção como parâmetro, que dizem quais seções recebem leitura e quais merecem reescrita; o INP (Interaction to Next Paint, a métrica de resposta ao toque dos Core Web Vitals) abaixo de 200 ms no percentil 75 em campo, lido no CrUX (relatório de experiência do Chrome, média de 28 dias) ou enviado ao GA4 pela biblioteca web-vitals com atribuição, porque o Lighthouse só carrega a página e mede o Total Blocking Time como aproximação; e o percurso só com teclado e com leitor de tela, repetido a cada mudança de cabeçalho fixo. Quando o acordeão de uma seção abre pouco e a seção é longa, a decisão é reescrever a síntese dela, e a medição aponta por onde começar.
Instrumente a página com eventos GA4 "portal_indice", "portal_paleta", "portal_acordeao"
e "portal_mostrar_mais", cada um com o parâmetro "secao". Escreva um script que lê o
CSV exportado do GA4 e lista as seções por uso, da menos lida à mais lida, com a data
da releitura. Nada de biblioteca de analytics: o Worker já injeta o GA4.
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. A medição corresponde exclusivamente ao arquivo completo citado. Instalações e carregamentos modulares exigem uma medição do conjunto efetivamente utilizado.
Instruções deste guia para agentes de IA (Markdown e JSON)
Regras, decisões, números, erros comuns, código e checklist destilados da página para Claude, Codex e outros agentes. Arquivos: agentes.md · agentes.json · índice dos guias
# Diagramas: instruções para agentes de IA
- Página: Diagramas de arquitetura e fluxo: do texto ao desenho pronto (https://brasilgeo.ai/leadlovers2026/design/diagramas/)
- Revisado em: 2026-11-16
- JSON com o mesmo conteúdo: https://brasilgeo.ai/leadlovers2026/design/diagramas/agentes.json
- Índice dos guias de Design para agentes: https://brasilgeo.ai/leadlovers2026/design/llms.txt
- Esquema: design-guia-para-agentes/v1
Diagrama nasce como texto versionado no repositório e vira SVG no build, nunca no navegador do leitor. A primeira pergunta é quem monta o desenho: quem escreve (Mermaid, D2, Graphviz), quem usa o produto (editor de fluxo) ou a própria rede de dados (grafo). O resultado é uma figura legível nos dois temas, com nome acessível e sem biblioteca na página.
## Quando consultar
- Pedido de fluxograma, sequência, estados, C4, organograma, matriz 2x2 ou outro diagrama de documentação.
- Escolha entre Mermaid, D2 e Graphviz para um diagrama de arquitetura.
- Tela em que o usuário arrasta caixas e salva o fluxo (editor tipo React Flow).
- Diagrama gerado por IA que precisa de validação antes de entrar no repositório.
- SVG exibido no celular, no tema escuro, em e-mail, slide ou arquivo baixado.
## Regras
- **DIA-01** (obrigatória). Antes de escolher ferramenta, responda: quem monta o desenho? Quem escreve usa texto compilado; quem usa o produto precisa de editor de fluxo; rede com milhares de nós usa grafo. Por quê: Errar a família transforma um dia de trabalho em duas semanas.
- **DIA-02** (obrigatória). Se quem olha precisa salvar o que montou, voltar para editar ou enviar a outra pessoa mexer, abandone Mermaid e trate como funcionalidade de produto (React Flow, Excalidraw). Por quê: Teste das três condições do curso: um sim em qualquer uma tira o caso do texto.
- **DIA-03** (obrigatória). Compile o diagrama no build e sirva SVG puro. Nunca embarque o runtime do Mermaid na página de leitura. Por quê: mermaid.min.js 11.16.1 pesa 3,4 MiB sem compressão; o SVG compilado fica perto de 30 KB.
- **DIA-04** (recomendada). Comece com Mermaid até cerca de 12 elementos; acima disso, ou com camadas aninhadas, compare com D2. Por quê: Convenção didática do curso, sem limite técnico; Mermaid também agrupa e aceita layout ELK.
- **DIA-05** (obrigatória). Fixe a versão do Mermaid no package.json e gere o código pela documentação dessa versão. Por quê: Exemplos usam a série 11 (11.16.1); a doc atual já mostra a 12 e a IA inventa sintaxe.
- **DIA-06** (obrigatória). Valide todo código Mermaid com await mermaid.parse() e trate a rejeição antes de renderizar. Depois confira atores, condições, saídas, retornos e exceções contra o processo real. Para definição vinda de fora, mantenha securityLevel: "strict". Por quê: parse() só confere sintaxe; não detecta condição omitida nem sanitiza. strict codifica HTML e desabilita cliques.
- **DIA-07** (obrigatória). Toda seta que sai de uma decisão leva a condição escrita, e o caminho de retorno existe. Por quê: Caixas ligadas sem condição escondem a decisão.
- **DIA-08** (obrigatória). Use accTitle e accDescr em todo Mermaid; em SVG manual, title, desc, role="img" e aria-labelledby. Se o SVG for usado como img, escreva o alt com origem, condição e destino. Por quê: Como img, o title interno não é exposto; PNG descarta os atributos.
- **DIA-09** (obrigatória). Nunca escreva hex solto no diagrama publicado. Injete tokens do projeto com reserva: var(--token, #hex). Por quê: Hex fixo some ao trocar de tema.
- **DIA-10** (obrigatória). Token só alcança SVG inline. Para SVG chamado por img, grave as cores no arquivo ou compile uma versão clara e outra escura e sirva por picture com prefers-color-scheme. Por quê: Como img, o SVG é documento isolado e var(--text) resolve para nada.
- **DIA-11** (obrigatória). No Mermaid, themeVariables aceita só hexadecimal: use uma paleta por tema no compilador ou aplique var() no SVG inline no pós-processo. Por quê: var(--token) passado ao motor não substitui a configuração.
- **DIA-12** (obrigatória). Dê fill explícito a cada text do SVG, sem herança do grupo. Por quê: Rótulo cinza sobre fundo cinza surge quando o preenchimento falha ao herdar.
- **DIA-13** (obrigatória). Contraste nos dois temas: 4,5:1 no texto normal e 3:1 em linhas e formas necessárias à compreensão, medido sobre o fundo real. Por quê: WCAG 2.2, critérios 1.4.3 e 1.4.11; a amostra cinza-claro do guia fica perto de 2:1.
- **DIA-14** (obrigatória). Rótulo com 14 px ou mais na dimensão exibida e nunca abaixo de 12 px a 390 px. Conta: fonte x largura exibida / largura do viewBox. Todo SVG tem viewBox. Por quê: Fonte 15 em viewBox 1200 chega a 4,9 px no celular. O 14 px é referência do curso, não norma.
- **DIA-15** (recomendada). Compile com mmdc usando -I (id único), -c (JSON de configuração) e -p (Puppeteer, sandbox em CI Linux): mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura. Por quê: Sem -I, todo SVG sai com id my-svg e dois diagramas colidem.
- **DIA-16** (recomendada). Uma figura responde uma pergunta só. No C4, um nível por figura (contexto, contêiner, componente, código), começando pelo contexto. Por quê: Contêiner e componente no mesmo quadro produzem desenho que ninguém lê inteiro.
- **DIA-17** (recomendada). Respeite o limite do tipo: fluxograma até 15 caixas, raias até 5, sequência até 8 mensagens, organograma até 4 níveis, árvore de decisão até 3, ER até 15 tabelas; grafo de força só com 20 nós ou mais. Por quê: Acima disso divida a figura ou troque de tipo (catálogo de 36 tipos).
- **DIA-18** (obrigatória). Antes de padronizar um tipo novo ou -beta do Mermaid, confira onde ele precisa renderizar (GitHub, GitLab, VS Code, Obsidian, Notion). Por quê: A versão embarcada de cada plataforma decide o que funciona.
- **DIA-19** (obrigatória). tldraw exige license key em produção; React Flow e Excalidraw são MIT. Confira a licença antes de orçar editor. Por quê: Quem orçou tldraw como MIT precisa refazer a conta.
- **DIA-20** (recomendada). No editor de fluxo, recuse conexão inválida com motivo escrito (nó ausente, autoligação, tipo proibido, duplicata, ciclo), valide o arquivo importado inteiro antes de trocar o estado e exporte com schemaVersion. Por quê: Evita apagar o desenho aberto e laço infinito na busca.
## Decisões rápidas
| Situação | Escolha | Evite |
| --- | --- | --- |
| Time escreve documentação e o leitor só lê | Texto compilado no build (Mermaid, D2 ou Graphviz), saída em SVG. | Biblioteca de diagrama no navegador do leitor. |
| Usuário do produto arrasta, conecta e salva caixas | Editor de fluxo: React Flow ou Excalidraw (MIT). | Mermaid; tldraw sem license key. |
| Milhares de nós e o agrupamento é a resposta | Cytoscape.js (layout cose) ou Sigma.js com Graphology em WebGL. | Grafo de força com menos de 20 nós. |
| Fluxo simples, até cerca de 12 elementos | Mermaid, com poucas linhas e suporte nativo nas plataformas. | |
| Contêineres dentro de contêineres, ou muitos elementos | D2 (agrupamento nativo) com layout ELK; compare com Mermaid. | Subgraphs profundos no Mermaid. |
| Raias horizontais fiéis ou mais de 5 raias | D2 ou Graphviz com clusters. | Mermaid subgraph. |
| Processo com decisão e retorno | Fluxograma com condição na seta. | Sequência (só ordem) e esteira (fila reta). |
| Situações e transições com volta | stateDiagram-v2. | Fluxograma quando o processo é linear sem volta. |
| Causas em paralelo, mais de uma por porquê | Espinha de peixe (flowchart RL com subgraphs). | Árvore de cinco causas, de uma resposta por degrau. |
| Figura vai para e-mail, slide ou download | SVG autocontido: fundo, cores, font-family, xmlns, title e desc; uma versão por tema. | var() sem reserva; id e class da página de origem. |
## Números de referência
| Valor | Para quê | Fonte |
| --- | --- | --- |
| 4,5:1 | Contraste mínimo do texto normal nos dois temas. | WCAG 2.2, 1.4.3 (AA) |
| 3:1 | Contraste mínimo de linhas e formas necessárias à compreensão. | WCAG 2.2, 1.4.11 |
| 14 px | Referência do curso para rótulos na dimensão exibida. | Convenção do curso, não norma |
| 12 px a 390 px | Piso da letra efetiva no celular. | Oficina de SVG legível |
| 12 elementos | Ponto para comparar Mermaid com D2. | Convenção didática do curso |
| 3,4 MiB | Peso do mermaid.min.js 11.16.1 sem compressão (medido em 10/09/2026). | Medição do guia |
| cerca de 30 KB | Peso do SVG compilado. | Guia da aula |
| Mermaid 11.16.1 | Versão de referência (4 de agosto de 2026); mermaid-cli 11.16.0. | Releases do GitHub |
## Erros comuns e a correção
- Erro: Embarcar o motor do Mermaid na página de leitura. Corrija: Compilar no build com mermaid-cli e servir SVG.
- Erro: Confiar no código de IA porque o desenho renderizou. Corrija: parse() mais revisão do processo contra a descrição.
- Erro: Fluxo só com caixas, setas sem condição. Corrija: Nomear cada saída de decisão e o retorno.
- Erro: Mermaid exportado com htmlLabels (foreignObject), que some fora do navegador. Corrija: Gerar com htmlLabels: false para os rótulos virarem text.
- Erro: Ampliar a letra sem ampliar a caixa. Corrija: Aumentar as caixas junto ou quebrar o rótulo em tspan.
- Erro: Usar área de círculo ou faixa como quantidade. Corrija: Avisar na legenda ou trocar por gráfico.
## Padrões de código
### Fluxograma Mermaid acessível
Fluxo com decisão, até cerca de 12 elementos.
```mermaid
flowchart TD
accTitle: Pedido de orçamento
accDescr: Fluxo do pedido com a decisão sobre o CNPJ
A([Lead pede orçamento]) --> B{Tem CNPJ no cadastro?}
B -- sim --> C[Robô responde o preço]
B -- não --> D[Pede o CNPJ antes do preço]
D --> C
C --> E[Cartão entra no CRM]
```
### Contêineres aninhados em D2
Camadas dentro de camadas; acima de 12 elementos.
```d2
cliente: Navegador
servidor: Servidor {
api: API
cache: Cache
}
banco: Banco de dados
cliente -> servidor.api: pede dados
servidor.api -> servidor.cache: consulta
servidor.api -> banco: grava
```
### Validação no build
Script de CI antes de compilar com mmdc.
```js
import mermaid from "mermaid";
mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
try {
await mermaid.parse(fonte); // Promise: use await
} catch (erro) {
throw new Error(`Sintaxe recusada: ${erro.message}`);
}
// Depois: mmdc -i arquitetura.mmd -o public/arquitetura.svg -I arquitetura
// Pós-processo: cores por var(--token, reserva) e fill em cada text.
```
### SVG autocontido e acessível
Figura que vai a e-mail, slide ou download.
```html
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 100" role="img"
aria-labelledby="t d">
<title id="t">Do rascunho à versão aprovada</title>
<desc id="d">Rascunho segue para revisão.</desc>
<style>
.fundo { fill: var(--fundo, #ffffff); }
.caixa { fill: var(--caixa, #edf3f8); stroke: var(--linha, #14589c); stroke-width: 2; }
text { fill: var(--texto, #182b3c); font-family: system-ui, sans-serif; font-size: 18px; }
</style>
<rect class="fundo" width="360" height="100"/>
<rect class="caixa" x="30" y="17" width="300" height="66" rx="8"/>
<text x="180" y="58" text-anchor="middle">Rascunho</text>
</svg>
```
## Checklist antes de entregar
- [ ] A pergunta do desenho está escrita e a família (texto, editor ou grafo) saiu dela.
- [ ] A fonte do diagrama está versionada e o SVG é compilado no build.
- [ ] A versão do Mermaid está fixada e mermaid.parse() passou.
- [ ] Condições, saídas, retornos e exceções conferem com o processo real.
- [ ] Cores vêm de tokens com reserva; nenhum hex solto.
- [ ] Cada text tem fill explícito e fonte de 14 px ou mais (12 px a 390 px no mínimo).
- [ ] Contraste medido nos dois temas: 4,5:1 no texto e 3:1 em linhas e formas.
- [ ] O SVG tem viewBox, title, desc, role="img" e aria-labelledby; como img, tem alt com as relações.
- [ ] O destino real foi aberto: celular a 390 px, tema escuro, e-mail ou arquivo baixado.
- [ ] Tipos novos ou -beta testados nas plataformas de leitura.
## Ferramentas citadas
- **Mermaid 11.16.1**: Fluxo, sequência, estados, C4, Gantt, quadrantChart, mindmap, gitGraph.
- **@mermaid-js/mermaid-cli 11.16.0 (mmdc)**: Compila .mmd em SVG no build; flags -I, -c e -p.
- **D2 v0.7.1**: Contêineres aninhados; layouts dagre, ELK e TALA (proprietário, marca-d'água sem licença).
- **Graphviz 16.0.0**: Motor DOT em manutenção ativa; clusters para raias.
- **React Flow (@xyflow/react 12.11)**: Editor de fluxo MIT; isValidConnection; toObject() serializa o estado.
- **Cytoscape.js 3.34, Sigma.js, Graphology**: Grafos de rede; Sigma usa WebGL.
## Onde aprofundar na página
- [As três famílias, teste de fronteira e modelo C4](https://brasilgeo.ai/leadlovers2026/design/diagramas/#familias)
- [Fluxograma de decisão em Mermaid](https://brasilgeo.ai/leadlovers2026/design/diagramas/#gd-fluxograma)
- [Tipos novos do Mermaid, accTitle, parse e mmdc](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid)
- [Plataformas que renderizam Mermaid](https://brasilgeo.ai/leadlovers2026/design/diagramas/#plataformas)
- [Mermaid, D2 e Graphviz](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid-d2)
- [Contraste e letra nos dois temas](https://brasilgeo.ai/leadlovers2026/design/diagramas/#temas)
- [IA gerando diagramas e validação](https://brasilgeo.ai/leadlovers2026/design/diagramas/#ia)
- [Oficina de SVG legível no celular e no escuro](https://brasilgeo.ai/leadlovers2026/design/diagramas/#oficina-diagrama-legivel)
## Guias relacionados
- [Gráficos](https://brasilgeo.ai/leadlovers2026/design/graficos/): Quando a figura precisa mostrar quantidade ou priorização. Instruções: https://brasilgeo.ai/leadlovers2026/design/graficos/agentes.md
- [Ícones](https://brasilgeo.ai/leadlovers2026/design/icones/): Ícones dentro de nós e legendas. Instruções: https://brasilgeo.ai/leadlovers2026/design/icones/agentes.md
- [Tailwind e tokens](https://brasilgeo.ai/leadlovers2026/design/tailwind/): Tokens de cor e tema claro e escuro que o SVG herda. Instruções: https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md
- [React](https://brasilgeo.ai/leadlovers2026/design/react/): Editor de fluxo com React Flow. Instruções: https://brasilgeo.ai/leadlovers2026/design/react/agentes.md
## Fontes primárias
- [Mermaid: uso e versões](https://mermaid.js.org/config/usage.html)
- [Mermaid: função parse](https://mermaid.js.org/config/setup/mermaid/interfaces/Mermaid.html#parse)
- [Mermaid: acessibilidade](https://mermaid.js.org/config/accessibility.html)
- [D2: contêineres](https://d2lang.com/tour/containers/)
- [WCAG 2.2: contraste de texto](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
Dados desta página para agentes de IA
# Diagramas de arquitetura e fluxo: do texto ao desenho pronto
- Endereço: https://brasilgeo.ai/leadlovers2026/design/diagramas/
- Objetivo: Aula de diagramas para o time, com vídeo e podcast: as três famílias de figura, Mermaid 11, a régua entre Mermaid e D2 e o contraste da WCAG 2.2.
- Tipo: portal-leadlovers-design
- Atualizada em: 2026-11-16
- Publicada em: 2026-08-18
- Idioma: pt-BR
- Indexável: sim
## Seções
1. [A aula, em vídeo e em podcast](https://brasilgeo.ai/leadlovers2026/design/diagramas/#aula-title)
2. [Qual desenho explica o processo que você precisa ensinar?](https://brasilgeo.ai/leadlovers2026/design/diagramas/#laboratorio-desenho-pergunta-title)
3. [Antes da biblioteca: quem monta o desenho?](https://brasilgeo.ai/leadlovers2026/design/diagramas/#familias-title)
4. [Catálogo: trinta e seis tipos de diagrama, cada um com a pergunta que responde](https://brasilgeo.ai/leadlovers2026/design/diagramas/#catalogo-title)
5. [Mermaid na aula: formatos além do fluxograma](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid-title)
6. [Onde o código renderiza sozinho, e onde trava](https://brasilgeo.ai/leadlovers2026/design/diagramas/#plataformas-title)
7. [Mermaid, D2 e o Graphviz que segue vivo](https://brasilgeo.ai/leadlovers2026/design/diagramas/#mermaid-d2-title)
8. [Compilado ao publicar: a figura que se refaz sozinha](https://brasilgeo.ai/leadlovers2026/design/diagramas/#build-title)
9. [Legível nos dois temas: os números da norma](https://brasilgeo.ai/leadlovers2026/design/diagramas/#temas-title)
10. [IA gerando diagramas: o que é real e como validar](https://brasilgeo.ai/leadlovers2026/design/diagramas/#ia-title)
11. [Quando o caso sai do texto: editores e grafos em 2026](https://brasilgeo.ai/leadlovers2026/design/diagramas/#fronteira-title)
12. [Editar um fluxo que sabe recusar uma conexão](https://brasilgeo.ai/leadlovers2026/design/diagramas/#od-editor-title)
13. [Levar o diagrama para fora da página sem perder os rótulos](https://brasilgeo.ai/leadlovers2026/design/diagramas/#od-svg-title)
14. [Prompts prontos](https://brasilgeo.ai/leadlovers2026/design/diagramas/#prompts-title)
15. [Dois guias prontos para o LinkedIn e o Instagram](https://brasilgeo.ai/leadlovers2026/design/diagramas/#llg-guias-title)
16. [Diagrama que se lê no celular e no tema escuro](https://brasilgeo.ai/leadlovers2026/design/diagramas/#osl-title)
17. [Interfaces amplas que se leem sem esforço: UX de 2026 para muita página, menu e link](https://brasilgeo.ai/leadlovers2026/design/diagramas/#ux-ampla-title)
18. [Perguntas frequentes](https://brasilgeo.ai/leadlovers2026/design/diagramas/#faq-title)
19. [Do texto à publicação](https://brasilgeo.ai/leadlovers2026/design/diagramas/#proximo-h)
20. [Fontes e notas da aula](https://brasilgeo.ai/leadlovers2026/design/diagramas/#fontes-title)
## Links principais
- [Início do portal](https://brasilgeo.ai/leadlovers2026/)
- [Design](https://brasilgeo.ai/leadlovers2026/design/)
- [menus, abas e paginação](https://brasilgeo.ai/leadlovers2026/design/navegacao/)
- [Baixar o vídeo](https://brasilgeo.ai/media/leadlovers/r2/design-diagramas/aula-diagramas.mp4)
- [Compartilhar](https://brasilgeo.ai/leadlovers2026/design/diagramas/)
- [ambiente de produção](https://brasilgeo.ai/leadlovers2026/glossario/)
- [Baixar o podcast](https://brasilgeo.ai/media/leadlovers/r2/design-diagramas/aula-diagramas.m4a)
- [Baixar a ilustração](https://brasilgeo.ai/leadlovers2026/media/laboratorios/desenho-pergunta.svg)
- [Baixar o editor nativo executado nesta página](https://brasilgeo.ai/leadlovers2026/design/diagramas/oficinas-diagramas.js?v=20261006)
- [Baixar o código desta oficina](https://brasilgeo.ai/leadlovers2026/design/diagramas/oficina-svg-legivel.js?v=20261006-impeccable)
- [Baixar o código desta oficina](https://brasilgeo.ai/leadlovers2026/design/diagramas/ux-ampla.js?v=20261021)
- [o CSS](https://brasilgeo.ai/leadlovers2026/design/diagramas/ux-ampla.css?v=20261021)
- [securityLevel: "strict"](https://mermaid.js.org/config/schema-docs/config-properties-securitylevel.html) (externo)
- [API retorna uma Promise](https://mermaid.js.org/config/setup/mermaid/interfaces/Mermaid.html) (externo)
- [FAQ oficial](https://docs.excalidraw.com/docs/%40excalidraw/excalidraw/faq) (externo)
- [laboratório de registro de componentes](https://alexandrecaramaschi.com/educacao/frontends-com-vibecoding/laboratorios) (externo)
- [pauta de estados e eventos](https://alexandrecaramaschi.com/educacao/frontends-com-vibecoding/animacoes-avancadas) (externo)
- [validação de conexões](https://reactflow.dev/examples/interaction/validation) (externo)
## Para agentes
- JSON com os mesmos dados no elemento script#pagina-para-agentes (esquema pagina-brasilgeo-para-agentes/v1).
- JSON-LD da página no <head>: Article, VideoObject, AudioObject, BreadcrumbList, FAQPage.
- Índice do site para agentes: https://brasilgeo.ai/llms.txt
- Listas resumidas para caber em 12 KB (sem subtítulos); a página completa está no endereço acima.