UI diff
Los revisores pueden leer un diff de CSS, pero no pueden verlo. Esta habilidad renderiza la aplicación en la base y la cabeza del PR, las compara, y coloca las imágenes antes/después en el PR. Junto a ellas va un breve resumen de lo que cambió para los usuarios, respaldado por valores medidos.
El trabajo mecánico es un solo script. Tu trabajo son las partes que requieren juicio: qué páginas revisar, qué significan los cambios y dónde publicar.
$SKILL a continuación significa el directorio que contiene este SKILL.md. Configúralo una vez, p.ej. SKILL=/ruta/a/habilidades/ui-diff. Todo se escribe en .ui-diff/ en la raíz del repositorio, que el script ignora localmente mediante .gitignore, por lo que nada rastreado cambia.
1. Contexto
gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short
Lee .ui-diff.json en la raíz del repositorio si existe. Puede contener rutas, el comando de desarrollo, máscaras y autenticación (ver references/config.md).
Qué cabeza renderizar depende de lo que esté haciendo el usuario:
- Publicar en un PR: renderiza exactamente lo que se ha subido pasando
--head <headRefOid>. De lo contrario, las ediciones locales sin confirmar terminan en un informe que pretende mostrar el PR. Si el árbol de trabajo está sucio o tiene commits sin subir, menciona que esos cambios no aparecerán. - Revisar su trabajo en progreso ("¿esto se ve bien?"): usa el árbol de trabajo (el valor predeterminado, sin
--head). El informe lo etiqueta como "+ cambios sin confirmar".
2. Elegir las páginas
node $SKILL/scripts/routes.cjs --base <base> --log # añade --head <sha> si se lo pasarás a run.sh
Asigna los archivos cambiados a rutas: archivos de página, rutas bajo un diseño cambiado, páginas que importan un componente cambiado (siguiendo alias y paquetes del espacio de trabajo), además de la página de inicio y algunas páginas bien enlazadas para estilos de toda la aplicación. Imprime JSON con las razones y confianza de cada ruta, needsExample (rutas dinámicas que no puede completar) y unmatched (archivos de UI que no pudo ubicar). Trátalo como una lista inicial y aplica criterio usando references/route-mapping.md: descarta selecciones de baja confianza que el diff no respalde, encuentra ids para needsExample y coloca los archivos unmatched tú mismo. Si nada relacionado con la UI cambió (todos los archivos ignored), dímelo y detente. No produzcas un informe vacío.
Proyectos Storybook (una carpeta .storybook/ o un script storybook): cuando el cambio es principalmente de componentes, compara sus historias en lugar de páginas con run.sh --storybook; él mismo elige las historias de los archivos modificados. Quédate con páginas para rutas, diseños y estilos a nivel de aplicación. Consulta la sección de Storybook de references/route-mapping.md.
Informa al usuario en una o dos líneas qué rutas capturarás y por qué, luego continúa. Solo pregunta cuando no puedas encontrar ninguna ruta, o cuando una ruta dinámica necesite un id que no puedas encontrar. Lleva un registro de las rutas que están afectadas pero no capturadas (demasiadas para revisar, necesitan inicio de sesión, un estado modal). Van en el resumen para que "sin cambio visual" no se interprete como un visto bueno.
3. Ejecutarlo
bash $SKILL/scripts/run.sh --routes "/,/pricing" [--head <sha>] [--base <ref>] \
[--viewports "desktop:1440x900,mobile:iPhone 13"] [--schemes light,dark] [--dev "<cmd with {port}>"]
(--auto-routes añade las rutas que selecciona routes.cjs, registradas con razones; úsalo cuando no tengas correcciones que hacer).
De una sola vez,:
- instala las herramientas en el primer uso (Playwright + Chromium en
~/.cache/ui-diff, aproximadamente un minuto; las dependencias del proyecto no se tocan); - cambia a la base, y a la cabeza si se da
--head, en worktrees de git, y copia los archivos.env*no rastreados en ellos; - reutiliza las dependencias instaladas cuando el archivo de bloqueo coincide, con cachés de compilación por checkout, e instala en caso contrario;
- inicia ambos servidores de desarrollo en puertos libres en sus propios grupos de procesos. Solo esos se detienen después, por lo que los otros servidores del usuario nunca se tocan;
- captura cada ruta × viewport. El móvil usa emulación de dispositivo real (toque, UA móvil). Las animaciones están congeladas y las superposiciones de desarrollo del framework están ocultas;
- compara las capturas de pantalla píxel a píxel (
results.json, imágenes de página completa y ampliadas) y ejecuta un diff de estilos calculados (measured.md).
Modo Storybook (--storybook, o --stories "button--primary,card--*" para elegirlas tú mismo) inicia Storybook en lugar del servidor de desarrollo, registra qué historias eligió y por qué, y nombra los resultados por id de historia. Si no coincide ninguna historia, sale y sugiere ids.
Imprime recuentos como {"changed":2,"added":1,"unchanged":3,...}. Valores predeterminados: base = la rama base del PR (si no, la rama predeterminada), viewports = escritorio 1440×900 + iPhone 13, modo claro. Añade --schemes light,dark cuando el cambio afecte a tema, colores o tokens.
Si falla, el error indica qué paso falló y dónde está su registro (.ui-diff/server-*.log, install-*.log, capture-*.log). Las causas habituales son una variable de entorno faltante, el comando de desarrollo incorrecto (pasa --dev), o dependencias no instaladas en el árbol de trabajo. Corrige la causa y vuelve a ejecutar. No te saltes un lado.
4. Leer los resultados y escribir el resumen
Lee primero .ui-diff/report/measured.md. Si comienza con Posibles problemas, revísalos primero: texto recortado, desplazamiento lateral, superposición, controles fuera de pantalla, pequeños objetivos táctiles en móvil y violaciones de accesibilidad de axe-core que son nuevas en la cabeza. Son heurísticas, así que abre cada imagen ampliada (report/issues/) y evalúala. Encabeza "merece la pena echarle un vistazo" con las reales, y descarta o suaviza las que parezcan intencionadas. El resto de measured.md contiene hechos medidos: cambios de estilo calculados agrupados por elementos, elementos redimensionados, desplazamientos de diseño, cambios de copia y nuevos fallos de contraste WCAG. Luego abre las imágenes ampliadas (report/zoom/*__after.png y __before.png) y las superposiciones de diff con cualquier visor de archivos o imágenes que tengas para ver cómo se ven esos hechos en contexto. Si no puedes ver imágenes, escribe el resumen solo a partir de measured.md y di que las capturas de pantalla no fueron revisadas. Revisa también results.json en busca de warnings: errores HTTP, superposiciones de error del framework, excepciones no capturadas.
¿Enlace de Figma proporcionado (o una ruta en .ui-diff.json tiene figma)? También compara la cabeza con el frame de diseño. Sigue references/figma.md.
Escribe .ui-diff/report/summary.md para un diseñador o PM que no leerá el código:
**Qué cambió**
- **Tarjetas de precios** — los botones CTA ahora son pastillas (radio 4 → 999px) con más padding (8×14 → 12×20px); la tarjeta Pro está resaltada (borde 2px `#2563EB`, relleno `#EFF6FF`) con una etiqueta "Más popular".
- **Encabezado (todas las páginas)** — los enlaces de navegación pasaron de azul `#2563EB` a gris `#9CA3AF`.
**Merece la pena echarle un vistazo**
- ⚠️ Los enlaces de navegación ahora tienen un contraste de 2.5:1 sobre blanco (era 5.2:1); el texto del cuerpo necesita 4.5:1.
- ⚠️ `/settings` cambió pero ninguno de sus archivos lo hizo — recoge el nuevo padding del `Button`, y "Guardar"/"Cancelar" ahora se ajustan en móvil.
**No revisado:** `/admin/*` (necesita inicio de sesión), el modal de eliminar cuenta.
Directrices:
- Usa valores medidos de
measured.mdpara colores, tamaños y espaciado. No los estimes a partir de píxeles. Si algo es visible en las imágenes pero no enmeasured.md(imágenes, canvas, contenido SVG), descríbelo como se ve. - Un gran porcentaje de cambio de píxeles con líneas de "desplazamiento de layout … desplazado" generalmente significa que el contenido fue empujado hacia abajo, no que todo cambió. Explícalo así.
- Encabeza "merece la pena echarle un vistazo" con cambios probablemente no intencionados: páginas que cambiaron sin que sus archivos cambiaran, roturas en un solo viewport, desbordamiento, elementos desaparecidos, errores de página. Luego fallos de contraste y objetivos táctiles pequeños (menos de unos 44px en móvil).
- Di "cambió", no "cambió intencionalmente". Puedes ver qué cambió, no por qué.
- Mantenlo proporcionado. Un ajuste de un color recibe un punto.
Luego ejecuta node $SKILL/scripts/viewer.cjs --report .ui-diff/report para actualizar la página de revisión local (report/index.html: deslizador, lado a lado, superposición de diff, resumen arriba) y ofrece abrirla para el usuario (open en macOS, xdg-open en Linux).
5. Publicar
Publicar escribe en un PR compartido y sube una rama. Muestra al usuario el resumen y confírmalo primero, a menos que su solicitud ya dijera que publiques. Luego:
PREFIX=$(bash $SKILL/scripts/publish.sh .ui-diff/report <pr> <head-short-sha>)
node $SKILL/scripts/comment.cjs --report .ui-diff/report --base-url "$PREFIX" \
--summary .ui-diff/report/summary.md --out .ui-diff/comment.md
node $SKILL/scripts/post.cjs --pr <pr> --body .ui-diff/comment.md --mode comment # o --mode description
publish.shsube las imágenes a una ramaui-diff-assets(un commit, reemplazado en cada publicación) desde un clon desechable. Las imágenes se renderizan entonces inline en GitHub, incluso en repositorios privados para cualquier persona con acceso de lectura.- Salida 3 significa que no hay acceso de push (típicamente un PR desde un fork). Cambia a modo manual.
- Si indica que el repositorio es público, informa al usuario de que las capturas de pantalla serán públicas. Eso importa sobre todo cuando
storageStateinició sesión como una cuenta real. Obtén un sí antes de publicar.
post.cjsreemplaza la sección anterior de comentario o descripción de ui-diff en lugar de acumular nuevas. Todo lo demás en la descripción se deja como estaba.- Añade
--approvalacomment.cjssolo si.ui-diff.jsontiene"requireApproval": true(el repositorio ejecuta el flujo de trabajo de revisión de diseño): añade una casilla "Diseño aprobado". - Modo manual (sin rama de assets, o sin acceso de push): ejecuta
comment.cjssin--base-url, luegoopen .ui-diff/report. El usuario arrastra las imágenes a la caja de comentarios del PR (GitHub no tiene API para esa subida). Indícale qué imagen va dónde. - Sin PR aún: conserva
.ui-diff/comment.mdy ofrece ponerlo en la descripción cuando se abra el PR.
6. Conclusión
Informa con el enlace, los recuentos y los elementos "merece la pena echarle un vistazo". Si dedujiste el comando de desarrollo, las rutas, las máscaras o los ids dinámicos por tu cuenta, ofrece guardarlos en .ui-diff.json para que la próxima ejecución sea un solo paso. Una vez que un PR se fusiona o cierra, bash $SKILL/scripts/prune.sh <pr> elimina sus imágenes de la rama de assets (pregunta primero si alguien podría necesitar aún su comentario).