scrollytelling

What this skill does

# Scrollytelling Skill

Build scroll-driven narrative experiences that reveal content, trigger animations, and create immersive storytelling as users scroll.

## What is Scrollytelling?

**Definition**: "A storytelling format in which visual and textual elements appear or change as the reader scrolls through an online article." When readers scroll, something other than conventional document movement happens.

**Origin**: The New York Times' "Snow Fall: The Avalanche at Tunnel Creek" (2012), which won the 2013 Pulitzer Prize for Feature Writing.

**Why it works**: Scrollytelling exploits a fundamental psychological principle—humans crave control. Every scroll is a micro-commitment that increases engagement. Users control the pace, creating deeper connection than passive consumption.

**Measured impact**:
- 400% longer time-on-page vs static content
- 67% improvement in information recall
- 5x higher social sharing rates
- 25-40% improved conversion completion

## Core Principles

### 1. Story First, Technology Second

The biggest mistake is leading with technology instead of narrative. Scrollytelling should enhance the story, not showcase effects.

### 2. User Agency & Progressive Disclosure

Users control the pace. Information reveals gradually to maintain curiosity. This shifts from predetermined pacing to user-controlled narrative flow.

### 3. Sequential Structure

Unlike hierarchical web content, scrollytelling demands linear progression with clear narrative beats. Each section builds on the previous.

### 4. Meaningful Change

Every scroll-triggered effect must serve the narrative. Gratuitous animation distracts rather than enhances.

### 5. Restraint Over Spectacle

Not every section needs animation. Subtle transitions often work better than constant effects. The format should amplify the content's message, not fight it.

## The 5 Standard Techniques

Research analyzing 50 scrollytelling articles identified these core patterns:

| Technique | Description | Best For |
|-----------|-------------|----------|
| **Graphic Sequence** | Discrete visuals that change completely at scroll thresholds | Data visualizations, step-by-step explanations |
| **Animated Transition** | Smooth morphing between states | State changes, evolution over time |
| **Pan and Zoom** | Scroll controls which portion of a visual is visible | Maps, large images, spatial narratives |
| **Moviescroller** | Frame-by-frame progression creating video-like effects | Product showcases, 3D object reveals |
| **Show-and-Play** | Interactive elements activate at scroll waypoints | Multimedia, audio/video integration |

## Layout Patterns

### Pattern 1: Side-by-Side Sticky (Most Common)

The classic scrollytelling pattern: a graphic becomes "stuck" while narrative text scrolls alongside. When the narrative concludes, the graphic "unsticks."

```
┌─────────────────────────────────────┐
│  ┌──────────┐  ┌─────────────────┐  │
│  │  Text    │  │                 │  │
│  │  Step 1  │  │    STICKY       │  │
│  ├──────────┤  │    GRAPHIC      │  │
│  │  Text    │  │                 │  │
│  │  Step 2  │  │  (updates with  │  │
│  ├──────────┤  │   active step)  │  │
│  │  Text    │  │                 │  │
│  │  Step 3  │  │                 │  │
│  └──────────┘  └─────────────────┘  │
└─────────────────────────────────────┘
```

**When to use**: Data visualization stories, step-by-step explanations, educational content requiring persistent visual context.

**Implementation**: Use CSS `position: sticky` (not JavaScript scroll listeners) for better performance and graceful degradation.

### Pattern 2: Full-Width Sections

Content spans the entire viewport with section-based transitions.

**When to use**: Highly visual narratives, immersive brand storytelling, portfolio showcases, timeline-based stories.

### Pattern 3: Layered Parallax

Multiple visual layers (background, midground, foreground) move at different speeds to create depth.

**When to use**: Atmospheric storytelling, game/product launches, long-form narratives where depth adds emotional impact.

**Accessibility warning**: Parallax triggers vestibular disorders (dizziness, nausea, migraines). Always provide reduced-motion fallback; limit to one subtle parallax effect per page maximum.

### Pattern 4: Multi-Directional

Combines vertical scrolling with horizontal sections or sideways timelines.

**When to use**: Timeline-based content, visually-driven showcases, unconventional layouts where surprise enhances the message.

## When to Use Scrollytelling

**Good candidates**:
- Long-form journalism with multimedia
- Brand storytelling celebrating achievements
- Product pages showcasing features
- Chronological/historical content
- Complex narratives broken into digestible chunks
- High-consideration products needing depth

**Avoid when**:
- You lack strong visual assets
- You're tight on time/budget (good scrollytelling requires more investment)
- The story lacks distinct chronology
- Content is brief
- Performance is critical on low-end devices

## Discovery Questions

Before implementing, clarify with the user:

```
header: "Scrollytelling Pattern"
question: "What scrollytelling pattern fits your narrative?"
options:
  - "Pinned narrative - text changes while visual stays fixed (NYT, Pudding.cool style)"
  - "Progressive reveal - content fades in as you scroll down"
  - "Parallax depth - layers move at different speeds (requires reduced-motion fallback)"
  - "Step sequence - discrete sections with transitions between"
  - "Hybrid - multiple patterns combined"
```

```
header: "Tech Stack"
question: "What's your frontend setup?"
options:
  - "React + Tailwind"
  - "React + CSS-in-JS"
  - "Next.js"
  - "Vue"
  - "Vanilla JS"
  - "Other"
```

```
header: "Animation Approach"
question: "Animation library preference?"
options:
  - "CSS-only (scroll-timeline API, IntersectionObserver) - best performance"
  - "GSAP ScrollTrigger - most powerful, cross-browser"
  - "Framer Motion / Motion - React ecosystem"
  - "Lenis + custom - smooth scroll"
  - "No preference - recommend based on complexity"
```

## Technical Implementation (2025-2026)

### Technology Selection Guide

| Complexity | Recommendation | Bundle Size |
|------------|----------------|-------------|
| Simple reveals, progress bars | Native CSS scroll-timeline | 0 KB |
| Viewport-triggered effects | IntersectionObserver | 0 KB |
| Complex timelines, pinning | GSAP ScrollTrigger | ~23 KB |
| React projects | Motion (Framer Motion) | ~32 KB |
| Smooth scroll + effects | Lenis + GSAP | ~25 KB |

### CSS Scroll-Driven Animations (Native - 2025+)

**Browser support**:
- Chrome 115+: Full support (since July 2025)
- Safari 26+: Full support (since September 2025)
- Firefox: Requires flag (`layout.css.scroll-driven-animations.enabled`)

**Key properties**:
- `animation-timeline: scroll()` - links animation to scroll position
- `animation-timeline: view()` - links animation to element visibility
- `animation-range` - controls when animation starts/stops

**Example - View-triggered fade in**:
```css
@supports (animation-timeline: scroll()) {
  .reveal-on-scroll {
    animation: reveal linear both;
    animation-timeline: view();
    animation-range: entry 0% entry 100%;
  }

  @keyframes reveal {
    from {
      opacity: 0;
      transform: translateY(30px);
    }
    to {
      opacity: 1;
      transform: translateY(0);
    }
  }
}
```

**Example - Scroll-linked progress bar**:
```css
.progress-bar {
  animation: grow linear;
  animation-timeline: scroll();
}

@keyframes grow {
  from { transform: scaleX(0); }
  to { transform: scaleX(1); }
}
```

**Performance benefit**: Tokopedia achieved 80% code reduction and CPU usage dropped from 50% to 2% by switching to native CSS scroll-driven animations.

### IntersectionObserver Pattern

For scroll-triggered effects without continuous scroll tracking:

```tsx
const RevealOnScroll = ({ children, delay = 0 }) => {
  const ref = useRef(null);
  c