scrollytelling_data_story v1.0.0

name: scrollytelling_data_story description: Build a scroll-driven data story for the web: write one claim per section in a story manifest, choreograph chart states that change as the reader scrolls past a sticky graphic, keep text and visual in lockstep on mobile and desktop, ship reduced-motion, no-JS and no-observer fallbacks so the story reads with animation off, and hold the page to a stated performance budget. Triggers on scrollytelling, scroll-driven story, data story, sticky graphic, scrollama, scroll-triggered chart, or a longform page where charts change on scroll.

Scrollytelling Data Story

Purpose

Build a web page where scrolling through short text steps changes one chart in stages, so a reader gets a data argument one claim at a time instead of facing the finished chart all at once.

The failure this skill prevents is drift: text that promises one thing while the chart shows another, a sticky graphic that never sticks on phones, a story that goes blank with JavaScript off, and a page so heavy the chart arrives after the reader has scrolled past it. The fix is order of work. Write the story as a manifest first, choreograph states against that manifest, build the fallback document before the scroll effects, and check the finished page against a budget.

Bundled tools and material:

• bin/story_check.py validates a story manifest: one claim per step, a distinct chart state per step, data behind every state, alt text, fallback text, a mobile note per step, named fallbacks, and a critical resource budget. Standard library only.
• assets/story-manifest.example.json is a complete validated manifest built from NASA GISTEMP v4 annual temperature data.
• references/story-arc-template.md gives the five beat arc and every manifest field.
• references/choreography-checklist.md covers sticky structure, triggers, chart states, and failure drills.
• references/accessibility-fallbacks.md covers reduced motion, no-JS reading, chart text alternatives, and keyboard pass conditions, tied to WCAG criteria.
• references/worked-example.md builds the example manifest into a page with a native IntersectionObserver skeleton, no library required.

Workflow

1. Pick a story the format fits. Use scrollytelling when the dataset has a sequence worth revealing in order: a change over time, a build up of layers, a comparison that lands harder in stages. Refuse it when a single labelled chart plus two paragraphs carries the same argument, when the data has no order, or when the audience needs to look values up rather than follow a line of reasoning. A table or a stepper the reader controls beats forced scrolling in those cases.

1. Lock the data before writing copy. Work from a primary source: the official dataset, the agency release, or the standards or platform document behind the numbers. Record the source URL, the baseline or reference point with its dates, the unit, and the exact rows the story will use. Copy values from the source table, never from a chart image or from memory. If a number cannot be traced to the source in one step, it does not go in the story.

1. Write the manifest using references/story-arc-template.md. Default to five steps, stay between three and nine. Each step gets one claim in one sentence of 140 characters or fewer, supporting text of about 90 words or fewer, one chart state described in plain words, the data rows that state shows, alt text that leads with the trend, fallback text with the values in reading order, and a mobile note for that state. Read the claims alone, in order. They must form the whole argument with no chart present. Rewrite until they do.

1. Validate the manifest before building anything. Run python3 bin/story_check.py <manifest.json>. Fix every FAIL line. Treat WARN lines as edit notes: long stories and long step text are where readers leave. Do not start markup with a failing manifest, because the build will faithfully reproduce the manifest's mistakes.

1. Build the fallback document first. Lay out every step as a normal headed section holding its claim, its text, its fallback values, and a static chart in that step's final state. Follow the story with a real data table whose caption carries the baseline and the source. Check the page with JavaScript disabled at this point. It must read as a complete, plain article. This version is the product. Everything after this step is an enhancement layered on top of it.

1. Add the sticky graphic and the triggers. Use one chart inside one sticky container, with position: sticky and an inset such as top: 0. The chart scrolls into view, sticks while the steps pass, then unsticks at the end of its section, which is the sticky graphic pattern The Pudding documents for Scrollama. Check ancestors for stray overflow values, since an ancestor with overflow: hidden, auto, or scroll becomes the scroll container and can stop the graphic sticking to the viewport. Drive state changes with IntersectionObserver, directly or through Scrollama, which is built on it. Set the trigger near the middle of the viewport: Scrollama defaults its offset to 0.5, and a native observer can get the same effect with a rootMargin that shrinks the root to the middle line. Record the trigger value in the story notes.

