coastdigitalgroup/coastai-skills

Sistema de Tour de Incorporación

Propósito

La habilidad Sistema de Tour de Incorporación proporciona una metodología de diseño integral para estructurar, estilizar y coordinar recorridos guiados de producto en múltiples pasos. Está diseñada para reducir la carga cognitiva del usuario durante la primera incorporación o el lanzamiento de funciones importantes, aislando visualmente elementos clave de la interfaz, proporcionando contexto secuencial y altamente relevante, y guiando al usuario hacia un estado activo y exitoso. Este sistema evita tours confusos, caóticos o demasiado intrusivos al establecer un ritmo predecible, accesible y controlado por el usuario.

Casos de Uso

• Incorporación de Usuarios por Primera Vez: Guiar a usuarios recién registrados a través de los flujos de trabajo centrales de una aplicación SaaS compleja para impulsar la activación.
• Promoción de Nuevas Funciones: Destacar y explicar una herramienta o elemento de interfaz recién lanzado de alto valor a usuarios existentes.
• Familiarización con Rediseños de UI: Ayudar a los usuarios que regresan a localizar herramientas familiares después de un rediseño o reorganización significativa de la interfaz.
• Tours de Entrada de Datos Complejos Paso a Paso: Guiar al usuario a través de un panel de control multifacético durante su configuración inicial (por ejemplo, configurar su primera regla de automatización).

Cuándo NO Usar

• Interfaces Autoexplicativas: Si una tarea se puede simplificar mediante diseños más claros, mejores etiquetas o iconografía intuitiva, mejore primero la interfaz de usuario central en lugar de enmascarar una mala UX con un tour.
• Microtareas Altamente Repetitivas: Evite interrumpir flujos de trabajo frecuentes con ventanas emergentes. Para obtener ayuda regular, use el sistema-de-consejos-e-indicaciones o texto de ayuda en línea.
• Interfaces Solo para Móviles o de Baja Resolución: Los tours de popover anclados en múltiples pasos consumen un espacio de pantalla masivo y son muy propensos a recortes o superposiciones en dispositivos móviles. Use tarjetas de pantalla completa o pasos en línea descartables integrados.
• Comentarios de Errores Críticos o Transaccionales: Para comentarios o errores instantáneos del sistema, use el sistema-de-banners-y-alertas o el sistema-de-toasts-y-snackbars.

Entradas

1. Arquitectura de la Información y Contexto: Los diseños de página específicos, secciones del panel de control o coordenadas de la interfaz de usuario donde se ejecutará el tour.
2. Inventario de Elementos Ancla: Los botones objetivo específicos, entradas, tablas o enlaces de navegación que deben resaltarse en cada paso.
3. Hitos de Incorporación (El "Por Qué"): Las acciones clave mínimas necesarias para completar la incorporación y garantizar la activación.
4. Puntos de Interrupción del Dispositivo: Viewports objetivo responsivos donde se debe renderizar el tour, utilizando las pautas del sistema-de-cuadrícula-responsiva.

Salidas

1. Especificación de Fondo y Máscara: Aislar visualmente los elementos objetivo mientras se oscurece el resto de la interfaz para centrar la atención del usuario.
2. Especificación de Anatomía del Popover (Tarjeta de Tour): Plano estructural detallado de la burbuja del tour (flechas, texto del cuerpo, indicadores de paso, botones de omitir/siguiente/atrás, controles de cierre).
3. Lógica de Secuencia y Flujo: Mapeo de ruta paso a paso, modelos de progresión (lineal estricto vs. impulsado por el usuario) y persistencia de sesión.
4. Estrategia Responsiva y Alternativas para Móviles: Reglas de adaptación para pantallas más pequeñas donde los popovers anclados flotantes no pueden caber de manera segura.
5. Hitos de Accesibilidad y Especificación de Interacción: Especificación completa de ARIA, mapa de navegación por teclado y comportamiento de bloqueo de foco.

Flujo de Trabajo

1. Definir la Secuencia de Pasos (El Camino Feliz)

• Limite la secuencia del tour a 3 a 5 pasos (Ley de Miller). Cualquier cosa más larga resulta en un alto abandono.
• Enfoque cada paso en un beneficio activo, no solo en una etiqueta (por ejemplo, en lugar de "Este es el menú de Configuración", escriba "Personalice su espacio de trabajo para que coincida con el flujo de trabajo de su equipo aquí").
• Asegúrese de que el paso final tenga una llamada a la acción (CTA) clara y procesable que deje al usuario en un estado activo y productivo.

2. Diseñar la Máscara de Fondo y el Aislamiento (Enfoque)

