albertirgi/replica

¿Qué hace replica?

Reconstruye lo que el usuario señala, luego pruébalo. capture convierte la referencia en un plano de hechos medidos. Tú construyes a partir del plano. compare califica la construcción en cuatro ejes (diseño, estilo, píxeles, movimiento) y te indica qué corrección vale más puntos. Terminas cuando compare sale con código 0, no cuando la construcción te parezca correcta.

<skill> a continuación significa el directorio donde se encuentra este SKILL.md.

Reglas

1. Mide, no adivines. Toma cada tamaño, color, fuente, espaciado, duración y suavizado de blueprint.md, blueprint.json o un informe. No uses tu memoria de cómo suelen verse sitios como este.
2. Nunca manipules la puntuación. No incrustes capturas de pantalla o fotogramas de video de la referencia, no hagas iframe ni proxies de la referencia, no pegues su HTML renderizado completo, no edites nada dentro de .replica/, ni bajes --level para aprobar. Construye una UI real en la pila del usuario.
3. Usa la pila del proyecto. Lee primero package.json y los componentes existentes más cercanos. Iguala el framework, el enfoque de estilos y la biblioteca de animaciones ya en uso. Agrega una dependencia solo cuando la referencia necesite algo que el proyecto no pueda hacer.
4. Corrige en orden del informe, de a pocos a la vez. Los elementos al principio a menudo causan elementos más abajo: una corrección de cascada puede mover docenas de elementos. Vuelve a ejecutar compare después de cada lote. Nunca acumules diez cambios especulativos.
5. Respeta la propiedad. Las fuentes, imágenes, iconos y textos de la referencia pertenecen a sus dueños. Usa los recursos y textos propios del usuario donde los tenga. Si no, pregunta, o usa marcadores con las mismas dimensiones, marcados data-replica="placeholder": compare aún revisa sus cajas pero deja sus píxeles fuera de la puntuación de píxeles. Indica en el mensaje final qué recursos de la referencia reutilizaste.

0. Alcance

Decide estos puntos y establécelos en tu primer mensaje:

• Objetivo: la URL o archivo, más qué parte: un selector CSS para una sección o componente, o un rango de tiempo para un video.

• Destino: el archivo o ruta en el proyecto del usuario, y la pila.

• Nivel, que establece la barra que compare te exige:

  nivel	cuando el usuario dice	compuertas (todas deben pasar)
  structure	"mismo diseño/sensación pero nuestra marca", "como X con nuestro contenido"	diseño ≥ 90, movimiento ≥ 85
  faithful (predeterminado)	"clona esto", "recrea", "haz que se vea como"	diseño ≥ 95, estilo ≥ 95, píxeles ≥ 85, movimiento ≥ 90
  exact	"perfecto en píxeles", "1:1", "exactamente"	diseño ≥ 98, estilo ≥ 98, píxeles ≥ 97, movimiento ≥ 95

• Disparador: lo que inicia el movimiento (carga de página, hover, clic, desplazarse a la vista, desplazamiento continuo). Esto se convierte en --action.

Deduce lo que puedas de la solicitud y del repositorio. Pregunta solo cuando dos interpretaciones lleven a trabajos diferentes.

1. Configuración (una vez por máquina)

npm install --prefix <skill>/scripts
node <skill>/scripts/replica.mjs doctor

Si doctor informa que no hay navegador, ejecuta el comando de instalación que imprime. Si Google Chrome está instalado, Replica lo usa como respaldo. Las referencias de video y GIF también necesitan ffmpeg en PATH.

2. Capturar la referencia

Mantén todo dentro de .replica/<nombre>/ en el proyecto del usuario, y agrega .replica/ a .gitignore.

node <skill>/scripts/replica.mjs capture <url|archivo.html|imagen|video> --out .replica/<nombre>/ref \
  --selector "<css de la parte>" --viewports 1440x900,390x844 --action load --motion 1500