1. Choreograph the states with references/choreography-checklist.md open. Keep the chart, the axis, the scale, and the units fixed across all states unless a change of scale is itself a step's claim and the text says so. Change one thing per step: a highlight, a range, an annotation, a group. Pair every colour change with a label, a direct value, or a marker change. Set each state from the active step index, so fast scrolling and scrolling back up both land on the exact right state without replaying skipped transitions.

1. Build the mobile layout as its own pass, not a shrink of the desktop one. The Pudding responsive guide makes two points that decide most mobile failures. First, do not size steps in vh: mobile browsers show and hide their bars while scrolling, the viewport height changes, and triggers jump. Set step heights in px from window.innerHeight on load and on resize instead. Second, keep CSS and JavaScript breakpoints in sync with the same matchMedia query. On small screens, stack the chart above the steps or run it as a shorter sticky band, keep annotations inside the chart area, stack end labels that would collide, and drop any state that depends on hover. Follow each step's mobile note from the manifest.

1. Wire the accessibility fallbacks from references/accessibility-fallbacks.md. Honour prefers-reduced-motion in CSS and check it in JavaScript through matchMedia: with reduce, states swap with no drawing animation, no parallax, and no self-moving parts, which is how a page meets WCAG 2.3.3 on interaction-triggered animation. Give any auto-moving content a pause, stop, or hide control, per WCAG 2.2.2. Add a fallback order for a missing IntersectionObserver: throttled scroll check, then the recap state as the static default. Never leave content hidden at zero opacity waiting for a trigger.

1. Hold the page to its budget, then test the whole story. Starter budget from web.dev: under 170 KB of compressed critical path resources, with Core Web Vitals targets of LCP at 2.5 seconds or less, INP at 200 ms or less, and CLS at 0.1 or less, judged at the 75th percentile. A hand-rolled observer and one inline chart fit easily; each library, font, and tracker spends from the same pot, so weigh them before adding. Then run the failure drills: story forwards and backwards, keyboard only, reduced motion on, JavaScript off, chart library blocked, and one full pass on a real phone. Finish with a value audit: pick three highlighted values at random and trace each one back to the source table.

Output Contract

Deliver these, every time:

• The story manifest as JSON, passing bin/story_check.py with zero FAIL lines, with source URL, baseline, and unit filled in.
• The built page, where the no-JS version reads as a complete article and the data table follows the story with baseline and source in its caption.
• A short build note listing: the trigger mechanism and its value, the breakpoint and how the mobile layout differs, which fallbacks were tested and how, the measured critical resource total against the budget, and any step where the shipped chart state differs from the manifest, with the reason.
• Source credit on the page itself, in the chart area or caption, not only in the build note.

Operating Rules

1. One claim per step, one change per state. A step that needs the word and to join two findings is two steps, or one finding gets cut.
2. The axis is part of the argument. Rescaling between states to make a change look bigger is a false claim with extra steps, and it breaks the reader's ability to compare states.
3. No number without a home. Every value in text, labels, alt text, and fallback text traces to a data row in the manifest, and every manifest row traces to the primary source.
4. Fallbacks are content, not error handling. Reduced motion, no-JS, and screen reader versions carry the full argument with all its values, written with the same care as the scroll version.
5. Scroll is the input, never a trap. Never hijack scroll speed, never override default scrolling, never hide content behind clicks in place of steps, and never move focus when a state changes. The reader can always just read down the page.
6. Budgets are set before build, not explained after. If a feature cannot fit inside the stated budget, the feature goes, or the budget change gets written into the manifest with a reason before the feature ships.
7. If any drill in the checklist fails and cannot be fixed in this run, ship the fallback document version and say so in the build note. A plain article that reads well beats a scroll effect that fails on part of the audience.