Cinematic Scroll

One sentence in. A cinematic, scroll-driven website out.

▶ Scroll the live site — five aesthetic worlds from one engine →

A free, MIT-licensed craft skill that gives any coding agent — Claude, Cursor, Hermes, OpenClaw — the taste to build cinematic, scroll-driven websites. Describe the aesthetic — palette, mood, references — and get a visual system, motion storyboard, pinned chapters, multi-depth parallax, 3D tilt, and full release pages art-directed to match. The motion is the constant · the look is yours · the agent is your choice. It's a skill, not a plugin — the craft travels with you across every agent.

New in v2.4.0 — a machine-readable design system under the hood. A DTCG token contract (design.md + tokens/), visual systems as one-file themes (swap one, or author your own), and a 9-component library (Mode A .html + Mode B .tsx) make output deterministic and gated, not improvised — hardened by an adversarial self-review (REVIEW.md). See Design system below.

Free for any use, personal or commercial (MIT). Actively developed — built from production work and shipped open source. Issues, PRs, and showcase submissions welcome — I collect what people build.

Built by Simone Leonelli · [email protected]

✦ Cinematic taste is now a number you can gate on

Cinematic Scroll isn't a prompt pack — it's a craft contract: plan the motion, build the scene, compile it to web and video, then run a doctor that catches cinematic slop before it ships. cinematic-doctor scores any build 0–100 across taste, performance, a11y, mobile, tokens, and 3D — and exits non-zero below threshold, so quality is CI-blockable, not a vibe.

npm run doctor -- examples/noir/index.html

It already scores the bundled examples (noir 87, luxe 88) and the 3D/WebXR flagship (100). The same scroll-choreography.json compiles to the website and its launch film — one choreography, two media.

Quality gate

node tools/cinematic-doctor/cli.mjs examples/luxe/index.html   # → score + per-category breakdown
npm run doctor -- examples/flagship/index.html                 # → 100

The doctor exits non-zero below 80, so you can wire it into CI and block builds that score under the bar. Its runtime twin, tools/page-proof/, opens the build in headless Chromium and returns console errors + scroll screenshots — contract and evidence:

npm run proof -- examples/noir/index.html

✦ Design system: one token contract → a living system → a component library

The look is the user's, but it's no longer improvised. A machine-readable design contract now drives every build:

• design.md + tokens/ — W3C DTCG design tokens (color, type, spacing, radii, and first-class motion tokens: the signature easing curves and §3 pacing rules as data). A zero-dependency pipeline emits CSS vars + typed TS; Mode A stays zero-build.
• Visual systems as one-file themes (themes/) — ready-made looks (Symmetric Monument, Clinical Noir, Storybook Geometry, Temporal Monument, Atmospheric Sublime, Warm Scrapbook, Naturalistic Drift, Brutalist Kinetic, Liquid Chrome, Botanical Editorial, Data Cinematic), each WCAG-AA contrast-checked — and any new look is one more theme file. Pick a look = swap one file.
• A named component library (components/ · component-grammar.md) — HeroParallax, PinnedReveal, DepthFigure, TiltCard, MorphBackground, HorizontalGallery, ScrubVideo, KineticHeadline, MagneticCursor — token-driven, both modes (Mode A .html + Mode B .tsx), each doctor-verified.

npm run tokens:check && npm run themes:check          # the contract is sound (tokens + 11 themes)
npm run verify -- components/mode-a/hero-parallax.html # one command: contract + doctor + runtime
npm test                                              # every gate — the same set CI runs

⚡ Real-3D flagships — start here (real WebGL, doctor 94–100)

The skill's most impactful builds, shown first: real-3D reference sites — scroll-driven three.js, no two sharing a technique (an asset-driven WebXR colonnade, a procedural particle galaxy, a raymarched volumetric sky, a refractive glass monolith, and scroll-scrubbed camera flythroughs through a sculpture gallery, an overgrown atrium, and a liquid-chrome vault). Each handles context-loss, caps devicePixelRatio, gates its loop on visibility, and falls back to a permanent poster — never a blank canvas. Open any live:

🌿 Verdant — Into the bloom → Scroll-scrubbed 3D walk — sterile concrete reclaimed by nature. A real rainforest sky lights the colonnade (image-based lighting), pollen drifts through god-rays, and instanced foliage streams past in layered 3D; move your cursor and the world leans with you. three.js · image-based light · drifting pollen — source in examples/jungle-flythrough.

