ux-quality-check

Verificación de calidad de UX

Verifica las superficies UI que toca un cambio contra las reglas en references/rules.md. Cada regla tiene una razón, una verificación en código, una verificación en el navegador y una corrección. La tabla al inicio de ese archivo indica a qué tipo de cambio aplica cada regla.

1. Encontrar el cambio

1. Obtén el diff que la solicitud nombra: un PR, una rama, un commit o los cambios no confirmados. Si no se proporciona un nombre, usa los cambios no confirmados. Si no hay ninguno, usa la rama contra su base de fusión con la rama predeterminada (git diff $(git merge-base HEAD origin/HEAD)...HEAD). Si la rama es la predeterminada, usa el último commit. Indica en el informe qué diff verificaste.
2. Enumera los archivos UI modificados: componentes, plantillas, estilos y las cadenas y props que renderizan. Un cambio en un componente compartido o un token también es un cambio de UI.
3. Si ningún archivo en el diff renderiza UI (solo código de servidor, pruebas, configuraciones o documentación), indícalo en una o dos oraciones y detente. Reporta que no se encontraron hallazgos.

2. Leer las reglas UI propias del repositorio y mapear las superficies

Las reglas del repositorio tienen prioridad sobre los valores predeterminados del catálogo.

• Lee la documentación del agente del repositorio (AGENTS.md, CLAUDE.md, un README del sistema de diseño) en busca de una sección "Reglas UI" o similar. Anota cada control, token o componente que mencionen para una regla, como un asistente de diálogo, un botón asíncrono, tokens de tipo o una marca de IA. Una corrección nombra ese componente.
• Busca las propias verificaciones de UX del repositorio: un objetivo make ux-check o ux:check, un script de diseño o accesibilidad, reglas de lint, o pruebas que analicen fuentes en busca de reglas UI. Ejecuta cada una que cubra el cambio y usa su salida como evidencia.

Luego mapea cada archivo modificado a las superficies que ve un usuario: la ruta, la vista y el control. Un componente compartido se mapea a cada superficie que lo utiliza. Nombra una superficie de la manera en que un usuario la encuentra ("Página de revisión, formulario de comentarios"). Para cada superficie, anota:

• Tipos. Etiqueta la superficie con cada tipo de la leyenda de references/rules.md que el diff añade o edita: write, data, form, list, control, overlay, layout, route, copy, chart, style. Un nuevo estilo de hover es control y list. Un botón de guardar es write.
• Estados. Vacío, cargando, pendiente, error, hover, focus, seleccionado y deshabilitado. La mayoría de los hallazgos se encuentran en un estado que el autor no abrió.

3. Ejecutar las verificaciones

Para cada superficie, ejecuta cada regla cuyo "Aplica a" comparta un tipo con la superficie. Lee la sección de la regla antes de verificarla. Anota cada regla que omitas y el motivo.

Lee el código primero. El "Verificar en código" de cada regla indica qué buscar. Esto detecta la mayoría de los defectos y no necesita navegador. Antes de reportar un estado faltante, lee los componentes que el código llama: un contenedor (un botón asíncrono, un hook de formulario, un padre que pasa pending) a menudo lo maneja.

Luego mide en el navegador, cuando puedas. Una página HTML estática se abre desde el disco con una URL file://. Para una aplicación, busca un servidor de desarrollo en ejecución, o inicia uno con el comando documentado del repositorio. Usa la herramienta de navegador que el anfitrión te proporcione: un panel de navegador integrado, un script de Playwright o Chrome sin cabeza. Si la página solicita inicio de sesión, pide al usuario que inicie sesión en ese navegador. No escribas credenciales tú mismo.

Carga scripts/measure.js en la página. Define las ayudas que el "Verificar en el navegador" de cada regla nombra, y references/rules.md enumera lo que cada una devuelve. Pégala de nuevo después de cada carga de página. Verifica cada tema y esquema que ofrezca la aplicación, y al menos un ancho de teléfono y un ancho de escritorio.

