coastdigitalgroup/coastai-skills

Sistema de Localizador de Lojas

Propósito

O Sistema de Localizador de Lojas fornece uma metodologia para projetar interfaces de descoberta de locais físicos (como localizadores de agências, localizadores de varejo, redes de concessionárias ou localizadores de clínicas médicas). Este sistema define a composição espacial, adaptação responsiva, sincronização de interação e diretrizes de acessibilidade necessárias para conectar pesquisas digitais a destinos físicos. Ele garante que os usuários possam encontrar locais próximos a eles, avaliar detalhes da loja e navegar até lá sem sobrecarga cognitiva, instabilidade de layout ou bloqueios de acessibilidade.

Casos de Uso

• Redes de Varejo e Concessionárias: Orientando clientes a lojas físicas, revendedores parceiros ou centros de serviço autorizados.
• Saúde e Clínicas: Ajudando pacientes a encontrar unidades de atendimento de urgência, hospitais ou consultórios médicos especializados próximos.
• Instituições Financeiras: Exibindo redes de caixas eletrônicos e agências bancárias com capacidades de serviço específicas (por exemplo, drive-thru, tabelião público).
• Restaurantes e Redes Alimentícias: Auxiliando clientes a encontrar locais próximos, verificar status operacional em tempo real e iniciar pedidos de retirada/entrega.

Quando NÃO Usar

• Empresas com Local Único: Se uma empresa tem apenas um ou dois escritórios físicos, uma interface de localizador completa é exagero. Uma simples página de contato com um mapa estático incorporado é suficiente (veja site-navigation-system ou diretrizes de página de contato).
• Marcas Puramente Digitais/E-commerce: Empresas sem presença física ou pontos de retirada física.
• Logística e Roteamento Dinâmicos: Aplicações avançadas de compartilhamento de caronas ou rastreamento de entregas em tempo real exigem rastreamento GPS contínuo e roteamento dinâmico, que se enquadram em sistemas GIS/trânsito em tempo real especializados.

Entradas

1. Inventário de Metadados de Locais: Conjuntos de coordenadas (latitude/longitude), endereço físico, detalhes de contato (telefone, e-mail), horários de funcionamento e características ou serviços específicos do local (facetas).
2. Sinal de Localização do Usuário: Disponibilidade da API de Geolocalização, código postal/CEP inserido pelo usuário ou entradas de texto de cidade/estado.
3. Capacidades da Plataforma de Mapa: Restrições e parâmetros de estilo personalizados do provedor de mapa subjacente (por exemplo, Google Maps API, Mapbox GL JS, Leaflet).
4. Objetivos Principais do Usuário: Os usuários estão principalmente procurando visitar imediatamente (precisam de direções e horários), contatar o local (precisam de telefone) ou verificar estoque (precisam de conexão com inventário)?

Saídas

1. Projeto de Layout Espacial: Especificações de layout espacial responsivo (proporções de painel dividido no Desktop vs. painéis com guias empilhadas no Mobile).
2. Especificação de Anatomia: Design detalhado do Cartão de Localização, Cabeçalho de Pesquisa/Filtro e Marcadores de Mapa.
3. Mapa de Interação e Estado: Comportamento definido para sincronização de clique em marcadores, estados de hover, indicadores de carregamento de lista e correlação cartão/marcador.
4. Mapa de Marcos de Acessibilidade e Teclado: Mecanismos de armadilha de foco definidos para visualizações de detalhes, anúncios aria-live para leitores de tela e caminhos de navegação não visuais do mapa.

Fluxo de Trabalho

1. Estabelecer a Composição Espacial

Projete a relação espacial entre o mapa e a listagem de locais:

• Layout Desktop (Painel Dividido): Use um design de tela dividida.
  • Painel Lateral (35% a 40% de largura): Coloque à esquerda (para idiomas LTR) para estabelecê-lo como o ponto de partida da hierarquia de leitura. Ele deve rolar independentemente da página principal, mantendo a entrada de pesquisa e as listas de locais acessíveis.
  • Painel do Mapa (60% a 65% de largura): Defina como um elemento fixo e persistente à direita.
• Layout Mobile (Guias Alternáveis): Como tanto o mapa quanto a lista não cabem lado a lado em viewports estreitas, implemente uma barra de alternância na parte superior ou inferior da tela:
  • Guia "Visualização de Lista": Exibe a entrada de pesquisa e a lista vertical de cartões. Recomendado como guia padrão.
  • Guia "Visualização de Mapa": Exibe o mapa em tela cheia.
  • Camada de Ação: Garanta que os controles flutuantes (por exemplo, botão "Pesquisar esta área" ou pin de geolocalização) fiquem confortavelmente acima do mapa sem obscurecer a navegação.