△ AUREUS — Into the Vault → Scroll-scrubbed raymarch — a flight down a liquid-chrome corridor that reflects a real studio. Raymarched metaballs rendered every frame, sparks drifting past, the descent steered by your cursor and paced to your scroll. three.js · raymarch · real reflections — source in examples/aureus-flythrough.

🏛 Atelier Marne — A gallery you walk → Scroll-scrubbed 3D walk — a museum you walk by scrolling. Image-based light from a generated atrium floods the hall, six AI-painted canvases hang in their frames, and dust drifts through the beams; glassmorphic cards + a clickable chapter index fly the camera anywhere. three.js · HDRI lighting · hung art — source in examples/gallery-flythrough.

🎬 3D Flagship — Four Movements → React Three Fiber + WebXR. A scroll-driven camera rail through four 3D modalities (Object · World · Field · Figure): a fal.ai-generated hero artifact on its stage ring → an instanced colonnade hall → a pure-GLSL field → a rigged dancer samba-ing under a concert spotlight. Velocity-reactive rail dust, aurora curtains, volumetric shafts, bloom. three.js · R3F · WebXR · Draco/WebP · fal.ai — vanilla twin in examples/flagship.

⚡ Nexus Immersive — Spatial Computing → Tier C procedural shaders — no external model. A 15,000-particle galaxy field (custom GLSL), a 60×60 wave-equation displacement grid, and a Lorenz-inspired attractor. A WebXR gate shows Enter VR only when navigator.xr.isSessionSupported returns true; context-loss handled, rAF gated on visibility. three.js · GLSL · WebXR — source in examples/immersive.

☁ Aether — Make Weather → Tier C raymarched shader — a fullscreen volumetric cloudscape, zero assets. Every pixel marches an fbm density field with a second light-march toward the sun (self-shadowing + god-rays); scroll flies the camera down through the weather as the palette morphs dawn → cosmic. three.js · raymarching · GLSL · no assets — source in examples/volumetric-aether.

△ Obsidian — Refract It → Tier B transmission glass — a faceted monolith of real MeshPhysicalMaterial (transmission, IOR 1.5, thickness, iridescence) lit by a procedural PMREM environment, ACES tone mapping and bloom. Scroll cranes the camera around it while 60 orbiting shards keep the facets alive. three.js · transmission · PMREM · bloom — source in examples/crystalline-monolith.

✦ The worlds — a glimpse, not a ceiling

There is no fixed set of styles. Every site below is real and scrollable, built from the same motion grammar + token contract, then art-directed into a different world — hand-crafted looks and one-file themes side by side. Swap a theme file or describe a new brief, and the engine builds any aesthetic. These are starting points, not the limit.

✦ Reviewed & hardened

This release went through an adversarial self-review — independent passes over every component, gate script, token, and doc. It surfaced 50 issues; all critical/high and every doc/data inaccuracy are fixed and re-verified, the rest tracked. Full ledger: REVIEW.md.

The flagship in depth. examples/flagship/ is one cinematic scroll site, four chapters, four 3D modalities — vanilla Three.js (Mode A) plus React Three Fiber + WebXR (Mode B). The 3D stack decision tree lives in references/3d-stack.md (with references/webxr.md and asset hand-off in ASSETS-3D.md).

Both tiers now carry the full experience: the vanilla example ships the real Draco meshes (the generated chronometer, the colonnade hall, and the rigged dancer — samba out of the box) plus the FX layer (velocity-reactive rail dust, fake-volumetric shafts, breathing stage rings, FOV kick), degrading to designed procedural geometry offline. The Mode-B twin in the Next.js template (/flagship — templates/nextjs/FLAGSHIP.md) adds on top:

