Cinematic Scroll

Cinematic Scroll

Reusable patterns + production templates for building cinematic, scroll-driven React pages: pinned chapters, multi-depth parallax, 3D mouse tilt, environment-morphing backgrounds, reduced-motion-safe degradation, and (optionally) a full Next.js release site with fal.ai-generated visuals.

This is v2.0 — built on a 5-phase pipeline that is adaptively gated (see "Match the gating to the ask" below). Every phase produces a reviewable artifact: the user approves each phase before the next when they want the process or the brief is ambiguous, and the agent runs straight through when handed a complete brief or asked for a result directly (still emitting every artifact). This replaces the v1.0 one-shot model with a process that consistently produces production-quality output.

Agent quickstart — route, act, verify

Read this section first; read the rest as the route demands. Three rules:

1 · Route the request. Match what the user asked for and go straight to work:

| Request shape | Do this | Read first | |---|---|---| | "a scroll section / hero / one-pager" | Mode A: one self-contained .html (GSAP + ScrollTrigger via pinned CDN + SRI). Start from the closest examples/* page. | Phase 4 Mode A rules · taste-guardrails.md | | "a release site / product launch / multi-chapter story" | Mode B: copy templates/nextjs/ verbatim, then art-direct. | Phase 4 Mode B rules · templates/nextjs/FLAGSHIP.md | | "3D / WebGL / WebXR / 'like the flagship'" | Mode A → adapt examples/flagship/ (vanilla three, manifest-driven GLBs, FX layer). Mode B → the /flagship route (templates/nextjs/FLAGSHIP.md). Generate real meshes: npm run generate:flagship -- --apply (needs FAL_KEY). | references/3d-stack.md · ASSETS-3D.md | | "a launch film / video of the site" | Compile the scroll choreography to a fixed-time timeline (Basic): node compile-choreography.mjs scene.json --target video. The full web→video render pipeline ships in Cinematic Scroll Studio. | scroll-choreography-compilation.md | | "score / review an existing URL's scroll experience" | Audit mode: analyze the user-supplied URL (only sites they own or are authorized to test) and score Pacing / Performance / Accessibility / Emotional Arc, then emit a remediation plan. | audit-mode.md | | "learn from / study / distill patterns from an existing URL" | Learn mode: study a user-authorized URL and distill reusable recipes (technique / visual system / archetype / taste rule) onto the learned shelf via the Pattern IR gate — never copying code/assets/brand. | learn-mode.md | | "audit / improve a page I'm building" | Run the doctor first, fix what it flags, re-run; pair with the verify orchestrator. | tools/cinematic-doctor/README.md · tools/verify/README.md | | "an immersive brand world / 'constant wow' / world-building / make it look like the reference" | Run Phase 1.5 Asset Direction before the storyboard — design the world premise, hero concept, motif system, material language, and per-asset sourcing; then clear the Wow Gate (reject generic before building). | references/asset-direction.md · references/wow-gate.md | | "Awwwards-tier / image distortion / kinetic type / custom cursor / preloader / page transitions" | The five second-generation techniques, each with its degrade contract; all five live in examples/atelier/. | references/awwwards-techniques.md |

1b · Speak the design contract. Before emitting any CSS/TS, resolve every color, type size, spacing value, easing curve, and pin height through a token — never a literal. The readable map is [design.md](design.md); the machine source is [tokens/](tokens/) (DTCG: core primitives, motion, semantic roles). Components/chapters reference semantic role vars only (--bg, --accent, --ease-reveal); a visual-system swap is one themes/*.theme.json. Verify the contract with npm run tokens:check. Full reference: references/design-tokens.md. Reusable, doctor-verified building blocks (HeroParallax, PinnedReveal, DepthFigure, TiltCard, MorphBackground, HorizontalGallery, ScrubVideo, KineticHeadline, MagneticCursor) live in references/component-grammar.md + components/ (Mode A html + Mode B tsx) — start from these instead of writing motion from scratch.

1c · Reuse what the skill has learned. Before building, scan the ## Learned additions pointer sections of references/scroll-patterns.md, references/visual-systems.md, references/film-archetypes.md, and taste-guardrails.md, and fetch any relevant references/learned//.md entry on demand (pointer-first, loaded only when relevant). These are distilled, original recipes the skill learned from authorized sites. To add to them, see learn-mode.md.

2 · Match the gating to the ask. The 5-phase pipeline below produces an artifact per phase. When the user wants the process (or the brief is genuinely ambiguous), gate each phase on their approval as written. When the user asked for a result ("build me…", one-shot, CI, or another agent invoked you), run the phases internally without pausing, still emit the artifacts (cinematic-audit.md, motion-storyboard.md, technical-spec.md, polish-report.md) as the audit trail, and replace human gates with the verify loop below. Never block an autonomous run waiting for approval the user can't give.

3 · Verify before you call it done — every time.

node tools/cinematic-doctor/cli.mjs .html   # 0–100; exits non-zero           # tools/page-proof — headless run +
                                        # console errors + scroll screenshots

page-proof opens the page in headless Chromium, scrolls it, collects every console error / uncaught exception / failed request, and writes screenshots at each depth (.page-proof/proof.json + shots). Exit 1 means runtime errors — fix and re-run. Add --fps on DOM pages to measure scroll smoothness (avg fps

• dropped-frame share — the §1 transform/opacity budget, measured, not

asserted). Needs playwright-core + any Chrome (--wait 8000 for WebGL).

Then LOOK at the shots — this step is not optional. You can read images: open every screenshot page-proof wrote and grade the frame like a director reviewing dailies, against taste-guardrails.md:

• Composition — is there a clear focal point at every depth, or dead/empty

frames mid-scroll? (A dwell with nothing composed in view is a failed shot.)

• Hierarchy — does the type read in order (eyebrow → display → body)?

Any title colliding with imagery or another overlay?

• Reveal state — are entrance animations finished or stuck half-way

(clipped masks, 0-opacity text that never arrived)?

• Canvas truth — for WebGL: is the scene actually rendering, or is it a

black/empty canvas behind healthy-looking DOM?

• Edges — stretched or wrongly-cropped media, horizontal overflow,

elements pinned off-screen.

Anything you would screenshot-and-complain-about as a user, fix and re-prove. A build is done when the doctor passes, proof exits 0, AND the shots would survive an art director's review.

Verification map — four surfaces, each answers a different question:

| Question | Use | Command | |---|---|---| | Is an existing URL's scroll experience any good? | audit-mode.md (4-dimension score + remediation) | agent-driven | | Does my static build clear the craft bar? | cinematic-doctor (taste/perf/a11y/mobile/tokens/3D) | npm run doctor -- | | Does it run without errors / jank? | page-proof (headless run, console, shots, fps) | npm run proof -- | | Prove a whole phase at once (contract + doctor + runtime + Mode B) | verify-build orchestrator | npm run verify -- |

The contract itself: npm run tokens:check · themes:check · links:check · evals:run, or all gates via npm test.

---

The aesthetic is the user's — the motion is yours

**This skill supplies the motion grammar, never a fixed look. The pinned chapters, parallax, tilt, title choreography, and morphing backgrounds are the constant; the visual world — palette, typography, imagery, mood — comes entirely from the user's brief. Derive the aesthetic from what they ask for (brand, references, palette, vibe, or a visual system from references/film-archetypes.md). If they haven't said, ask** or offer 2–3 distinct directions — never default to any one style. The same machinery must produce a brutalist black-on-white drop, a quiet-luxury launch, a neon Gen-Z page, a sci-fi noir reveal, an organic wellness story, or a Renaissance editorial. None is "the" style. The five public examples (examples/renaissance, examples/studio, examples/noir, examples/luxe, examples/pop) are different worlds from the same engine — proof the look is a variable, not a default.

---

Philosophy

1. Taste is non-negotiable

The difference between slop and craft is anti-convergence. This skill ships with taste-guardrails.md — 11 banned patterns, a cinematic vocabulary, pacing rules, and anti-convergence principles. These are the skill's default craft constraints (anti-slop quality, not a forced aesthetic or locale): the user's explicit preferences always win — palette, tone, intensity, language, or a minimal/static fallback are theirs to set. Absent such direction, an agent that skips these guardrails produces tasteless output regardless of prompt quality, so every generated file is checked against the banned-patterns list before delivery.

2. Process over prompt

A great prompt is not enough. The 5-phase gated pipeline ensures that auditing, planning, specifying, building, and polishing happen as discrete, reviewable steps. The user sees a cinematic-audit.md before any code is written. They approve a motion-storyboard.md before any animation is implemented. Process de-risks the output.

3. Film grammar over web patterns

Scroll is not "web design." It is digital cinematography. The cinematic vocabulary in taste-guardrails.md (Section 2) maps 12 film techniques to scroll equivalents — dolly zooms, whip pans, rack focus, tracking shots, crane shots. Every scroll behavior names the film technique it implements. This is how we produce cinema, not PowerPoint transitions.

4. Measurable quality

Every output has reviewable artifacts. Every phase has a decision gate. Every build is checked against performance-budget.md (Section 6, 11-point pre-launch checklist). Quality is not a feeling — it is a checklist.

---

The 5-Phase Pipeline

Each phase produces a reviewable .md artifact. Gating is adaptive (see the quickstart's "Match the gating to the ask"): when the user wants the process or the brief is ambiguous, the user reviews and approves each phase before the next; when the user asked for a direct result (a complete brief, one-shot, CI, or another agent invoked this skill), the agent runs the phases internally without pausing and still emits every artifact as the audit trail. The agent never silently drops a phase's artifact.

---

Phase 1: Cinematic Audit

Purpose: Analyze the brand/content, define the emotional arc, select the visual system, and establish the motion personality.

| | | |---|---| | Input | User's brief, brand materials (palette, logo, copy), reference sites, target audience, device context | | Output | cinematic-audit.md | | Decision gate | User approves the emotional arc and visual system before proceeding |

Agent instructions

1. Ask the user about their brand's motion personality if not provided:

• "What emotion should the first 3 seconds produce?"
• "Is your brand closer to a Symmetric Monument (meticulous, formal) or a Warm Scrapbook (intimate, playful)?"
• "Who is scrolling this — a curious visitor or a decision-maker?"

1. Select a visual system from references/film-archetypes.md.

Read the archetypes file (Section 1-7) and match the brief to ONE primary visual system. Document the choice in the audit with rationale. Never mix more than 2 visual systems; if hybridity is needed, choose one primary and one accent.

1. Define the emotional arc across the full scroll journey:

• Opening emotion (what the user feels at scroll position 0)
• Mid-journey turning point (where the narrative shifts)
• Closing emotion (what the user carries away)
• Pacing rhythm: glacial / medium / energetic / variable

1. Document:

• Brand motion personality (3-5 adjectives)
• Emotional arc definition (opening → midpoint → closing)
• Audience analysis (device split, technical sophistication, attention span)
• Device context (primary viewport, performance tier expectation)
• Accessibility requirements (reduced-motion needs, WCAG target)
• Visual system selection (primary + optional accent, with rationale)
• Color temperature progression across chapters (warm → cool → neutral)
• Typography strategy (display font + body font, from archetype)

Output: cinematic-audit.md

→ Full template: [references/artifact-templates.md](references/artifact-templates.md). Copy the cinematic-audit.md section and fill every field.

Phase 1.5: Asset Direction — the world before the layout

Purpose: Decide the physical world the brand lives in and where every visual comes from — so the build can't drift into a generic dark-landing-page. This is the module that makes wow reproducible instead of occasional. Required for any release · launch · immersive · premium · flagship · "wow" brief; skippable only for a single utilitarian section.

| | | |---|---| | Input | cinematic-audit.md | | Output | art-direction.md (world premise · hero concept · motif system · material/light language · per-asset sourcing · signature moment) | | Decision gate | The Wow Gate — Hero Concept Gate (hard pass/fail) + Wow Rubric (≥ 8/12). A failed concept is regenerated before any code is written; never build a generic hero because the prompt was thin. |

Read [references/asset-direction.md](references/asset-direction.md) (the five decisions + the coherence rule) and [references/wow-gate.md](references/wow-gate.md) (the gate). The storyboard (Phase 2) then makes every chapter carry ≥1 motif, and the polish phase (Phase 5) verifies the signature moment survived in the page-proof frames — paired with cinematic-doctor, which scores the executed contract. Doctor = "not slop"; Wow Gate = "actually memorable."

→ Artifact template: [references/artifact-templates.md](references/artifact-templates.md), the art-direction.md section.

Phase 2: Motion Storyboard

Purpose: Plan the scroll sequence — chapters, patterns, transitions, depth layers, timing, and mobile degradation.

| | | |---|---| | Input | cinematic-audit.md | | Output | motion-storyboard.md | | Decision gate | User approves the chapter structure and pattern choices before proceeding |

Agent instructions

1. Design a chapter breakdown of 5-8 chapters. Each chapter is one

pinned section with a distinct visual world. The total scroll distance should be 1500-3000vh for the full experience.

1. Select ONE pattern from references/scroll-patterns.md per chapter.

The 12 available patterns (Section 1-12) are:

• Pinned Hero, Scrubbed Timeline, Velocity-Reactive, Sticky Narrative,

Chaptered Release, Parallax Gallery, 3D Product Orbit, Editorial Longread, Data Story, Landing Sequence, Portfolio Reveal, Archive Explorer. Document the pattern choice and rationale for each chapter.

1. Ensure no adjacent chapters use the same pattern or transition type.

This is a hard rule from taste-guardrails.md Section 4.4. Alternate: fade → slide → scale → rotate → crossfade → wipe.

1. Configure depth layers per chapter following the selected pattern's

depth configuration. Reference taste-guardrails.md Section 4.3: never repeat a dept

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MustBeSimo
• Source: MustBeSimo/cinematic-scroll-skill
• License: MIT
• Homepage: https://mustbesimo.github.io/cinematic-scroll-skill/

Install and usage instructions live in the source repository linked above.