Cinematic Scroll Landing

Cinematic Scroll Landing Pages

Methodology distilled from production builds (agency-grade studio site rebranded into an institutional LMS landing; a full-page book site for an LMS trial). It produces sites that feel like one continuous film, not a stack of sections.

The core system (always applies)

1. Research the reference, don't clone the stack. Award sites are

usually custom WebGL engines. Decompose the feel into reproducible mechanics: smooth scroll, parallax, distortion, looping. You get 90% of the feel with Lenis + GSAP + disciplined art direction.

1. One visual universe. The #1 cause of "sections feel unrelated" is

mixed-source imagery. Generate ALL imagery with ONE locked style template (see references/imagery-universe.md). Never mix stock photos with generated art. QA every batch on a contact sheet; crop generator watermarks (bottom ~5.5% is typical).

1. A shared atmosphere layer. One position: fixed layer behind all

content (radial gradient + slow-drifting fog/noise + faint watermark), mounted ONCE at layout level — never per-section. Content floats through one continuous world.

1. One transition grammar. Pick ONE reveal recipe and ONE dissolve

recipe and use them site-wide (e.g. clip-path inset(12%)→0 + scale 1.2→1; cross-dissolves with ~25vh overlap). Matched parallax on ALL media. Consistency, not variety, is what reads as cinematic.

1. Film grammar. Section labels as slates (SC.01 / HERO), mono folios,

accent progress ticks, preloader with 000→100 counter, film grain. For book-themed sites this becomes book grammar: folios, running heads, ribbon bookmark, colophon.

Set-piece menu (choose deliberately — each has costs)

| Set-piece | Use when | Do NOT use when | Cost | |---|---|---|---| | Endless loop (Lenis infinite: true) | Portfolio/brand reels meant for wandering | Conversion pages — they must END on a CTA; content users need to re-find | Kills scrollbar/footer wayfinding; disorienting | | Image-morph gallery (pinned) | Showcasing N related works/products | Text-heavy content | ~N×100vh scroll runway | | Flip-book section (pinned) | A chaptered feature story inside a longer page | Only 1–2 items to show | ~pages×100vh runway | | Full-page book (references/book-mode.md) | The whole page IS the story; trial/launch pages wanting max wow | Docs-like or frequently-revisited utility pages | Whole page pinned; content must fit page spreads; mobile needs a flat fallback | | Cross-dissolve scenes | Any multi-section cinematic page | — | Cheap; default choice |

