Sistema de Paleta de Comandos

¿Qué hace Sistema de Paleta de Comandos?

Propósito

El Sistema de Paleta de Comandos proporciona un marco de diseño y espacial para menús superpuestos globales activados por teclado (generalmente invocados con Cmd+K o Ctrl+K). En aplicaciones web modernas de alta densidad, plataformas de desarrolladores y portales de documentación con mucho contenido, las barras de navegación estándar se vuelven abrumadoras. Una paleta de comandos actúa como un "centro de comandos", brindando a los usuarios avanzados rutas de teclado directas y sin fricción para buscar, navegar y ejecutar acciones, mientras sirve como un diccionario interactivo de atajos de teclado.

Este skill garantiza que las paletas de comandos sean espacialmente ergonómicas, visualmente estructuradas para prevenir la fatiga cognitiva y completamente compatibles con especificaciones de accesibilidad avanzadas (WCAG 2.2 AA).

Casos de Uso

• Diseñar un controlador de espacio de trabajo global basado en atajos para tableros SaaS.
• Estructurar portales orientados a desarrolladores y portales de búsqueda de documentación (por ejemplo, referencias de API).
• Implementar paneles administrativos de acción rápida para plataformas CRM o CMS empresariales.
• Crear interfaces de línea de comandos (CLIs) unificadas dentro de productos web complejos y de múltiples capas.

Cuándo NO Usar

• Páginas de Aterrizaje Estáticas: Donde la intención del usuario es puramente exploratoria y centrada en la conversión; una barra de navegación global y llamadas a la acción (CTA) claras son más efectivas.
• Sitios Informativos Superficiales (<15 páginas): Donde la sobrecarga de implementar y enseñar una paleta de comandos supera cualquier beneficio de orientación.
• Sitios Móviles de Consumo Simple: Donde el espacio en pantalla es mínimo y los usuarios dependen estrictamente de interacciones táctiles sin teclados físicos externos.

Entradas

1. Inventario de Comandos y Acciones: Una taxonomía completa de acciones, páginas, configuraciones y documentos buscables.
2. Reglas de Mapeo Contextual: Reglas sobre qué comandos son globales frente a cuáles son específicos del contexto (por ejemplo, "Eliminar Proyecto" solo aparece mientras se visualiza un proyecto).
3. Sistema de Atajos de Teclado: Un mapeo de acciones a atajos de teclado físico (por ejemplo, G luego D para "Ir al Tablero").
4. Tokens de Diseño de Marca: Escalas tipográficas, colores, proporciones de espaciado y tokens de sombra (de fluid-spacing-system y fluid-typography-system).

Salidas

1. Especificaciones de Disparadores: Diseños visuales para puntos de entrada persistentes e insignias de atajos de teclado.
2. Arquitectura de Diseño de la Paleta: Estructuras de cuadrícula para el modal superpuesto, agrupación de resultados, navegación por categorías y pies de página de ayuda.
3. Especificaciones Visuales de la Fila de Comandos: Especificaciones de jerarquía para iconos, títulos de comandos, insignias de categoría y anotaciones de atajos.
4. Especificación de Accesibilidad y Teclado: Mapeos exactos de eventos de teclado y especificaciones de estado ARIA que coincidan con el patrón Combobox de ARIA APG.

---

Flujo de Trabajo

1. Establecer el Disparador de la Paleta y los Puntos de Entrada

Debido a que una paleta de comandos está oculta por defecto, debes diseñar puntos de entrada descubribles:

• El Disparador Persistente en el Encabezado: Un botón que imita una barra de búsqueda en el encabezado global, con un icono de lupa, una etiqueta de texto (por ejemplo, "Buscar o ejecutar un comando...") y una insignia de atajo de teclado alineada a la derecha (por ejemplo, ⌘K o Ctrl+K).
• Botón de Comando Flotante: Para tableros intensivos o ventanas gráficas de pantalla completa, coloca un botón disparador sutil en la esquina inferior derecha de la ventana gráfica.
• Oyente Global Invisible: Asegúrate de que al presionar Cmd+K (macOS) o Ctrl+K (Windows/Linux) en cualquier lugar del documento (a menos que el foco esté en una entrada de texto) se abra inmediatamente la paleta.

2. Diseñar la Superposición Modal y el Fondo (Scrim)

• Fondo (Scrim): Usa un fondo semitransparente de alto contraste (por ejemplo, rgba(15, 23, 42, 0.4)) para atenuar la página de fondo, enfocando la atención completamente en la tarea activa.
• Ubicación Vertical: Centra el modal horizontalmente, pero ancla a la parte superior del 10%–15% de la ventana gráfica, en lugar de centrarlo verticalmente de forma absoluta. Esto se alinea con el nivel de ojo natural y deja espacio para el teclado virtual físico en pantallas táctiles.
• Límites de Tamaño: Limita el ancho a un rango de escaneo cómodo, idealmente entre 600px y 680px. La altura debe ser dinámica, con un máximo de 450px a 550px para asegurar que nunca se desborde en pantallas de portátiles pequeñas.

3. Estructurar la Cuadrícula de Diseño Interno

