coastdigitalgroup/coastai-skills

Sistema de Localizador de Tiendas

Propósito

El Sistema de Localizador de Tiendas proporciona una metodología para diseñar interfaces de descubrimiento de ubicaciones físicas (como buscadores de sucursales, localizadores minoristas, redes de distribuidores o buscadores de clínicas médicas). Este sistema define la composición espacial, la adaptación responsiva, la sincronización de interacción y las barreras de accesibilidad necesarias para cerrar la brecha entre las búsquedas digitales y los destinos físicos. Garantiza que los usuarios puedan encontrar ubicaciones cercanas, evaluar detalles de la tienda y navegar hasta allí sin sobrecarga cognitiva, inestabilidad del diseño ni bloqueos de accesibilidad.

Casos de Uso

• Redes Minoristas y de Distribuidores: Guiar a los clientes a tiendas físicas, minoristas asociados o centros de servicio autorizados.
• Salud y Clínicas: Ayudar a los pacientes a encontrar centros de atención de urgencia cercanos, hospitales o consultorios médicos especializados.
• Instituciones Financieras: Mostrar redes de cajeros automáticos y ubicaciones de sucursales con capacidades de servicio específicas (por ejemplo, autoservicio, notario público).
• Restaurantes y Cadenas de Comida: Ayudar a los clientes a encontrar locales cercanos, verificar el estado operativo en tiempo real e iniciar pedidos de recogida/entrega.

Cuándo NO Usar

• Negocios con una Sola Ubicación: Si una empresa tiene solo una o dos oficinas físicas, una interfaz de localizador completa es excesiva. Una página de contacto simple con un mapa estático incrustado es suficiente (consulte sistema-de-navegación-del-sitio o las pautas de página de contacto).
• Marcas Puramente Digitales/Comercio Electrónico: Negocios sin presencia física o puntos de recogida físicos.
• Logística Dinámica y Enrutamiento: Aplicaciones avanzadas de viajes compartidos o seguimiento de entregas en tiempo real requieren seguimiento GPS continuo y enrutamiento dinámico, que pertenecen a sistemas SIG/especializados de tránsito en tiempo real.

Entradas

1. Inventario de Metadatos de Ubicación: Conjuntos de coordenadas (latitud/longitud), dirección física, datos de contacto (teléfono, correo electrónico), horario de atención y características o servicios específicos de la ubicación (facetas).
2. Señal de Ubicación del Usuario: Disponibilidad de la API de Geolocalización, código postal/zip ingresado por el usuario o entradas de texto de ciudad/estado.
3. Capacidades de la Plataforma de Mapas: Restricciones y parámetros de estilo personalizados del proveedor de mapas subyacente (por ejemplo, API de Google Maps, Mapbox GL JS, Leaflet).
4. Objetivos Principales del Usuario: ¿Los usuarios buscan principalmente visitar de inmediato (necesitan indicaciones y horarios), contactar la ubicación (necesitan teléfono) o verificar existencias (necesitan conexión con el inventario)?

Salidas

1. Plano de Diseño Espacial: Especificaciones de diseño espacial responsivo (proporciones de panel dividido en escritorio versus paneles con pestañas apiladas en móvil).
2. Especificación de Anatomía: Diseño detallado de la Tarjeta de Ubicación, el Encabezado de Búsqueda/Filtro y los Marcadores de Mapa.
3. Mapa de Interacción y Estados: Comportamiento definido para la sincronización de clics en marcadores, estados de hover, indicadores de carga de lista y correlación tarjeta/marcador.
4. Mapa de Puntos de Referencia de Accesibilidad y Teclado: Mecanismos de bloqueo de enfoque definidos para vistas detalladas, anuncios de aria-live para lectores de pantalla y rutas de navegación no visuales del mapa.

Flujo de Trabajo

1. Establecer la Composición Espacial

Diseñar la relación espacial entre el mapa y la lista de ubicaciones:

• Diseño de Escritorio (Panel Dividido): Usar un diseño de pantalla dividida.
  • Panel Lateral (35% a 40% de ancho): Colocar a la izquierda (para idiomas LTR) para establecerlo como el punto de partida de la jerarquía de lectura. Debe desplazarse independientemente de la página principal, manteniendo accesibles la entrada de búsqueda y las listas de ubicaciones.
  • Panel del Mapa (60% a 65% de ancho): Configurar como un elemento fijo y persistente a la derecha.
• Diseño Móvil (Pestañas Alternables): Dado que el mapa y la lista no caben uno al lado del otro en viewports estrechos, implementar una barra de alternancia en la parte superior o inferior de la pantalla:
  • Pestaña "Vista de Lista": Muestra la entrada de búsqueda y la lista vertical de tarjetas. Se recomienda como pestaña predeterminada.
  • Pestaña "Vista de Mapa": Muestra el mapa a pantalla completa.
  • Capa de Acción: Asegurarse de que los controles flotantes (por ejemplo, el botón "Buscar esta área" o el marcador de geolocalización) se ubiquen cómodamente sobre el mapa sin obstruir la navegación.

