Cinematic Web

Build live Next.js scroll-motion cinematic sites.

Skill metadata

Source	Bundled (installed by default)
Path	skills/web-development/cinematic-web
Version	1.0.0
Author	VibeOS
License	MIT
Platforms	linux, macos, windows
Tags	nextjs, scroll, gsap, lenis, motion, cinematic, web, landing
Related skills	internet-starter, design-to-code-loop, browser-e2e, site-page-analyze, site-map-crawl, large-admin-ia

Reference: full SKILL.md

info

The following is the complete skill definition that VibeOS loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Cinematic Web Skill

Build live, interactive cinematic marketing/landing sites: scroll-driven chapters, pinned heroes, and parallax layers that run in the browser.

Not HyperFrames. The optional skill hyperframes turns HTML/GSAP into an MP4/WebM video. This skill ships a live Next.js App Router site users scroll. Do not route video-render requests here.

When to Use

• User wants a scroll-story, product launch, or cinematic landing (interactive)
• Pin/scrub hero, sticky chapters, layered parallax — not a card dashboard
• After internet-starter (Next) or when polishing an existing App Router app
• Brand/tokens via design-to-code-loop; verify with browser-e2e

Prerequisites

• Node.js 20.9+ and npm (required by the starter's Next.js 16 line)
• Next.js App Router + TypeScript + Tailwind target (or scaffold first)
• Optional: Lenis, GSAP + ScrollTrigger, Framer Motion for UI micro only
• Browser tools for verify: browser_navigate, browser_snapshot

How to Run

1. Audit an existing project before adding motion: python3 scripts/motion_inventory.py <project> --format markdown from this skill directory. Use repeated --source arguments to narrow large monorepos.
2. Scaffold or open a Next App Router app (internet-starter / terminal + npm).
3. Add Lenis (smooth scroll) + GSAP ScrollTrigger; optional Framer Motion for small UI transitions — not the scroll timeline.
4. Define motion tokens in CSS: --motion-duration-*, --motion-ease-*.
5. Implement sections from references/motion-recipes.md (hero pin, sticky chapter, parallax, reduced-motion fallback).
6. Honor prefers-reduced-motion: shorten or disable scrub/pin; keep layout.
7. terminal: npm run dev → browser_navigate + browser_snapshot smoke.
8. Re-run the inventory with --fail-on-risk; review every candidate before using it as a gate because cleanup may belong to a shared runtime.
9. Run Creative Studio asset_manifest.py with the starter's design/asset-policy.json; record provenance and responsive/fallback links.
10. Capture normal and reduced-motion frames at 0/25/50/75/100 percent for Chromium, Firefox, WebKit, and a mobile DPR 2 viewport. Pass --expect-normal-registry and --expect-normal-triggers so responsive scene policy is a hard gate.
11. Run mobile DPR 2 again with --performance-profile low-end; review frame p95/max gap, slow-frame ratio, estimated drops, long tasks, DCL, and load.
12. Run scripts/mobile_device_lab.py discover --require-physical any. Validate the physical iOS/Android evidence against design/device-lab-policy.json; never count a simulator as a physical pass.
13. Polish brand with design-to-code-loop; avoid purple-glow AI slop.

If paths are unknown: search_files for cinematic-web/.

Quick Reference

Piece	Role
Next.js App Router + TS + Tailwind	App shell
Lenis	Smooth scroll (scroll-driven sites)
GSAP + ScrollTrigger	Pin, scrub, chapter timelines
Framer Motion (optional)	UI micro only (menus, presence)
CSS --motion-*	Duration/easing tokens
scripts/motion_inventory.py	Deterministic engine, lifecycle, and asset audit
scripts/temporal_capture.mjs	Cross-browser temporal, payload, and runtime gates
scripts/mobile_device_lab.py	Hashed device discovery and physical evidence gate
Creative Studio asset_manifest.py	Dimensions, hashes, provenance, and asset budgets
references/motion-recipes.md	Pin, sticky, parallax, a11y

Do	Don't
Animate transform / opacity	Animate width / height / top / left
One hero plane + brand + CTA	Card stacks / dashboard hero
Live interactive site	HyperFrames MP4 pipeline

Procedure

1. Scope — Confirm deliverable is a live site, not rendered video. If the user asks for MP4 from GSAP/HTML, hand off to optional hyperframes.
2. Shell — App Router layout, global CSS with motion tokens, Tailwind.
3. Scroll stack — Wire Lenis → document; register GSAP ScrollTrigger once (client component / effect). Kill triggers on unmount.
4. Composition — First viewport: brand, one headline, one support line, one CTA group, one full-bleed visual plane. No hero cards, emoji stickers, or stat strips.
5. Chapters — Sticky or pinned sections with scrubbed progress; keep one job per section (headline + short support).
6. Parallax — Layer translateY/scale on transform only; clamp speeds.
7. Reduced motion — Media query / matchMedia: static or fade-in only; no scrub dependence for content meaning.
8. Verify — Dev server via terminal; browser_navigate home; snapshot hero + mid-scroll chapter; check no layout jump on reduced-motion path.
9. Audit — Save JSON or Markdown inventory; inspect RAF, GSAP, Lenis, Three.js, listener cleanup, reduced-motion coverage, and largest assets.
10. Assets — Keep generated facts separate from authored metadata; require responsive hero/full-bleed variants and static fallbacks for heavy runtimes.
11. Temporal QA — Capture both motion modes and desktop/mobile viewports; fail on page/console errors, unloaded fonts, horizontal overflow, excess RAF handles, wrong registry/trigger counts, or active reduced-motion runtimes.
12. Low-end lab — Run the named Chromium CPU x4/fast-3g profile. Do not present CDP throttling as evidence from a physical phone.
13. Physical lab — Require a connected physical device, ten-minute touch session, orientation/background cycles, artifact hashes, and explicit support status for touch, frames, memory, and thermal telemetry.

Pitfalls

• Wrong skill — HyperFrames = video encode; this skill = live Next scroll.
• Layout thrash — Never drive scroll with width/height/top/left.
• AI slop look — No purple gradients, glow orbs, emoji decoration, or multi-card hero dashboards.
• Double smooth-scroll — Don't stack native CSS scroll-smooth with Lenis without testing; prefer one owner.
• SSR traps — GSAP/Lenis are client-only; guard window / use "use client".
• Meaning in motion — Content must remain readable with motion off.

Verification

1. npm run dev (or project script) succeeds in terminal.
2. browser_navigate → local URL; browser_snapshot shows brand + hero CTA.
3. Scroll mid-page; snapshot confirms chapter/sticky content (not blank).
4. With reduced-motion (OS or emulated), page still readable; no broken pin.
5. Optional: site-page-analyze on / for SEO basics after motion lands.
6. temporal-report.json has no violations and includes the requested frame sequence for normal and reduced-motion contexts.
7. documentFontsStatus is loaded, horizontalOverflowPx is zero, and the mobile registry contains only scenes whose policy is full.
8. Chromium reports long-task/CLS budgets; engines without those observer entry types record supported: false rather than a synthetic zero measurement.
9. The low-end report meets frame p95, max gap, slow-ratio, estimated-drop, navigation, and startup long-task budgets after the scene readiness gate.
10. The device evidence validator rejects simulators, disconnected device hashes, short sessions, missing artifacts, and unsupported measurements without a reason.