# Atlas — pesquisa do mapa holográfico e card de agente

Data: 10 de setembro de 2026. Pesquisa para o próximo design system; nenhuma alteração no site ou publicação realizada por esta frente.

## Direção recomendada

Manter o MapLibre como motor geográfico e construir a assinatura visual do Atlas em três objetos coordenados: um **mini retrato projetado sobre a cidade do cliente**, um **vínculo luminoso de seleção** e um **card lateral com busto grande em vidro escuro**. O impacto da referência vem da composição, escala do retrato e iluminação de borda. Adicionar bibliotecas sem resolver esses três pontos não corrige a distância visual.

As dimensões, durações e orçamentos abaixo são propostas de design a validar no protótipo, não resultados de benchmark. Fontes consultadas são documentação oficial, código instalado e trabalhos dos próprios estúdios.

## Auditoria concreta: o que separa o atual da referência

Código inspecionado: `site/features/atlas/Globe.tsx`, `AgentCard.tsx`, `AtlasApp.tsx` e `site/app/globals.css`.

| Elemento | Situação no código | Distância da imagem aprovada | Direção de correção |
|---|---|---|---|
| Retrato | `AgentAvatar` circular; variante grande começa em 136 px e é reduzida a 96 px no dock desktop; máscara radial apaga a silhueta | Na referência o busto ocupa aproximadamente a metade superior do card e tem contorno visível | Área de retrato vertical de 220–260 px no desktop, busto com ombros, sem máscara circular; manter o rosto nítido |
| Card | Dock de 300 px, orientação frontal, fundo em gradiente, blur 28 px | Referência tem placa lateral larga, sensação de espessura, perspectiva discreta e luz percorrendo o perímetro | Card de 340–380 px conforme tela; borda de luz direcional, segunda borda interna, superfície interior calma e leve perspectiva |
| Identidade no mapa | Pontos de raio 5 px, halo 17 px; só o selecionado recebe botão DOM com anel e nome | O usuário quer reconhecer o avatar antes de clicar | Retratos DOM nos pontos individuais, grupos com contagem e miniaturas; prioridade ao selecionado |
| Vínculo geográfico | Card aparece no dock, sem ligação ao ponto | Na referência uma linha conecta Orlando e o card | Um único traço SVG entre ponto e entrada lateral do card, sincronizado com câmera |
| Densidade | Card mostra cabeçalho, identidade, cliente, descrição, três especificações, ações e rodapé | Retrato compete com detalhes administrativos | Vista inicial prioriza rosto, nome, cidade, status, especialidade e infraestrutura; detalhes adicionais em expansão acessível |
| Loading | Um anel CSS de 78 px e texto “Conectando o mundo” | Não comunica a linguagem orbital nem as etapas reais de entrada | Logo como núcleo, arcos de calibração e mensagens de etapas reais; liberar exploração assim que disponível |

O CSS possui múltiplas redefinições de `.hologram-dock`, `.hologram-identity` e `.agent-avatar.large`. O redesign deve consolidar variantes explícitas (exploração desktop, exploração mobile, story vertical, story horizontal), evitando adicionar outra camada de sobrescritas ao fim do arquivo.

## Pino holográfico — anatomia

1. **Âncora geográfica:** núcleo de 4–6 px colocado exatamente na coordenada do cliente. Uma elipse luminosa de aproximadamente 24 × 8 px mostra o contato com o planeta. É uma representação da cidade, sem inventar precisão de rua.
2. **Projeção:** haste de 12–18 px, fina, com brilho decrescente; nasce na âncora e sustenta o retrato. Uma leve abertura em leque pode sugerir emissão sem parecer uma barra de energia.
3. **Retrato:** moldura vertical de cerca de 40 × 48 px no estado base, cantos suaves de 12 px. Usar o mesmo arquivo e o mesmo enquadramento focal do agente selecionado. A silhueta é mais reconhecível que um pequeno círculo com muitos detalhes.
4. **Vidro:** fundo escuro translúcido, borda de 1 px, realce frio em um canto e reflexo quente discreto no canto oposto. Brilho deve delinear o retrato, sem lavar o rosto.
5. **Estado:** ativo usa ponto sólido e texto acessível; futuro usa anel aberto e rótulo “Em breve”; pausado usa desenho interrompido e rótulo. Cor é apoio, não o único código.
6. **Área acionável:** botão com pelo menos 44 × 44 CSS px e espaço que não intercepte vizinhos. Essa é a meta confortável do Atlas; WCAG 2.2 AA define 24 × 24 px ou condições de espaçamento/exceções, não 44 px. [W3C — Target Size Minimum](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)

O `Marker` oficial aceita elemento HTML, âncora, offset e alinhamento ao viewport; portanto o mini retrato não precisa ser uma cena Three.js. Usar `pitchAlignment: 'viewport'` e `rotationAlignment: 'viewport'` mantém o rosto legível durante a rotação. [MapLibre — MarkerOptions](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/)

### Estados e comportamento

