UI clone: mide la referencia, reconstruye, demuestra que coincide
Cada trabajo sigue un ciclo: capturar la referencia → medirla (leer valores exactos cuando sea posible, medir píxeles cuando no) → escribir la especificación → construir en el stack del usuario → capturar la nuestra de la misma manera → comparar → corregir, hasta que la especificación se cumpla. El entregable es código en el proyecto del usuario más evidencia (números, imágenes de diferencias, hojas comparativas), nunca "se ve más o menos bien". Métodos adaptados de NiazMorshed2007/reanimate y rossark0/rossark-motion-skill (ambos MIT); cada script aquí es propio.
<skill> = la carpeta de este skill. El trabajo va en ./ui-clone/<nombre>/ del proyecto: ref/, ours/, figma/, compare-N/, diff-N/, spec.md. Agrega ui-clone/ al .gitignore a menos que el usuario quiera que se suba la evidencia.
Configuración (una vez por máquina)
- Python (numpy + Pillow):
~/.ui-clone/venv/bin/python(crear conpython3 -m venv ~/.ui-clone/venv && ~/.ui-clone/venv/bin/pip install numpy pillowsi no existe). Ejecutar scripts con-I. - Captura de navegador (Playwright + Chromium, ~250 MB, solo para entradas URL / servidor de desarrollo): ejecutor en
~/.ui-clone/runner(npm i [email protected] && npx [email protected] install chromiumallí). Ejecuta los scripts.mjsconnode <skill>/scripts/<script>.mjs(carga Playwright desde~/.ui-clone/runner, oUICLONE_RUNNER; si el Chromium propio de Playwright no está instalado, usa cualquier Chromium en la caché de Playwright, oUICLONE_CHROMIUM). - ffmpeg/ffprobe en PATH. Figma solo:
FIGMA_TOKEN=...en el entorno, en el archivokeys.envdel proyecto, o en~/.ui-clone/keys.env(token de acceso personal de solo lectura). Nunca imprimir ni subir tokens. Preguntar antes de instalar cualquier cosa que no esté presente.
0. Alcance (al inicio de spec.md, antes de cualquier captura)
- Objetivo: exactamente qué clonar (URL + selector, archivo + rango de tiempo + recorte, nodo de Figma) y nada más.
- Fidelidad (indicarla en la primera respuesta; decide qué se verifica):
nivel cuándo debe coincidir puede diferir fiel-al-movimiento (por defecto para trabajo de otros) "hacer que la nuestra se sienta/se mueva como la de ellos" estructura y proporciones, orden, temporización ±0.08 s, familia de easing, overshoot, desplazamiento relativo al tamaño, escalonamiento copia, colores, fuentes, imágenes, marca fiel-al-píxel el diseño propio del usuario (Figma → código), su propio sitio, trabajo de clientes del que tenga derechos, o práctica privada todo lo anterior + fuentes, tamaños, espaciado, colores, radios, sombras, activos; diferencia de captura de pantalla ≤ 2% (≤ 0.5% en reposo), sin desplazamientos medidos nada que no haya pedido cambiar mixto "clonar X y agregar Y" la parte clonada con uno de los niveles anteriores las adiciones (mantenidas separadas, mostradas, verificadas que no rompan el clon) - Derechos: las copias fieles al píxel de UIs, logotipos, ilustraciones, fuentes y textos de otras empresas son de su propiedad; úsalas solo para aprendizaje o con permiso, y nunca las publiques como trabajo propio del usuario. Cuando la referencia sea un producto de un tercero y el usuario quiera publicarlo, por defecto usa fiel-al-movimiento con su propio diseño y explica por qué.
- Destino: dónde va el código y en qué stack. Lee
package.json, los componentes existentes, el sistema de estilos (configuración de Tailwind, variables CSS, tokens de diseño) y la biblioteca de animaciones ya en uso; adáptate a ellos en lugar de agregar una nueva biblioteca.
1. Elegir el método de entrada (el más preciso disponible; indica cuál usas)
| Entrada | Captura | Lo que obtienes |
|---|---|---|
| URL en vivo | inspect_web.mjs + capture_web.mjs | valores CSS exactos, fuentes, duraciones/retrasos/easings declarados, keyframes; grabación cuadro exacto con reloj virtual |
| Servidor local de desarrollo (nuestro) | mismos scripts en http://localhost:… | el lado "nuestro" de cada comparación, capturado exactamente como la referencia |
| Video / GIF / grabación de pantalla (web o app) | ref_frames.py | cada cuadro a la fps de origen + hojas de temporización/pose; valores medidos desde píxeles |
| Figma | figma_fetch.py (token) o imágenes PNG exportadas | tamaños exactos, espaciado, auto-layout, tipografía, colores, efectos, transiciones de prototipo + un PNG de referencia |
| App móvil | grabación de pantalla (referencia); para nuestra: xcrun simctl io booted recordVideo ours.mp4 (simulador iOS) o adb shell screenrecord (Android) | como video; la nuestra capturada de la misma manera |
| Combínalos: valores de URL + una grabación para interacciones difíciles de activar (flujos con inicio de sesión, arrastres); valores de Figma + el servidor de desarrollo para verificar "¿mi construcción coincide con el diseño?"; referencia de video + captura del servidor de desarrollo para la nuestra. Páginas con inicio de sesión: pide una grabación de pantalla o que el usuario inicie sesión; nunca manejes sus contraseñas. |
2. Capturar y medir la referencia
URL:
inspect_web.mjs --url URL --selector "<seccion>" --out ui-clone/<nombre>/ref [--state hover --target "<btn>"]→inspect.md: por elemento, caja + estilos computados, transiciones declaradas, animaciones en ejecución con keyframes, @keyframes, fuentes, bibliotecas detectadas (GSAP, Framer Motion, Lottie, three.js, Lenis...), canvas (2d/WebGL), diferencia hover/enfoque. Los valores declarados tienen prioridad sobre los medidos: cópialos.capture_web.mjs --url URL --selector "<seccion>" --trigger load|hover|click|scroll|none --duration 2 --fps 30 --out ui-clone/<nombre>/ref→ frames/, video.mp4, frames.json, animations.json. Por defecto--mode seek(reloj virtual: temporizadores JS y requestAnimationFrame en el reloj de Playwright, CSS/Web Animations pausadas y buscadas cuadro por cuadro: capturas idénticas). Usa--mode realtimepara páginas donde el reloj virtual falle (elementos de video, algunas bibliotecas WebGL/canvas) y dilo.--stillda una sola captura de pantalla estabilizada para trabajo de píxeles;--dpr 2para comparaciones nítidas en retina (--dpr 3para elementos pequeños: un crecimiento de hover de 12 píxeles es demasiado pequeño para ajustar un easing a 1x);--pad 12agrega un margen alrededor de--selectorpara que los efectos hover/scale que crecen más allá de la caja en reposo queden dentro del cuadro;--viewport 390x844para teléfonos. El modo seek está verificado como idéntico cuadro por cuadro entre ejecuciones.--mode realtimetoma capturas de pantalla reales tan rápido como la máquina lo permita (~19/s en un portátil típico) y las remuestrea; imprime la tasa alcanzada: la temporización solo es tan precisa como eso. Video / GIF / grabación:ref_frames.py REF.mp4 --out ui-clone/<nombre>/ref [--start --end --crop x:y:w:h]. Figma:figma_fetch.py --url "<enlace de figma con node-id>" --out ui-clone/<nombre>/figma --scale 2→ design.md/json + frame.png. Luego medir el movimiento (cualquier entrada con cuadros):- Cortes y secciones:
motion_compare.py <ref> <ref> --out <ref>/self --no-align. - Colores:
track_motion.py <ref>/frames --sample X,Y --at T. - Cada elemento en movimiento:
track_motion.py <ref>/frames --name el --colors HEX,HEX --tol 35 --region x,y,w,h(siempre una región en referencias ocupadas). - Cada movimiento:
fit_easing.py <ref>/track_el.json --prop cx|cy|w|h|aspect|presence --from A --to B→ temporización, easing, overshoot, y líneas listas para copiar y pegar en CSS / WAAPI / Framer Motion / GSAP / Remotion. Error ≤ 0.03 = ajuste cercano; "ningún easing único ajusta" = dividir la ventana o es una cadena de keyframes. Cuando el error del segundo mejor está dentro de ~0.003 del mejor, trátalo como un empate (p. ej., easeOutQuad 0.58 s vs easeOutCubic 0.80 s ajustan los mismos cuadros): dilo, y prefiere los valores declarados deinspect.md, el código fuente o las hojas para romperlo. El seguimiento solo ve un elemento por su color, por lo que un elemento que se desvanece mientras se mueve parece que comienza tarde: para entradas web, usa los valores declarados. Lee cada hoja tú mismo (sheets/poses.png,sheets/timing_NN.png): los números dicen qué, las hojas dicen cómo.
3. Escribir la especificación (ui-clone/<nombre>/spec.md; cada fila se convierte en una verificación)
- Estructura y estilo estático (fiel-al-píxel): elemento → caja, fuente (familia/tamaño/peso/interlineado/espaciado entre letras),
colores, radio, sombra, espaciado; fuente (
inspect.json/design.json/ medido). - Línea de tiempo (movimiento):
| # | elemento | propiedad | desde → hasta | inicio ms | duración ms | easing | escalonamiento / repetición | disparador | fuente |. - Nota lo que no se mueve. Un "?" significa que la referencia aún no se ha leído. Muestra la especificación antes de una gran construcción.
4. Construir
En el stack y sistema de diseño del usuario. Copia los valores declarados exactamente (fiel-al-píxel) o las proporciones relativas
(fiel-al-movimiento). Easings de inspect.json o de la línea de fit_easing.py para su biblioteca; muelles donde la
referencia sobrepase y se estabilice; escalonamientos como base + índice × paso. Respeta prefers-reduced-motion (muestra el estado
final). Mantén las adiciones en componentes separados. Dale a nuestra implementación una ruta/página que renderice el componente en la ventana gráfica de la referencia
con el mismo disparador, para que pueda ser capturado de manera idéntica. Efectos WebGL: reconstruye el shader a partir de lo que muestra la referencia
(o su fuente legible cuando el usuario pueda usarla); paso de tiempo fijo desde el tiempo, aleatoriedad con semilla.
5. Verificar, corregir, repetir (2-5 rondas; conserva la carpeta de cada ronda)
- Captura la nuestra con el mismo comando que la referencia (solo cambian
--url/entrada y--out), oref_frames.py OURS.mp4 --out ui-clone/<nombre>/ours --like <ref>/frames.jsonpara entradas de video. - Píxeles:
screenshot_diff.py <ref>/still.png <ours>/still.png --out ui-clone/<nombre>/diff-N [--strict] [--max 0.02] [--mask x,y,w,h](fiel-al-píxel: siempre--strict: umbral por píxel 0.03, máximo 0.5%, y cualquier región cuyo color se desvíe más de 3 niveles RGB falla; el valor predeterminado es permisivo y deja pasar pequeños cambios de padding y color) → % de diferencia, peores regiones, desplazamientos de toda la imagen o por elemento ("algo en la región… se movió +0 px x, +6 px y"), deriva de color,side_by_side.png. Corrige los desplazamientos primero (hacen que todo parezca incorrecto), luego los tamaños, luego los colores. Fiel-al-píxel FALLA en cualquier desplazamiento medido; fiel-al-movimiento usa--allow-shifty un--maxmás permisivo. - Movimiento:
motion_compare.py <ref> <ours> --out ui-clone/<nombre>/compare-N(cortes, movimientos, desfase; PASA ±0.08 s;activity.png,sheets/compare_NN.png) y, por fila de especificación,fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK. - Lee las hojas cada ronda. Cambia la cosa más pequeña que la evidencia señale; vuelve a capturar; vuelve a comparar.
- Después de 5 rondas, reporta cada fila que aún falle con su número y razón (licencia de fuente, un efecto WebGL aproximado, un muelle ajustado a ojo). Nunca aflojes un umbral de forma silenciosa.
| Síntoma | Causa habitual | Corrección |
|---|---|---|
| toda la imagen desplazada N px | diferente scroll/desplazamiento/recorte o un margen de wrapper faltante | igualar viewport, dpr, recorte; corregir el espaciado externo |
| un elemento se movió | margin/padding/line-height/gap difieren | comparar su caja con inspect.json / design.json |
| texto ligeramente descentrado en todas partes | fuente de respaldo, diferente peso o espaciado entre letras | cargar la misma fuente (o el equivalente con licencia del usuario), igualar tamaño/peso/seguimiento |
| colores ligeramente descentrados en todas partes | espacio de color, apilamiento de opacidad, puntos de gradiente | copiar colores/gradientes computados; verificar opacidad en padres |
| movimiento desplazado por un desfase | latencia del disparador o retraso faltante | corregir el primer retraso |
| nuestra sobrecargada / demasiado rápida | easing más fuerte (expo vs cúbico) | usar la bezier ajustada o el easing declarado |
| la referencia sobrepasa, la nuestra no | muelle/back vs bezier | muelle/back ajustado al overshoot y estabilización medidos |
| animación de scroll comienza antes/tarde | umbral/desfase del disparador | igualar la posición de scroll donde comienza el movimiento |
| un movimiento extra en la nuestra | una transición perdida (p. ej., transition: all) | limitar las transiciones a las propiedades que deben animarse |
6. Reporte (debe ser autónomo)
Nivel de fidelidad y qué se clonó / agregó; archivos cambiados y cómo disparar el movimiento; las tablas de la última ronda
(diferencia de píxeles y desplazamientos; temporización de cortes/movimientos; easing por elemento), rutas a side_by_side.png, activity.png y
hojas de comparación; cada diferencia restante con su número y razón; qué verificaciones fueron medidas (un script
las produjo) vs evaluadas a ojo (se miró una hoja).
Límites
- La captura con reloj virtual no puede controlar la reproducción de
<video>ni algunas bibliotecas GPU/física: usa--mode realtimey espera ±1-2 cuadros de variación; dilo. - Las hojas de estilo y fuentes de origen cruzado pueden ocultar las reglas @keyframes/@font-face de la inspección; los estilos computados y las animaciones en ejecución aún se leen.
- De videos, el 3D se iguala como movimiento de cámara/objeto, no modelos o materiales; la acción real ocupada da ritmo, no valores de elementos exactos.
- Móvil: los valores provienen de grabaciones (sin fuente); las capturas del simulador de la nuestra se comparan de la misma manera.