- Grupo: Animación
- Cuándo se activa: Smooth scroll con Locomotive Scroll
- Se instala: Opcional: llega con un paquete de skills.
Documentación completa upstream (inglés): SKILL.upstream.md (480 líneas). No la leas entera: usa el mapa y lee solo la sección que necesites (Read con offset/limit o Grep).
- Usar: landings inmersivas tipo Apple con scroll suavizado (lerp), capas parallax por velocidad y elementos sticky dentro de secciones.
- Usar: scroll horizontal o storytelling largo que necesita progreso por elemento (
data-scroll-id) o disparadores data-scroll-call.
- NO usar: solo fade-in al entrar en viewport → scroll-reveal-libraries (AOS) o IntersectionObserver.
- NO usar: animaciones scrubbed/pin sin smooth scroll → gsap-scrolltrigger (ScrollSmoother si se quiere suavizado); en React → motion-framer.
| Tarea |
Lee solo |
| Empezar un proyecto/starter |
SKILL.upstream.md L33-116 (§Installation + §Core Concepts) + assets/starter_locomotive/ |
| Parallax, sticky, scroll horizontal |
L139-161 (§2. Parallax), L193-209 (§4. Sticky), L236-254 (§6. Horizontal) |
| Eventos, progreso y scrollTo |
L163-191 (§3. Viewport Detection) + L211-234 (§5. Programmatic Scrolling) + L333-353 (§Instance Methods) |
| Combinar con GSAP ScrollTrigger |
L277-331 (§Integration with GSAP ScrollTrigger) + references/gsap_integration.md |
| Depurar / rendimiento |
L355-383 (§Performance Optimization) + L385-466 (§Common Pitfalls) |
| Líneas |
Sección |
Para qué |
| 10-32 |
Overview |
Capacidades y trade-offs (accesibilidad, móviles, position fixed) |
| 33-47 |
Installation |
npm + CSS obligatorio, o CDN |
| 49-116 |
Core Concepts |
Estructura data-scroll-container/-section, opciones de new LocomotiveScroll, tabla de atributos |
| 118-275 |
Common Patterns |
Smooth básico, parallax, eventos, sticky, scrollTo, horizontal, breakpoints tablet/smartphone |
| 277-331 |
Integration with GSAP ScrollTrigger |
scrollerProxy, scroller, refresh/update mutuos |
| 333-353 |
Instance Methods |
init/update/destroy/start/stop, scrollTo, on/off |
| 355-383 |
Performance Optimization |
Secciones, limitar parallax, desactivar en móvil, update en resize, destroy |
| 385-466 |
Common Pitfalls |
Fixed roto, lazy images, posiciones desactualizadas, accesibilidad, fugas de memoria, z-index |
| 468-480 |
Related Skills / Resources |
Skills relacionadas e índice de scripts, references y assets |
references/api_reference.md — API completa: opciones, atributos, métodos, eventos.references/gsap_integration.md — Patrones de ScrollTrigger + Locomotive (scrollerProxy, pin, scrub).scripts/generate_config.py — Genera la configuración inicial: py -3 scripts/generate_config.py --smooth / --horizontal (o python3 …).scripts/integration_helper.py — Genera código de integración GSAP por patrón/framework: py -3 scripts/integration_helper.py --pattern fade-in --framework react.assets/starter_locomotive/ — Starter completo (index.html, main.js, style.css, package.json, README.md).
- Importa siempre
locomotive-scroll/dist/locomotive-scroll.css; envuelve el contenido en data-scroll-container y segmenta con data-scroll-section.
- Respeta
prefers-reduced-motion: smooth: !matchMedia('(prefers-reduced-motion: reduce)').matches; considera smartphone: { smooth: false }.
- Llama a
scroll.update() tras insertar contenido dinámico, cargar imágenes o en resize; llama a scroll.destroy() al desmontar o cambiar de ruta.
- Los elementos
position: fixed van fuera del contenedor (o usa data-scroll-sticky); las capas parallax necesitan z-index explícito.
- Con GSAP: registra
scrollerProxy, pasa scroller: '[data-scroll-container]' a cada ScrollTrigger y encadena ScrollTrigger.refresh() → locoScroll.update().
- SSR-safe: instancia solo en cliente (
useEffect/onMounted/client:only), nunca en el nivel superior del módulo.
- Detecta el stack como indica la skill
front-activation/skill-router (senzu/senzu.json → package.json). Es vanilla JS y sirve en HTML estático, Astro, Vue (instancia en onMounted, destruye en onUnmounted) y React (useEffect con cleanup). En proyectos React con GSAP, valora ScrollSmoother (gsap-scrolltrigger) para evitar dos sistemas de scroll; con barba-js, destruye y recrea la instancia en cada transición.