| Estado | Visual e interação |
|---|---|
| Repouso | Retrato visível, luz estável, sem todos os nomes permanentemente abertos |
| Hover ou foco | Elevação de 2 px e nome + cidade; nenhum voo automático ao passar o mouse |
| Pressionado | Pequena compressão visual; reconhecer o toque antes do voo |
| Selecionado | Moldura cresce a aproximadamente 48 × 58 px, nome persiste, um pulso de confirmação, traço para o card |
| Câmera em movimento | Rostos continuam nítidos; suspender pulsos e detalhes periféricos |
| Encoberto pelo planeta | Sem retrato fantasma, clique ou parada de Tab do outro lado do globo |
| Imagem indisponível | Monograma do agente e a mesma moldura, sem ícone de imagem quebrada |
| Movimento reduzido | Estados instantâneos ou dissolve breve; sem órbita, flutuação ou voo longo |

MapLibre adiciona a classe pública `maplibregl-marker-covered` quando o marcador fica atrás do terreno ou do globo. Usar `opacityWhenCovered: 0`, ocultar eventos e garantir que elementos cobertos não recebam foco; não confiar apenas em opacidade zero. A documentação de opções descreve terreno, mas a documentação da classe e o código instalado 6.9.0 confirmam o caso do verso do globo. [MapLibre — Marker](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/)

### Agrupamento e proximidade

- **Visão mundial:** cada ponto individual pode mostrar retrato; grupos mostram uma lente com quantidade e até três miniaturas discretas. Não usar o rosto de um agente como se representasse sozinho toda uma região.
- **Visão regional:** expandir grupos por distância em tela; nomes só para selecionado e foco. Preservar estabilidade para evitar que miniaturas mudem a cada pequeno deslocamento.
- **Mesma cidade/coordenada:** abrir seletor curto dos agentes daquela cidade. Não deslocar artificialmente latitude/longitude nem continuar aumentando zoom indefinidamente. Se usar disposição radial visual, desenhar hastes de volta à mesma âncora e não salvar os deslocamentos como geografia.
- **Filtro aplicado:** quantidade do grupo, retratos, resultados e card precisam refletir o mesmo conjunto; o selecionado pode ser removido com uma saída coerente caso deixe de corresponder ao filtro.
- **Acessibilidade:** Vitrine continua sendo uma rota completa de exploração por teclado e leitor de tela. Botões do mapa usam nome, cidade e situação no nome acessível.

