​

Protocolo de patrones UX

Este documento define los patrones de experiencia de usuario que DEBEN respetarse en toda implementación de interfaz. Si un componente no está listado aquí, buscar el patrón más cercano y seguir sus principios. Ante la duda, preguntar antes de implementar.

​

1. Arquitectura de navegación

​

1.1 Separación por dominio

• Contiene SOLO features del negocio — lo que el usuario final usa para cumplir sus objetivos.
• Ejemplos: Decisiones, Proyectos, Reportes, Contrapartes, Documentos.
• Cada ítem del sidenav lleva a una vista de nivel 1 (browse/listado).

• Contiene SOLO features de administración y gestión del sistema.
• Ejemplos: Gestión de usuarios, Roles y permisos, Configuración de cuenta, Facturación, Integraciones, Preferencias.
• Acceso desde el avatar del usuario o un ícono de configuración, NUNCA desde el sidenav principal.

​

1.2 Navegación por capas (layouts contextuales)

• Layout: completo con sidenav visible.
• Propósito: el usuario explora módulos y listados.
• Ejemplo: lista de decisiones, dashboard principal, listado de contrapartes.
• El sidenav permanece visible y funcional.

• Layout: limpio, SIN sidenav.
• Propósito: el usuario está en un flujo de creación o edición paso a paso.
• Navegación: stepper/wizard con indicador de progreso.
• Acciones: “Siguiente”, “Anterior”, “Cancelar” (con confirmación si hay cambios sin guardar).
• Al completar o cancelar, regresa a Capa 1.
• NUNCA mostrar el sidenav durante un flujo de creación — distrae y rompe el foco.

• Layout: limpio, SIN sidenav.
• Propósito: el usuario está viendo el detalle de un registro o información expandida.
• Navegación: botón “Volver” o “Salir” (iconografía + texto) en la parte superior.
• Al salir, regresa a la vista de origen (Capa 1 o el contexto que lo invocó).
• Puede contener tabs internos para organizar información del detalle.
• NUNCA mostrar el sidenav en la vista de detalle.

Capa 1 (Browse) → click en registro → Capa 3 (Detail)
Capa 1 (Browse) → click en "Crear nuevo" → Capa 2 (Create)
Capa 3 (Detail) → click en "Editar" → Capa 2 (Edit)
Capa 2/3 → "Volver" / "Cancelar" → Capa anterior

​

2. Patrones de interacción

​

2.1 Tablas y listados

• SIEMPRE usar un ícono de acción (ojo, chevron, o botón “Ver”) en la columna de acciones.
• NUNCA hacer el texto de una celda clickeable como mecanismo de navegación al detalle.
• Razón: el texto clickeable no es discoverable y rompe la expectativa de selección.

• Posición: SIEMPRE última columna a la derecha.
• Contenido: íconos de acción con tooltip (ver, editar, eliminar).
• Si hay más de 3 acciones, agrupar en un menú contextual (tres puntos verticales).
• Orden consistente: Ver → Editar → Más opciones (menú) → Eliminar.

• Checkbox en la primera columna si se requiere selección múltiple.
• Barra de acciones bulk aparece al seleccionar al menos un registro.

• Columnas ordenables muestran ícono de flechas (↕) en el header.
• Filtros van encima de la tabla, nunca dentro del header de columna.

​

2.2 Formularios

• Máximo 2 columnas en desktop, 1 columna en mobile.
• Labels SIEMPRE encima del campo (top-aligned), nunca inline/placeholder-only.
• Campos obligatorios marcados con asterisco (*) junto al label.

• Validar al salir del campo (on blur), no en tiempo real mientras el usuario escribe.
• Mensajes de error debajo del campo, en rojo, con texto descriptivo.
• Al enviar formulario con errores, scroll automático al primer campo con error.

• Botón primario (Guardar/Crear/Enviar) a la derecha.
• Botón secundario (Cancelar) a la izquierda del primario.
• Si el formulario tiene cambios sin guardar y el usuario intenta salir, mostrar diálogo de confirmación.

​

2.3 Modales y diálogos

• Modal: confirmaciones, formularios cortos (≤5 campos), alertas.
• Nueva página (Capa 2 o 3): formularios largos, vistas de detalle, flujos multi-paso.

• Header: título descriptivo + botón X para cerrar.
• Body: contenido.
• Footer: acciones (Cancelar a la izquierda, Acción primaria a la derecha).
• Cerrar con X, con botón Cancelar, o con click en el overlay — los tres deben funcionar.
• Cerrar con Escape SIEMPRE habilitado.

• Título claro: “¿Eliminar [nombre del recurso]?”
• Descripción del impacto: “Esta acción no se puede deshacer.”
• Botón destructivo en rojo, con texto explícito (“Eliminar”, no “Aceptar”).

​

2.4 Feedback y estados

1. Loading: skeleton o spinner. Preferir skeleton para layouts conocidos.
2. Empty: mensaje + ilustración/ícono + CTA para crear el primer registro.
3. Error: mensaje descriptivo + acción de reintentar.
4. Success: los datos se muestran. Transición suave desde skeleton.

• Posición: esquina superior derecha.
• Duración: 5 segundos para info/success, persistente para errores.
• Acciones dentro de toast solo para “Deshacer”.

​

3. Layout y espaciado

​

3.1 Sistema de espaciado

​

3.2 Breakpoints

​

3.3 Grid y contenedores

• Contenido principal: máximo 1200px de ancho, centrado.
• Formularios de creación/edición: máximo 800px de ancho, centrado.
• Cards dentro de dashboards: grid responsivo con gap de 24px.

​

4. Reglas cross-stack

​

4.1 Mapeo de componentes equivalentes

​

4.2 Regla de consistencia cross-stack

​

5. Checklist de verificación

• ¿La navegación respeta las 3 capas (Browse → Create → Detail)?
• ¿Las features de admin están en settings, NO en el sidenav?
• ¿Las tablas usan ícono de acción para navegar al detalle?
• ¿Los formularios tienen labels visibles (no solo placeholders)?
• ¿Los 4 estados (loading, empty, error, success) están cubiertos?
• ¿El espaciado usa múltiplos de 4px?
• ¿La vista se ve correcta en mobile, tablet y desktop?
• ¿Los modales se cierran con X, Cancelar, overlay y Escape?
• ¿El comportamiento de interacción es idéntico al patrón equivalente en el otro stack?

​

6. Cómo usar este protocolo

​

Como skill de Claude Code (.claude/skills/ux-patterns/SKILL.md)

​

Como sección en CLAUDE.md

​

Como referencia en AGENTS.md (herramienta agnóstica)

​

Para herramientas que no usan archivos .md (Antigravity, Lovable, etc.)