---
name: wireframes-flujos
description: Wireframes y user flows para Claude. Cubre wireframes descriptivos en formato texto, user flows como diagrama de texto, information architecture, navigation patterns (tabs/drawers/breadcrumbs), empty states/error states/loading states, decisiones de breakpoints responsivos y protocolo de handoff a implementador.
version: "1.0.0"
herramientasPermitidas: [Read, Grep]
evolvable: true  # default para skill estandar
exclusiones:
  - "No cargar para diseño visual de alta fidelidad con colores, tipografía y design tokens — para diseño visual de UI cargar `design-tokens` y el skill de diseño responsivo."
  - "No cargar para implementar los componentes Angular/React descritos en el wireframe — los wireframes son specs para el implementador; para implementación cargar `angular-moderno` o el skill de frontend correspondiente."
  - "No cargar para investigación de usuarios (entrevistas, encuestas, usabilidad) — los wireframes asumen que el UX research ya definió las necesidades; para investigación cargar el skill de UX correspondiente."
  - "No cargar para generación de diagramas UML de arquitectura o diagramas de secuencia técnicos — para diagramas de arquitectura cargar `diagrama-arquitectura` o `generacion-mermaid`."
---
# Wireframes y Flujos de Usuario

## Cuándo NO cargar

- La tarea es diseño visual de alta fidelidad (colores, tipografía, design tokens): cargar `design-tokens`.
- La tarea es implementar los componentes descritos en el wireframe: cargar `angular-moderno` o el skill de frontend del stack.
- La tarea es investigación de usuarios (entrevistas, usabilidad): cargar el skill de UX correspondiente.
- La tarea es diagramas de arquitectura o secuencia técnicos: cargar `diagrama-arquitectura` o `generacion-mermaid`.

## Filosofía

Claude trabaja con **wireframes descriptivos en texto**, no imágenes. Un wireframe
de texto bien escrito comunica estructura, jerarquía, comportamiento y decisiones
de UX mejor que un mockup visual de baja fidelidad, y puede ser consumido
directamente por el agente implementador sin ambigüedad.

El objetivo no es describir cómo se verá — es describir qué hay, dónde está,
qué hace y cómo responde al usuario.

---

## 1. Formato de Wireframe Descriptivo

### Estructura de un wireframe de pantalla

```
PANTALLA: [Nombre de la Pantalla]
URL/RUTA: [/ruta o nombre de pantalla]
PROPÓSITO: [Qué logra el usuario aquí en 1 oración]
USUARIO: [Rol o tipo de usuario que ve esta pantalla]

━━━ LAYOUT ━━━
[Descripción del grid/layout general]

┌─────────────────────────────────────────────┐
│  HEADER                                     │
│  [Logo]    [Nav: Inicio | Usuarios | Config]│
│                          [Avatar + Dropdown]│
├──────────────────────────────────────────── ┤
│  SIDEBAR (240px fijo)  │  CONTENIDO PRINCIPAL│
│                        │                     │
│  - Sección A (activa)  │  [Área de trabajo]  │
│  - Sección B           │                     │
│  - Sección C           │                     │
├────────────────────────┴─────────────────────┤
│  FOOTER: versión | soporte | términos        │
└──────────────────────────────────────────────┘

━━━ CONTENIDO PRINCIPAL (detalle) ━━━

H1: "Gestión de Usuarios"
[Botón primario: "+ Nuevo Usuario"] [Botón secundario: "Exportar CSV"]

Barra de búsqueda: [Buscar por nombre o email...] [Filtros]

Tabla:
  Columnas: Nombre | Email | Rol | Último acceso | Acciones
  Ordenable por: Nombre (asc actual), Último acceso
  Filas: 20 por página
  Acciones por fila: [Editar] [Desactivar] [...]

Paginación: [< Anterior] [1] [2] [3] [...] [12] [Siguiente >]

━━━ COMPORTAMIENTOS ━━━
- Búsqueda: debounce 300ms, actualiza tabla en tiempo real
- Click en fila: abre panel lateral con detalle del usuario
- Nuevo Usuario: abre modal de 3 pasos
- Filtros: se persisten en query params de la URL

━━━ ESTADOS ━━━
(Ver sección de estados abajo)
```