Divide la paleta de comandos en cuatro zonas horizontales distintas:

1. La Zona de Búsqueda y Filtro: Un campo de entrada sin bordes de ancho completo con un icono de búsqueda prominente (mín. 20px). Usa texto de marcador de posición que guíe al usuario (por ejemplo, "Escribe un comando o busca...").
2. La Barra de Filtro de Categorías (Opcional): Una fila horizontal de chips compactos o controles segmentados (por ejemplo, "Todo", "Acciones", "Páginas", "Usuarios") para permitir a los usuarios filtrar resultados antes de buscar.
3. El Feed de Resultados (Contenedor de Desplazamiento): Una listbox contenida con encabezados agrupados (por ejemplo, "Recientes", "Navegación", "Configuración del Sistema").
4. El Pie de Página de Ayuda: Una barra de estado de bajo contraste que muestra guías de teclado (por ejemplo, ↑↓ para navegar, ↵ para seleccionar, esc para cerrar).

+-----------------------------------------------------------+
|  [Icono de Búsqueda]  Buscar o escribe un comando... [ESC]|
+-----------------------------------------------------------+
|  ( Todo )  ( Acciones )  ( Páginas )  ( Miembros ) ( Ayuda )|
+-----------------------------------------------------------+
|  BÚSQUEDAS RECIENTES                                      |
|  [Icono] Ir a Facturación                     [ ⌘ G ] [ B ]|
|  [Icono] Crear Nueva Factura                  [ ⌘ N ]      |
|                                                           |
|  NAVEGACIÓN                                               |
|  [Icono] Tablero                                           |
|  [Icono] Configuración del Equipo             [ ⌘ , ]      |
+-----------------------------------------------------------+
|  ↑↓ Navegar  |  ↵ Seleccionar  |  esc Cerrar  |  ? Docs de Ayuda|
+-----------------------------------------------------------+

4. Crear la Jerarquía Visual de la Fila de Comandos

Cada elemento en la lista de resultados debe ser escaneable en milisegundos:

• Icono Alineado a la Izquierda: Un icono explícito y de alto contraste que indique el tipo del elemento (por ejemplo, un icono de archivo para documentos, un engranaje de configuración para acciones, un avatar de usuario para personas).
• Etiqueta Principal: Texto seminegrita de color primario del comando en sí (por ejemplo, "Invitar miembro del equipo").
• Subetiqueta Secundaria (Opcional): Descripción más pequeña y atenuada debajo o al lado de la etiqueta principal para dar contexto (por ejemplo, "Configuración > Organización").
• Insignias de Atajo Alineadas a la Derecha: Muestra el atajo de teclado físico asociado con ese comando usando insignias de tecla pequeñas y de alto contraste (por ejemplo, ⌥I).

5. Definir Estados Interactivos y Selección por Teclado

Una paleta de comandos se maneja principalmente con el teclado; por lo tanto, el estado de selección con el teclado tiene prioridad sobre el hover del ratón:

• Estado de Elemento Activo/Enfocado: Cuando se navega a un elemento usando las teclas de flecha, aplica un cambio de fondo prominente (usando el token de luz primaria, por ejemplo, var(--color-primary-light)), y un indicador de borde izquierdo. El texto principal debe cambiar al color de la marca.
• Estado Hover (Ratón): Refleja el estado activo del teclado. Mover el ratón sobre los elementos debe actualizar la selección del teclado para evitar estados de doble enfoque.
• Estado Vacío: Cuando una búsqueda no devuelve resultados, muestra un estado vacío limpio e ilustrativo que sugiera acciones alternativas (por ejemplo, "No se encontraron comandos. Intenta buscar en nuestro centro de ayuda" con un enlace de búsqueda).
• Estado de Carga: Si los resultados de la consulta de búsqueda se obtienen de forma asíncrona, muestra un indicador de carga lineal sutil en la base del campo de búsqueda, evitando tarjetas esqueleto que causen cambios de diseño.

---

Reglas de Decisión

• La Regla de "Cmd+K vs Búsqueda Persistente": Si el valor principal del sitio es consumir contenido estructurado (como un catálogo de comercio electrónico), usa una barra de búsqueda persistente. Si el valor es un flujo de trabajo administrativo, ejecución de comandos o navegación densa, usa una paleta de comandos con Cmd+K.
• La Regla del Límite de Agrupación: Nunca muestres más de 3–4 categorías de comandos simultáneamente. Mantén el máximo de elementos visibles en cada categoría en 5, proporcionando una opción "Mostrar más..." si existen más.
• La Regla de "Conteo de Teclas": Los atajos de teclado físico mostrados junto a los comandos nunca deben exceder 3 teclas (por ejemplo, Ctrl+Shift+P es aceptable; Ctrl+Alt+Shift+Z es demasiado complejo).
• La Regla de Contexto Dinámico: Filtra dinámicamente los comandos basándote en la ruta activa. Si un usuario está en la página de facturación, prioriza "Actualizar Tarjeta de Crédito" o "Descargar Factura PDF" en la parte superior de la lista de resultados predeterminada (sin escribir).

