Escolher mapas, diagramas e cenas espaciais

Um mapa só vale a tela quando a geografia muda a decisão; quando um ranking por estado responde, a tabela ordenada vence. Quem escolhe entre mapa e lista para o próprio site termina com o teste que decide, o mapa sem chave paga e a cor que diz a verdade.

Antes de instalar qualquer biblioteca (o pacote de código pronto que desenha o mapa na tela), faça o teste do embaralhamento: troque o Acre de lugar com Sergipe. Se a conclusão continua a mesma, a geografia não muda a decisão, e uma lista ordenada resolve melhor.

Passam no teste a rota de entrega e o raio de atendimento de uma clínica, porque a distância entre os pontos é a própria resposta. Reprova quase sempre a penetração por estado, porque a cor muda a leitura sem mudar a decisão. O mapa custa tela e atenção, e precisa devolver algo que a lista não devolve.

Quando o mapa vence o teste, escolha o degrau mais baixo que resolve. O Leaflet põe meia dúzia de marcadores no ar numa tarde; fique na série 1, porque a 2.0 segue em alfa, sem data, e migrar hoje é aposta.

O MapLibre desenha o mapa vetorial, aquele que chega como desenho e não como foto, e por isso continua nítido em qualquer aproximação. Nele o mapa é feito de camadas empilhadas: uma para as ruas, outra para os bairros, outra para os seus pontos. Cada camada liga, desliga e muda de cor por conta própria.

Acima de centenas de milhares de pontos entra o deck.gl, porque manda o desenho para a placa de vídeo. Abaixo desse volume ele só pesa. O Kepler.gl explora o dado sem escrever código, e o trio com deck.gl e MapLibre é a pilha de geomarketing.

Mapbox GL JS entra só quando a licença paga já existe. O OpenLayers fica para trabalho de GIS, porque lê projeções, as várias maneiras de achatar a Terra redonda numa tela plana, que as outras bibliotecas não abrem.

O mapa sem chave troca a chave de API (a senha paga que libera cada carregamento do mapa) por um único arquivo PMTiles hospedado por você. O navegador pede só o trecho do arquivo que precisa, como quem lê duas páginas de um livro sem comprar o volume inteiro, e nenhum servidor conta pedido.

Todo dia o Protomaps publica uma versão nova do mapa-base do OpenStreetMap, o mapa aberto que qualquer um pode baixar. Você troca fatura variável por armazenamento fixo e agenda a atualização do arquivo, porque mapa desatualizado custa o mesmo trabalho do mapa correto.

A montagem tem ordem. Recorte só o território que precisa. Suba o arquivo com entrega parcial ligada, senão cada visita baixa o arquivo inteiro. Registre o protocolo antes de criar o mapa, senão o erro chega disfarçado de falha de rede.

O erro mais fácil de cometer é colorir pelo número bruto. Vendas e clientes crescem junto com a população, e o mapa vira uma cópia do mapa demográfico.

Escolha o denominador (o número que divide o dado, como habitantes ou domicílios) antes da cor, e escreva o nome dele na legenda. A figura circula sozinha, e o que só você sabe não protege ninguém.

Numa imobiliária, a pergunta sobre qual bairro vende mais rápido passa no teste, e o mapa entra com MapLibre v6 lendo um PMTiles do próprio armazenamento. A pergunta sobre qual imóvel tem o menor preço reprova, e a lista ordenada resolve sem mapa.

Colorir pelo número de imóveis vendidos faz o bairro mais populoso brilhar. Dividir pelo total de imóveis do bairro mostra onde a venda é proporcionalmente mais forte, com o denominador escrito na legenda.

Antes de publicar o mapa, teste o embaralhamento na última pergunta que ele responde e confirme que ainda há geografia real ali. Divida sempre pelo denominador certo e confira na aba de rede do navegador que só o seu domínio aparece nas requisições.

Escolher o tipo de diagrama e montar o editor visual dele

O mapa entra quando a geografia muda a resposta, e relação e sequência pedem outra família, com o editor visual separado do painel que a equipe abre.

Diagrama é uma palavra para três famílias com preços diferentes. Quem desenha decide a família: você em texto, o cliente arrastando peças ou ninguém, porque a rede se acomoda sozinha. Quem pede a peça para o próprio site aprende a nomear a família certa, separar o editor visual do painel e recusar o 3D que raramente vale.

Na primeira família você escreve o desenho em texto e a máquina decide onde cada caixa fica. Isso vale a pena porque o diagrama passa a viver junto do código, e muda com ele. O Mermaid resolve até 12 elementos, a régua do hub de design; acima disso, ou com camadas dentro de camadas, o D2 agrupa melhor.

O modelo C4 (quatro níveis de zoom: contexto, contêiner, componente e código) define o que entra em cada figura. Um diagrama que mistura o nível de contexto com o de código fica ilegível para os dois públicos.

Saída de IA passa pelo portão mermaid.parse() antes de virar figura, porque o agente erra sintaxe em silêncio. O compilador mmdc roda na publicação e entrega SVG estático com as cores do site, e a figura se refaz sozinha a partir do mesmo texto.

