Svelte Scrollytelling Guide Set

This system helps a journalist and an AI agent collaborate to build a scrollytelling story - from raw idea to polished interactive page.

Agent: follow the phases in order. Do not skip to building until the story is shaped.

This README is only the router. Use it to decide which guide or skill to enter next, then read that guidance directly before doing the work.

---

Phase 0: Story Discovery

Before touching any code or guide, interview the user. Ask these questions one or two at a time — never dump the full list.

Must-ask

1. What happened? One sentence: what is the story about?
2. Why now? What makes this timely or important?
3. For whom? Who is the intended audience? (general public, policy experts, community members, etc.)
4. What should the reader feel or understand after scrolling? This is the takeaway.
5. Do you have data? If yes, what format? If no, what evidence supports the story?

Ask as needed

6. What is the single most striking finding or moment?
7. Are there characters, places, or dates the reader should anchor to?
8. Is there an existing article or report this accompanies, or is this standalone?
9. What is the publication context? (newsroom CMS, standalone deploy, embedded widget)
10. Any hard constraints? (deadline, max page weight, must work on mobile, no external APIs)

Agent behavior

• Listen more than suggest. Let the journalist lead on editorial judgment.
• If answers are vague, reflect back what you heard and ask one clarifying question.
• Capture the angle (the specific claim or perspective the story advances) and the takeaway (what the reader should remember). Write both down before moving on.

---

Phase 1: Data Review

If the user provides data files, review them before proposing any visuals.

Steps

1. Inventory: list every data file in the project folder. Note format, size, and column names.
2. Quick audit: for each file, report row count, column types, obvious quality issues (nulls, mixed types, outliers). Keep it to a few sentences per file.
3. Connect to the angle: which columns or records relate to the story's angle? Which are irrelevant?
4. Surface story candidates: start with the macro picture first (overall trend, totals, composition shifts, rank changes), then flag anomalies like spikes, gaps, or unusual names. These are candidate leads.
5. Ask the journalist:
   • "Does this match your understanding of the data?"
   • "Which of these findings do you want to highlight?"
   • "Is anything missing that you expected to see?"

Data workflow routing

Use the data skills as a sequence with explicit handoffs. Do not collapse them into one step.

Transparency requirement

Whenever any data processing happens, the agent must create and maintain data_processing_transparency.md.

Treat this as required for any step that loads, cleans, filters, joins, reshapes, aggregates, analyzes, or exports data. Do not wait until the end. Start the document when processing begins and update it as work proceeds.

At minimum, this document must record:

• the goal of each processing step
• input files used and output files produced
• code artifacts used, with exact filenames for scripts, SQL files, notebooks, or other executable files
• how the code was run, including command lines when relevant
• dependencies or runtime details that affect reproducibility
• transformations applied and why they were needed
• results produced, including key counts, tables, summaries, or generated artifacts
• errors, failed attempts, partial extractions, and warnings, not just successful runs
• decisions that required journalist approval and the outcome of those decisions
• unresolved limitations, caveats, or quality concerns

The document should make it possible for another person to understand what was done, what succeeded, what failed, which code produced which outputs, and what would need to be rerun to reproduce the work.

1. Messy or uncertain data -> preprocessing first

   • Enter guides/structured-data-preprocessing-journalism/SKILL.md when files need loading, provenance, column audits, duplicate checks, type cleanup, or transformation decisions.
   • Read report-template.md when preparing the human-review report.
   • Produce the audit/report artifacts that skill expects, update data_processing_transparency.md with the loading and audit steps, propose transformations, and stop for journalist approval before transforming data.

2. Clean data -> analysis

   • Enter guides/structured-data-analysis-journalism/SKILL.md once the data is analysis-ready.
   • If the dataset is unfamiliar, large, or mixed-format, read analysis-playbook.md before choosing methods.
   • If the journalist is still asking "what's the story?", use story-finding mode: start with macro trends, then specific signals, then contextual significance. Produce story_tipsheet.md, log the analysis path and outputs in data_processing_transparency.md, and stop until the journalist picks a lead.
   • If the journalist already has a hypothesis, use question-driven mode: produce analysis_proposal.md, wait for approval, then run the approved analyses and produce analysis_findings.md plus supporting record exports. Record each executed analysis, output file, and any failed or discarded attempts in data_processing_transparency.md.

3. Python execution layer -> python-runner

   • When preprocessing or analysis requires Python scripts, run them through guides/python-runner/SKILL.md, not ad hoc python commands.
   • Prefer self-contained scripts with inline dependencies and uv run.
   • Every Python script run must be referenced in data_processing_transparency.md by filename, purpose, run method, and resulting outputs or errors.
   • If uv is unavailable, check install-uv.md.

4. Approved findings -> scrollytelling skill

   • Enter guides/data-scrollytelling-journalism/SKILL.md only after the findings or lead are approved.
   • Start with story-architecture.md to turn findings into chapters.
   • Then use data-shaping.md to define presentation data contracts before building charts.
   • Use chart-interaction-patterns.md when deciding how each scroll step changes the visual.
   • Bring forward only the approved lead, chapter plan, and presentation-shaped data into implementation.

When there is no data

The story may be narrative-driven (photo essay, timeline, explainer). Skip to Phase 2.

---

Phase 2: Story Shape

Now decide how to tell the story visually. Work through these choices with the user.

2a. Structure