Costs & trade-offs (read before choosing): infinite scroll destroys the scrollbar and footer as navigation; every pinned scene adds scroll runway the user must budget (report total "lap length"; keep home ≤ ~25 viewports); stacked blurred layers and unscoped will-change melt GPUs — prefer opacity overlays over animated filter; pinned scenes need keyboard/AT escape paths; a preloader IS your LCP (a 1.6s counter + wipes ≈ +2.3s to first content — choose that knowingly and keep observed LCP ≤ 2.5s). Skipping imagery unity (core #2) or the atmosphere layer (core #3) is what makes sections feel unrelated — those two are not optional.

Workflow

1. Teardown (if a reference URL is given): fetch HTML + screenshots +

web research; identify engine, type, palette, motion vocabulary. Write findings to info.md. Conclusion is almost always "custom WebGL — imitate the mechanics, not the stack".

1. Design doc first (palette ≤3 colors + accent, type pairing,

hairlines), then implement. Pick set-pieces from the menu ON PURPOSE. Decide imagery SHIP formats/sizes now (WebP q80-85 at ≤2× render size, og as JPEG) — retrofitting at deploy time churns manifest + tests.

1. Budget scroll length: each pinned scene costs viewports. Tell the

user the total.

1. Verify visually (NON-NEGOTIABLE): serve the build, screenshot at

multiple scroll depths — hero, each set-piece mid-state, transitions, ending. Static builds of cinematic sites ALWAYS have at least one bug you can't see in code.

1. Deep-link test: hard-load nested routes and hash anchors.
2. Deploy, then verify the LIVE URL the same way (see checklist).

First-run setup (new machine or new user)

Install needs nothing beyond copying the files. On FIRST use, run python scripts/check_setup.py and show the user the gap report, then offer to close gaps — with their approval, never silently. The only credential is an image-gen key (free at https://aistudio.google.com/apikey; stored wherever the user's image tool expects, e.g. ~/.banana/api_key.txt — or skip if the session has an image-gen MCP/skill). Deploy auth (npx vercel login, gh auth login) is the user's own interactive step — hand them the command. Missing pieces never block design/build work; each matters only when its workflow step arrives.

Gotchas (each cost real time — check them all)

• Vite base: './' breaks deep links. Relative asset URLs 404 the JS

bundle on hard-load of nested routes → blank page. Use base: '/' (or the deployment subpath, e.g. /repo-name/ for GitHub Pages).

• Pinned sections + loops: pins live INSIDE loop content;

atmosphere/HUD are global. Outros go inside the pin timeline's tail.

• GSAP filter clobbers Tailwind filter classes: animate filters on a

wrapper div, never on the same element as Tailwind filter utilities — better, avoid animated filters entirely (opacity overlays composite cheaper).

• Generated images ship watermarks: contact-sheet every batch, crop

bottom ~5.5%.

• "Missing images" is often logical, not 404s: audit data-level wiring

(per-item image fields), not just file existence (scripts/audit_images.py).

• Mobile + reduced-motion: unpin everything; stacked fades. Gate with

gsap.matchMedia. No strobing (WCAG 2.3.1: any flash < 3/sec); pinned scenes must not trap keyboard focus; preloaders resolve instantly under reduced-motion and always carry a failsafe timeout.

• External credentials: probe capabilities before use (list what the

token can actually do before depending on it).

• A stopped Lenis silently ignores scrollTo: preloaders stop Lenis,

so programmatic jumps (hash deep-links) need { force: true }.

• Verification tooling: puppeteer's networkidle0 never fires on hosts

with keepalive connections (e.g. Vercel) — use load + a settle sleep. Local antivirus page-injection (e.g. Kaspersky) skews simulated Lighthouse scores; judge by observed FCP/LCP.

• Unreliable filesystems: if your environment's FS is flaky, verify

every git ref update immediately after making it.

Bundled resources

• references/motion-recipes.md — copy-paste GSAP/Lenis code: Lenis

infinite loop, morph gallery, flip-book section, cross-dissolves, velocity marquee, preloader.

• references/book-mode.md — full-page book sites: sheet model, z-index

choreography, timeline math, flat fallback.

• references/imagery-universe.md — locked style template, per-item

prompts, generation ops probes, contact-sheet QA + watermark crop, ship-size discipline.

• references/verification-harness.md — screenshot/console/Lighthouse

verification when browser tooling misbehaves: probe order, puppeteer-core fallback harness, binary-deploy CLI-vs-MCP probe.

• scripts/audit_images.py — image refs vs public/ (missing + unused +

shared-generic wiring smells).

• scripts/check_setup.py — first-run environment gap report (stdlib only).

Delivery checklist

• [ ] npm run build passes
• [ ] Screenshots at ≥5 scroll depths reviewed (local)
• [ ] Deep link / hash-anchor hard-loads render (not blank)
• [ ] All imagery passes contact-sheet review (one universe, no watermarks)
• [ ] Reduced-motion + mobile fallbacks render ALL content
• [ ] Scroll-length budget reported to user
• [ ] og/meta/favicon present
• [ ] Deployed URL smoke-tested: re-screenshot hero, one mid-set-piece,

ending; hash deep-link hard-load

• [ ] Quick Lighthouse pass (perf + a11y sanity)
• [ ] Demo copy contains no real institutions/people; credits are

nominative only

Source & license

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

• Author: kash-123
• Source: kash-123/cinematic-scroll-landing
• License: MIT
• Homepage: https://codex-academy-five.vercel.app

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