Pular para o conteúdo

Diagramas de arquitetura e fluxo

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

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

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

Ilustração editorial em índigo e azul-marinho: uma folha de código à esquerda se transforma, por uma seta fluida com filete rosa-carmim, num fluxograma de caixas conectadas à direita
Texto versionado convertido em diagrama. Ilustração gerada por IA para esta aula.

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

A aula, em vídeo e em podcast

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

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

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

As saídas estão nomeadas

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

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

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

O desenho só tem caixas

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

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

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

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

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

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

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

Antes da biblioteca: quem monta o desenho?

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

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

1. Você escreve, a máquina desenha

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

2. Quem usa o produto arrasta as peças

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

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

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

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

O modelo C4: o que entra em cada figura

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

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

Mermaid na aula: formatos além do fluxograma

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

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

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

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

Dois recursos merecem lugar fixo no fluxo do time. O primeiro é a dupla accTitle e accDescr, que insere <title> e <desc> no SVG com os atributos ARIA correspondentes, disponível para todos os tipos de diagrama (documentação do Mermaid): a figura ganha nome e descrição para leitor de tela sem uma linha de CSS. O benefício sobrevive apenas onde o SVG é preservado; rasterizar para PNG descarta os atributos.

O segundo é a função 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.
PlataformaO que renderizaA letra miúda
GitHubBlocos mermaid em issues, discussions, pull requests, wikis e arquivos MarkdownA versão embarcada é a que o GitHub escolhe; plugins de terceiros podem conflitar
GitLab.comBlocos mermaid no MarkdownA documentação atual informa Mermaid 11. Confira o tipo de diagrama e a versão da instância antes de padronizar o uso
VS CodePreview de Markdown, células de notebook e chat, com pan, zoom e cópia do fonteNativo desde a 1.121 (extensão embutida "Mermaid Markdown Features"); o chat renderiza desde a 1.109
ObsidianBlocos mermaid nas notasVersão embarcada sem declaração na doc
NotionBloco de código Mermaid pelo atalho /mermaidAtalho documentado na release de agosto de 2022

Documentações oficiais de GitHub, GitLab, VS Code, Obsidian e Notion. Pesquisa inicial em 18/08/2026; suporte do GitLab conferido novamente em 10/09/2026.

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

Mermaid, D2 e o Graphviz que segue vivo

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

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

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

A régua do curso: até uma dúzia de elementos, começar com Mermaid; acima disso, ou com camadas aninhadas, comparar o resultado com D2. Essa é uma convenção didática, sem limite técnico de doze nós. O Mermaid também aceita agrupamentos e o layout ELK. A decisão deve considerar cruzamento de setas, legibilidade dos rótulos, controle de posição e manutenção do código. O D2 oferece contêineres aninhados como parte da linguagem.

Compilado ao publicar: a figura que se refaz sozinha

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

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

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

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

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

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

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

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

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

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

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

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

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

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

IA gerando diagramas: o que é real e como validar

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

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

A empresa por trás do Mermaid vende o Mermaid AI (descreva, envie um documento ou cole uma transcrição e receba o diagrama), com servidor MCP para Claude, VS Code e Cursor. No ChatGPT e em outros assistentes, confira a superfície usada para exibir o resultado. Gerar código, renderizar uma prévia e exportar SVG são capacidades diferentes; valide a entrega no destino escolhido.

Validar sintaxe e conferir significado são etapas diferentes. 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

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

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

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

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

React Flow (xyflow)

Licença MIT MIT

A série 12.11 consultada usa licença MIT. A assinatura Pro oferece exemplos avançados e suporte. Persistência oficial: toObject() serializa nós, arestas e viewport em JSON.

tldraw

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

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

Excalidraw