Ask: "How should the reader move through this?"

Structure	Best for	Notes
Linear scroll	Most stories	Sections revealed as reader scrolls. Default choice.
Defined steps	Data-driven stories	Discrete numbered steps with clear transitions.
Branching / interactive	Exploratory stories	Reader chooses paths. More complex to build.
Single visual + annotations	One chart or map	A focal visual with scroll-triggered annotations.

2b. Visual elements

For each major section or finding, ask: "What is the best way to show this?"

Element	When to use
Chart (bar, line, scatter)	Comparing quantities, showing trends, distributions
Map	Geography matters to the story
Image / photo	Human moments, places, evidence
Video or animation	Process, motion, before/after
Illustrated diagram	Systems, flows, relationships
Pull quote or big number	Emphasis, pacing, emotional beats
Interactive widget	Reader needs to explore or filter

Guide the user toward the simplest element that serves the story. A well-placed number can hit harder than a complex chart.

2c. Tone and aesthetics

Ask: "What should this feel like?"

Offer a few spectrums and let the user point:

• Sober and institutional ---- Urgent and emotional
• Minimal and spacious ---- Dense and data-rich
• Photographic ---- Illustrated / diagrammatic
• Dark palette ---- Light palette

These choices inform color, typography, spacing, and motion decisions later.

2d. Outline

Before building, produce a short section outline:

1. [Title / hook] — what the reader sees first
2. [Context] — background the reader needs
3. [Key finding 1] — visual: chart showing X
4. [Key finding 2] — visual: map of Y
5. [Human moment] — photo + quote
6. [Takeaway] — what it means, what comes next

Get the journalist's approval on this outline before writing any code.

---

Phase 3: Build

Now route to the technical guides. Read one primary guide in full, plus at most one or two secondary guides if the task crosses domains.

Fast Routing

• Component structure, reactive state, step logic, snippets, bindings, DOM refs --> 01-svelte-core.md
• Scroll progress, pinned scenes, reveals, transitions, springs, tweens --> 02-motion-scroll.md
• Images, responsive art direction, video, audio, canvas, SVG --> 03-media.md
• Maps, charts, WebGL, D3, Mapbox, Leaflet, Three.js, browser-only libs --> 04-imperative-integrations.md
• Routes, load, CMS/API data, URL state, SSR/CSR, multi-page --> 05-sveltekit-routing-data.md
• Performance, accessibility, reduced motion, code splitting, QA --> 06-polish.md
• Chart-led scrollytelling structure, step-driven graph updates, chapter planning, explore modals --> data-scrollytelling-journalism/SKILL.md
• Python execution for preprocessing, analysis, and data-shaping scripts --> python-runner/SKILL.md

Common Combinations

• Messy newsroom data: structured-data-preprocessing-journalism then python-runner
• Story discovery from clean data: structured-data-analysis-journalism then python-runner
• Approved findings to chart-led story: data-scrollytelling-journalism then 04 then 02 then 06
• Scroll story with images: 02 then 03
• Scroll story with a map: 04 then 02
• Editorial longform with CMS data: 05 then 03
• One-page explainer with animation: 01 then 02
• Data-heavy interactive with charts: 04 then 05 then 06
• Chart-led scrollytelling with analysis still in progress: structured-data-analysis-journalism then data-scrollytelling-journalism then 04 then 02 then 06

Routing Rules

• Prefer one primary guide. Branch only when the task clearly spans domains.
• Start with the guide that owns the hardest technical constraint.
• If the task is still about understanding, cleaning, or defending the data, stay in the data skills. Do not jump to Svelte implementation yet.
• Use python-runner whenever you need Python for preprocessing, analysis, export generation, or data shaping.
• If any data processing occurs, create and maintain data_processing_transparency.md alongside the other workflow artifacts.
• If the page is driven by approved findings and chart-state changes, start with data-scrollytelling-journalism before the lower-level technical guides.
• Use 04 whenever a library manages its own DOM, canvas, WebGL, or map instance.
• Use 05 whenever the task mentions +page, +layout, load, navigation, or URL params.
• Use 06 near the end, even if it was not the primary guide.

---

Phase 4: Polish and Review

Before the story ships, always consult 06-polish.md for:

• Performance audit (asset sizes, lazy loading, code splitting)
• Accessibility (screen readers, keyboard nav, reduced motion)
• Mobile testing
• Final QA checklist

Ask the journalist: "Is there anything that feels off when you scroll through it?"

---

Guide Boundaries

Guide	Owns
01-svelte-core	How Svelte components think
02-motion-scroll	Motion and scroll orchestration
03-media	Media elements and visual assets
04-imperative-integrations	Non-Svelte runtime systems
05-sveltekit-routing-data	App-level data flow and navigation
06-polish	Production quality
python-runner	Safe, reproducible execution of Python scripts with uv
structured-data-preprocessing-journalism	Provenance-preserving data loading, audit, reporting, and approved transformations
structured-data-analysis-journalism	Story-finding and question-driven analysis with documented stop points and defensible outputs
data-scrollytelling-journalism	Data-first chapter structure, presentation data shaping, and step-driven graph storytelling

Source Scope

These guides were derived from the Svelte and SvelteKit docs, especially sections on runes, bindings, transitions, motion, attachments, lifecycle hooks, load, page options, shallow routing, images, performance, accessibility, and $app/*.