2. Definir la Anatomía de la Tarjeta de Ubicación

La Tarjeta de Ubicación es la unidad informativa principal. Ordenar sus elementos según la prioridad de escaneo cognitivo:

+-------------------------------------------------------------+
|  [Etiqueta de Categoría]                  [Distancia: 0.8 mi] |
|  **Título de Ubicación / Nombre de Sucursal**              |
|  [Calificación de Estrellas / Reseñas (Opcional)]          |
|                                                             |
|  123 Dirección Física, Ciudad, Estado Código Postal         |
|  Indicador de Estado: [Abierto Ahora / Cerrado] (Cierra a las 8:00 PM) |
|                                                             |
|  [Botón: Indicaciones]     [Botón: Llamar]    [Enlace: Detalles] |
+-------------------------------------------------------------+

• Nivel Primario: Nombre de la ubicación y distancia desde el centro de búsqueda. La distancia debe calcularse sobre la marcha y ser altamente visible (esquina superior derecha).
• Nivel Secundario: Dirección física y estado abierto/cerrado en tiempo real (utilizar codificación de colores combinada con texto, por ejemplo, verde para abierto, rojo para cerrado).
• Nivel Terciario: Acciones principales como botones CTA altamente táctiles (por ejemplo, "Indicaciones", "Llamar", "Ver Detalles").

3. Diseñar la Búsqueda y el Filtrado por Facetas

Proporcionar herramientas de consulta y filtrado altamente intuitivas en la sección del encabezado del panel lateral:

• Entrada de Búsqueda: Una entrada combinada que admita códigos postales, nombres de ciudades y direcciones, completa con un menú de autocompletado.
• Activador de Mi Ubicación: Un botón de geolocalización prominente y accesible representado por un icono estándar de "punto de mira", etiquetado adecuadamente para lectores de pantalla (aria-label="Encontrar ubicaciones cerca de mi posición actual").
• Filtro de Radio: Un menú desplegable que permite a los usuarios refinar el radio de búsqueda (por ejemplo, 5, 10, 25, 50 millas).
• Desplegables de Facetas: Filtros rápidos para características específicas de la tienda (por ejemplo, "Autoservicio", "Accesible para Silla de Ruedas", "24 Horas"). Usar insignias en los botones de filtro para mostrar los recuentos seleccionados.

4. Implementar la Sincronización de Interacción Bidireccional

Los marcadores del mapa y las tarjetas de la lista deben comportarse como un sistema unificado. Establecer relaciones interactivas claras:

• Hover/Foco en Tarjeta de Lista -> Marcador de Mapa: Al pasar el ratón o enfocar una tarjeta de lista, se debe activar un cambio de estado visual en su marcador de mapa correspondiente (por ejemplo, aumentar de escala, cambiar de color o traer al frente usando ajuste de z-index).
• Clic en Marcador de Mapa -> Tarjeta de Lista: Al hacer clic en un marcador de mapa, se debe:
  • Desplazar automáticamente la lista del panel lateral para mostrar la tarjeta correspondiente.
  • Resaltar la tarjeta con una breve animación de transición (por ejemplo, un pulso sutil de fondo).
  • Abrir una "Ventana de Información" (Popup) del mapa sobre el marcador que contenga el nombre de la tienda, la distancia y un enlace de "Indicaciones".
• Buscar-esta-Área (Arrastre de Mapa): Proporcionar un botón flotante "Buscar esta área" que aparezca en el centro superior del panel del mapa solo cuando el usuario desplace o haga zoom alejándose del centro de búsqueda inicial.

5. Establecer la Adaptación Táctil y del Mapa en Móvil

Gestionar las interacciones en dispositivos móviles para evitar frustraciones:

• Prevención de Secuestro de Scroll: Deshabilitar el zoom gestual en mapas móviles por defecto (requerir arrastre con dos dedos para desplazar o hacer zoom). Esto evita que los usuarios se queden "atascados" en el mapa al intentar desplazarse por la página.
• Controles Flotantes: Colocar los controles flotantes de zoom (+ / -) y un botón de geolocalización en la esquina inferior derecha del mapa, con una sombra de alto contraste y objetivos táctiles mínimos de 44x44px.
• Carrusel de Tarjetas Superpuesto: En la Vista de Mapa Móvil, proporcionar un carrusel horizontal deslizable de tarjetas en la parte inferior del viewport que muestre la ubicación activa o más cercana, manteniendo unificados la exploración del mapa y los detalles.

Reglas de Decisión

• La Regla de "Búsqueda Predeterminada": Cuando la página del localizador se carga sin una consulta de búsqueda o permiso de geolocalización:
  • No mostrar un mapa vacío.
  • Por defecto, mostrar las ubicaciones más cercanas basadas en geolocalización IP, o mostrar todas las ubicaciones ordenadas alfabéticamente/por prioridad.
