Docs / 09

The kit: files and what each does

Every file in the Cinematic UI kit, from reel.js scroll scenes and designed cuts to grade.js, type-fx.js, plane.js and the app-mode rig, and what each needs.

kit/ is infrastructure with no look of its own. Its lens and print effects all start at zero and nothing in it is mandatory: two sites built on it should share no visible trait. Copy the files you need into the project, and copy them fresh at the start of each production, because copies go stale.

Only reel.js and reel.css are needed for a site. The 3D stage is one medium among several.

File	What it does	Needs
`reel.js`, `reel.css`	The playhead. `[data-scene]` sections with pinned frames; each scene gets `enter`, `main` and `exit` clips on one master GSAP timeline scrubbed by scroll. Designed cuts via `data-cut`. Reduced-motion stills. Any frame reproducible from one number	GSAP
`looks.js`	The lab for media other than photoreal: ink wash, pencil sketch, pixel, halftone / riso and CRT looks, cel materials and outlines, liquid and gradient plates, layered 2.5D image planes, hand-drawn line boil for DOM and SVG	three, `stage.js` (except `boil`)
`stage.js`	The sound stage for 3D or canvas work: HDR Three.js pipeline, image-based studio lighting, a tweenable camera rig and colour look, optional bloom and depth of field, quality tiers, WebGL fallback	three
`props.js`	The prop shop for photoreal sets: seamless backdrop, procedural surface maps, lathed forms, PBR material starting points, dust	three, `stage.js`
`type-fx.js`, `type-fx.html`	The type department: forty-four text performances in families (impact, flow, 3D, switch, style, and award moves). Each frame is a pure function of progress and time, real text stays in the DOM. The HTML file is the gallery	nothing
`grade.js`, `grade.html`	The colour grade for DOM sites, with the same parameters as the 3D stage’s look plus halation, grain, vignette, light leak and gate weave. The HTML file is the gallery	nothing
`plane.js`	The UI plane camera for scenes whose cast is an interface: live DOM under CSS perspective, shot presets from extreme macro to wide, DOM depth of field and rack focus without WebGL, a shot audit	GSAP (for some features)
`site-dom.html`	Grey animatic of a site with no canvas: type, flat shapes, an image slot. Start here for graphic, typographic, drawn or photographed films	`reel.js`
`site.html`	Grey animatic of a site on the 3D stage	all of the above
`app.js`	App mode’s rig: router with state in the URL, screening states, frozen clock, shortcuts, row navigation, drawer, command palette, undo toasts	nothing
`fixtures.js`	Seeded stand-in data with real shape	nothing
`app-shell.html`	Grey animatic of an app with all eight states. Start here for app mode	`app.js`, `fixtures.js`

Site mode in a few lines

<main>
  <section data-scene="arrival" data-still="0.6" style="--length: 250"><div class="frame">...</div></section>
  <section data-scene="turn" data-cut style="--cut: 100; --length: 300"><div class="frame">...</div></section>
  <section data-scene="plans" data-flow><div class="frame">...</div></section>
</main>

Markup	Meaning
`data-scene="name"`	A scene; the name is the handle for `reel.scene()` and for screening
`--length: 250`	Scroll length in vh; the frame is pinned for `length - 100`
`.frame`	The shot: sticky, one viewport tall, `overflow: clip`
`data-flow`	A reading scene, exactly as tall as its content, not pinned
`data-cut` with `--cut: 100`	A designed cut: this frame is pinned on top of the previous one for `--cut` vh
`data-still="0.6"`	Where the money frame is, which is also the reduced-motion pose
`data-hold`	Marks a scene of deliberate stillness so screening does not flag a dead hold

Things to know

Pages must be served over HTTP; ES modules do not load from file://. Use a server that honours byte-range requests (npx serve, Vite, any real dev server). Without ranges browsers cannot seek video. python -m http.server does not support them.
The animatics were verified with three 0.186.1, GSAP 3.15.0 and Lenis 1.3.26. Pin versions and screen again after upgrading.
Never put overflow: hidden on an ancestor of a .frame, because it breaks sticky; use overflow: clip.
Other stacks are fine. In React, Next or Astro keep the model (scenes with pinned frames, one scrubbed timeline, real DOM copy, any frame reproducible) and port the kit’s ideas rather than its files.

Read kit/README.md before using the kit; it lists the API and the handful of rules that keep frames deterministic.