Licença MIT MIT

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

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.
Como o editor decide aceitar ou recusar uma conexão À esquerda, o grafo com quatro nós em coluna: Rascunho, Revisão, Aprovação e Publicação simulada, ligados de cima para baixo. Uma seta tracejada de alerta sai de Aprovação e volta para Revisão, representando o pedido. À direita, a cadeia de testes em ordem: o pedido chega; passam os testes simples de nó existente, origem diferente do destino, tipos e duplicata; a busca em profundidade parte do destino e pergunta se chega à origem; se chega, a conexão é recusada com motivo e o grafo fica intacto; se não chega, a conexão entra e a figura é redesenhada. Embaixo, a exportação grava o documento com schemaVersion 1 e a importação valida o texto inteiro antes de trocar o estado. Grafo do processo Rascunho Revisão Aprovação Publicação simulada pedido pedido: Aprovação para Revisão Testes simples, nesta ordem nó existe, origem difere do destino, tipos, duplicata Busca em profundidade a partir do destino alcanca(Revisão, Aprovação)? Alcança: ciclo recusada com motivo, grafo intacto Não alcança: aceita edges.push e render() Exportar documento schemaVersion: 1 Importar: validar tudo antes de trocar o estado

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Exportar serializa o estado com schemaVersion 1 e dispara o download por Blob (objeto de arquivo em memória) e URL temporária.
  7. 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
OrigemDestinoResposta
AprovaçãoRevisãoRecusada: criaria um ciclo
RascunhoRevisãoRecusada: já existe
RevisãoRevisãoRecusada: nó aponta para si mesmo
Publicação simuladaRascunhoRecusada: tipos de saída e entrada
RascunhoAprovaçãoAceita: atalho válido, percurso continua completo

Selecione um nó para renomeá-lo ou escolha origem e destino. O JavaScript precisa estar ativo para editar.

  1. Rascunho
  2. Revisão
  3. Aprovação
  4. 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

  1. 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.
  2. 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.
  3. 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
SintomaCausa provávelComo confirmarCorreção
O desenho some ao colar um arquivo com erroO 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 pilhaA 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 listaO 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 antigoA 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ãoO 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 avisoO 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.

O laboratório de registro de componentes ajuda a documentar um tipo de nó reutilizável. A pauta de estados e eventos propõe controlar a animação quando chegam novos comandos; aqui o contrato validado é o processo desenhado.

Fontes oficiais React Flow: validação de conexões, prevenção de ciclos, salvar e restaurar e acessibilidade dos controles. Sobre o download por arquivo em memória: MDN, URL.createObjectURL.

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.
O mesmo SVG em três destinos e o que se perde em cada um À esquerda, a caixa do SVG escrito na página, com cor por variável CSS, fonte herdada, fundo da página e title e desc. Três setas levam aos destinos no centro: inline no HTML, onde tudo da página vale; como img externo, onde as variáveis somem, a fonte precisa ser nomeada, o fundo fica transparente e vale o alt; e arquivo baixado, onde só existe o que está gravado no XML e a fonte é a do sistema de quem abre. À direita, o que a oficina faz: a função render grava fundo, preenchimento e traço em cada elemento; uma cópia sem id nem class é serializada e vira URL data para a imagem e Blob para o download; por fim, a conferência no destino real, com alt e contraste sobre o fundo verdadeiro. SVG escrito na página fill="var(--text)" font: herdada do body fundo: o da página <title> e <desc> Inline no HTML herda CSS, fonte, cor e fundo leitor de tela lê o title Como <img> externo var() some, fonte só se nomeada fundo transparente, vale o alt Arquivo baixado só o que está gravado no XML fonte: a do sistema de quem abre render() grava a paleta fill="#182b3c" rect de fundo com a cor do tema font-family nomeada no text cópia sem id e class XMLSerializer, URL data: no img Blob e URL temporária no download Conferir no destino alt no img, contraste no fundo real abrir o arquivo fora do site

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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
PapelPaleta claraPaleta 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
Do rascunho à versão aprovadaRascunho segue para revisão. A revisão libera a versão aprovada. Exemplo didático sem integração com publicação real. Rascunho Revisão Versão aprovada Cenário didático
O mesmo SVG como imagem externa
Relações que a figura precisa preservar
OrigemCondiçãoDestino
RascunhoEnviar para conferirRevisão
RevisãoConteúdo aprovadoVersão aprovada

Confira o arquivo no destino em que será usado

  1. 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.
  2. 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.
  3. 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
SintomaCausa provávelComo confirmarCorreção
No e-mail ou no slide, as caixas aparecem vaziasO 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 caixaO <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 destinoO 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 apareceA 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 destinoO 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.

Use o laboratório de auditoria de interface para guardar a evidência antes e depois. A pauta de anotações responsivas estuda outra extensão, com rótulos sobre imagens recortadas. Fontes: MDN, SVG como imagem, MDN, o elemento picture, Mermaid, acessibilidade e D2, contêineres.