• --selector: delimita la captura a la parte que estás clonando. Páginas completas producen planos enormes.
• --viewports: los anchos que entregarás. El primero es el principal; el movimiento se registra allí.
• --action y --motion <ms>: solo cuando hay movimiento que clonar. Haz que la grabación sea lo suficientemente larga para cubrirlo todo; capture imprime una nota si algo aún se movía al final.
• --hide "<css>": oculta banners de cookies, widgets de chat y superposiciones de desarrollo. Esto se aplica a ambos lados.

Recetas para imágenes, videos, páginas con muro de inicio de sesión, iframes, canvas y modo oscuro están en references/sources.md.

Luego lee ref/blueprint.md completo. Mira ref/<viewport>/shot.png y ref/motion/filmstrip.png con tu visor de imágenes. La sintaxis del plano se explica en references/blueprint.md. Las referencias de imagen y video no tienen plano, así que construye a partir de las tomas y fotogramas.

3. Construir

Trabaja en este orden: tokens → esqueleto de diseño → tipografía → cajas y pintura → medios → responsive → movimiento.

• Tokens: coloca los colores, la escala tipográfica, los radios, las sombras y las variables CSS del plano en el sistema de tokens del proyecto (variables CSS o el tema de Tailwind) con sus valores exactos.
• Diseño: reproduce los valores flex … / grid cols[…], gap y pad de cada línea de contorno, y los anchos de los contenedores.
• Tipografía: iguala exactamente la familia, el peso, el tamaño/interlineado y el espaciado entre letras. Si una fuente no está disponible o tiene licencia, usa la más cercana disponible y regístrala como una diferencia conocida.
• Movimiento: cuando el plano tenga "Animaciones declaradas", copia su duración, retardo, suavizado y fotogramas clave exactamente. De lo contrario, usa el inicio, duración y suavizado de la línea de tiempo, o sus parámetros de resorte.
• Sírvuelo: haz que el clon sea accesible en una URL o archivo HTML que renderice el mismo estado (una ruta de servidor de desarrollo, una historia o un archivo estático). Si su elemento raíz necesita un selector diferente al de la referencia, pasa --selector a compare.

Notas para cada pila (CSS, Tailwind, Framer Motion, GSAP) están en references/building.md.

4. Comparar, corregir, repetir

node <skill>/scripts/replica.mjs compare .replica/<nombre>/ref <url del clon|archivo> [--selector "<css raíz del clon>"]

Esto escribe ronda-N/ con report.md, issues.json, score.json y sheets/. Código de salida 0 significa aprobado, 1 significa aún no, y 2 significa un error.

1. Lee ronda-N/report.md: la tabla de puntuaciones, luego Corregir siguiente. Cada elemento muestra cuántos puntos vale corregirlo.
2. Mira ronda-N/sheets/*.png: la referencia | la tuya | resumen de diferencias, zonas ampliadas y la tira de movimiento.
3. Corrige los 3 a 5 elementos principales, incluyendo siempre cualquier elemento de "Causa probable". Luego ejecuta compare nuevamente.

• Si el informe muestra ▼ (la puntuación bajó), deshaz tu último cambio antes de probar cualquier otra cosa.
• Si dos rondas consecutivas ganan menos de 1 punto, deja de parchear. Vuelve a leer el plano para el área que falla y verifica que las fuentes se cargaron y que estás comparando el selector, estado y viewport correctos.
• Detente después de 8 rondas e informa qué queda y por qué.

references/fixing.md cubre qué significa cada tipo de hallazgo y el cambio que generalmente lo resuelve.

5. Entregar

Termina con esto, completado:

Replica · <objetivo> → <archivos cambiados>
Nivel <nivel> · ronda <N> · puntuación <general> — APROBADO | AÚN NO
diseño <n> · estilo <n> · píxeles <n> · movimiento <n>
Diferencias conocidas: <cada una, con su motivo (fuente con licencia, texto propio del usuario, …)>
Recursos de referencia reutilizados: <lista, o ninguno> · marcadores: <lista, o ninguno>
Evidencia: .replica/<nombre>/ronda-<N>/report.md y sheets/

Si no aprobó, dímelo claramente y enumera los hallazgos principales restantes.