chukaofili/agent-plugins

Verificar UI

Construir las pantallas es la primera mitad. Un cambio de UI no está completo hasta que se ha ejecutado en un navegador real y sus capturas de pantalla están en el PR. Una verificación de tipos limpia, una ejecución de lint y un conjunto de pruebas unitarias confirman que el código compila y su lógica se sostiene. Ninguno de ellos dice que el panel se renderiza, o que el pie de página está donde el diseño lo coloca. Los revisores que nunca ejecutan la rama juzgan el trabajo a partir de las capturas de pantalla, o no lo juzgan en absoluto.

1. Ejecútalo en un navegador real, con datos reales

Usa una aplicación en ejecución con una base de datos real (sembrada), no simulaciones, y no solo una captura de pantalla del camino feliz. Recorre cada estado que el diseño nombra, más los que no:

• Ambos temas. Los colores escritos a mano son donde las variantes de modo oscuro se olvidan.
• Móvil y escritorio. Los diseños se reordenan en los puntos de quiebre, y los pies de página y las barras de herramientas pueden huérfano la mitad de su contenido.
• Estados vacío, de carga, al límite y de error, no solo el estado poblado.
• Cada transición donde un diálogo o vista se cierra y otro se abre.
• Abre cada menú, popover y desplegable que hayas agregado. Un menú que nunca abres se ve idéntico a uno que bloquea la página cuando se abre.
• Revisa la consola del navegador y el panel de red en busca de errores mientras lo haces.

2. Ejecuta una revisión sistemática

Revisa el cambio contra las guías de diseño y framework que utiliza el repositorio (sistema de diseño, accesibilidad, mejores prácticas del framework). Si tu agente puede generar subagentes, ejecuta un revisor por guía en paralelo en un modelo más económico. Es trabajo de reconocimiento de patrones, no de juicio.

• Dale a los revisores las reglas propias del repositorio. Un revisor que no las haya leído reportará decisiones documentadas como violaciones.
• Indícales que solo reporten. Luego juzga cada hallazgo tú mismo según la probabilidad del mundo real. Rechaza hallazgos que serían ciertos para un producto diferente, como consejos de virtualización para una lista que está limitada a una docena de filas.

3. Captura capturas de pantalla para el PR

No una descripción de las pantallas: las pantallas. Capturarlas también es la forma más barata de detectar un estado que realmente no has mirado.

• Ejecuta la aplicación real. Un script de navegador desechable que alcance cada estado es suficiente. Usa los ayudantes de siembra del arnés E2E para alcanzar estados que ningún flujo de UI produce, luego elimina el script una vez que las imágenes existan. No afirma nada y no es cobertura.
• Reconstruye antes de capturar. De lo contrario, podrías capturar una captura del error que acabas de corregir.
• Espera a que terminen las animaciones antes del disparo. "Visible" se resuelve cuando un elemento está dispuesto, no cuando termina su transición de entrada, por lo que una captura ingenua muestra diálogos medio desvanecidos sin fondo. Espera a que terminen las animaciones finitas (filtra las infinitas como los pulsos de esqueleto), con un tiempo de espera.
• Alcanza cada estado como lo haría un usuario donde puedas. Forzar una bandera omite la condición de carrera que podría exponer un error.
• Confírmalos en docs/screenshots/<tema>/, junto al diseño que implementan si existe.
• Referéncialos por el SHA del commit, no por la rama, p. ej. https://github.com/<org>/<repo>/blob/<sha>/<path>?raw=true. Una URL de rama muere cuando la rama se elimina al fusionar, y deja el PR lleno de imágenes rotas.

Sin navegador disponible

Si el entorno realmente no puede ejecutar la UI (sin herramientas de navegador, credenciales faltantes, infraestructura que no controlas), díselo en la sección de Pruebas del PR. Nombra qué lo bloqueó y qué verificaste en su lugar. El silencio se lee como "verificado".

Envía las correcciones de la revisión como una etapa adicional

Las correcciones encontradas por este pase van en un nuevo PR apilado sobre la funcionalidad, para que la compilación y el pase de revisión sigan siendo revisables por separado (consulta stacked-prs).

Lo que este pase detecta

Ninguno de estos vino de un verificador de tipos, linter o conjunto de pruebas unitarias:

• Un esqueleto de carga que no coincidía con su página. Esqueletizó una barra de herramientas que la página no tiene, por lo que cada navegación saltaba entre dos diseños. Refleja el diseño real fila por fila, o no envíes un esqueleto.
• Dos diálogos pintados a la vez en una transición, porque cada diálogo estaba montado y solo su bandera open se alternaba. Oculto no es desmontado.
• Un destello de identidad incorrecta: la propia fila del usuario ofrecía eliminarlos durante un fotograma, porque el cliente leyó la sesión después del primer renderizado. La identidad que el servidor ya conoce debería venir con la página.
• Un estado vacío falso: "No se encontraron resultados" se renderizó durante un fotograma antes de que la consulta se resolviera, porque cero filas significaban tanto "cargando" como "vacío".
• Un token de diseño intercambiado por uno de apariencia similar, visiblemente diferente en uno de los temas.
• Una etiqueta codificada junto a otros cuatro puntos de llamada que leen la misma etiqueta de un catálogo compartido.
• Un menú que bloqueaba la página al abrirse, porque un subcomponente requería un padre que no tenía. Una pulsación manual lo pasó por alto dos veces, porque nadie abrió el menú.
• Un elemento de especificación omitido silenciosamente, y otro eliminado por una buena razón pero dejado sin documentar. Cualquier desviación del diseño necesita una nota que explique por qué.
• Un diálogo que se contradice a sí mismo, encontrado al mirar la captura de pantalla: un aviso decía "todos los asientos están en uso" mientras el pie de página a su lado aún ofrecía "quedan 2 asientos".