Prompts prontos

Diagrama de arquitetura compilado na publicação

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

Requisitos:
- Compile o D2 para SVG no passo de build (nunca no navegador do leitor).
- Injete os tokens de cor do projeto (var(--accent), var(--text),
  var(--border)) no SVG gerado; nada de cores hardcoded.
- Todo <text> com fill EXPLÍCITO. Adote a referência do curso de
  14px na dimensão exibida e confira ampliação e legibilidade.
- Use layout ELK; agrupe por camada com contêineres aninhados.

Critérios de aceite:
1. O SVG final não referencia nenhuma lib em runtime.
2. Rodei o auditor de contraste e todo texto passa AA (4,5:1) e
   as partes gráficas necessárias à compreensão passam 3:1 (WCAG 2.2, critérios 1.4.3 e 1.4.11).
3. Compare Mermaid e D2 se o desenho ficar denso ou exigir grupos aninhados.
   A regra de 12 nós é uma convenção deste curso, não um limite técnico.
4. As setas têm rótulo quando o tipo de chamada não é óbvio.

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

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

Critérios de aceite:
1. O código passa em mermaid.parse() sem erro de sintaxe.
   Confira separadamente entradas, condições, retornos e destinos: o parser
   não verifica se o processo descrito corresponde à realidade.
2. Cada nó tem rótulo em português, sem abreviação inventada.
3. Se você não tiver certeza de uma sintaxe, diga que não tem,
   em vez de arriscar.

Auditoria de uma figura antes de publicar

Audite o SVG anexo nos dois temas do site (claro e escuro):
1. Confira o fill calculado de cada <text>, inclusive quando herdado,
   e marque fontes menores que 14px na dimensão exibida (convenção da aula).
2. Meça o contraste de cada rótulo contra o fundo real e aponte o que
   fica abaixo de 4,5:1; confira 3:1 nas partes gráficas necessárias
   à compreensão (WCAG 2.2).
3. Confirme a presença de <title> e <desc> acessíveis.
4. Devolva a lista de correções em ordem de impacto, sem reescrever
   o arquivo inteiro.
Infográfico da aula: as três famílias de figura (você escreve com Mermaid ou D2, o usuário arrasta com React Flow, os dados formam a rede com Cytoscape), a régua de uma dúzia entre Mermaid e D2, o pipeline de compilar no build (versão em texto, gera SVG no build, serve sem bibliotecas) e o contraste WCAG de 4,5:1 conferido nos temas claro e escuro.
A aula inteira num quadro: as três famílias, a régua de uma dúzia, o pipeline de build e o contraste nos dois temas. Infográfico gerado no NotebookLM a partir do dossiê da aula.
Guias para postar

Dois guias prontos para o LinkedIn e o Instagram

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

Design · Diagramas como códigoLeadlovers 2026

O diagrama nasce em texto e compila no build

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

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

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

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

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

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

Nenhum rótulo da figura pode sumir na tela

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

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

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

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

#Leadlovers #Acessibilidade #Diagramas #WCAG

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

  1. 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.
  2. 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.
  3. 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.
Do SVG colado à versão legível no celular e no tema escuro Na linha de cima, o código SVG colado entra no DOMParser com limpeza de script, foreignObject e atributos de evento, e a largura escolhida é 390 pixels. Na linha do meio, três conferências em alerta: a letra, com a conta 15 vezes 390 dividido por 1200 igual a 4,9 pixels, abaixo de 12, fator sugerido 3,08; as cores fixas, com cinco valores como o azul 1e2365 e o cinza 999999 que somem no tema escuro; e o acesso, sem title, desc, role img e aria-labelledby. Na linha de baixo, a função corrigir multiplica as letras pelo fator em style, troca cada cor por var com a cor original de reserva e insere title e desc com role img; ao lado, a prévia como imagem por URL data sobre fundo claro ou escuro, com o SVG corrigido e o mapa de cores para copiar. Código SVG colado DOMParser e limpeza sem script, foreignObject e on* largura escolhida 390 px (celular) 1. Letra efetiva 15 × 390 ÷ 1200 = 4,9 px abaixo de 12: fator 3,08 2. Cores fixas #1e2365, #999999, #bbbbbb somem no tema escuro 3. Nome acessível sem title, desc e role="img" leitor de tela diz só "imagem" corrigir() letras × 3,08 em style: 15 vira 46,2 fill: var(--diagrama-cor-1, #1e2365) title, desc, role="img", aria-labelledby Prévia e saída img com URL data:, fundo claro ou escuro SVG corrigido para copiar mapa de cores para o CSS da página

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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
ItemAntesDepois
Rótulos das caixas15 px declarados, 4,9 px na tela46,2 px declarados, 15,0 px na tela
Nota de rodapé12 px declarados, 3,9 px na tela37 px declarados, 12,0 px na tela
Cores fixas5 valores em 15 usos5 variáveis com valor de reserva
Nome acessívelSem title, desc, role e aria-labelledbyOs 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
SintomaCausa provávelComo confirmarCorreção
Rótulos viram riscos no celularO 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 caixaO 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 escuroCores 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 telaO 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.

