/scrollytelling-web

name: scrollytelling-web
description: "Design and implement cinematic scroll-driven web narratives: pinned scenes, scrubbed timelines, product decomposition, image sequences, section transitions, spatial storytelling, and progressive 3D reveals. Use when scroll itself drives the story."

Scrollytelling Web

Build scroll experiences as authored narratives, not a pile of parallax effects. Scroll is the user's timeline controller; every pinned section, camera move, reveal, and product transformation must advance understanding or emotion.

1. Storyboard before code

Convert the page into **beats**. For every beat define:

• what the user should understand or feel;
• what remains spatially stable;
• what changes with scroll progress;
• the entry and exit state;
• whether the user can stop at any intermediate frame without seeing a broken composition;
• mobile/reduced-motion alternative.

For a product-decomposition sequence, a useful structure is:

1. establish the intact product; 2. isolate the key assembly; 3. explode parts along authored axes; 4. hold long enough for labels/copy to explain them; 5. move camera or product only after the part relationship is understood; 6. reassemble or transition into the next narrative state.

Do not make everything move simultaneously. Choreography needs hierarchy.

2. Pick the smallest correct engine

Use the simplest tool that can express the intended motion **well**:

• **CSS transitions / native scroll-driven animation** — simple reveals, progress-linked decoration, sticky sections with modest transforms.
• **Motion (`motion/react`)** — local React interactions, springs, component transitions, lightweight viewport effects.
• **GSAP + ScrollTrigger** — default for serious scrollytelling: pinned/scrubbed timelines, coordinated multi-element chapters, horizontal story tracks, image-sequence scrubbing, long-form section handoffs, precise start/end markers.
• **Lenis / smooth-scroll layer** — only when the choreography materially benefits from controlled smoothing. Never add scroll hijacking as decorative infrastructure.
• **Lottie / Rive** — authored 2D/vector animations with well-defined state machines or timelines.
• **Three.js / React Three Fiber** — real 3D camera work, lighting, materials, exploded assemblies, depth, product rotations, particles, or scenes where flat DOM transforms would be a fake substitute.

If a 2D solution communicates the product just as well, do not pay the 3D complexity/performance tax.

3. Scroll model

Normalize complex scroll experiences around a semantic progress value (`0..1`) or named chapter states. Keep narrative state separate from raw browser events.

Do **not** wire dozens of independent `scroll` listeners that each call layout reads and state updates. Prefer one timeline/controller that owns the sequence.

For GSAP, pair with `gsap-scrolltrigger`. For React, also apply the project's lifecycle/cleanup conventions and keep hot continuous values out of React render state.

4. Pinned scene rules

Pinned scenes work when the user understands why the page temporarily stops moving in document space.

• Pin a stable wrapper/stage; animate descendants or scene state rather than fighting the pinned element's own transform.
• Give the sequence enough scroll distance to read, but do not make the user grind through empty motion.
• Design the exact first and last frame so the handoff back to normal document flow is seamless.
• Avoid multiple nested pins unless there is a compelling reason and tested behavior.
• Recompute positions after asset/font/layout changes when the animation engine requires it.
• Test browser resize, dynamic address bars, and orientation changes.

5. Product exploded views

When the brief asks to “descompose/despiezar/explotar” a product:

Asset preparation

Prefer a properly authored GLB/glTF with meaningful node names and pivots. Parts that must separate independently need separate meshes/groups. Preserve a hierarchy that matches the product's conceptual assemblies.

If only a flattened render/image exists, do not pretend it is genuine 3D. Use an image-sequence/masked 2.5D treatment or request/produce the missing 3D asset through the project's asset workflow.

Explosion choreography

• Define an intact pose and an exploded pose for each semantic part.
• Use authored local axes or vectors; random radial explosions look like a debug visualization.
• Stagger related assemblies in logical order.
• Keep labels anchored to the relevant part and readable through camera motion.
• Let camera movement support the part motion, not compete with it.
• Reserve depth, rotation, focus changes, and lighting shifts for explanatory emphasis.

Scene quality

For premium product work, lighting/material/camera quality matters as much as the scroll linkage. Use physically plausible materials when the object demands realism, intentional environment/reflections, restrained post-processing, and consistent tone mapping. Avoid excessive bloom and “tech neon” unless the brand actually calls for it.

Use `threejs-product-storytelling` for the scene-specific craft layer.

6. Image-sequence scrollytelling

For photorealistic product transformation without real-time 3D, pre-rendered sequences are often the best solution.

• Decode/preload intelligently around the current frame instead of loading hundreds of full-size frames synchronously.
• Prefer modern formats where the delivery pipeline supports them.
• Draw to a canvas sized for the displayed resolution, not the original camera master.
• Map scroll progress monotonically to frame index; avoid jitter from repeated rounding around boundaries.
• Provide a poster/static state before the sequence is ready.
• On constrained mobile/network conditions, fall back to a short video/static milestone sequence if needed.

7. Typography and narrative layering

Copy is part of the choreography. Avoid forcing users to read paragraphs while the visual target