# Narrative Deck – AI Agent skill for creating interactive web stories

> Source: <https://aakatheeri.github.io/narrative-deck/>
> Published: 2026-10-23 22:18:39+00:00

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 README](https://github.com/aakatheeri/narrative-deck)for 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

*caused*the 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

*feel*authored.

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

*see*what 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

*felt*rather 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