Scroll Progress Storytelling

When to use this

• You are building a long-form narrative page (data journalism, brand story, product launch page) where scroll position should drive which "chapter" of content and visuals are shown, like NYT's scrollytelling pieces or Apple product pages.
• You need to decide how many viewport-heights (vh) a story beat deserves before moving to the next, and want a repeatable pacing method instead of guessing.
• You are combining text overlays with a visual that changes underneath (image sequence, 3D scene, chart), and need to decide which one should lead the pacing.
• Do NOT use this for a short single-viewport landing page hero; that is simple parallax or entrance animation territory, not narrative structure. This skill is about pages spanning 5+ screen heights with distinct narrative beats; for the pinning mechanics themselves, pair with sticky-pinning-sequences, and for canvas-based visual scrubbing, pair with image-sequence-scrubbing.

Mental model

Scrollytelling is fundamentally a mapping problem: you have a 1-dimensional input (scroll progress, 0 to 1 across the whole story or per-chapter) and you need to map it onto N narrative beats, each with its own sub-progress. Get the mapping structure right before touching any animation library.

Think in acts, not pixels. A well-paced long-form piece has 3-7 acts (introduction, rising complexity, climax/key-insight, resolution/CTA), each act contains 1-4 beats, and each beat occupies a contiguous scroll range measured in viewport heights (vh), not raw pixels, so the pacing holds regardless of screen size. The single most important number in this whole discipline is vh-per-beat: how much scroll distance a reader spends on one idea before the next replaces it.

Two failure modes dominate bad scrollytelling: pacing too fast (a complex chart appears and is gone in 50vh, reader has no time to read it) and pacing too slow (400vh of scrolling for one static insight, reader thinks the page is broken or gives up). The fix is to separately budget vh for "read text" and vh for "watch transition," since these are different cognitive tasks: reading averages roughly 200-250 words/minute, and a typical scroll-through-a-beat happens over 2-4 seconds of continuous scrolling for someone moving at a natural pace, meaning a beat with 40 words of text needs far less vh than one with 120 words, but the visual transition itself (an image morphing, a chart drawing) needs its own minimum vh regardless of text length, because transitions read as broken if they complete before 20-30% of their allotted scroll range.

The other core decision is which one leads: text-led means the visual is reactive wallpaper illustrating what the text says (visual changes are secondary, subtitles almost), used when the information is precise and verbal (financial data, quotes, methodology). Visual-led means scroll advances a visual sequence and short text captions ride along explaining what's on screen (used for products, physical processes, anything where seeing beats reading). Mixing without deciding which leads is the most common structural mistake: text and visual compete for attention and neither reads cleanly.