---

## 2. User Flows (Diagrama en Texto)

### Notación de flujo

```
[Pantalla] → acción → [Pantalla destino]
[Pantalla] → acción → (Decisión) → SÍ → [A]
                                 → NO → [B]
[Pantalla] → acción → {API call} → éxito → [C]
                                 → error → [D]
```

### Ejemplo: Flujo de Login

```
[Login]
  Ingresa email y password
  │
  ├─ [Olvidé mi contraseña] → [Recuperar Contraseña]
  │                              ↓
  │                           {API: reset}
  │                              ├─ éxito → [Mensaje: "Revisa tu email"]
  │                              └─ error → [Error inline: "Email no registrado"]
  │
  └─ [Iniciar Sesión]
       ▼
    {API: login}
       ├─ éxito, rol=ADMIN → [Dashboard Admin]
       ├─ éxito, rol=USUARIO → [Dashboard Usuario]
       ├─ error: credenciales → Error inline (sin indicar cuál es incorrecto)
       ├─ error: cuenta bloqueada → Modal: "Cuenta bloqueada"
       └─ error: 2FA requerido → [Verificación 2FA]
```

Para flujos multi-paso completos, mapa de sitio IA y navigation patterns detallados,
ver [recursos/referencia-completa.md](recursos/referencia-completa.md).

---

## 3. Empty States, Error States, Loading States

### Empty State

```
CUANDO: La lista/tabla no tiene datos

ESTRUCTURA:
[Ícono ilustrativo grande]
[Título: "No hay usuarios aún"]
[Descripción: "Agrega el primer usuario para comenzar."]
[Botón primario: "+ Agregar Usuario"]   ← solo si el usuario tiene permiso

VARIANTES:
- Primera vez (onboarding): ícono friendly, CTA activo
- Sin resultados de búsqueda: "Intenta con otros filtros", [Limpiar filtros]
- Sin permisos: ícono de candado, sin CTA
```

### Error States

```
Error inline (campos de formulario):
[Input con borde rojo]
"El email ya está registrado"   ← debajo del campo, 14px, color error

Error de página (4xx):
H1: "Página no encontrada" (404) | "Acceso denegado" (403)
[Descripción en lenguaje humano, sin códigos de error]
[Botón: "Ir al inicio"]

Error de API (500 en acción):
Toast (rojo): "No se pudo guardar. Intenta de nuevo."
[Reintentar]   ← si la acción es reintentable
NO mostrar el error técnico al usuario
```

### Loading States

```
SKELETON (preferido para listas y cards — evita layout shift):
┌─────────────────────────┐
│ ████████████ ██████████ │  ← líneas grises animadas
│ ████████             ██ │
└─────────────────────────┘

SPINNER (para acciones puntuales — submit de form, botón):
[Botón: Guardando...]   ← botón deshabilitado con spinner inline

PROGRESO (para operaciones largas >3s):
Subiendo archivo: [████████░░░░░░░] 53%
[Cancelar]
```

---

## 4. Handoff de Wireframe a Implementador

El wireframe está listo para el implementador cuando incluye:

- Nombre, ruta URL y propósito de cada pantalla
- Layout descrito con grid, columnas y proporciones
- Todos los elementos nombrados específicamente
- Comportamientos interactivos descritos (hover, click, debounce)
- Empty, loading y error states definidos
- Entradas y salidas de la pantalla
- API calls marcadas con `{API: ...}` y manejo de errores
- Comportamiento responsive en desktop, tablet y móvil

El implementador NO debe inventar comportamientos no descritos en el wireframe.
Si encuentra una ambigüedad, PARA y reporta. No adivina.