---

Restricciones

1. Accesibilidad (WCAG 2.2 AA Mínimo)

• Patrón Combobox de ARIA: Debes estructurar el marcado siguiendo estrictamente la Guía de Prácticas de Autoría ARIA (APG):
  • El contenedor de entrada debe tener role="combobox", aria-expanded="true", aria-autocomplete="list" y aria-controls="command-listbox-id".
  • La lista de resultados debe tener role="listbox", y cada fila de comando debe tener role="option".
  • A medida que el usuario presiona las teclas de flecha, la entrada debe actualizar aria-activedescendant para apuntar al ID de la opción activa, y esa opción debe tener aria-selected="true".
• Gestión de Enfoque: Abrir la paleta debe atrapar el enfoque del teclado dentro de la superposición. Presionar Tab debe ser interceptado para ciclar dentro de la paleta o deshabilitarse por completo (prefiriendo las teclas de flecha para la navegación de opciones). Cerrar la paleta debe devolver el enfoque al elemento disparador exacto.
• Anuncios para el Lector de Pantalla: Coloca un div invisible con aria-live="polite" y aria-atomic="true" junto a la entrada. Al buscar, completa dinámicamente este div con el estado de los resultados (por ejemplo, "12 resultados encontrados, usa las teclas de flecha arriba y abajo para navegar").
• Relaciones de Contraste: Todo el texto, las insignias de atajo y los indicadores de enfoque deben cumplir con WCAG AA (4.5:1 mínimo para texto normal, 3:1 para bordes de UI e indicadores de selección).
• El Bloqueo de Fondo: Cuando la paleta está activa, el resto de la aplicación debe renderizarse como inert y ocultarse de los lectores de pantalla. Usa <dialog>.showModal() para lograr el atrapamiento de enfoque, el oscurecimiento del fondo y el cierre nativo con Escape.

2. Adaptaciones de Respuesta y Táctiles

• Ajuste de Ventana Gráfica Táctil: En pantallas móviles, la paleta de comandos debe cambiar a un overlay de pantalla completa o un cajón deslizante inferior.
• Manejo del Teclado Virtual: Autoenfoca la entrada de búsqueda al abrir, y usa inputmode="search" para asegurar que el dispositivo móvil muestre el botón de acción "Buscar" correcto en su teclado virtual.
• Ocultar Indicaciones Físicas: En dispositivos solo táctiles, oculta las insignias de atajos de teclado físico (por ejemplo, ⌘K o ⌥I) ya que son irrelevantes y crean desorden visual.
• Tamaño de Objetivos Táctiles: Las etiquetas removibles, los chips de categoría y las filas de lista deben tener una altura de al menos 44px en pantallas táctiles para acomodar toques de dedos, cumpliendo con WCAG 2.2 SC 2.5.8.

---

Patrones de Falla Comunes

• La Trampa de "Desplazamiento Infinito": Permitir que el feed de resultados renderice más de 100 coincidencias sin un contenedor de desplazamiento, desbordando la pantalla y haciendo que las guías del pie de página sean inaccesibles.
• Falta de Bloqueo de Desplazamiento del Fondo: Permitir que el documento de fondo se desplace mientras el usuario navega por la paleta de comandos, causando desorientación en el diseño.
• Pérdida del Enfoque de Entrada: Hacer clic en un chip de categoría o una opción de resultado y perder el enfoque del teclado desde la entrada de texto, requiriendo que los usuarios de teclado vuelvan a hacer tabulación.
• Visualización Móvil Incomprensible: Mantener un modal pequeño centrado en escritorio en una pantalla móvil de 320px, cortando las etiquetas principales y las insignias de atajo.
• Falta de Reflejo del Estado del Disparador: El botón persistente del encabezado no muestra el atajo de teclado, dejando a los usuarios de teclado sin saber que existe una paleta de comandos.

---

Criterios de Validación

• Un botón disparador persistente está presente en el encabezado con una insignia visual clara de Cmd+K / Ctrl+K.
• Presionar Cmd+K o Ctrl+K en cualquier lugar de la página abre el modal.
• El enfoque del teclado se mueve inmediatamente a la entrada de búsqueda y el desplazamiento de la página de fondo se bloquea.
• La navegación de opciones se maneja con las teclas de flecha Arriba y Abajo, con un estado activo enfocado altamente visible.
• Las filas de opciones presentan una jerarquía estructurada: Icono izquierdo, Título de acción en negrita, Jerarquía de ruta contextual e Insignia de atajo derecha.
• El patrón Combobox de ARIA APG está completamente especificado, incluyendo role="combobox", role="listbox", role="option" y aria-activedescendant.
• Una región aria-live="polite" está presente para anunciar cambios en el recuento de resultados de búsqueda a los lectores de pantalla.
• En ventanas gráficas móviles, la paleta se adapta a pantalla completa o a un cajón inferior, ocultando las insignias de atajos físicos y ajustando las filas a un mínimo de 44px de altura.
• Presionar Escape o hacer clic en el fondo (scrim) cierra la paleta y devuelve el enfoque al botón disparador.