2. Definir a Anatomia do Cartão de Localização

O Cartão de Localização é a unidade informacional primária. Ordene seus elementos por prioridade de escaneamento cognitivo:

+-------------------------------------------------------------+
|  [Tag de Categoria]                           [Distância: 0.8 mi] |
|  **Título do Local / Nome da Agência**                           |
|  [Classificação por Estrelas / Avaliações (Opcional)]         |
|                                                             |
|  123 Endereço Físico, Cidade, Estado CEP               |
|  Indicador de Status: [Aberto Agora / Fechado] (Fecha às 20:00)  |
|                                                             |
|  [Botão: Direções]     [Botão: Ligar]    [Link: Detalhes] |
+-------------------------------------------------------------+

• Nível Primário: Nome do local e distância do centro pesquisado. A distância deve ser calculada dinamicamente e altamente visível (canto superior direito).
• Nível Secundário: Endereço físico e status aberto/fechado em tempo real (utilize codificação de cores combinada com texto, por exemplo, verde para aberto, vermelho para fechado).
• Nível Terciário: Ações primárias como botões de CTA altamente tocáveis (por exemplo, "Direções", "Ligar", "Ver Detalhes").

3. Projetar Pesquisa e Filtragem por Facetas

Forneça ferramentas de consulta e filtragem altamente intuitivas na seção de cabeçalho do painel lateral:

• Campo de Pesquisa: Uma entrada combinada que aceita códigos postais, nomes de cidades e endereços físicos, completa com um menu de autocompletar.
• Gatilho de Minha Localização: Um botão de geolocalização proeminente e acessível representado por um ícone padrão de "miras", rotulado adequadamente para leitores de tela (aria-label="Encontrar locais perto da minha posição atual").
• Filtro de Raio: Um menu suspenso que permite aos usuários refinar o raio de pesquisa (por exemplo, 5, 10, 25, 50 milhas).
• Menus Suspensos de Facetas: Filtros rápidos para características específicas da loja (por exemplo, "Drive-thru", "Acessível para Cadeiras de Rodas", "24 Horas"). Use badges nos botões de filtro para mostrar contagens selecionadas.

4. Implementar Sincronização de Interação Bidirecional

Marcadores de mapa e cartões de lista devem se comportar como um sistema unificado. Estabeleça relações interativas claras:

• Hover/Foco em Cartão da Lista -> Marcador do Mapa: Passar o mouse ou focar um cartão da lista deve acionar uma mudança de estado visual em seu marcador de mapa correspondente (por exemplo, aumentar de tamanho, mudar de cor ou trazer para a frente usando ajuste de z-index).
• Clique no Marcador do Mapa -> Cartão da Lista: Clicar em um marcador de mapa deve:
  • Rolar automaticamente a lista do painel lateral para trazer o cartão correspondente à vista.
  • Destacar o cartão com uma breve animação de transição (por exemplo, um pulo de fundo sutil).
  • Abrir uma "Janela de Informação" (Popup) do mapa sobre o marcador contendo o nome da loja, distância e um link "Direções".
• Pesquisar-esta-Área (Arrastar Mapa): Forneça um botão flutuante "Pesquisar esta área" que aparece no centro superior do painel do mapa apenas quando o usuário desloca ou amplia o mapa para longe do centro de pesquisa inicial.

5. Estabelecer Toque em Dispositivos Móveis e Adaptação do Mapa

Gerencie interações em dispositivos móveis para evitar frustrações:

• Evitar Sequestro de Rolagem: Desabilite o zoom baseado em gestos em mapas móveis por padrão (exija arrastar com dois dedos para deslocar ou ampliar). Isso impede que os usuários fiquem "presos" no mapa ao tentar rolar a página para baixo.
• Controles Flutuantes: Coloque controles flutuantes de zoom (+ / -) e um botão de geolocalização no canto inferior direito do mapa, estilizados com uma sombra de alto contraste e alvos de toque mínimos de 44x44px.
• Sobreposição de Carrossel de Cartões: Na Visualização de Mapa Móvel, forneça um carrossel de cartões horizontais deslizável na parte inferior da viewport mostrando o local único ativo ou mais próximo, mantendo a exploração do mapa e os detalhes unificados.

Regras de Decisão

• Regra de "Pesquisa Padrão": Quando a página do localizador carrega sem uma consulta de pesquisa ou permissão de geolocalização:
  • Não mostre um mapa vazio.
  • Padrão para mostrar os locais mais próximos com base na geolocalização por IP, ou exibir todos os locais ordenados alfabeticamente/por prioridade.