Para checklist de entrega completo y decisiones de breakpoints responsive,
ver [recursos/referencia-completa.md](recursos/referencia-completa.md).

---

## Gotchas / Errores comunes no obvios

**Los wireframes de texto no especifican el comportamiento de scroll en paneles laterales, causando que el implementador elija entre `overflow-y: auto` en el sidebar o en el body, y la decisión incorrecta hace que el header desaparezca al scrollear**: en un layout con sidebar fijo y contenido principal scrollable, si el wireframe dice "SIDEBAR (240px fijo)" sin especificar `height: 100vh; overflow-y: auto` explícitamente, el implementador puede implementar el scroll en el `body` haciendo que el sidebar desaparezca del viewport. Causa: las dimensiones en wireframes de texto no implican comportamiento de overflow ni posicionamiento CSS. Fix: en la sección `━━━ LAYOUT ━━━`, agregar siempre la línea `SCROLL: [componente que scrollea] — [contenido fijo que no scrollea]`. Ejemplo: "SCROLL: contenido principal. FIJO: header y sidebar".

**Un user flow que muestra `{API: login} → éxito, rol=ADMIN → [Dashboard Admin]` no especifica qué pasa durante la transición — si hay un estado de carga, un redirect, o si el componente de Dashboard es el mismo con diferente contenido**: el implementador que lee el flujo puede implementar un redirect `/dashboard-admin` (ruta separada) o un router Angular que carga el componente `DashboardComponent` con un guard, o simplemente mostrar/ocultar secciones en el mismo componente. Las tres implementaciones son válidas según el flujo, pero incompatibles entre sí. Causa: los user flows de texto documentan estados y transiciones pero no el mecanismo técnico de navegación. Fix: agregar una nota de "decisión de implementación" en cada `{API call} → éxito → [pantalla]` donde la transición no sea obvia: `[Dashboard Admin] ← guard verifica rol en el token, ruta separada /admin/dashboard` o `[Dashboard compartido, contenido condicional por rol]`.

**Los wireframes de empty states que incluyen `[Botón primario: "+ Agregar"]` sin especificar las condiciones de visibilidad del botón resultan en interfaces donde usuarios sin permiso de escritura ven un botón que falla con 403 al hacer clic**: el wireframe describe el empty state feliz, pero el implementador que ve `[Botón primario: "+ Agregar Usuario"]` no sabe si debe verificar el permiso antes de renderizarlo. Causa: los wireframes frecuentemente documentan el flujo del usuario con permisos completos y omiten los estados de permisos reducidos. Fix: en la sección `COMPORTAMIENTOS` de cada pantalla, incluir explícitamente las condiciones de visibilidad de acciones: `"+ Agregar Usuario: visible solo si usuario tiene permiso USERS_WRITE"`. Si la pantalla tiene variantes por rol, documentar cada variante como sección separada `━━━ VARIANTE: USUARIO_SOLO_LECTURA ━━━`.

**Los wireframes de formularios multi-paso no especifican si el estado de los pasos anteriores persiste cuando el usuario regresa al paso 1 desde el paso 3, causando inconsistencias entre implementaciones donde uno limpia el form y otro lo conserva**: en un wizard de 3 pasos donde el paso 2 depende de datos del paso 1, si el usuario regresa al paso 1 y cambia el tipo de cuenta, el paso 2 puede quedar con datos inválidos para el nuevo tipo. Causa: los user flows documentan la ruta feliz forward; la navegación hacia atrás y sus efectos en el estado son una decisión de UX no documentada. Fix: en el user flow del wizard, agregar explícitamente los bordes de retroceso: `[Paso 2] → [Atrás] → [Paso 1, datos anteriores pre-llenados]` o `[Paso 1, formulario limpio, pasos 2 y 3 invalidados]`. La elección entre ambos depende del impacto de un cambio en paso 1 sobre los datos de pasos posteriores.
