BrainLiuYH/ui-quality-workbench

UI Quality Workbench

Utilice este skill para ejecutar el módulo local de UI 走查 (inspección de UI). Compara una imagen de diseño con una captura de pantalla de la implementación en un Worker del navegador, agrupa las diferencias visibles en candidatos de revisión y admite confirmación humana y exportación.

El analizador es heurístico. Llame a su salida candidatos o posibles discrepancias hasta que una persona verifique el diseño, la ruta, el estado, el contenido y la ventana gráfica previstos. Nunca presente un resultado no revisado como un defecto confirmado.

Iniciar el banco de trabajo

1. Resuelva el directorio de este skill desde el SKILL.md seleccionado. No asuma la raíz del repositorio ni codifique una ubicación de instalación.

2. Verifique el paquete y el puente de origen local antes del primer lanzamiento en una sesión:

   python3 <directorio-del-skill>/scripts/serve_workbench.py --check
   

3. Inicie el servidor como un proceso de larga duración:

   python3 <directorio-del-skill>/scripts/serve_workbench.py
   

   El lanzador imprime una línea JSON con event: "ready", protocol: 2, una URL de bucle de retorno dinámica y metadatos del proceso. Use la URL devuelta exactamente; su fragmento lleva el token por lanzamiento que utiliza la aplicación del navegador.

4. Si el control del navegador está disponible y el usuario desea que se abra la interfaz, navegue a esa URL. De lo contrario, entregue la URL al usuario.

5. Mantenga el proceso en ejecución mientras el banco de trabajo esté en uso. Deténgalo con Ctrl+C cuando el usuario pida cerrarlo o la sesión ya no lo necesite.

Si el lanzamiento falla con EPERM o una restricción explícita de socket de bucle de retorno, solicite permiso de ejecución local y reintente el mismo comando. No cambie la dirección de enlace, sustituya una copia alojada ni cargue imágenes locales en otro lugar.

Elegir fuentes

El banco de trabajo necesita una imagen de diseño y una imagen de implementación. Cada cambio de fuente invalida los resultados anteriores; ejecute la auditoría nuevamente después de reemplazar cualquiera de las fuentes.

• Imagen local: haga clic para seleccionar o arrastre un PNG, JPEG o WebP al área de diseño/implementación correspondiente. La decodificación, la comparación de rásteres y la agrupación permanecen en la sesión local del navegador.
• Marco de Figma: proporcione una URL de Figma design o file que contenga un node-id, más un token de acceso personal (PAT), o inicie el lanzador con FIGMA_ACCESS_TOKEN. Esto importa una representación PNG de ese marco a través de la API de Figma; no navega por el archivo ni hereda una sesión de Figma.
• Captura web: proporcione una URL HTTP(S), dimensiones de ventana gráfica y un tiempo de espera de renderizado opcional. El puente inicia un perfil temporal de Chrome/Chromium/Edge sin interfaz y captura esa ventana gráfica. No hereda el perfil del navegador del usuario, cookies, extensiones ni sesión autenticada.

Lea references/source-imports.md antes de operar o solucionar problemas de importación de Figma o captura web.

Ejecutar y revisar una auditoría

1. Confirme que ambas fuentes representan la misma ruta, estado de UI, configuración regional, contenido, ventana gráfica y posición de desplazamiento lo más cerca posible.
2. Verifique la vista previa de normalización mostrada. El motor usa la fuente más ancha como ancho objetivo, la mantiene a 1×, agranda proporcionalmente solo la fuente más estrecha a ese ancho, luego alinea ambas imágenes en la esquina superior izquierda. No estira ni recorta ninguna fuente, y una diferencia de altura restante en la parte inferior permanece en la comparación.
3. Inicie la auditoría. Antes de la clasificación local, el Worker verifica si los rásteres normalizados son adecuados para la comparación directa. Un par de baja comparabilidad se detiene sin generar candidatos; un par de comparabilidad media continúa con una advertencia explícita. Esta es una puerta heurística conservadora, no una probabilidad ni un juicio semántico sobre qué imagen es correcta.
4. Inspeccione los candidatos en la comparación visual, la lista y el panel de detalles. El contenido transparente unilateral se reporta solo como una diferencia de presencia de región/diseño. Los cambios de contenido multimedia o contenido ambiguo usan redacción neutral en lugar de forzarse en defectos de color, texto, icono o geometría. Verifique si el suavizado, la carga de fuentes, la animación, los datos dinámicos, el comportamiento responsivo o el diseño desactualizado explican la diferencia.
5. Confirme solo los candidatos verificados. Requiera una razón cuando ignore intencionalmente una diferencia real o descarte un falso positivo.
6. Asigne severidad y prioridad de forma independiente, luego exporte la lista revisada. No infiera la prioridad únicamente del área de píxeles o la distancia de color.

Lea references/audit-model.md al clasificar, priorizar, cambiar el estado de revisión o decidir qué exportar. Lea references/v0-boundaries.md antes de explicar privacidad, integraciones compatibles, comportamiento de captura o limitaciones analíticas.

Mantenga las afirmaciones precisas

• El motor de comparación está adaptado de SemineChen/yangao en el commit fijo beac836ba3c81b9a1d40bac8fe75af08444ab742, bajo el permiso del autor según lo informado por el usuario. Consulte THIRD_PARTY_NOTICES.md.
• La importación de Figma requiere un PAT y acceso saliente a Figma. No es OAuth, vinculación de cuentas, extracción de tokens de diseño ni análisis general de archivos de Figma.
• La captura web es una captura de pantalla aislada de la ventana gráfica actual. No es unión de página completa, navegación interactiva, herencia de estado de inicio de sesión, inspección del DOM ni extracción de estilos calculados.
• El procesamiento local del navegador no es una certificación de seguridad. La importación de Figma necesariamente envía el PAT a Figma y descarga el marco seleccionado; la captura de página web necesariamente solicita la URL proporcionada.
• La puerta de comparabilidad no tiene OCR, DOM ni semántica de producto. Puede detener entradas muy diferentes y advertir sobre cambios localizados, pero no puede demostrar que dos pantallas representan la misma ruta/estado ni identificar el lado autoritario.
• UI 走查 es el módulo implementado. No afirme que los módulos planificados de experiencia de interacción, accesibilidad o colaboración ya se ejecutan.

Lea references/v0-boundaries.md para obtener más detalles.