_{Every image above is a verify capture, taken by driving a real mouse wheel through a deck. Every picture inside the decks is a vector infographic drawn by a script. Nothing here is a mockup. Click a capture to open the live deck.}

One-minute demo

_{Full 59-second trailer: docs/demo.mp4 (1080p). Every shot is a real deck driven by real wheel events; the score is synthesised in ffmpeg. Regenerate with tools/demo/.}

Live examples

Four decks, four concepts, all generated and gate-verified by the skill. Open one and scroll, or press →.

Gallery of all four: https://gongnyang.github.io/awesome-html-scrolline-deck/ — rebuilt by GitHub Pages on every push (scripts/site/build-examples.mjs). Each deck folder has a README with its storyboard and the scripts that draw its assets; all figures are sample data.

What this is

A slide deck cuts. A scrollytelling deck does not — each scene is pinned to the viewport while the wheel drives its progress from 0 to 1, so motion is continuous and the presenter controls the pace by scrolling. Scrolline Deck is:

• A Claude Code skill (SKILL.md) that takes a topic and an outline and authors the deck for you.
• A CLI (scripts/cli.mjs) that scaffolds a Vite project, adds scenes from 12 templates, cuts frame sequences, and runs the gates.
• An engine (engine/) built on GSAP ScrollTrigger and Lenis, copied into each generated project so the deck keeps working after you stop using the tool.
• Ten gates (G1–G10, plus a schema check) that fail with a non-zero exit code. Six of them drive a real browser with real wheel events.

Output is a static HTML bundle you run locally or host anywhere. Deployment is out of scope on purpose.

Install

git clone https://github.com/gongnyang/awesome-html-scrolline-deck.git
cd awesome-html-scrolline-deck
npm install

To use it as a Claude Code skill, symlink the repo into your skills directory:

ln -s "$(pwd)" ~/.claude/skills/scrolline-deck

Then ask Claude for "a scrollytelling deck about X" and it will follow SKILL.md.

Requirements. Node ≥ 20. qrcode is the only hard dependency. Playwright is optional — without it the browser gates report skipped and exit 0. ffmpeg is needed only for scrolline frames.

Quickstart

# 1. scaffold
node scripts/cli.mjs init my-deck --title "How we ship" --style dark

# 2. add scenes (one per storyboard row; never repeat a technique back to back)
node scripts/cli.mjs add frame-scrub-hero    --id 01-hero    --kicker "2026" --title "How we ship"
node scripts/cli.mjs add horizontal-gallery  --id 02-work    --kicker "Work" --title "Six things we shipped"
node scripts/cli.mjs add closing-qr          --id 03-closing --kicker "Next" --title "Come build with us" --url https://example.com

# 3. run it
cd my-deck && npm install && npm run dev

# 4. gate it
node ../scripts/cli.mjs check .
node ../scripts/cli.mjs verify .     # writes qa/<id>-{30,55,85}.jpg

Read the three captures per scene: 30% should be mid-entrance, 55% should be the finished frame you talk over, 85% should be mid-exit. If 55% is not a frame you would be happy to stand in front of, the choreography is wrong, not the capture.

The twelve techniques

references/techniques.md is the canonical list; the numbers above track it.

deck.json

The whole deck is one data file. Scene folders carry the motion; this carries the meaning.

{
  "title": "Scrolline Deck",
  "lang": "en",
  "presenter": { "name": "gongnyang", "autoDurationSec": 180 },
  "theme": { "style": "dark", "accent": "#5e6ad2" },
  "scenes": [
    {
      "id": "01-hero",                    // must equal the src/scenes/<id>/ folder name
      "order": 1,
      "technique": "frame-scrub-hero",
      "pinVh": 260,                       // pin distance as a % of viewport height
      "pin": true,
      "assets": {
        "frames": "/frames/hero/f_%03d.jpg",
        "count": 120,
        "critical": [1, 30, 60, 90, 120], // decoded before the scene is allowed to start
        "poster": "/frames/hero/poster.jpg"
      },
      "copy": { "kicker": "2026", "title": "How we ship", "lines": ["One line, maybe two."] },
      "notes": "Required. Shown in the N panel while you present.",
      "fallback": "Poster still plus a faded-in title, for reduced motion."
    }
  ]
}

Full schema: references/deck.schema.json.

Gates

check is static and needs no browser. verify drives Chromium with real wheel events — it never calls scrollTo, because a deck that only works when you teleport to a scroll position is a deck that breaks under a real wheel.

Without Playwright installed, verify prints how to install it, reports skipped: true, and exits 0 so CI stays honest instead of green-by-accident.

Presenting

Build with npm run build && npm run preview, and run verify once on the machine that will actually be on stage.

Project structure

awesome-html-scrolline-deck/
├─ SKILL.md              Claude Code router: principles, workflow, technique picker
├─ engine/               runtime copied into every generated deck (no Vite API)
├─ templates/project/    Vite scaffold: index.html, tokens.css, data/deck.json
├─ templates/scenes/     12 technique templates (scene.html/css/js + template.json)
├─ references/           contract, schema, techniques, choreography, design, pitfalls
├─ scripts/              cli.mjs and cmd/ + gates/ + lib/
├─ examples/              four sample decks (sample-deck, product-launch, annual-report, city-guide)
├─ tests/                node --test: gate units, bad-* fixtures, build smoke
└─ book/                 the companion handbook (Korean, PDF in docs/)

Handbook

「스크롤로 발표하라」 (Korean, 46 pages, PDF in docs/) — a practical guide for presenters, not developers: what a scrollytelling deck is, the enter/hold/exit grammar, the one-table storyboard, how to ask Claude Code for the deck, presenting keys and rehearsal, and a teardown of a real 12-scene seminar deck.

Contributing

Issues and pull requests are welcome. A new scene technique needs four files under templates/scenes/<technique>/ — scene.html, scene.css, scene.js, template.json — plus a row in references/techniques.md and a passing node --test. Keep colours in tokens, keep every timeline at or under 1, and keep the boxes out.

License

MIT. See LICENSE.

Credits

Extracted from the twelve-scene cinema deck built for the FastCampus "ChatGPT Astra" seminar — https://fc-astra-site.vercel.app/deck/. That deck is where the pin-unit bug, the smooth-scroll prevent exception and the CSS-variable interpolation failure were all found the hard way; the gates in this repo exist so you do not have to find them again.

Built with GSAP ScrollTrigger, Lenis and Vite.