Fontes: MDN, o atributo viewBox, MDN, DOMParser, W3C, SVG Accessibility API Mappings e Mermaid, acessibilidade.

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.

Três camadas de leitura num portal amplo A camada de síntese, no topo, tem painel com números e guia em quatro passos. A camada de roteiro, no meio, tem índice que acompanha a rolagem, trilhas por papel e próximo passo. A camada de fonte, embaixo, tem seções completas, tabelas longas e glossário. Setas descem da síntese ao roteiro e do roteiro à fonte, e setas de volta sobem. Um ponto pulsante marca a posição atual no roteiro. Camada 1: síntese que cabe numa tela painel com números e fonte, guia em 4 passos, decisões por estado, paleta de comandos Camada 2: roteiro que conduz índice que acompanha a rolagem, trilhas por papel, tempo de leitura, próximo passo ao fim de cada seção aqui Camada 3: fonte completa seções inteiras, tabelas longas com cabeçalho fixo e mostrar mais, glossário em popover, fontes datadas volta volta
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ãoQuando usarQuando evitarEvidência e referênciaQuem 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ívelPortal 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.GitHub Docs, Shopify Polaris, GOV.UK Design System.
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 summaryPerguntas 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 computadorSó 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 leituraArtigo 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çãoGuia 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 papelMesmo 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 visualPortal 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 rolarCelular, 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.

RecursoServe paraSuporte em 21/10/2026Como pedir ao agente
details com nameAcordeã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 APIGlossá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 PositioningPrender 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 nativoPaleta 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-discreteAnimar 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-gutterTí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-schemeCor 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: contentCaixa de texto que cresce com o que a pessoa digita.Baseline desde junho de 2026."textarea com field-sizing: content e max-height."
overflow-anchorA 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áginaTrocar 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áginasTransiçã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-scopeDisparar 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çãoPeso gzip (jul. 2026)LicençaUse quandoO que costuma sair errado do agente
CSS e Web Animations API0 KBNativoHover, foco, entrada, acordeão, barra de leitura, revelação ao rolar.Esquecer prefers-reduced-motion e animar height sem interpolate-size.
motion/mini3,4 KBMITSequê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 scrollMITLinha 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/reactMITInterface em React com entrada, saída e layout.Animar lista sem key estável, perdendo a identidade do item.
GSAP core e ScrollTrigger28,2 KB; 46,1 KB com ScrollTriggerGratuito desde a 3.13, 30/04/2025, com cláusula contra ferramentas sem código concorrentes do WebflowRolagem presa, pin, linha do tempo com rótulos, MorphSVG.Não limpar o ScrollTrigger ao desmontar; scrub acima de 1 segundo.
Lottie e RiveLottie-web perto de 60 KB; runtime Rive menor, variável por recursoMIT (lottie-web); Rive com runtime aberto e editor próprioIlustração animada e personagem com máquina de estados.Arquivo JSON pesado em cima da dobra; sem imagem de reserva.
cmdk e Sonner17,1 KB (cmdk 1.1.1); 9,2 KB (Sonner 2.0.8)MITPaleta 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-animateperto de 2 KB (3,2 KB na 0.9.0 pelo Bundlephobia)MITLista 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.

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.

  1. 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.
  2. Í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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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

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.

Consultar a documentação citada
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.