O exemplo oficial de HTML clusters mantém cache de marcadores, consulta as features e remove os que saem de cena. É um ponto de partida concreto, não um pacote de estilo pronto. Para separar grupos, MapLibre expõe `getClusterExpansionZoom` e `getClusterLeaves`; usar as folhas para o seletor de mesma cidade. [HTML clusters](https://maplibre.org/maplibre-gl-js/docs/examples/display-html-clusters-with-custom-properties/), [GeoJSONSource](https://maplibre.org/maplibre-gl-js/docs/API/classes/GeoJSONSource/)

## Card lateral — composição e material

**Desktop:** reservar uma área à direita sem cobrir o pin selecionado. Largura inicial de 360 px, com altura adaptativa limitada pela janela. O retrato ocupa 40–48% da composição; os dados vêm abaixo, em tipografia frontal e claramente legível. Para telas baixas, reduzir detalhes visíveis antes de reduzir novamente o rosto a avatar de lista. Ações principais permanecem acessíveis sem conflito com o chat.

**Perspectiva:** testar `perspective` de 1200–1600 px com giro Y de 4–7° e X próximo de 1°. Isso é uma placa lateral observada em profundidade, não um cartão constantemente girando. A camada material recebe a perspectiva mais forte; texto e controles recebem menos distorção. No foco de teclado, a placa pode se estabilizar. Não animar inclinação a cada movimento do cursor na tela inteira.

**Camadas do vidro:** silhueta externa e espessura; um reflexo direcional; fundo translúcido escuro; área interna de conteúdo com opacidade suficiente para leitura; retrato por cima; no máximo uma órbita do retrato em repouso. Separar estas camadas permite remover blur em dispositivos mais limitados sem perder a identidade.

**Hierarquia inicial:** retrato → nome → cidade e país → situação → especialidade/infraestrutura → ação. A descrição longa e dados administrativos ficam em “Detalhes do agente”. Esse conteúdo continua disponível, mas deixa de disputar a primeira impressão.

**Linha de seleção:** um SVG sobre o mapa, `pointer-events: none`, origem obtida da projeção geográfica e destino medido no card. Uma curva leve com nó na borda, brilho discreto e traçado único de 300–450 ms na seleção. Reposicionar em movimentos da câmera sem recomeçar a animação; ocultar quando o agente está atrás do globo, fora da área visível ou quando o card fecha. É uma conexão entre objeto e detalhe, nunca uma indicação de tráfego real ou localização da VPS.

**Enquadramento:** medir o espaço efetivo do dock e usar padding de câmera em vez de número fixo. O MapLibre documenta deslocamento do ponto de fuga para preservar conteúdo ao abrir painéis laterais. [Exemplo oficial de padding](https://maplibre.org/maplibre-gl-js/docs/examples/offset-the-vanishing-point-using-padding/)

**Mobile:** manter o retrato no pino. Ao tocar, abrir placa inferior com cantos/vidro da mesma família e prévia de cerca de 38–45% da altura útil; expansão deliberada revela o retrato grande e detalhes. Em 390 px de largura, uma coluna lateral desktop roubaria o mapa e reduziria alvos. O card pode nascer com uma perspectiva breve e estabilizar frontalmente para leitura. Preservar o pin acima da placa com padding inferior; retirar a longa linha de conexão quando não houver espaço. Story vertical é uma composição própria, não uma captura do dock desktop encolhido.

## Linguagem de carregamento

O núcleo Atlas pode ser cercado por dois arcos incompletos, pequenos ticks e uma varredura curta. Texto descreve etapas reais: “Preparando Atlas”, “Carregando o mapa”, “Posicionando agentes”. O estado pronto desmonta os arcos e revela o planeta; não inserir atraso artificial para terminar uma animação. Se dados ou mapa falharem, interromper a coreografia, manter uma mensagem compreensível e oferecer tentativa novamente/Vitrine. Evitar porcentagens inventadas e “sincronizando” quando só existe IndexedDB local.

O rigor visual dos interfaces de cinema vem de pesquisa e coerência narrativa. Territory explica que o laboratório de Stark foi informado por engenharia, robótica, IA e aviônica; seus trabalhos para jogos usam profundidade e transparência em interfaces holográficas. Para Atlas, os elementos precisam corresponder a seleção, alcance geográfico e apresentação, em vez de números técnicos sem significado. [Territory — Age of Ultron](https://territorystudio.com/project/marvels-avengers-age-of-ultron/), [Territory — Avengers Game](https://territorystudio.com/project/marvelsavengersgame/)

## Comparação de tecnologias

| Opção | Capacidade documentada | Adequação ao Atlas |
|---|---|---|
| **MapLibre + CSS/SVG/Motion** | Mapa vetorial, globo, câmera, HTML markers e agrupamento | Escolha recomendada para esta evolução: preserva navegação e dados existentes; permite pinos, vidro e card sem substituir o mapa |
| **three-globe / Three.js** | Objeto 3D com materiais de globo, pontos, arcos, anéis e camadas HTML | Mais liberdade para planeta cinematográfico e materiais; requer trabalho adicional de câmera, seleção, agrupamento e detalhe geográfico. Considerar apenas para uma abertura/apresentação separada depois de validar custo, sem duplicar o mapa principal agora |
| **deck.gl + MapLibre** | Integração sobreposta ou intercalada; no modo intercalado usa WebGL2 compartilhado | Interessante quando houver visualização analítica densa ou camadas de dados que justifiquem o motor adicional. Desnecessário para vinte mini retratos |
| **deck.gl GlobeView** | A própria documentação o classifica como experimental, com limitações de precisão em zoom alto e de camadas | Não recomendável substituir o globo de exploração atual por ele só para aparência |

Fontes: [MapLibre GL JS](https://maplibre.org/projects/gl-js/), [three-globe — documentação do projeto](https://github.com/vasturiano/three-globe), [deck.gl — MapLibre](https://deck.gl/docs/developer-guide/base-maps/using-with-maplibre), [deck.gl — GlobeView](https://deck.gl/docs/api-reference/core/globe-view).

## Implementação responsável e prova visual

Proposta: cache de marcadores por ID e atualização incremental; montar mini retratos apenas do conjunto visível; manter os pontos em GPU como representação simplificada quando houver densidade elevada; escolher o limiar após medir o Atlas, não por um número universal. Não chamar `setData` a cada frame para fazer o brilho respirar. MapLibre recomenda reduzir volume de GeoJSON, clusterizar quando apropriado e considerar tiles para conjuntos grandes. [Guia de desempenho](https://maplibre.org/maplibre-gl-js/docs/guides/large-data/)

Na decoração, animar transform e opacity; deixar blur e sombras largas estáticos ou limitados à entrada. O custo real deve ser medido no navegador, pois uma propriedade visual bonita pode implicar pintura a cada frame. Pausar efeitos quando a aba está oculta e quando o mapa está sendo manipulado. [web.dev — animações eficientes](https://web.dev/articles/animations-guide)

Critérios de aprovação do próximo protótipo:

1. Comparação lado a lado com a referência em desktop: rosto dominante, placa lateral e luz de borda presentes.
2. Em mobile real, reconhecer qual agente será aberto antes do toque, abrir/fechar e explorar sem taps perdidos.
3. Agentes na mesma cidade são todos alcançáveis; grupos não indicam identidades ou locais errados.
4. Girar o globo não revela avatares do outro lado nem rótulos atravessando o planeta.
5. Card e pino selecionados permanecem coerentes após filtro, troca rápida e fechamento.
6. Retorno de foco ao fechar e leitura por teclado funcionam; movimento reduzido mantém toda a informação.
7. Sem spinner infinito, espera artificial, erro coberto por animação ou semântica falsa de integração em tempo real.
8. Medir fluidez e carregamento em dispositivo real antes de prometer desempenho. Esta pesquisa não executou benchmark nem validou o protótipo futuro.