Mide también cada fila, tarjeta y control modificado en sus estados de interacción. Un estado de hover, focus o seleccionado a menudo añade un relleno, borde, sombra o control. Entonces dos elementos con caja se tocan, un elemento crece y mueve a sus vecinos, o una acción solo al pasar el ratón desplaza un recuento fuera de línea. Para cada lista, grupo de tarjetas o grupo de controles en la superficie:

1. Ejecuta snapshot(sel, "rest") y gaps(sel) con los elementos en reposo.
2. Pasa el ratón sobre un elemento con la herramienta del navegador, luego ejecuta snapshot(sel, "hover") y gaps(sel) de nuevo. Haz lo mismo con el foco de teclado (presiona Tab) y con el elemento seleccionado junto a un elemento sobre el que se pasa el ratón.
3. Ejecuta moved("rest", "hover"). Un espacio de 0px entre dos elementos con caja, o un elemento que se movió cuando se pasó el ratón sobre otro, es un hallazgo.

Haz lo mismo alrededor de cada acción que abre un menú, popover o panel: toma una instantánea de los bloques principales, ábrelo, toma otra instantánea y compara. En código, lee cada regla :hover, :focus-visible y de clase seleccionada en busca de propiedades que añadan una caja o cambien el tamaño: background, border, box-shadow, padding, margin, width y display.

Sin navegador, o sin página que abrir, reporta los hallazgos de código y enumera las verificaciones de navegador que no se ejecutaron.

4. Verificar cada hallazgo

Antes de reportar un hallazgo, verifícalo una vez más:

• Hallazgo de código. Confirma que un usuario puede alcanzar el estado: la rama se ejecuta, la prop se pasa y ningún contenedor o padre lo maneja.
• Hallazgo de navegador. Mídelo una segunda vez, después de una recarga, en el estado que nombra el hallazgo. Descarta un valor que no se repita.
• En el cambio o antes. Un defecto en una línea que el diff añadió o modificó pertenece al cambio. También un estado que el diff añade sin su contraparte, incluso si la línea faltante iría en otro lugar: una nueva regla :hover sin regla :focus-visible, o un nuevo write sin estado pendiente. Un defecto en una línea que el diff no tocó existía antes. Repórtalo bajo "Defectos existentes", aparte de los hallazgos del cambio, y solo cuando esté en una superficie modificada.

Descarta un hallazgo que falle su verificación. Reporta un hallazgo que no pudiste verificar como "No confirmado", con el motivo.

5. Reportar los hallazgos

Comienza con una línea que nombre el diff que verificaste y las superficies. Luego proporciona un hallazgo por defecto, primero el más grave. Gravedad:

• Alta: el usuario pierde datos o entrada, envía un write duplicado, no puede alcanzar un control o no puede leer texto.
• Media: el control engaña (icono incorrecto, estado solo con color, marca de IA faltante) o el diseño está visiblemente roto.
• Baja: inconsistencia con el sistema del repositorio (valores de tipo sin formato, controles de selección mixtos, relleno).

Cada hallazgo tiene cuatro partes:

Parte	Contenido
Superficie	La vista y el control, más el archivo y la línea (ReviewForm.tsx:42)
Regla	El id de la regla del catálogo, o la regla del repositorio que infringe
Evidencia	Lo que leíste o mediste: la línea de código, los valores medidos, el estado, tema y ancho
Corrección	El cambio, en una o dos oraciones, con el componente o token del repositorio cuando lo nombra

Ejemplo:

Superficie: Barra lateral de pila, lista de filtros de autor (AuthorList.tsx:58) Regla: no-cramped-controls Evidencia: gaps(".author-row") a 1440px, con la fila 2 con hover: y: 0 entre la fila 1 (seleccionada) y la fila 2. En reposo el espacio también es 0, pero solo la fila seleccionada dibuja una caja. Corrección: Añade gap: 2px a la lista, o inseta el relleno de hover en 2px.

Luego añade estas secciones:

1. Defectos existentes: los defectos del paso 4 que el cambio no introdujo, uno por línea.
2. No verificado: las reglas que omitiste y por qué, y las verificaciones de navegador que no se ejecutaron.

Cuando el usuario solicite correcciones, hazlas y luego vuelve a ejecutar las mismas verificaciones en las mismas superficies.