motion-review

Motion review

Una página con movimiento no está terminada cuando funciona en tu monitor. Lo está cuando obtiene una buena puntuación en una rúbrica fija, pasa todas las comprobaciones bloqueantes en tamaños de escritorio y móvil, y has mirado el resultado en lugar de confiar en el código.

Esta habilidad te proporciona tres cosas:

1. Un bucle de observación y corrección: captura, puntúa, corrige lo peor, vuelve a capturar.
2. Una rúbrica de 10 criterios puntuados del 1 al 10, con lo que significan un 5, un 8 y un 10: references/rubric.md.
3. Una lista de verificación de control de calidad bloqueante y dos scripts independientes que la miden: references/qa-checklist.md, scripts/section-shots.mjs, scripts/qa-lite.mjs.

El estándar

• Media de la rúbrica de 8 o más, y ningún criterio individual por debajo de 7.
• Todas las comprobaciones bloqueantes pasan a 1440x900 y 390x844.
• Has visto cada sección en ambos tamaños. Una revisión sin capturas de pantalla es una suposición.

Si la página no alcanza el estándar, no está lista, por muy bien que se vea el héroe.

Requisitos

• Node 18 o más reciente.
• Playwright en el proyecto que estás revisando: npm i -D playwright y luego npx playwright install chromium. O usa un Chrome instalado con playwright-core y pasa --chrome "<ruta a chrome>". Los scripts encuentran Chrome o Edge en las ubicaciones habituales de Windows, macOS y Linux por sí solos.
• Opcional: npm i -D sharp para las hojas de contactos. Sin él, igual obtienes todos los PNG.
• Ejecuta los scripts desde tu carpeta de proyecto. Primero buscan Playwright y sharp en la carpeta desde la que los ejecutas y luego junto al script, así que una instalación en tu proyecto es suficiente. Las rutas de los scripts a continuación son relativas a la carpeta de esta habilidad. Claude Code muestra esa carpeta cuando la habilidad se carga; después de una copia manual, es, por ejemplo, ~/.claude/skills/motion-review/, por lo que la llamada completa es node ~/.claude/skills/motion-review/scripts/qa-lite.mjs ./site.

La convención ?shot=N

Los scripts abren index.html?shot=N y esperan que la página aterrice en la sección N. Añade esto a tu página una vez (cuesta unas pocas líneas y hace que cada revisión sea repetible):

// Gancho de control de calidad: ?shot=N desplaza la sección N al centro del viewport después de la carga.
const shot = new URLSearchParams(location.search).get("shot");
if (shot !== null) addEventListener("load", () => {
  const marked = document.querySelectorAll("[data-shot]");
  const s = (marked.length ? marked : document.querySelectorAll("section"))[+shot];
  if (s) scrollTo(0, s.getBoundingClientRect().top + scrollY + s.offsetHeight / 2 - innerHeight / 2);
});

Para una película o una introducción de una sola reproducción, también salta la línea de tiempo a su estado estable cuando ?shot está presente, para que la captura muestre el fotograma compuesto y no el fotograma 1. Para películas con temporización, consulta el método de captura justa en la habilidad de análisis: ../motion-analytics/references/reference-grading.md.

El bucle de observación y corrección

Ejecuta este bucle hasta que la página cumpla el estándar. Cada pasada debe corregir primero el problema más dañino, no diez pequeños a la vez.

1. Capturar

node scripts/section-shots.mjs ./mi-sitio 6 ./qa/capturas

Esto sirve ./mi-sitio en un puerto local, abre index.html?shot=0 hasta ?shot=5 en tamaños de escritorio y móvil, escribe d0.png ... d5.png, p0.png ... p5.png, y desk-sheet.png y phone-sheet.png cuando sharp está instalado. Imprime todos los errores de página y errores de consola que vio.

2. Observar

Abre primero las dos hojas de contactos, luego los fotogramas individuales. Pregunta, sección por sección:

• ¿La idea única de la página es visible en este fotograma, o es una sección genérica?
• ¿El fotograma de móvil tiene su propia composición, o es el de escritorio comprimido?
• ¿Hay algún texto sobre una parte ocupada de la imagen?
• ¿Hay algo recortado, superpuesto, en blanco o todavía cargando?
• ¿Todas las secciones parecen de la misma marca?

Escribe lo que ves en palabras sencillas antes de puntuar. "El título del héroe en móvil cubre la cara del sujeto" es útil. "Se ve bien" no lo es.

3. Verificar

node scripts/qa-lite.mjs ./mi-sitio

Imprime PASA o FALLA por cada comprobación bloqueante, con los números medidos. Cualquier FALLA bloquea el lanzamiento. Consulta references/qa-checklist.md para saber qué significa cada comprobación, cómo la mide el script y la corrección habitual.

Algunas comprobaciones necesitan un humano: ¿el control de pausa detiene todo lo que se mueve?, ¿el desplazamiento inverso se reproduce limpiamente después de un tirón rápido?, ¿la página se siente bien con el sonido activado? La lista de verificación marca estas como manuales. Hazlas.

4. Puntuar

Puntúa los 10 criterios de la rúbrica a partir de las capturas de pantalla y del uso de la página. Usa los anclajes en references/rubric.md. Puntúa lo que está en pantalla, no lo que el código pretende. Escribe una frase de evidencia por cada puntuación.

5. Corregir lo peor

Elige la puntuación más baja o el primer FALLO. Corrige la causa, no el síntoma: si el texto es ilegible en el móvil, corrige la escala tipográfica y el degradado, no reduzcas la imagen. Mantén el cambio pequeño y local.

6. Repetir

Vuelve a capturar, vuelve a observar y vuelve a puntuar los criterios que tocaste. Detente cuando se cumpla el estándar. De tres a cinco pasadas es normal para una página nueva.

Formato del informe de revisión

Cuando informes una revisión, usa esta forma para que los resultados se puedan comparar a lo largo del tiempo:

Página: <nombre>   Pase: <n>   Fecha: <aaaa-mm-dd>
Rúbrica: idea 8, artesanía 7, movimiento 9, ... media 8.1, mínimo 7 (artesanía)
Bloqueante: 11 de 12 PASAN. FALLA: objetivos táctiles (3 por debajo de 44 px en móvil: .nav a, #prev, #next)
Visto: 6 fotogramas de escritorio, 6 de móvil
Peor problema: <una frase>
Corrección aplicada: <una frase>
Siguiente: <una frase>

Reglas prácticas

• Móvil primero al puntuar. La mayoría de los visitantes llegan desde un móvil. Una página que es un 9 en escritorio y un 6 en móvil es un 6.
• El movimiento que no se puede detener es un error. Cualquier cosa que se mueva durante más de cinco segundos necesita un control de pausa visible, y el movimiento reducido debe dar una página completa y estable.
• El desplazamiento debe funcionar en ambos sentidos. Desplazarse hacia arriba debe deshacer lo que hizo el desplazamiento hacia abajo, limpiamente, a cualquier velocidad.
• Sin errores silenciosos. Un error de consola es un FALLO, incluso si la página se ve bien. Normalmente significa que una ruta de respaldo está rota.
• Juzga el fotograma estable y el fotograma en movimiento. Una captura de pantalla muestra la composición; solo usar la página muestra el tiempo. Haz ambas cosas.

Relacionado

• Medición del tiempo de fotograma, niveles de calidad y peso de la página: ../motion-analytics/SKILL.md.
• Construir la página desde cero: ../motioncraft-builder/SKILL.md.