Quinus/screen-flow

Flujo de pantallas

Crea un flujo de pantallas HTML independiente a partir de capturas de pantalla reales de la aplicación en ejecución. Hay tres partes:

1. Mapea las pantallas y los enlaces entre ellas, principalmente desde el código, y escríbelos en flow.json.
2. Captura cada pantalla en la aplicación en ejecución con las herramientas del agente que tengas. Para cada enlace, registra también su hotspot: dónde se encuentra el botón, pestaña o fila que lo activa en la captura de pantalla. El visor entonces inicia cada flecha en ese punto.
3. Construye la página con scripts/build_flow.py. El script realiza el diseño, las flechas, el desplazamiento y zoom, e incrusta las imágenes. Nunca escribas el HTML del visor tú mismo. Dedica tu esfuerzo a un mapa correcto y buenas capturas de pantalla.

Las rutas a continuación son relativas a la carpeta de esta habilidad (la carpeta donde se encuentra este archivo).

0. Alcance y salida

• Alcance: feature (una funcionalidad o flujo, como "checkout" o "control parental") o app (todas las pantallas). Si la solicitud no lo especifica, usa la funcionalidad que nombraron. Si no se nombra ninguna funcionalidad, usa toda la aplicación.
• Alcance de funcionalidad: incluye las pantallas de entrada que conducen a la funcionalidad, como la pestaña o pantalla de inicio con el botón que la abre. Colócalas en un pequeño grupo nav para que los lectores puedan ver dónde comienza la funcionalidad. No captures el resto de la aplicación.
• Carpeta de salida: usa lo que el usuario pidió. De lo contrario, usa screen-flows/<slug>/ en el proyecto: flow.json, screens/<screen-id>.png y screen-flow.html. Antes de escribir en el repositorio, verifica si screen-flows/ debe agregarse a .gitignore. Los PNG pueden ser grandes.

1. Mapea la navegación (antes de cualquier captura de pantalla)

Lee el código para construir un inventario. No hagas clic al azar. Dónde buscar:

Stack	Dónde vive la navegación
React Router / TanStack Router	configuración de rutas, createBrowserRouter, <Route>, carpeta routes/
Next.js / Remix / Nuxt / SvelteKit	rutas basadas en archivos: app/, pages/, routes/, src/routes/
Angular / Vue	*-routing.module.ts, router/index.ts
SwiftUI / UIKit	NavigationStack, TabView, .sheet, .fullScreenCover, coordinadores, storyboards/segues
Android	NavHost / rutas composable(...), nav_graph.xml, Activities en el manifiesto, menús de navegación inferior
Flutter	GoRouter / routes: / Navigator.push, BottomNavigationBar
React Native	createNativeStackNavigator, createBottomTabNavigator, Expo Router carpeta app/
TV / aplicaciones a 10 pies	menús basados en enfoque, rieles, tecla de retroceso del control remoto, manejadores de enlaces profundos

Luego encuentra los disparadores que enlazan las pantallas: botones, enlaces, barras de pestañas, menús, navigate(...), router.push, .sheet(isPresented:), redirecciones después de inicio de sesión, guardias. Cada disparador se convierte en un borde.

Escribe un primer flow.json sin imágenes. El formato completo está en references/flow-schema.md. En resumen:

• Grupos
  • Crea exactamente un grupo kind: "nav" para el shell de navegación principal: los destinos de la barra de pestañas o la barra lateral, la pantalla de inicio y los menús globales. Estas pantallas se colocan juntas en una fila en la parte superior del lienzo.
  • Crea un grupo kind: "feature" por funcionalidad, con sus pantallas en orden de tarea (por ejemplo: lista → detalle → editar → confirmar).
  • Coloca la incorporación, el inicio de sesión y el registro en su propio grupo de funcionalidad.
• Pantallas: una por vista distinta. Los modales, hojas, diálogos y estados importantes (vacío, error, paywall) cuentan como pantallas cuando son relevantes para el flujo. Márcalos con state. Establece entry: true en la pantalla donde comienza un grupo.
• Bordes: escribe la acción del usuario como etiqueta, por ejemplo "Tocar 'Pagar'" o "Deslizar a la izquierda". Usa kind para back (rutas de retorno), modal y redirect (navegación automática). Omite los enlaces de retorno obvios a menos que sean importantes. No enlaces cada pestaña con todas las demás. Enlaza la pestaña predeterminada con cada una de las otras, de modo que una aplicación de 5 pestañas tenga 4 bordes, no 20.

Verifica el mapa con python3 scripts/build_flow.py flow.json --check. Para una aplicación completa con más de unas 25 pantallas, muestra al usuario la lista de grupos y pantallas y pídele que la confirme antes de capturar nada.

2. Captura capturas de pantalla reales

Lee references/capture.md para la herramienta y los comandos que usar en cada plataforma. Reglas para cada plataforma:

• Utiliza primero las herramientas que te proporciona tu entorno. Estas incluyen herramientas del navegador o de vista previa, herramientas de dispositivo o simulador, y servidores MCP de Playwright/Chrome DevTools. Si no tienes ninguna, usa las alternativas en capture.md: scripts/capture_web.mjs (Playwright), xcrun simctl io, o adb exec-out screencap.
• Ejecuta la aplicación tú mismo. Usa las propias instrucciones de ejecución del proyecto (README, AGENTS.md/CLAUDE.md, scripts de package.json, configuraciones de ejecución). Usa una compilación local o de desarrollo con datos de prueba.
• Inicia sesión con una cuenta de prueba. Si necesitas credenciales, pregunta al usuario. Nunca adivines, nunca uses una cuenta de un cliente real y nunca peges secretos en flow.json.
• Usa un único dispositivo y viewport para todo el flujo. Para web móvil, usa 390×844 a 2×. Para web de escritorio, usa 1440×900. Para aplicaciones nativas, usa un único modelo de simulador o emulador. Usa el mismo tema e idioma en todas partes.
• Llega a cada pantalla como lo haría un usuario cuando sea práctico. Esto también verifica tus bordes. Si un paso es lento o inestable, abre la pantalla directamente con un enlace profundo o URL. Si la ruta real difiere de tu mapa, corrige el mapa.
• Espera hasta que la pantalla se haya estabilizado. Sin spinners, sin esqueletos, imágenes cargadas, sin toasts a menos que sean el objetivo. Cierra las superposiciones de desarrollo y los banners de depuración.
• Nunca hagas nada destructivo o irreversible, como pagos, eliminaciones o envío de correos electrónicos o mensajes, fuera de un sandbox. Captura la pantalla de confirmación y detente allí.
• Guarda cada captura de pantalla como screens/<screen-id>.png, y establece image en flow.json.
• Graba un hotspot para cada enlace mientras estés en la pantalla de origen: el cuadro delimitador del elemento que el usuario toca. Escríbelo en el mismo sistema de coordenadas que la captura de pantalla (píxeles de la imagen, o fracciones de 0 a 1). En la web, scripts/capture_web.mjs hace esto por ti a partir de un selector y escribe hotspots.json. En plataformas nativas, toma los límites del elemento del árbol de la interfaz de usuario (consulta capture.md). Omítelo para enlaces que no son un elemento visible, como un deslizamiento, una redirección automática o el botón de retroceso del sistema.
• Revisa cada captura de pantalla después de guardarla, usando tu visor de imágenes o la herramienta de lectura. Vuelve a capturar cualquier toma que esté en blanco, recortada, sea la pantalla incorrecta, una pantalla de inicio de sesión o una página de error.
• Si no se puede alcanzar una pantalla, mantenla en el mapa sin image, y escribe la razón en notes. El visor muestra una tarjeta "No se capturó captura de pantalla" para ella.

3. Construye y verifica

python3 scripts/build_flow.py <out>/flow.json            # escribe <out>/screen-flow.html
python3 scripts/build_flow.py <out>/flow.json -o docs/flow.html --max-width 900

El script solo necesita la biblioteca estándar de Python. Lee hotspots.json junto a flow.json cuando ese archivo existe, o un archivo que pases con --hotspots. Para mantener el archivo pequeño, reduce la escala de las capturas de pantalla más anchas que --max-width (por defecto 1000 px) cuando Pillow o sips de macOS esté disponible.

Abre el HTML y míralo. Usa una herramienta del navegador para capturarlo en pantalla, o ábrelo para el usuario. Luego corrige el diseño a través de flow.json y reconstruye:

Problema	Solución
Pantallas en el orden incorrecto dentro de un grupo	Reordena screens, establece entry: true, o fija una pantalla con "column": n
Un grupo es un conjunto suelto de pantallas, no una secuencia	"layout": "grid" en el grupo
Una secuencia larga debe ir en una fila	"layout": "row"
Una funcionalidad está lejos de donde comienza	Agrega el borde que lleva a ella, o establece "parent": "<group-id>"
Demasiadas flechas	Elimina los enlaces de retorno que no necesites, o enlaza las pestañas solo desde la pestaña predeterminada
Una flecha comienza en el lugar equivocado en una captura de pantalla	Corrige el hotspot de ese borde (verifícalo en el panel de detalles)

Exportaciones PNG y PDF

Si el usuario pide una imagen o un PDF, o el flujo debe ir en una solicitud de extracción, un ticket, Confluence o diapositivas, expórtalo sin interfaz gráfica. Esto utiliza el mismo renderizador que el botón de Exportar de la página:

node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png                 # todo el flujo
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout   # un grupo
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf                 # vista general + una página por grupo

Opciones: --theme light|dark (por defecto light), --no-hotspots, --no-group-pages (PDF). El script necesita Playwright, configurado de la misma manera que para capture_web.mjs. Revisa el PNG antes de entregarlo.

4. Informa

Proporciona al usuario la ruta a screen-flow.html y el número de pantallas y grupos. Enumera las pantallas sin captura de pantalla y el motivo. Menciona estos controles del visor:

• Arrastra para desplazar; desplázate o pellizca para hacer zoom.
• Haz clic en una pantalla para verla grande, con sus enlaces entrantes y salientes.
• Arrastra las pantallas, o un grupo por su encabezado, para reorganizarlos; esto se guarda en ese navegador.
• Hotspots (botón de la barra de herramientas, o H) inicia cada flecha en el botón que la activa. En el panel de detalles, los hotspots se pueden hacer clic, para que los lectores puedan navegar por el flujo como un prototipo.
• / busca, F ajusta todo en la pantalla.
• Exportar (barra de herramientas) descarga un PNG o un PDF de todo, la vista actual o un grupo, en el tema claro u oscuro. El PDF tiene una página de vista general más una página por grupo. Las exportaciones siguen las alternancias actuales (etiquetas, enlaces entre grupos, enlaces de retorno, hotspots).
• #<screen-id> al final de la URL abre esa pantalla.