• Regra de Recuperação de "Nenhum Resultado": Se um usuário pesquisar em uma área com zero locais:
  • Afaste o mapa para mostrar os locais disponíveis mais próximos.
  • Exiba uma mensagem útil na lista do painel lateral (por exemplo, "Nenhum local encontrado em um raio de 25 milhas de [Consulta]. Aqui estão os locais mais próximos de você:").
  • Forneça um link "Ver Todos os Locais".
• Regra de Popup vs. Painel de Detalhes:
  • Se o local tiver metadados mínimos (apenas endereço e horários), mostre todas as informações dentro do popup da Janela de Informação do Marcador do Mapa.
  • Se o local tiver metadados extensos (inventário, lista de equipe, fotos), clicar em "Ver Detalhes" deve deslizar um painel de detalhes em profundidade total dentro do painel lateral, prendendo o foco do teclado lá e oferecendo um botão claro "Voltar para a Lista".

Restrições

• Acessibilidade (Navegação por Teclado):
  • Usuários de teclado devem ser capazes de navegar por todo o fluxo de pesquisa e lista de locais sem usar o mapa diretamente.
  • Os marcadores do mapa devem ser focáveis por teclado (tabindex="0") ou representados por uma lista alternativa acessível.
  • Quando os resultados da pesquisa forem atualizados, anuncie a mudança aos leitores de tela usando um elemento aria-live="polite" (por exemplo, "3 locais encontrados perto de Seattle, WA").
• Tamanho do Alvo de Toque: Todos os botões, marcadores de mapa e controles de filtro devem atender ao WCAG 2.2 SC 2.5.8 (mínimo 24x24px com espaçamento ao redor), com os acionadores de ação primária nos cartões e controles flutuantes dimensionados para 44x44px para conforto do polegar.
• Contraste Visual: Mapas de alto contraste são preferidos. Marcadores padrão e rótulos de marcadores ativos devem ter uma taxa de contraste de pelo menos 3:1 contra o fundo do mapa. Texto dentro de cartões e popups deve atender ao WCAG AA (4.5:1).
• Prevenção de Mudança de Layout: Reserve espaço vertical/horizontal para estados de carregamento usando cartões esqueleto no painel lateral durante pesquisas ativas, prevenindo Mudança Cumulativa de Layout (CLS).

Padrões de Falha Comuns

• A Armadilha de Rolagem Móvel: Os usuários ficam presos na página porque rolar em sua tela móvel apenas desloca/aplica zoom no mapa, impedindo-os de rolar além do componente do mapa.
• Sincronização Bidirecional Quebrada: Clicar em um marcador de mapa abre um popup, mas não rola ou destaca o cartão correspondente no painel lateral, forçando os usuários a combinar nomes manualmente.
• O "Mapa Cego" (Exclusão por Teclado): Implementar os marcadores do mapa como formas SVG ou elementos de tela não focáveis, tornando os locais físicos completamente inacessíveis para leitores de tela e usuários somente de teclado.
• Ponto Morto Vazio Sem Consulta: Exibir uma tela completamente em branco e um mapa silencioso no carregamento inicial da página, exigindo que o usuário adivinhe que deve pesquisar primeiro.
• Arrastar Mapa Lento: Tentar buscar e renderizar centenas de marcadores em tempo real a cada pequeno arrasto de mapa, causando congelamento da interface. Implemente debounce (250–400ms) nas mudanças de limites do mapa e agrupe marcadores próximos.

Critérios de Validação

• O layout espacial é definido tanto para desktop (painel lateral de tela dividida) quanto para mobile (guias alternáveis Lista/Mapa).
• A sincronização bidirecional é especificada (clicar no marcador destaca/rola para o cartão; passar o mouse/focar no cartão destaca o marcador).
• O zoom por gesto em dispositivos móveis está desabilitado por padrão (rolagem com dois dedos necessária) para evitar sequestro de rolagem em dispositivos móveis.
• Estados de carregamento (esqueletos) são projetados para evitar mudanças de layout (CLS) quando as consultas de pesquisa são atualizadas.
• Alternativa acessível é definida: Usuários de teclado podem navegar por todos os locais, ler seus detalhes e obter direções sem precisar de um mouse para passar o mouse sobre itens da tela do mapa.
• Os leitores de tela recebem um anúncio aria-live descritivo e educado quando os resultados da pesquisa são atualizados.
• Os alvos de toque para todos os elementos interativos do cartão, marcadores e botões de zoom atendem pelo menos ao mínimo de 24x24px do WCAG 2.2 (44x44px preferido para CTAs principais).
• O contraste do texto dentro dos cartões de localização e popups do mapa atende ao WCAG AA (4.5:1).
• Fluxos de fallback claros são projetados para pesquisas sem resultados e negações de permissão de localização.