For AI-assisted makers
Use this as a skill, not just a demo #
Install the Narrative Deck skill in your AI assistant, then ask it to use narrative-deck before building. The skill helps your agent choose the right story beats, place effects with restraint, and keep the page dependency-free.
Start here: Use
npx skills add aakatheeri/narrative-deck for supported agents. If your assistant does not support the installer, copy this repo’s skill/ folder into the skills, rules, or project-context location your tool uses. See the GitHub READMEfor install notes. Then prompt: “Use the narrative-deck skill to turn this material into a nine-beat interactive article.”
Before the effects
The Structural Frame #
Fifteen techniques are useless without a skeleton to hang them on. This is the beat sequence underneath a premium article — nine positions, each with a job. Click any beat to see what belongs there and which effects serve it.
Why this comes first: A hook's authority ends the moment it opens the loop. Everything after that is structure. Most web writing fails not at the opener but at beat four, where the reader's initial curiosity has been spent and nothing has replaced it.
—
—
Principle:—
Effect 01
Scroll-Triggered Reveal #
Elements stay invisible until they enter the viewport, then fade and rise into place. An IntersectionObserver watches each block and adds a class — no scroll listener, no jank.
Why it hooks: Movement at the edge of vision triggers an orienting response. The reader's scroll
causedthe reveal, creating a reward loop that pulls the thumb down again.
Panel one arrives first.
Panel two follows at 180 ms.
Panel three closes the sequence.
Effect 02
Sticky Scrollytelling #
A city map pins to the viewport while text panels scroll past it. Each panel pans, zooms, or labels the same map — the scroll becomes a guided investigation.
Why it hooks: The reader keeps one visual model in memory while each step adds meaning: first location, then focus, then evidence.
Step 01 — Whole city Start wide so the reader understands the shape of the place.
Step 02 — Neighborhood The map moves toward the station where the story begins.
Step 03 — Impact zone A red zone appears around the streets with repeated delays.
Step 04 — Evidence The final label connects the hotspot to reported disruption.
Effect 03
Hover Disclosure #
Detail lives one gesture away. Hover reveals hidden content without cluttering the default view.
Why it hooks: Curiosity is rewarded on demand. Density rises only for readers who want it.
Effect 04
“You Draw It” Canvas #
Drag across the blank half of the chart to predict the trend. Release, then reveal the truth.
Why it hooks: Commitment bias plus the generation effect. Once you've drawn a guess you have stakes, and the reveal lands emotionally.
Effect 05
Physics Field (Canvas) #
Orbs with a simple physics simulation respond to the cursor. The same engine can push body text aside in magazine-style layouts.
Why it hooks: Responsiveness implies aliveness. A surface that reacts feels authored for you specifically.
Effect 06
Forensic Annotation & Scrubber #
Pins teach the reader how to look. The timeline slider replays the decisive seconds.
Why it hooks: Detective structure. The reader becomes co-investigator; the conclusion is withheld until evidence is assembled.
Effect 07
Kinetic Type & Highlight Wipe #
Characters animate in sequence; a key phrase fills with colour as it scrolls into view.
Why it hooks: Typography stops being a container and becomes an actor. The eye follows motion before it reads meaning.
Attention is earned per scroll.
The strongest sentence gets a colour wipe instead of bold — slower, and therefore noticed.
Effect 08
Parallax Depth #
Six layers translate at different rates against the scroll. Distant layers barely move; near layers move most, which the brain reads as physical depth.
Why it hooks: Implied depth signals production value within the first second, justifying the reader's time investment before a word is read.
Six layers, six speeds
Depth 0.05 → 0.95
0px · scroll progress 0%
Effect 09
Color-Threaded Entities #
A colour introduced in prose reappears in every chart, map and timeline that follows. The reader builds a private visual vocabulary and never needs a legend.
Why it hooks: Each recurrence produces a small recognition reward. The technique operates continuously rather than as discrete moments of spectacle, which is what makes a page
feelauthored.
Three districts reported sharply different outcomes. Northfield recovered fastest, while Lakeside stalled by midyear. Eastgate never regained its baseline at all.
Effect 10
Binary Quiz Accumulator #
Twelve statements, one tap each. Lowering the cost of a single interaction is what lets you raise the number of interactions.
Why it hooks: Sunk-cost accumulation. By the fifth answer the reader has invested enough to want the result, and the progress bar makes that investment visible.
—
Effect 11
Turn-by-Turn Procedural Graphic #
One continuous action, decomposed into five inspectable phases. The reader can watch it run, or stop and interrogate any single stage.
Why it hooks: Expertise is invisible at full speed. Slowing a motion down and labelling its parts converts a spectator into someone who can
seewhat the athlete is doing — a genuine transfer of knowledge, not just spectacle.
Effect 12
AR Placeholder — Spatial Artifact Viewer #
A 3D object you inspect by tilting your phone or dragging on desktop. Annotation hotspots surface context when you rotate the artifact to face them.
Why it hooks: Embodiment. Scale and form become
feltrather than described — the reader's own movement does the explaining, which is the mechanism real AR exploits.
Effect 13
Before / After Comparison #
A draggable divider between two states of the same scene. The reader performs the comparison rather than being told the conclusion.
Why it hooks: Change is hard to perceive from two images side by side, but trivial when they occupy the same pixels. The reader's hand does the analysis.
—
Effect 14
Audio Waveform & Transcript Sync #
A scrubable waveform bound to a transcript. Clicking any line jumps the playhead; the active line highlights as it plays.
Why it hooks: It makes audio skimmable. Readers who would never sit through eight minutes will happily jump to the sentence that interests them — and often stay.
Effect 15
Dynamic Paywall Simulator #
The most consequential storytelling effect is invisible: a model deciding where in your reading journey the narrative gets interrupted. Adjust the reader profile and watch the meter move.
Why it hooks: Making a hidden system inspectable is itself a story. The reader discovers the cut point is a tuned variable, not a fixed rule.
8
—
—
—
Global