• La Regla de Recuperación "Sin Resultados": Si un usuario busca en un área sin ubicaciones:
  • Alejar el mapa para mostrar las ubicaciones disponibles más cercanas.
  • Mostrar un mensaje útil en la lista del panel lateral (por ejemplo, "No se encontraron ubicaciones en un radio de 25 millas de [Consulta]. Aquí están las ubicaciones más cercanas a usted:").
  • Proporcionar un enlace "Ver Todas las Ubicaciones".
• Regla de Popup vs. Panel de Detalles:
  • Si la ubicación tiene metadatos mínimos (solo dirección y horario), mostrar toda la información dentro del popup de la Ventana de Información del Marcador de Mapa.
  • Si la ubicación tiene metadatos extensos (inventario, lista de equipo, fotos), al hacer clic en "Ver Detalles" se debe deslizar un panel de detalles de profundidad completa dentro del panel lateral, atrapando el enfoque del teclado allí y ofreciendo un botón claro "Volver a la Lista".

Restricciones

• Accesibilidad (Navegación por Teclado):
  • Los usuarios de teclado deben poder navegar por todo el flujo de búsqueda y la lista de ubicaciones sin usar el mapa directamente.
  • Los marcadores del mapa deben ser enfocables por teclado (tabindex="0") o estar representados por una lista alternativa accesible.
  • Cuando los resultados de búsqueda se actualicen, anunciar el cambio a los lectores de pantalla usando un elemento aria-live="polite" (por ejemplo, "Se encontraron 3 ubicaciones cerca de Seattle, WA").
• Tamaño del Objetivo Táctil: Todos los botones, marcadores de mapa y controles de filtro deben cumplir con WCAG 2.2 SC 2.5.8 (mínimo 24x24px con espaciado circundante), con los activadores de acción principales en tarjetas y controles flotantes dimensionados a 44x44px para comodidad del pulgar.
• Contraste Visual: Se prefieren mapas de alto contraste. Los marcadores estándar y las etiquetas de marcadores activos deben tener una relación de contraste de al menos 3:1 contra el fondo del mapa. El texto dentro de las tarjetas y popups debe cumplir con WCAG AA (4.5:1).
• Prevención de Desplazamiento del Diseño: Reservar espacio vertical/horizontal para los estados de carga usando tarjetas esqueleto en el panel lateral durante las búsquedas activas, evitando el Desplazamiento Acumulativo del Diseño (CLS).

Patrones de Falla Comunes

• La Trampa de Scroll Móvil: Los usuarios se quedan atascados en la página porque desplazarse en su pantalla móvil solo desplaza o hace zoom en el mapa, impidiéndoles pasar el componente del mapa.
• Sincronización Bidireccional Rota: Hacer clic en un marcador de mapa abre un popup pero no desplaza ni resalta la tarjeta correspondiente en el panel lateral, obligando a los usuarios a coincidir nombres manualmente.
• El "Mapa Ciego" (Exclusión por Teclado): Implementar los marcadores del mapa como formas SVG o elementos de lienzo no enfocables, haciendo que las ubicaciones físicas sean completamente inalcanzables para usuarios de lectores de pantalla y solo teclado.
• Punto Muerto Vacío Sin Consulta: Mostrar una pantalla completamente en blanco y un mapa silencioso en la carga inicial de la página, requiriendo que el usuario adivine que debe buscar primero.
• Arrastre de Mapa Lento: Intentar obtener y renderizar cientos de marcadores en tiempo real en cada pequeño arrastre del mapa, causando congelación de la interfaz. Implementar debounce (250–400ms) en los cambios de límites del mapa y agrupar marcadores cercanos.

Criterios de Validación

• El diseño espacial está definido tanto para escritorio (panel lateral de pantalla dividida) como para móvil (pestañas alternables de Lista/Mapa).
• La sincronización bidireccional está especificada (hacer clic en un marcador resalta/desplaza a la tarjeta; pasar el ratón/enfocar la tarjeta resalta el marcador).
• El zoom gestual en móvil está deshabilitado por defecto (se requiere desplazamiento con dos dedos) para evitar el secuestro de scroll móvil.
• Los estados de carga (esqueletos) están diseñados para evitar desplazamientos del diseño (CLS) cuando se actualizan las consultas de búsqueda.
• Se define una alternativa accesible: Los usuarios de teclado pueden navegar por todas las ubicaciones, leer sus detalles y obtener indicaciones sin necesidad de un ratón para pasar sobre elementos del lienzo del mapa.
• Los lectores de pantalla reciben un anuncio descriptivo y educado de aria-live cuando los resultados de búsqueda se actualizan.
• Los objetivos táctiles para todos los elementos interactivos de tarjetas, marcadores y botones de zoom cumplen al menos con el mínimo de 24x24px de WCAG 2.2 (44x44px preferido para CTA principales).
• El contraste del texto dentro de las tarjetas de ubicación y popups del mapa cumple con WCAG AA (4.5:1).
• Se diseñan flujos de respaldo claros para búsquedas sin resultados y denegaciones de permiso de ubicación.