• Use una superposición de fondo semitransparente oscura (generalmente #000000 con 50-70% de opacidad) para silenciar el ruido de fondo y enfocar la vista.
• Cree una "Máscara de Aislamiento" (usando recortes de ruta SVG o clip-path / sombras de caja CSS) alrededor del elemento ancla activo.
• Mantenga un margen de relleno de 4px a 8px alrededor del ancla resaltada para evitar que la máscara se adhiera demasiado a los bordes del elemento.

3. Construir la Jerarquía del Popover (Tarjeta de Tour)

• Alineación del Ancla: Posicione el popover dinámicamente junto al elemento resaltado. Use una pequeña flecha/indicador direccional para vincular visualmente la tarjeta al ancla.
• Anatomía del Componente:
  • Encabezado: Incluya un botón de Cerrar estándar ('X') y un indicador de progreso (por ejemplo, "Paso 2 de 4").
  • Cuerpo: Use títulos en negrita y concisos y un máximo de 2 oraciones de texto descriptivo.
  • Barra de Acciones: Alinee a la izquierda el enlace "Omitir", alinee a la derecha los botones de navegación. Asegúrese de que "Siguiente" (o "Entendido") use el estilo de CTA principal, y "Atrás" use un estilo terciario de bajo contraste.

4. Codificar para Accesibilidad (Paridad de Teclado y Lector de Pantalla)

• Bloqueo de Foco: Cuando un paso del tour está activo, el foco del teclado (tecla Tab) debe estar atrapado dentro del popover del tour para evitar que los usuarios de teclado naveguen por los elementos de fondo.
• Asociaciones ARIA: Asegúrese de que el contenedor del popover use role="dialog" o role="alertdialog" con aria-modal="false" (para que las tecnologías de asistencia sepan que los elementos de fondo aún están presentes). Vincule el encabezado del popover con aria-labelledby y la descripción con aria-describedby.
• Atajos de Teclado: Soporte de navegación por teclado: Escape para descartar/omitir el tour, FlechaDerecha para "Siguiente" y FlechaIzquierda para "Atrás".

5. Mapear la Estrategia de Adaptación Móvil

• Si el viewport es menor a 768px (Tableta/Móvil), transicione de popovers anclados flotantes a un panel inferior (bottom sheet) o un modal centrado y no anclado. Esto evita que la tarjeta se salga de la pantalla o cubra elementos críticos.
• Asegúrese de que la máscara de fondo esté deshabilitada o simplificada en dispositivos móviles para evitar errores de recorte causados por el desplazamiento móvil.

Reglas de Decisión

• Tour Lineal vs. Lista de Tareas Impulsada por el Usuario:
  • Use un Tour Lineal para una secuencia de configuración inicial rígida donde el Paso A debe preceder al Paso B.
  • Use un Widget de Progreso Interactivo (Lista de Tareas) si las tareas se pueden completar en cualquier orden, permitiendo a los usuarios seleccionar tareas a su propio ritmo.
• Condición de Activación:
  • Activar automáticamente solo durante la primera ejecución o después de actualizaciones explícitas.
  • Nunca active tours automáticamente para usuarios que regresan en visitas estándar.
• Anulación de Posición del Ancla:
  • Predeterminado: Posicione el popover "Centro-Inferior" o "Centro-Derecho" del ancla.
  • Regla de Colisión: Si el ancla está cerca del borde de la pantalla, invierta la colocación del popover para evitar recortes (por ejemplo, de "Derecha" a "Izquierda"). Si el ancla está oculta (dentro de un panel contraído), expanda el panel programáticamente antes de renderizar el popover.
• La Opción "Omitir":
  • Proporcione siempre una acción visible "Omitir Tour" o "Descartar" en cada paso. Forzar a los usuarios a completar un tour sin posibilidad de escape genera frustración.

Restricciones

• Accesibilidad (WCAG 2.2):
  • El contraste de texto dentro de la tarjeta del tour debe cumplir con WCAG AA (al menos 4.5:1).
  • Debe haber un anillo de foco visual de alto contraste (outline) en los botones interactivos.
  • Los objetivos táctiles para los botones de siguiente/atrás deben ser de al menos 44x44px (recomendado) o cumplir con el mínimo de 24x24px (WCAG 2.2 SC 2.5.8).
  • Los anclas interactivas dentro del recorte de fondo deben ser enfocables.
• Gestión de Desplazamiento de Diseño:
  • La aparición del fondo, la máscara de recorte y el popover no debe desplazar los elementos de diseño existentes. Use position: absolute o position: fixed relativo al viewport del documento.
• Alineación de Z-Index:
  • El fondo y la tarjeta del tour deben estar por debajo de las alertas de utilidad de nivel superior, como los Toasts (por ejemplo, fondo en z-index 900, popover en z-index 910) para garantizar que las alertas del sistema de alta prioridad puedan seguir apareciendo.

Patrones de Falla Comunes

• La Trampa del "Tour Infinito": Tours con más de 5 pasos, lo que provoca que los usuarios abandonen inmediatamente.
• El Conflicto de "Doble Foco": Iniciar automáticamente un tour en una página que ya tiene un modal activo, creando superposiciones apiladas y entradas atrapadas.
• Resaltado de Ancla Ciego: Resaltar un elemento que está desplazado fuera de la pantalla o contraído, apuntando la flecha a un espacio vacío.
• Acciones de Fondo Inalcanzables: Requerir que el usuario escriba en un elemento enmascarado para continuar, pero bloqueando su entrada o clics del mouse con el fondo.
• Compresión de Burbujas en Móviles: Permitir que las burbujas ancladas se reduzcan a anchos ilegibles en dispositivos móviles, causando que las palabras se rompan de manera incómoda.

Criterios de Validación

• El tour está estrictamente limitado a 3-5 pasos.
• Cada paso tiene una opción claramente etiquetada y visible de "Omitir" o cerrar.
• El foco de tabulación del teclado está atrapado dentro del popover durante los pasos activos.
• El foco se desplaza suavemente a la siguiente tarjeta de tour (o al elemento recién resaltado) cuando se presiona "Siguiente".
• Los atributos ARIA (role="dialog", aria-modal, aria-describedby) están configurados correctamente.
• Se define el manejo de colisiones del popover (invierte automáticamente la posición cerca de los bordes de la pantalla).
• Los viewports móviles transicionan de manera fluida de popovers anclados a un modal centrado o un panel inferior persistente.
• Se mantiene un margen de relleno de 4-8px alrededor del ancla aislada para evitar recortar los bordes.
• Los estados activo y hover de todos los botones cumplen con WCAG AA (contraste 4.5:1).