Constructor de Sitios Web con Animaciones de Desplazamiento
Toma un tema y un sujeto del usuario y entrega un sitio web completo, verificado, impulsado por el desplazamiento, sin devolver el trabajo a mitad de camino.
Antes de empezar: ¿es un sitio nuevo o una adaptación?
Añadir movimiento a una página que ya tiene posicionamiento es un trabajo diferente con riesgos
diferentes: el presupuesto de desplazamiento debe incluir la altura existente de la página, y un pin es
distancia de desplazamiento muerta en una página que alguien está escaneando para tomar una decisión. Por defecto, construye
en una URL de showcase separada y enlázala; convierte en el mismo lugar solo cuando
la página no tenga tráfico que perder y su función sea impresión en lugar de
referencia. Siempre haz primero una copia de seguridad byte a byte y entrega al usuario el comando
para restaurar. Lee references/08-failure-modes.md §3 antes de aceptar una adaptación.
El flujo de trabajo
Seis fases. Ejecútalas en orden. Solo la Fase 1 habla con el usuario.
1 DESCUBRIR → asistente, 2–3 rondas de preguntas [interactivo]
2 PUNTUAR → compilar plano scroll-score.json [autónomo]
3 ACTIVOS → generar/recopilar imágenes, fotogramas, video [autónomo]
4 ANDAMIAR → esqueleto del proyecto + motor de movimiento [autónomo]
5 CONSTRUIR → implementar cada beat en la Puntuación [autónomo]
6 VERIFICAR → conducir un navegador real, corregir, repetir [autónomo]
Después de que el asistente se cierre en la Fase 1, deja de hacer preguntas. Las fases 2–6 se ejecutan hasta
completarse según tu propio criterio. Registra las suposiciones en DECISIONS.md e infórmalas
al final en lugar de bloquearte con preguntas. El usuario pidió una construcción de principio a fin;
una página a medio construir más una pregunta es una ejecución fallida.
Fase 1 — DESCUBRIR (el asistente)
Pregunta con la herramienta AskUserQuestion, nunca como un muro de prosa. Dos rondas es
típico, tres es el máximo. Banco de preguntas completo, rama por rama:
→ Lee references/01-discovery-wizard.md
La ronda 1 son siempre las mismas dos preguntas: tipo de sujeto y objetivo principal:
| Sujeto | Qué está haciendo realmente el scroll |
|---|---|
| Persona (portafolio, currículum, marca personal) | Generar confianza: trabajo → prueba → contacto |
| Producto (físico o digital) | Revelar el objeto: héroe → características → comprar |
| Empresa (agencia, startup, estudio) | Establecer escala: manifiesto → trabajo → equipo |
| Evento / Lanzamiento (conferencia, lanzamiento, estreno) | Construir anticipación: fecha → programa → registrarse |
| Causa / Historia (sin ánimo de lucro, editorial, informe) | Llevar un argumento: gancho → evidencia → actuar |
La rama en la que aterrices define el esqueleto de secciones y el patrón de movimiento dominante. La ronda 2 hace preguntas específicas de la rama (qué trabajo, qué producto, qué prueba). Ronda 3, solo si aún hay ambigüedad, resuelve la dirección estética, la intensidad del movimiento y la estrategia de activos.
Detén el asistente tan pronto como puedas nombrar: el sujeto, el objetivo, 4–7 secciones, una dirección estética y de dónde vienen los activos. Infiere el resto.
Fase 2 — PUNTUAR (el plano)
Compila todo en scroll-score.json en la raíz del proyecto. Este es el
contrato que tanto la construcción como el verificador leerán. Escríbelo antes de escribir cualquier
componente.
→ Lee references/02-scroll-score.md para el esquema completo.
Una Puntuación (Score) es una lista de beats. Un beat = un momento impulsado por el scroll: qué se fija (pin), qué se arrastra (scrub), sobre qué distancia y qué se mueve.
{
"meta": { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
"theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
"motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
"beats": [
{ "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
"scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
{ "id": "features", "pattern": "sticky-stack", … }
]
}
Presupuesta el desplazamiento. La altura total de la página debe estar cerca de
100vh × (1 + Σ costo de scroll del beat). Un beat con pin y scrub cuesta 1.5–2.5 alturas de
viewport; un beat de revelación cuesta ~1. Por debajo de 3 en total, el sitio se siente abrupto; por encima de 12, se siente
como una tarea pesada. Apunta a 5–9.
Fase 3 — ACTIVOS
Nunca envíes cajas grises. Cada beat nombrado en la Puntuación necesita su activo real antes de la Fase 5 — una construcción con marcadores de posición siempre tiene que rehacerse.
→ Lee references/05-asset-pipeline.md para el flujo completo, incluyendo
la cadena de renderizado por IA → video interpolado → secuencia de fotogramas, todas las invocaciones de ffmpeg
y los presupuestos de peso.
Tres fuentes, en orden de preferencia:
- Proporcionados por el usuario — siempre ganan. Pídelos en el asistente, nunca después.
- Generados —
mcp__image-gen-mcp__generate_image(gpt-image-2,background: "transparent"para productos, hasta3840x2160), oedit_imagepara convertir una foto de producto real en un render estilizado. - Marcadores de posición — solo para un beat que el usuario haya diferido explícitamente, y debe ser una composición considerada de gradiente/tipografía, nunca una caja gris.
Para un héroe de secuencia de imágenes (el estilo Apple "el producto explota mientras te desplazas"), la cadena es: primer fotograma + último fotograma → video interpolado → fotogramas extraídos → secuencia WebP → canvas scrub. Mantén la secuencia por debajo de 4 MB en total, 36–60 fotogramas, 1600 px de ancho. Ese presupuesto es la única razón por la que el efecto sigue siendo usable; superarlo es el fallo más común de este patrón.
Fase 4 — ANDAMIAR
Stack por defecto, a menos que el usuario haya nombrado uno: Vite + vanilla TS + GSAP. No tiene
ciclo de vida de framework con el que luchar, y los errores de ScrollTrigger en React son casi
siempre errores de limpieza. Usa Next.js/React solo cuando el usuario lo pida o el
proyecto necesite enrutamiento, y entonces usa useGSAP() para la limpieza — nunca un useEffect
desnudo.
El scroll suave (Lenis) es OPCIONAL — ya no forma parte del stack por defecto.
Añádelo solo cuando el usuario pida scroll suave o inercial por su nombre. Reemplaza
el scroll nativo con su propia posición animada, y cuando se siente incluso ligeramente
incorrecto, toda la página se lee como rota — esta es la razón más común por la que una construcción
técnicamente correcta es rechazada. El scrub de ScrollTrigger ya te da
la sensación suave y cinematográfica que la gente suele querer decir con "suave".
Consulta references/08-failure-modes.md §1.
→ Lee references/07-stack-setup.md para andamios y comandos exactos.
GSAP es 100% gratuito desde v3.13 (adquisición por Webflow), incluyendo SplitText,
ScrollSmoother y MorphSVG. npm install gsap obtiene todo — sin clave de licencia,
sin gsap-trial, sin soluciones de plugins CDN. No le digas al usuario que un plugin
es de pago.
El contenido vive en src/content.ts, nunca en línea en el marcado. El usuario debe poder
cambiar el texto sin tocar el código de movimiento.
Fase 5 — CONSTRUIR
Implementa cada beat de la Puntuación usando las implementaciones de patrón canónico:
→ Lee references/03-pattern-library.md — 12 patrones, listos para copiar.
| Patrón | Úsalo para |
|---|---|
reveal-on-enter | Entradas de sección estándar, cuadrículas de tarjetas |
text-reveal | Titulares, citas destacadas (SplitText, enmascarado) |
pin-scrub | El momento "wow" central: escenario fijo, línea de tiempo arrastrada |
parallax-layers | Profundidad: fondos, accesorios en primer plano |
media-scrub-sequence | Revelación de producto estilo Apple (canvas + fotogramas) |
media-scrub-video | Mismo efecto desde un archivo de video (currentTime) |
horizontal-scroll | Portafolios, galerías, líneas de tiempo |
mask-reveal | Una imagen que se abre para tragar el viewport |
sticky-stack | Listas de características, tarjetas apiladas |
scroll-progress | Barras de progreso, contadores, indicadores de sección |
theme-morph | Cambio de fondo/color entre secciones |
snap-sections | Páginas tipo mazo, una sección por scroll |
Y las reglas no negociables de GSAP:
→ Lee references/04-gsap-rules.md antes de escribir código de ScrollTrigger.
Las cinco que más a menudo rompen las construcciones:
- Un ScrollTrigger por línea de tiempo, en la línea de tiempo — nunca en un tween hijo, nunca anidado dentro de una línea de tiempo padre.
- Si — y solo si — añadiste Lenis, comparte el bucle de GSAP.
lenis.on('scroll', ScrollTrigger.update)+gsap.ticker.add(t => lenis.raf(t * 1000))+gsap.ticker.lagSmoothing(0). Nunca añadas un buclerequestAnimationFrameseparado para Lenis. ease: "none"en cualquier tween que impulsecontainerAnimationo un media scrub.scrubotoggleActions, nunca ambos en el mismo trigger.ScrollTrigger.refresh()después de que las fuentes y las imágenes carguen — no solo al redimensionar.- Antes de cualquier pin, recorre los ancestros en busca de
transform/filter/contain. Cualquiera de ellos rompe silenciosamenteposition: fixed, así que el pin se crea, reportapin: truey no hace nada. Elimina la propiedad o establecepinType: 'transform'. Consulta08-failure-modes.md§2.
Anima solo transform y opacity. Cualquier cosa que toque top, left,
width, height o margin al hacer scroll hará que se pierdan fotogramas.
Fase 6 — VERIFICAR
Esta fase no es opcional, y es lo que separa esta habilidad de escribir GSAP a mano. Las animaciones de desplazamiento no se pueden verificar leyendo código — los pins colapsan, los triggers se disparan a la profundidad incorrecta y los fotogramas desaparecen solo en un navegador real con un viewport real.
→ Lee references/06-verification.md para el bucle completo y la lista de verificación.
→ Lee references/08-failure-modes.md — fallos que pasan todas las comprobaciones automatizadas. Léelo antes de la Fase 4, no después de que algo se rompa.
Inicia el servidor de desarrollo, luego condúcelo con Playwright MCP:
mcp__playwright__browser_navigate → la URL del servidor de desarrollo
mcp__playwright__browser_resize → 1440×900, luego 390×844
mcp__playwright__browser_evaluate → hacer scroll a profundidad, leer estado
mcp__playwright__browser_take_screenshot → en cada profundidad
mcp__playwright__browser_console_messages → errores y advertencias de GSAP
mcp__playwright__browser_network_requests → 404, peso de activos
Barre 0 %, 15 %, 30 %, 50 %, 70 %, 85 %, 100 % de la altura de la página en escritorio y móvil. En cada parada, haz una captura de pantalla y mírala. Estás comprobando que la página se vea bien, no simplemente que no haya lanzado errores.
Conduce la página con ENTRADA REAL — mouse.wheel() o pulsaciones de teclas, nunca
window.scrollTo. El scroll sintético es tragado por las bibliotecas de secuestro de scroll,
que es precisamente el fallo que necesitas detectar. Si tres muescas de rueda no mueven la página,
está rota sin importar lo que digan las afirmaciones.
Falla la ejecución y corrige si alguna de las siguientes condiciones es cierta:
- Un error de consola, o cualquier advertencia de
ScrollTrigger - Cualquier 404, o peso total de activos por encima del presupuesto
- Una captura de pantalla en blanco/sin estilo a cualquier profundidad
- Una sección fijada que se superpone con la siguiente sección, o colapsa el diseño
- Contenido que nunca se vuelve visible (una revelación que nunca se dispara)
- Desbordamiento horizontal a 390px de ancho
markers: truesobreviviendo en alguna parte del código fuente- Sin fallback para
prefers-reduced-motion - Tres muescas reales de rueda no mueven visiblemente la página
- Un pin cuyo escenario todavía sigue el scroll (afirma
|rect.top| < 10dentro del rango) - Medios arrastrados (scrubbed) que llegan a su final antes de ~90% de su pin
- Más de ~40 muescas de rueda para alcanzar la CTA principal
Bucle corrección → re-verificar hasta que esté limpio, hasta 5 rondas. Si algo aún falla después de 5, entrega el resto, deshabilita ese beat detrás de una bandera y dilo claramente en el informe final. Nunca reportes éxito en una página no verificada.
Definición de completado
-
scroll-score.jsoncoincide con lo que realmente se construyó - Cada beat verificado en escritorio y móvil
- Cero errores de consola, cero 404
-
prefers-reduced-motiondegrada a estados instantáneos, sin movimiento - Cordura tipo Lighthouse: sin cambios de diseño por pins, imágenes con tamaño
-
README.md— cómo ejecutar, dónde vive el contenido, cómo intercambiar activos -
DECISIONS.md— suposiciones hechas después de que el asistente se cerró - Mensaje final: qué se construyó, qué se asumió, qué revisar
No hagas
- ❌ Hagas preguntas después de que el asistente se cierre — asume, registra e informa en su lugar
- ❌ Reportes completado sin ejecutar la Fase 6 en un navegador real
- ❌ Entregues
markers: true,console.logo unTODOen el código entregado - ❌ Uses
gsap-trialo digas que SplitText/ScrollSmoother necesitan una licencia Club - ❌ Animes propiedades de diseño al hacer scroll
- ❌ Fijes (pin) en móvil sin comprobarlo — prefiere desvanecer por debajo de 768px
- ❌ Superes el presupuesto de activos para una secuencia héroe