Docs / 06

Grades: casting a film's colour onto the page

How Cinematic UI casts a grade from a film's own frames: 14 sourced looks in two families, grade-from-stills measurement, grade.js and drift checks.

A cast film’s colour has to reach the page. Until it does, a “retro” site is one sepia overlay and a “neon” site is a pink-to-cyan gradient behind white type. Cinematic UI treats the grade as part of the director’s mechanism and commits to it in full: a timid grade is a different film.

What a grade is

The GRADE block in the treatment records where the colour comes from, the blacks, the highlights, the hues and the banned hues, the grain, and the look numbers. The same measurement feeds the page tokens (ground, ink, accent and chrome) and the pictures, so a retro film looks like that film’s print and a neon film is lit by its sources, not just tinted.

Fourteen looks in two families

references/grades.md holds fourteen sourced looks. Each gives what the cinematographer actually did, what to borrow, and what is costume. They are worked examples of the method, not a menu: any film can be researched and cast.

Grade from stills

The chain starts with research and ends with measurement. The agent gathers six to twelve reference stills of the cast sequence and runs:

node scripts/grade-from-stills.mjs refs/

It loads the stills in headless Chromium and writes grade.json and a contact sheet grade.jpg. The numbers include the palette with shares, black and white points, chroma range, shadow and highlight warmth, and a suggested look. The stills are reference material for analysis only; they never ship.

If there are no stills, the skill uses the look book’s starting values, marks the grade unmeasured and asks for stills in the asset call. Starting values in the look book are marked as translations to be replaced by measurement.

Applying it: grade.js

On DOM sites, kit/grade.js applies the grade to photographs, video and canvases through one SVG filter. createGrade({ look, spec }) takes the same parameters as the 3D stage’s stage.look (white balance, contrast, saturation, split-tone, lift, fade) and adds halation, bloom, grain, vignette, light leak and gate weave, plus a print’s lifted blacks. Type and controls stay unfiltered. Frames are reproducible from one time value, and reduced motion keeps the colour. kit/grade.html is the gallery.

Checking it: drift

node scripts/screening.mjs <dir> --grade grade.json (or the spec the page’s own grade.js publishes) adds grade flags to the screening report: grade-drift, grade-warmth, grade-black, grade-white, grade-saturation and grade-outlier. These catch frames that drift off the cast grade, crushed or lifted blacks, clipped whites, and saturation or warmth that does not match.

Refused defaults

Two uncast grades are on the lazy-cut list: warm paper with vermilion and dark ink, and cool grey with one blue or green accent. A grade that never reached the page, such as tidy hex tokens on white and ungraded pictures, is refused too.