Revisión UI de Diseño (UAT)
Revisa la implementación visual de un sitio web frente a sus referencias de diseño. Por defecto, genera un informe HTML en inglés, centrado en incidencias; respeta el idioma o formato de informe solicitado. La habilidad es reutilizable en varios proyectos. Las URL de proyecto, mapeos de frames, desviaciones aceptadas, credenciales y evidencia de ejecución no pertenecen a esta carpeta de habilidad.
Comienza con el alcance del usuario
Usa las URL del sitio web y de Figma proporcionadas como el alcance inicial. Reutiliza un perfil de proyecto adecuado si existe; de lo contrario, comienza el descubrimiento sin exigir una lista de rutas o configuración preparada. Cuando una página de Figma representa una entrega de versión, inventaría toda la página y descubre la ruta de prueba de cada módulo. La URL del sitio web proporcionada es un punto de entrada, no una restricción de ruta. Respeta un alcance explícito de página completa; registra exclusiones y estados bloqueados en lugar de sustituir silenciosamente una muestra. Para un alcance grande no especificado, indica un límite de revisión útil. Muestrear una sola pantalla no acepta un módulo completo.
Mantén los datos del proyecto en el espacio de trabajo escribible del proyecto actual, respetando las instrucciones del repositorio. Un valor predeterminado útil es design-uat/<proyecto>/project.json y ejecuciones/<id-ejecucion>/, pero conserva una ubicación establecida. Consulta project-data.md al crear mapeos, construir la entrada del informe o registrar una re-ejecución.
Descubre las herramientas realmente disponibles. Prefiere un conector de Figma para la estructura y medidas de diseño, y control del navegador para la UI en vivo. Usa las instrucciones de herramienta relevantes y las habilidades prerrequisito cuando sea necesario; esta habilidad no proporciona esas herramientas. Reutiliza una sesión de inicio de sesión autorizada existente si es posible. Si el acceso está bloqueado, continúa con trabajo independiente útil e informa con precisión qué estados no pudieron revisarse.
Descubre el mapeo de diseño a página
Inspecciona la jerarquía del diseño y la navegación en vivo antes de comparar imágenes. Un lienzo puede contener contenedores de módulos, frames de pantalla, ejemplos de estados locales, notas, anotaciones y propuestas alternativas. Identifica el objetivo visual dentro de esa estructura en lugar de exportar todo el tablero de documentación como una pantalla.
Lee las notas asociadas y los ejemplos de estados locales. Pueden especificar comportamiento responsive, dimensiones de entrada, truncamiento o detalles de componentes que el frame principal no muestra. Usa el contenido visible/efectivo del nodo; el texto oculto de ayuda/error de un componente no es un requisito activo simplemente porque existe en el árbol.
Distinguir una especificación de página real de una ilustración de interacciones generales. Un ejemplo genérico de cajón puede revelar una discrepancia en un módulo existente, pero no establece los campos requeridos de cada categoría. Conserva un hallazgo útil entre módulos con su ruta real, contexto de navegación y limitación de línea base; etiqueta el estado de legado sospechoso como no confirmado a menos que se conozca su historial.
Coincide usando la evidencia combinada del contexto del módulo, la ruta, el título de página visible, las etiquetas de campo, la estructura de la UI y la apariencia renderizada. Registra los IDs de frame, página/estado, región de comparación, confianza y estado de mapeo en los datos del proyecto. Una URL puede tener muchos estados visuales. No confundas una lista, un cajón abierto, un input enfocado y un estado vacío.
Procede con coincidencias bien respaldadas marcadas como inferidas cuando no estén confirmadas por humanos. Agrupa las opciones genuinamente ambiguas para el usuario mientras continúas con los casos no bloqueados. Registra diseños alternativos/de respaldo como fuera del alcance seleccionado con una razón; el nombre por sí solo no establece la versión aceptada. Verifica los mapeos guardados previamente contra el diseño actual y la página en vivo antes de reutilizarlos.
Para archivos grandes de Figma, conserva los metadatos sin procesar localmente y devuelve resúmenes compactos y superficiales al contexto. Reduce según los ancestros conocidos antes de extraer subárboles detallados o capturas de pantalla. Evita cargar repetidamente todo el archivo.
Captura evidencia comparable
Lee evidence-workflow.md antes de la primera captura o al diagnosticar un problema de comparación. Cubre el desbordamiento de mesa de trabajo, coincidencia de estados, exclusión de anotaciones, contenido dinámico, recortes locales y aceptación de capturas de pantalla.
Expón los estados visuales necesarios a través de navegación, enfoque y cambios de entrada reversibles. No realices cambios de negocio solo para obtener una captura de pantalla sin autorización para esos cambios. Si un estado requiere datos no disponibles o una acción de escritura, registra esa limitación en lugar de inventarla.
Captura la región de diseño exacta y el estado del navegador en un viewport, escala y tema compatibles. Verifica que las fuentes/contenido se hayan cargado y que el objetivo esté estable. Rechaza capturas de carga transitoria a menos que la carga sea el estado revisado. Inspecciona las capturas de pantalla guardadas antes de usarlas en un informe. Conserva las capturas originales junto con cualquier recorte, superposición y anotación.
Fundamenta las diferencias en ambas imágenes juntas y, cuando sea útil, en la geometría de Figma y los límites de elementos del navegador. Atribuye los valores medidos a su origen. Usa scripts/compare_regions.py para recortes emparejados opcionales a escala nativa y marcas cuando Pillow esté disponible. El renderizador del informe solo requiere la biblioteca estándar de Python.
Inspecciona las relaciones en una fila de control, así como las dimensiones individuales: espacios adyacentes, alineación, espacio de acción restante y cambios cuando aparecen controles de filtro activo. Agrupa una corrección de diseño compartida y sus consecuencias visuales bajo un solo problema estable cuando esté respaldado por evidencia o comentarios explícitos del revisor. Distingue esa agrupación de un diagnóstico de causa raíz a nivel de código.
Distinguir el contexto de los defectos: los datos de muestra, la identidad de la cuenta, la navegación expandida, los anuncios globales y las versiones posteriores de componentes pueden cambiar una captura de pantalla. Regístralos; no descartes silenciosamente sus efectos de diseño. Los valores de texto pueden excluirse de la coincidencia de copia mientras su ajuste, desbordamiento y alineación siguen siendo revisables. Nunca estires las capturas de pantalla para ocultar diferencias ni inventes una puntuación de similitud de página completa.
Haz hallazgos procesables
Clasifica cada hallazgo según lo que su evidencia respalda:
defecto-visual: una falla visual reproducible, como recorte, superposición o una violación de implementación confirmada. Indica las condiciones y la fuente de la expectativa.discrepancia-linea-base: una diferencia demostrada con respecto a la referencia proporcionada cuyo diseño/versión actualmente aceptado puede necesitar confirmación.aclaracion-diseno: una condición observada con orientación de diseño insuficiente o contradictoria para decidir la aceptación.
Mantén separados la confianza de la observación, la prioridad sugerida y el estado de seguimiento. No llames a una diferencia de captura de pantalla de alta confianza un defecto aceptado simplemente porque la diferencia sea obvia. Usa el esquema de prioridad del proyecto; etiqueta sugerencias y deja la prioridad sin establecer cuando la decisión no esté resuelta. No inventes propietarios, versiones objetivo, desviaciones aprobadas, finalización de implementación o re-pruebas exitosas.
Cada hallazgo necesita un ID estable, página/estado, título conciso, resultado real, resultado esperado o incertidumbre explícita, base de evidencia, acción recomendada y pasos de reproducción. Adjunta evidencia de comparación dirigida y la captura completa del estado actual. Incluye referencias relevantes de Figma. Los hallazgos sin evidencia visual son limitaciones o preguntas, no defectos visuales confirmados.
Registra las comprobaciones observadas y los estados bloqueados/no revisados por separado. Mantén los mismos IDs de incidencia en una re-ejecución. Cierra o marca un hallazgo como resuelto solo con nueva evidencia que coincida; conserva la observación anterior y explica los criterios de aceptación cambiados.
Incorpora la revisión de diseño
Por defecto, crea un borrador de revisión, luego incorpora las decisiones del diseñador antes de producir una entrega al desarrollador. Lee review-workflow.md al recibir comentarios, revisar una línea de base de diseño o preparar el informe formal. La revisión y aprobación explícitas ya proporcionadas en la conversación son suficientes; no pidas la misma confirmación nuevamente.
Registra las decisiones de conservar, excluir, aceptar, fusionar, diferir y actualizar diseño en los datos del proyecto con su fuente y alcance. Una corrección de la referencia de diseño no es una corrección de implementación. Los comentarios del revisor sobre un cambio de diseño no autorizan por sí mismos a editar Figma. Mantén el borrador y el historial de decisiones; la entrega al desarrollador contiene solo los elementos de acción retenidos, incluido cualquier seguimiento de aclaración o módulo existente retenido explícitamente. No conviertas campos de prioridad, propiedad, versión o re-prueba no asignados en valores confirmados.
Entrega el informe
Lee report-format.md al redactar el informe. Conserva el orden de lectura probado: contexto del alcance → registro de incidencias conciso → evidencia visual real/esperada de la incidencia seleccionada → notas de cobertura y revisión. Haz que la evidencia visual sea la sustancia del informe, no un apéndice separado. Evita repetir capturas de pantalla grandes para cada incidencia y para cada verificación exitosa.
Escribe los datos de ejecución estructurados descritos en project-data.md, luego renderiza:
python3 <directorio-habilidad>/scripts/render_report.py <directorio-ejecucion>/report.json
Esto produce report.html autónomo, issue-register.csv y un aceptación-checklist.csv cuando se proporcionan criterios. En una entrega al desarrollador, cada elemento retenido necesita una URL de prueba directa, navegación/contexto, acción del desarrollador y criterios de aceptación observables. El renderizador admite estos campos directamente; no parchees el HTML generado para agregarlos. El renderizador necesita Python 3.9+ y ningún paquete de terceros. Valida la entrada/evidencia pero no infiere decisiones de revisión, accede a sistemas externos ni envía el informe a los desarrolladores.
Inspecciona el informe renderizado, su cambio/filtrado de incidencias, expansión de imágenes y cualquier control de comparación. Abre el resultado usando las herramientas de previsualización local disponibles, siguiendo sus reglas de navegador. Usa una previsualización local no conflictiva si es necesario, vinculada a loopback; no publiques ni escribas en sistemas externos a menos que se solicite. Restablece las anulaciones temporales de viewport del navegador y las entradas de prueba cuando sea práctico, e informa cualquier estado que permanezca cambiado.
Entrega el enlace del informe, la cobertura concisa y el resultado clave en el idioma de la conversación. Explica las limitaciones materiales. No requieras aprobación solo para producir el informe ya solicitado. Una solicitud para discutir el enfoque no es una solicitud para ejecutar una ejecución de UAT.