• Generate real 3D assets with one command. npm run generate:flagship runs a two-stage fal.ai pipeline per chapter: an art-directed concept image (fal-ai/nano-banana-2), then image→3D (fal-ai/trellis by default, fal-ai/hyper3d/rodin for high-detail heroes). Each mesh is auto-compressed in place (Draco geometry + WebP textures, ~10–13 MB raw → ~1–3 MB) and auto-normalized at load to chapter height with its base on the floor — arbitrary generated scales and offsets are safe, including rigged (skinned) models.
• The Figure dances out of the box. The template ships a Mixamo-rigged, animation-baked dancer (dancer.glb, ~0.8 MB Draco'd) with root motion stripped so the samba stays planted on its stage ring — no Blender, no Mixamo account, no manual rigging step.
• An immersive FX layer. A scroll-velocity-reactive GPU dust field spans the whole camera rail (travel feels like travel — motes swell and stream, the lens FOV kicks, then everything settles at each dwell), aurora light curtains flow overhead, fake-volumetric shafts rake the colonnade and spotlight the dancer, the hero artifact levitates with an orbiting comet glint, and chapters materialize on arrival through damped presence gates. Atmosphere morphs both fog color and density per chapter; a blurred mirror floor, bloom, chromatic aberration, and film grain finish the frame.
• The engineering contract holds. Every effect answers prefers-reduced-motion with a composed still frame, the mobile path cuts particle counts and skips heavy passes, the scroll-camera freezes while a WebXR session presents, and the swap from procedural placeholder to generated .glb is data, not code (one manifest line).

Get started — two paths

Pick how you want to build:

Mode A: Single scroll section — one runnable .html file, no build step, no keys. Perfect for a hero chapter or one-off section.
Mode B: Full release site — complete Next.js project, tested templates, optional AI image generation pipeline. Best for product launches and multi-chapter stories.

Install

Pick whichever channel fits your client. All four install the same skill.

Claude Code — plugin marketplace (recommended for Claude Code)

/plugin marketplace add MustBeSimo/cinematic-scroll-skill
/plugin install cinematic-scroll@mustbesimo

Installs as a namespaced plugin and stays updatable with /plugin marketplace update mustbesimo.

Any client — npx installer

npx cinematic-scroll-skill          # copies the skill into ~/.claude/skills/cinematic-scroll
npx cinematic-scroll-skill --dir .cursor/skills   # or a custom skills directory

Any client — git clone

git clone https://github.com/MustBeSimo/cinematic-scroll-skill ~/.claude/skills/cinematic-scroll

Registries

npx skills add MustBeSimo/cinematic-scroll-skill   # skills.sh

Also listed on agentskills.io (search "cinematic-scroll").

Platform-specific

Paths vary by client — see COMPATIBILITY.md for step-by-step instructions:

• Claude Desktop — Settings → Capabilities → Skills → Upload
• Cursor — drop into .cursor/skills/ (or npx cinematic-scroll-skill --dir .cursor/skills)
• Hermes Agent — hermes skills install MustBeSimo/cinematic-scroll-skill (repo form — pulls the full multi-file skill, including references/, templates/, and tools/), or git clone to ~/.hermes/skills/
• OpenClaw — via ClawHub, the OpenClaw skill registry: clawhub install cinematic-scroll (or openclaw skills install git:MustBeSimo/cinematic-scroll-skill@main)

Quick start

After installing, describe what you want to build in chat — see examples/PROMPTS.md for 20+ copy-paste examples across aesthetic worlds.

Live examples — a few worlds, in depth

A closer look at some of the worlds from the gallery above — single, build-free index.html files (GitHub-Pages-native) running the skill's Mode A grammar: vanilla JS on requestAnimationFrame with optional GSAP/ScrollTrigger enhancements, dependency-free core, progressively enhanced showcase beats (deferred GSAP + ScrollTrigger from CDN with vanilla fallback). They render fully with zero image files (CSS-only placeholders that upgrade when you add stills). Proof the look is a variable, not a default — and not a fixed set.

Same motion grammar; any aesthetic. The worlds above are different visual directions the skill can art-direct — change the copy, palette, and references, and the same engine produces any world you describe. The styling is infinite; the cinematic motion is the constant, and the look is whatever you ask for. (See the full gallery and the real-3D flagships — both above.)

Running locally

python3 -m http.server 8099   # then open /examples/renaissance/ · /studio/ · /noir/ · /luxe/ · /pop/

Under the motion, every chapter ships with:

| | | |---|---| | Cinematic depth | 5–7 parallax layers per chapter, perspective camera, dolly-back transitions | | Editorial type | Oversized titles with word-stagger / clip-path mask / letter-spacing-scrub reveals | | Atmosphere morphs | Backgrounds crossfade between chapter color-worlds as you scroll | | Image pipeline | Optional: fal.ai-generated heroes (FLUX.2, Nano Banana, Imagen); required: bring your own images or render CSS-only visuals. Generated assets remain subject to your input rights and model-provider terms — review output before commercial deployment. | | Bulletproof basics | Reduced-motion fallback, iOS video safety, mobile-stacked layout, transform/opacity-only core hot paths; optional GSAP showcase enhancements in selected examples; no WebGL required. Validate performance on target devices before production. |

✦ New: one choreography, two media

A single scroll-choreography.json now compiles to the website and its launch film — same beats, same easings, same depth choreography. Rebrand your site, and the video rebrands itself.

node compile-choreography.mjs scene.json --target web     # → GSAP ScrollTrigger page
node compile-choreography.mjs scene.json --target video   # → paused timeline for HyperFrames / Remotion
node compile-choreography.mjs scene.json --harness --out preview.html   # → watch it move, zero install
node compile-choreography.mjs scene.json --target hyperframes           # → render-ready composition → MP4

The web target is scroll-driven and responsive; the video target is a deterministic 16:9 timeline for HTML-to-video renderers — directed by FRAME.md, the brand spec that translates this design system for the frame. The --harness flag emits a self-contained preview HTML with play/scrub controls so you can watch any choreography in a plain browser.

Same DOM contract ([data-chapter] / [data-layer] / [data-title]) serves both targets. Full mapping table + Remotion adapter: scroll-choreography-compilation.md · mixing strategy (HyperFrames × Remotion): video/PIPELINE.md

Reference film projects — both stacks, ready to render:

| Film | Stack | Length | What it covers | |---|---|---|---| | video/ship-in-5/ | HyperFrames | 60s | the launch guide: install → prompt → compose → ship | | video/flagship-3d/ | HyperFrames | 60s | the 3D/WebXR flagship — built on real captures of the live route (hero frame, virtual-time scroll-through, concept→mesh, the spotlit dancer) | | video/doctor/ | HyperFrames | 45s | "Scored" — the cinematic-doctor film: the scan, the 0–100 score landing, the CI gate blocking a 64 and stamping an 87 PASS | | Promo + TwoMedia + Flagship3D + Doctor in video/ | Remotion | 24–30s each | the product promo, the "one choreography, two media" feature film, the flagship launch film built on the same live captures (npm run render:flagship), and the doctor quality-gate film (npm run render:doctor) |

Every HyperFrames film has a Remotion twin (and vice versa) — two renderers, one art direction, so you can A/B the stacks or pick per platform.

Quickstart

Mode A — instant scroll section

"Use cinematic-scroll to build a self-contained HTML pinned hero chapter for [YOUR BRAND]. Include a progress HUD."

You get one runnable .html file. Open it. Done.

Mode B — full release site

"Use cinematic-scroll to scaffold a complete Shopify-Editions-tier release page for [YOUR PRODUCT IN ONE LINE]. Demo mode first — do not require my fal.ai key. Copy all bundled templates verbatim. 8 chapters. Finish with the exact commands to run."

Then, in the scaffolded project:

npm install
npm run dev

Open http://localhost:3000 — a full 8-chapter cinematic page, CSS-only visuals, zero AI setup.

Want real generated chapter art? Add your own fal.ai key and run the command below. Generation cost varies by model and resolution — see MODELS.md and current fal.ai pricing before running a batch.

npm run setup        # interactive key wizard → writes .env.local
npm run generate     # generates all chapter heroes into public/generated/

Full walkthrough: examples/GETTING_STARTED.md. Model menu + costs: MODELS.md.

What's in the box

cinematic-scroll-skill/
├── SKILL.md                  # the agent contract (Mode A + Mode B). For Claude, not humans.
├── README.md                 # you are here
├── design.md                 # ✦ the design contract — token roles, motion, banned patterns
├── tokens/                   # ✦ DTCG design tokens (core · motion · semantic) + build/ (emitted CSS/TS)
├── themes/                   # ✦ visual systems as one-file theme overlays (author more)
├── components/               # ✦ named component library — Mode A .html + Mode B .tsx + manifest.json
├── evals/                    # ✦ triggering set + golden-output evals + runner
├── REVIEW.md                 # ✦ adversarial self-review ledger (50 findings + status)
├── COMPATIBILITY.md          # platform installation & verification (Claude, Cursor, Hermes, OpenClaw)
├── LICENSE                   # MIT
├── manifest.json             # skill metadata (free)
├── MODELS.md                 # fal.ai model menu, costs, when-to-use
├── ASSETS-3D.md              # 3D asset hand-off: generate → compress → normalize → manifest
├── compile-choreography.mjs  # ✦ scroll-choreography.json → page / film / preview
├── scroll-choreography.json  # the declarative choreography schema + example
├── FRAME.md                  # brand spec for video agents (the frame translation)
├── taste-guardrails.md       # banned patterns, cinematic vocabulary, pacing rules
├── references/               # scroll patterns · film archetypes · component grammar · design tokens · perf · 3d · webxr
├── tools/cinematic-doctor/   # ✦ the 0–100 quality gate (taste·perf·a11y·mobile·tokens·3D, CI-blockable)
├── tools/                    # ✦ check-tokens · check-themes · check-links · check-consistency · build-tokens · verify · skill-sync
├── video/                    # PIPELINE.md (HyperFrames × Remotion) + the film projects
│   ├── src/                  # Remotion: Promo · TwoMedia · Flagship3D · Doctor
│   ├── ship-in-5/            # HyperFrames: the 60s launch guide
│   ├── flagship-3d/          # HyperFrames: "Four Movements" (the 3D flagship film)
│   └── doctor/               # HyperFrames: "Scored" (the quality-gate film)
├── examples/
│   ├── PROMPTS.md            # 20+ trigger prompts across aesthetic worlds
│   ├── GETTING_STARTED.md    # fal.ai setup, troubleshooting, queue+webhook
│   ├── KNOWN_ISSUES.md       # QA log of real failure modes + fixes
│   ├── renaissance/          # Mode A example — warm classical editorial
│   ├── studio/               # Mode A example — brutalist creative-director portfolio
│   ├── noir/                 # Mode A example — signal clean / editorial sci-fi (VANTASCOPE)
│   ├── luxe/                 # Mode A example — quiet luxury (Maison Solenne)
│   ├── pop/                  # Mode A example — Gen-Z pop (BLOOM)
│   └── flagship/             # the 3D/WebXR flagship — four chapters, four 3D modalities
└── templates/nextjs/         # tested, copy-verbatim Next.js App Router project
    ├── app/ (+ /flagship route, api/fal/*, generate-edition-asset)
    ├── components/ (ChapterScene, EditionsPage, flagship/ — chapters + fx layer)
    ├── lib/ (editions-manifest, flagship-manifest, normalize-model, fal-*, use-lenis)
    ├── scripts/ (setup.mjs, generate-chapter-assets.mjs, generate-flagship-assets.mjs)
    └── package.json, tailwind.config.ts, tsconfig.json, FLAGSHIP.md, …

Peer dependencies (in the consuming app)

npm install choreo-3d framer-motion gsap @gsap/react lenis @fal-ai/client @fal-ai/server-proxy

The motion primitives target the choreo-3d package, with a built-in vanilla fallback (sticky + IntersectionObserver + rAF) for sandboxes where npm packages can't be installed — identical math, same keyframes.

On GSAP: as of the 2025 Webflow acquisition, GSAP is 100% free — every former Club plugin included (SplitText, ScrollSmoother, ScrollTrigger, MorphSVG…), commercial use too. The Next.js build (Mode B) uses ScrollTrigger + SplitText for pinning and title reveals; the standalone demos retain a vanilla rAF core with optional deferred GSAP enhancements in selected showcase beats (loaded from CDN with vanilla fallback). This means Mode A files run from file:// with zero build, and gracefully fall back to CSS-only rendering if the CDN is unavailable. For low-level GSAP help, pair this with the official greensock/gsap-skills — that skill teaches the GSAP API; this one teaches the cinematic system on top.

Originality & legal

The reference direction is Shopify Editions, used only as an art-direction benchmark — chaptered release storytelling. The skill never copies Shopify's assets, logos, copy, source, or exact compositions, and never bakes readable UI text into generated images or imitates a named living artist. Generated assets may be used subject to fal.ai, model-provider and input-rights terms. Review output before commercial deployment.

License

MIT © 2026 Simone Leonelli — see LICENSE.

Built something with it? I'd genuinely love to see it: [email protected]