Communitygithub.com

hemangjoshi37a/scroll_animated_webpages_skill

Construye sitios web galardonados con animaciones de desplazamiento de principio a fin. Ejecuta un asistente de descubrimiento (persona/producto/empresa/evento/causa), compila un plano de Scroll Score, genera el proyecto, implementa animaciones con GSAP ScrollTrigger (con Lenis smooth scroll opcional) y luego verifica en un navegador real con Playwright MCP, corrigiendo lo que encuentre. Úsalo cuando el usuario quiera un sitio con animaciones de desplazamiento, una landing page scroll-driven, un scroll estilo Apple, un sitio awwwards, scrollytelling, parallax o secciones fijas, o un efecto de secuencia de imágenes al hacer scroll.

¿Qué es scroll_animated_webpages_skill?

Esta habilidad (skill) está diseñada para crear sitios web completos con animaciones basadas en el desplazamiento (scroll-driven), ideales para portfolios, lanzamientos de productos o narraciones visuales (scrollytelling). Funciona en seis fases automatizadas: un asistente interactivo descubre el sujeto y objetivo del proyecto; se genera un plano técnico (`scroll-score.json`) que detalla cada 'beat' de animación; se recopilan los activos visuales; se crea la estructura del proyecto con Vite, TypeScript y GSAP; se implementan todas las animaciones usando patrones probados; y finalmente se verifica todo en un navegador real con Playwright MCP, realizando correcciones hasta que pase todas las pruebas. Soporta cualquier tipo de contenido (persona, producto, empresa, evento, causa) y permite elegir entre múltiples patrones de animación, desde simples revelaciones hasta complejas secuencias de imágenes al estilo Apple. La habilidad es especialmente útil porque no solo genera el código, sino que lo prueba exhaustivamente, evitando errores comunes como pins que no funcionan, animaciones rotas en móvil o activos demasiado pesados.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hemangjoshi37a/scroll_animated_webpages_skill/tree/HEAD/skills/scroll-animated-site

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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:

SujetoQué 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:

  1. Proporcionados por el usuario — siempre ganan. Pídelos en el asistente, nunca después.
  2. Generados — mcp__image-gen-mcp__generate_image (gpt-image-2, background: "transparent" para productos, hasta 3840x2160), o edit_image para convertir una foto de producto real en un render estilizado.
  3. 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-enterEntradas de sección estándar, cuadrículas de tarjetas
text-revealTitulares, citas destacadas (SplitText, enmascarado)
pin-scrubEl momento "wow" central: escenario fijo, línea de tiempo arrastrada
parallax-layersProfundidad: fondos, accesorios en primer plano
media-scrub-sequenceRevelación de producto estilo Apple (canvas + fotogramas)
media-scrub-videoMismo efecto desde un archivo de video (currentTime)
horizontal-scrollPortafolios, galerías, líneas de tiempo
mask-revealUna imagen que se abre para tragar el viewport
sticky-stackListas de características, tarjetas apiladas
scroll-progressBarras de progreso, contadores, indicadores de sección
theme-morphCambio de fondo/color entre secciones
snap-sectionsPá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:

  1. 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.
  2. 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 bucle requestAnimationFrame separado para Lenis.
  3. ease: "none" en cualquier tween que impulse containerAnimation o un media scrub.
  4. scrub o toggleActions, nunca ambos en el mismo trigger.
  5. ScrollTrigger.refresh() después de que las fuentes y las imágenes carguen — no solo al redimensionar.
  6. Antes de cualquier pin, recorre los ancestros en busca de transform / filter / contain. Cualquiera de ellos rompe silenciosamente position: fixed, así que el pin se crea, reporta pin: true y no hace nada. Elimina la propiedad o establece pinType: 'transform'. Consulta 08-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: true sobreviviendo 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| < 10 dentro 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.json coincide con lo que realmente se construyó
  • Cada beat verificado en escritorio y móvil
  • Cero errores de consola, cero 404
  • prefers-reduced-motion degrada 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.log o un TODO en el código entregado
  • ❌ Uses gsap-trial o 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

Skills relacionados