ui-preview-gate

UI Preview Gate

Cada cambio que altere una pantalla pasa por cuatro fases. No omitas una fase porque el cambio parezca pequeño; las imágenes son lo que los revisores aprueban.

1. Inspeccionar el estado actual
2. Previsualizar y obtener aprobación (antes de comenzar a trabajar)
3. Implementar
4. Verificar que el resultado coincida con la vista previa aprobada (después de terminar)

Excepción: una corrección de errores que no cambie la pantalla prevista puede omitir la fase 2. Si los usuarios aún pueden ver una diferencia, reporta las imágenes antes/después con la corrección. Mostrar una pantalla, diálogo, hoja o mensaje diferente al anterior es un cambio de pantalla, no esta excepción, incluso si reutiliza un componente existente. Obtén primero la aprobación de la fase 2.

Cuándo aplica

• Aplícalo sin que te lo pidan. Los usuarios nunca deberían tener que nombrar este skill.
• Revisa cada turno, no solo el primero. Una conversación que comenzó como soporte, investigación, revisión o reporte de errores a menudo se convierte en "¿y si la pantalla hiciera X?" a mitad de camino; a partir de ese turno, este skill aplica.
• "¿Qué opinas?", "¿alguna idea?" y "¿cómo se vería?" sobre una pantalla cuentan como propuestas.
• Una vez iniciado, sigue aplicándolo en turnos posteriores hasta que el cambio aprobado sea verificado (fase 4) o el usuario lo descarte.
• Una propuesta respondida solo en prosa o en una tabla de casos está incompleta. Adjunta la imagen antes/después en la misma respuesta, o di por qué aún no se puede hacer y cuándo se hará.
• Mientras un cambio de UI está pendiente de aprobación o en progreso, los informes de avance, listas de opciones y preguntas sobre el mismo también deben volver a adjuntar su imagen antes/después o dar la ruta de la imagen. Nunca describas la pantalla modificada solo en prosa.

Los skills normalmente se seleccionan por turno a partir de su descripción, por lo que los turnos a mitad de conversación pueden pasarse por alto. agent-instructions.md junto a este archivo es una regla corta para agregar a AGENTS.md / CLAUDE.md para que el agente vuelva a verificar en cada turno.

1. Inspeccionar el estado actual

Nunca propongas desde la memoria o suposiciones.

• Captura la pantalla real desde un servidor de desarrollo o compilación en ejecución. La ventana gráfica predeterminada es móvil de 375 px de ancho; agrega escritorio cuando el cambio también afecte los diseños de escritorio.
• Lee el código que la renderiza: estructura de pestañas/rutas, componentes, texto actual.
• Registra la evidencia como ruta/al/archivo:línea más la captura. Cada afirmación sobre la UI actual debe apuntar a uno de ellos.
• Prefiere componentes, patrones y texto existentes. Si se necesita un nuevo patrón, indica por qué los existentes no se ajustan.

Captura con scripts/capture.mjs (ver Scripts) para que la toma anterior, la vista previa y la toma de verificación compartan una misma ventana gráfica, escala y estado de datos.

Inventario de casos (haz esto sin que te lo pidan, antes de la primera vista previa)

El aprobador nunca debería tener que preguntar "¿y después de tocarlo?" o "¿y si hay datos?". Antes de enviar cualquier vista previa, enumera cada caso que toca el cambio, a partir del código y de la aplicación real:

• Estados de la pantalla modificada: vacía / tiene datos / muchos elementos (truncamiento, "ver todo") / cargando / error / bloqueada por plan, rol o permiso / otras configuraciones (tienda única vs. multi-tienda, flags de funcionalidad).
• Cada pantalla a la que se llega desde un control nuevo o modificado: formularios, selectores, diálogos, errores de validación, cancelar/volver, confirmación, éxito, fallo.
• Después de la acción: cómo se ve la pantalla de origen una vez que la acción se completa (aparece un nuevo elemento, cambian los contadores), y cómo deshacer o editarlo.
• Otros lugares que muestran los mismos datos: listas, pantallas de detalle, historial, informes, exportaciones, otras plataformas (escritorio, Web, LINE, lado del cliente). Marca cada uno como cambios / sin cambios pero muestra nuevos datos / no afectado.

Envía el inventario como una tabla con la primera vista previa: caso, lo que el usuario ve, componente existente reutilizado y estado de la imagen (adjunta / necesita datos de prueba - cómo se preparará / fuera del alcance - por qué). Las vistas previas pueden llegar en lotes, pero el primer mensaje siempre muestra el inventario completo, y la aprobación de una imagen nunca implica la aprobación de casos aún no mostrados. Propón valores predeterminados sensatos para decisiones abiertas en lugar de solo enumerar preguntas.

2. Previsualizar y obtener aprobación

Antes de escribir código de implementación, muestra al aprobador una imagen lado a lado y un resumen breve, luego espera una confirmación explícita.

Reglas de la imagen:

• Antes a la izquierda, después a la derecha, en una sola imagen.
• Recuadra cada región modificada: rojo en antes, verde en después.
• Empareja los recuadros: cada cambio obtiene un recuadro en ambos lados en el lugar correspondiente. Para una adición, marca el punto de inserción en antes con un marcador fino en el espacio ("pad": 0, h pequeño); para una eliminación, marca el espacio en después. Nunca recuadres un vecino no relacionado (por ejemplo, la fila de abajo) para que represente un elemento faltante.
• Toma las coordenadas de los recuadros de la salida de capture.mjs --selector (o rectángulos de elementos medidos con Playwright en una prueba e2e cuando el estado requiera interacción, p. ej., un diálogo que se abre después de ingresar datos), no a ojo. Mira la imagen compuesta antes de enviarla para confirmar que cada recuadro está sobre su objetivo.
• Misma ventana gráfica, posición de desplazamiento y datos de muestra en ambos lados.
• Si la pantalla se ramifica por estado (datos presentes/ausentes, error, vacía, por rol o por configuración), muestra un par antes/después para cada estado que toque el cambio. Un estado que no mostraste no está aprobado. Haz una imagen por estado; nunca pongas varios pares en una sola imagen.
• Una pantalla real a la que solo se llega mediante preparación (código modificado temporalmente para abrirla) debe llevar "staged" en la especificación para que la imagen lo indique.
• Verificación previa al envío: compose.mjs rechaza las especificaciones que infringen estas reglas e imprime una lista de verificación. Abre la imagen, responde cada elemento y coloca las respuestas en el mensaje (ver plantillas). Si un elemento falla, corrige y vuelve a componer; nunca expliques un elemento fallido en texto.
• Sigue la política de imágenes a continuación.

Política de imágenes

El usuario o proyecto decide si se permiten maquetas. Busca la elección en la solicitud o en las instrucciones del proyecto (AGENTS.md, CLAUDE.md, documentos de contribución). Si no se indica nada, usa real-only. Nunca cambies a mockup-allowed por tu cuenta porque capturar sea difícil; pregunta en su lugar.

• real-only (predeterminado): ambos lados son capturas de pantalla completa de la aplicación real en ejecución. Construye el lado "después" en una rama prototipo o detrás de un flag de funcionalidad y captúralo. Nunca uses fragmentos recortados o pegados, maquetas redibujadas desde código o a mano (incluidas imágenes generadas), capturas que corten una fila por la mitad, o datos ficticios que difieran de lo que muestra la aplicación real.
• mockup-allowed: el lado "después" puede ser una maqueta solo cuando el usuario o proyecto lo permita explícitamente. El lado "antes" sigue siendo una captura real. Marca cada panel de maqueta con "mockup": true en la especificación de compose para que la imagen lo muestre, e indícalo en la solicitud de aprobación. Una maqueta nunca cuenta como evidencia de la fase 4: la verificación siempre usa una captura real de la pantalla implementada.

Una regla de proyecto más estricta siempre gana sobre una preferencia de usuario más laxa; si entran en conflicto, señálalo y sigue la regla del proyecto.

Resumen (usa references/templates.md):

• Dónde: qué pantalla/pestaña y dónde en ella aparece el cambio
• Qué se vuelve posible, por tipo de usuario (p. ej., administrador, cliente)
• Qué no cambia, y las plataformas/superficies afectadas

La aprobación cubre exactamente lo que se mostró. Cualquier cosa fuera de eso necesita una nueva vista previa.

3. Implementar

Construye según la vista previa aprobada. Si la implementación fuerza una desviación visible (diseño, texto, comportamiento, nuevo impacto en plataforma), detente y vuelve a la fase 2 con una vista previa actualizada en lugar de enviar la diferencia.

Esto incluye pequeñas ediciones de texto y correcciones realizadas en respuesta a la revisión de código: si una corrección cambia lo que los usuarios ven más allá de las imágenes aprobadas, detente y obtén una nueva vista previa aprobada primero. Reportarlo después en texto no cuenta.

4. Verificar contra la vista previa aprobada

No reportes la finalización solo a partir de la diferencia de código.

1. Vuelve a capturar la pantalla implementada con la misma configuración de captura y estado utilizados para la vista previa.
2. Compone una imagen de verificación: vista previa aprobada | resultado real. Recuadra cada cambio prometido; recuadra cada diferencia de la vista previa aprobada en ámbar, incluso un pequeño desplazamiento. Una diferencia descrita solo en texto no está verificada.
3. Verifica, elemento por elemento:
   • cada cambio prometido está presente y coincide con la vista previa;
   • todo lo listado como "no cambia" no ha cambiado;
   • nada fuera de las regiones recuadradas se ha movido, envuelto o desbordado;
   • la interacción modificada realmente funciona al ejecutarla, no solo se renderiza. Las pruebas e2e que pasan confirman el comportamiento; no reemplazan la verificación de imagen para cada estado que debería verse sin cambios.
4. Decide:
   • Coincidencia: reporta con la imagen de verificación y el resultado de la lista de verificación.
   • Desajuste menor dentro de la intención aprobada: corrige, vuelve a capturar, vuelve a verificar.
   • Desajuste que cambia lo que fue aprobado: repórtalo y obtén aprobación nuevamente.

Enumera cualquier cosa que no hayas podido verificar (una plataforma, un dispositivo, datos reales) por separado en lugar de darlo por terminado.

Scripts

Ambos scripts necesitan Node 18+ y Playwright (npm i -D playwright && npx playwright install chromium). Configura PLAYWRIGHT_MODULE con la ruta de un módulo para reutilizar una instalación existente.

Capturar una pantalla y obtener coordenadas de recuadro para elementos:

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

Imprime los rectángulos de los selectores en píxeles CSS, listos para pegar como boxes.

Componer paneles desde una especificación JSON:

node scripts/compose.mjs spec.json

El formato de la especificación, los tonos y el diseño de verificación están en references/compose-spec.md.