Scroll Story Chapter Contract

Large Theory

Scrollytelling is not a long page plus flashy motion. It is a chaptered explanation structure. Users control reading pace through scroll, while the interface connects the active chapter to visual state through sticky graphics, step triggers, progress, or short pinned sections. A healthy scroll story defines chapter questions and static readability before choosing Scrollama, IntersectionObserver, CSS scroll-driven animations, GSAP ScrollTrigger, or native sticky behavior.

Small Points

1. Each chapter answers one question: what is happening, why it is credible, how state changes, or what the user should do next.
2. Text is the anchor, not a caption layer. Headings, body copy, key numbers, and CTAs should remain real HTML in document flow instead of living only inside canvas, video, hover, or intermediate frames.
3. Step triggers fit discrete chapters: step 2 can switch a chart, device state, or product screenshot. Continuous scrub fits only real continuous variables such as progress, time, or model state.
4. Sticky graphics are safer than long pins. Long pinning changes scroll-distance expectations and can make mobile users feel stuck.
5. Fallback comes before motion: no-JS, reduced-motion, mobile, print, and slow-network contexts should still show complete chapters and representative keyframes.
6. Avoid driving React state on every scroll tick. IntersectionObserver fits threshold triggers, Scrollama wraps step/progress patterns, and GSAP fits complex timelines. Observers, RAF loops, ScrollTriggers, Lenis instances, and media listeners all need cleanup.

Design Judgment

A scroll story works when users can stop at any chapter, understand the conclusion, and continue only to gain causality and rhythm. It fails when users must precisely land on a frame to understand pricing, compliance, product capability, or the CTA.

Implementation Notes

Create ScrollStoryStep data with id, title, body, visualState, fallbackImage, alt, and evidenceHref. Then choose the motion model: static, sticky, step, scrub, pinned, or video-sequence. Start with lower-risk technology: CSS sticky, then IntersectionObserver/Scrollama, CSS scroll-driven animation as progressive enhancement, GSAP ScrollTrigger, and only then Lenis/WebGL sync. QA should cover keyboard, anchors, browser back/restore, reduced motion, mobile touch, no horizontal overflow, media failure, and unmount cleanup.

Counterexamples/Risks

A first viewport pinned for a long abstract animation, all explanation hidden in video frames, Scrollama or ScrollTrigger with no static fallback, desktop sticky columns squeezed into mobile, smooth scroll still active under reduced motion, scroll handlers setting state every frame, and observers or RAF loops continuing after route changes.

Case Study

Scrollama's official repository positions it as a lightweight scrollytelling library built on IntersectionObserver and focused on simpler scroll interactives instead of direct scroll-event handling. The Pudding's Scrollama introduction separates the pattern into step triggers, step progress, and sticky graphics. Awwwards lists Dayos as Site of the Day on 2025-05-29 and highlights scroll scrubbed video, form transition, storytelling, and CTA elements; the product context is operational AI connecting multi-cloud systems. The reusable lesson is that scroll motion can explain abstract enterprise AI workflows, but it must be organized around chapters, states, and actions rather than around scroll spectacle.

Source Links

Scrollama GitHub: https://github.com/russellsamora/scrollama The Pudding Scrollama introduction: https://pudding.cool/process/introducing-scrollama/ MDN Intersection Observer API: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API Awwwards Dayos: https://www.awwwards.com/sites/dayos MDN prefers-reduced-motion: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/%40media/prefers-reduced-motion