A armadilha de tema derruba o diagrama pronto. O SVG chamado como imagem externa não enxerga as cores da página, e por isso o texto preto some quando o leitor liga o tema escuro. Cole o SVG dentro da própria página, ou gere duas versões, clara e escura, e dê cor própria a cada texto do desenho.

Depois disso, guarde uma captura do diagrama a cada publicação e compare com a anterior. É assim que você descobre que uma palavra a mais empurrou uma caixa por cima da outra.

Na segunda família quem usa o produto arrasta, conecta e apaga peças, e o desenho vira parte do que ele contratou. O React Flow e o Svelte Flow tratam cada nó como uma peça rica, com formulário e estado próprios.

O tldraw transforma rascunho em página pronta por IA. O Excalidraw converte Mermaid em formas editáveis e sincroniza o quadro via Yjs, a tecnologia que deixa várias pessoas desenharem juntas sem uma apagar a outra.

Editor sério, com conectores que grudam na peça e com desfazer, é categoria própria: GoJS ou JointJS sobre um canvas como o Konva ou o PixiJS. O Konva traz a alça que move e redimensiona, além de ligações para React, Vue, Svelte e Angular.

O Fabric.js faz editor de imagem tipo Canva, com ida e volta para SVG. O Paper.js teve a última versão em julho de 2024, sinal de manutenção lenta, então prefira Fabric ou Konva.

Nunca use a mesma pilha para o painel e para o editor visual: ECharts ou D3 de um lado, JointJS ou GoJS com Konva do outro. Os dois resolvem problemas opostos, porque um mostra número fechado e o outro guarda o desenho que alguém ainda está mexendo.

Na terceira família o desenho é a própria rede: cadeia de fornecedores, quem indicou quem, quais páginas apontam para quais. Essa rede tem nome técnico, grafo, e é só isso: pontos, chamados nós, ligados por linhas, chamadas arestas.

O Cytoscape.js já traz as contas que apontam quem é o nó central e quem ficou isolado. O vis-network deixa os pontos se acomodarem sozinhos, como ímãs que se repelem. O Sigma.js com Graphology desenha mais de 100 mil nós usando a placa de vídeo.

Acima desse teto, o deck.gl com WebGPU, a via mais nova de falar com a placa de vídeo, é o degrau seguinte.

O 3D obedece à regra do conselho: em relatório executivo é quase sempre vaidade, porque impressiona sem esclarecer. Ele vale na vitrine institucional, na página de produto e na peça artística.

Quando vale, o Three.js é a base, e já desenha pela via nova da placa de vídeo em produção. Com o Safari embarcando essa via, ela virou o piso do mercado. Quem escreve em React usa o React Three Fiber com Drei, e há equivalentes no Vue e no Svelte.

O gaussian splatting (a captura fotorrealista feita de milhões de pontos coloridos, como uma foto que dá para girar) ganhou o Spark, da World Labs. Ele transmite mais de 100 milhões desses pontos sobre o Three.js, inclusive em celular e em óculos de realidade virtual.

Para o caso mais simples, o model-viewer mostra um arquivo GLTF sem uma linha de código. O Globe.gl faz globo de dados quando a geografia muda a decisão.

Numa escola, o fluxo de matrícula tem nove caixas e sai em Mermaid compilado no build, no nível de contexto do C4. A coordenação que quer montar trilhas arrastando disciplinas pede outra família, o React Flow, com outro orçamento. O gráfico 3D no relatório à mantenedora sai do pedido, porque impressiona sem esclarecer.

Antes de pedir a próxima peça, escreva a família na primeira linha do pedido ao agente: texto compilado, editor com nós ou rede. Só aceite 3D em vitrine, produto ou peça artística, e mantenha painel e editor em pilhas separadas. Deu certo quando o diagrama cabe na tela e ninguém pergunta o que cada caixa significa.

Guia prático: o globo bonito da biblioteca e o custo que vem junto

Globo girando e mapa com pontos acesos viraram enfeite comum de página de SaaS, e quase sempre chegam por uma biblioteca de componentes. Na biblioteca de 1.451 componentes estudada em 07/10/2026, a busca por globos, mapas e diagramas nas tags, categorias e descrições deu este quadro:

São 43 componentes no total, e 21 deles desenham em WebGL. A biblioteca d3 aparece em 1 e three em 2. No acervo inteiro, 319 componentes usam WebGL, shader ou biblioteca 3D, 22% do total, e 245 desses não declaram dependência nenhuma, porque o código de desenho vem escrito dentro do componente. Dos 43, 28 trazem exemplo de uso preenchido e nenhum desses trata a preferência por menos movimento; 14 não têm licença declarada.

O cobe, a dependência dos globos, se apresenta como biblioteca de cerca de 5 kB, sem dependências e sob licença MIT. O peso de download é pequeno; o custo está no desenho contínuo na placa de vídeo, que gasta bateria enquanto gira. Este capítulo já ensina o teste do embaralhamento: um globo que só diz "atendemos o mundo" não passa nele. A lição: trate o globo como peça de vitrine, com orçamento, pausa e alternativa parada, e não como mapa.

Aplicar os recursos ao projeto