Motion charts skill

Motion charts

Numbers that move and stay true: a total counting up to the exact figure, columns growing from zero with their labels riding the tops, a line drawing across the months, a donut sweeping to its shares, a note pointing at the peak. The whole film is one HTML file that can draw any moment from the time alone, so it previews in any browser, renders frame-exact, and loops without a seam. Every number in it is formatted from the data, and the data cites its source.

The skill folder is ${CLAUDE_SKILL_DIR}; the reference files call it <skill>. If the variable shows up literally or empty in your shell (you opened this file directly, as a subagent or from a copy), it is the folder that holds this SKILL.md: put that absolute path in every command below.

A film lives in the user's project at videos/<film>/ (BRIEF.md, DESIGN.md, src/film.html, fonts/, the built <film>.html, stills/, renders/).

Ground rules

• Every number comes from the data. FILM.data holds each dataset with its values, its format and the BRIEF.md Facts row it comes from; counters, chart labels and {refs} in text are formatted from it by the engine. A number typed into a title fails the critique unless the data holds it.
• Real data, sourced; demo data, labelled. Numbers come from the user's own data or the product's live pages, logged in BRIEF.md with where and when they were read. Invented numbers are for demos only, and the source line says so on screen. See reference/brief.md.
• Honest charts only. Bars start at zero; no truncated, broken, dual or log axes, no 3D, no legends; a donut has at most 5 slices and its parts make the whole; every mark is at least 3:1 on its background and distinguishable from its neighbours, also under colour-blindness simulation. See reference/data-design.md.
• Data moves on critically damped springs. ζ = 1 for anything bound to data, or a bar passing 100 on its way to 100 shows 108. Counters land exactly on the formatted value, in fixed digit slots that never jitter.
• A source line whenever a number is on screen, and every value landed in its scene's rest still.
• One finding a beat, four words a beat, one call to action.
• seek(t) is pure. No timers, Date, Math.random, state or CSS animation; seeded randomness only. Layout is measured once, after the fonts load.
• One file. Fonts embedded as base64; nothing loads over the network. The build enforces it.
• The loop is exact. In the default hold loop, frame 0 is the lockup at rest and equals the last frame: loopcheck reports a max diff of 0.
• Look before you ship. Numbers pass while frames look wrong; read the stills and the decoded frames, and every printed value against the brief.
• The user decides what leaves the machine. Get a yes before any commit, push or upload.

Workflow

0. Once per machine. node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" doctor checks Node 20+, playwright-core, a Chromium, ffmpeg with libx264, ffprobe, npm and tar, and prints the exact command for anything missing (usually npm install --prefix "${CLAUDE_SKILL_DIR}" --no-package-lock, or npm i -D playwright-core in the user's project). Re-run it until it says DOCTOR OK.
1. Brief and data intake. Name the video type first (a launch bumper, a feature highlight, a testimonial, an event promo...): reference/video-types.md gives each type its length, formats, beats and the styles that fit. Read the product's live site and get the numbers: the user's own export or report, or figures the live site states today. Ask at most one round of questions (the story, the numbers with their source and period, formats, duration, palette), or use the defaults: 1080 x 1080, 12 s, 60 fps, 120 BPM, muted, hold loop, brand colours from the site's CSS. The 1:1 film is the master; 9:16 (1080 x 1920) and 16:9 (1920 x 1080) are delivered when asked for, from the same file. Fill templates/BRIEF.md into videos/<film>/BRIEF.md: one Facts row per dataset, with its values, unit, period and source. With no data there is only a demo, labelled as one. See reference/brief.md.
2. Story pass. 3 to 5 beats, each one finding and the chart that shows it: a total counting up (the hook), a breakdown or a ranking, a trend or a share, the call to action. Title each chart with its finding in at most 4 words (OAT MILK LEADS., not MILK SHARE). Show the user the beats and proceed unless they object; when nobody can answer, write them into BRIEF.md and proceed. See reference/data-design.md.
3. Design spec. Fill templates/DESIGN.md into videos/<film>/DESIGN.md: canvas and grid, the data (every number, its format, its Facts row), palette roles with the chart colours measured, type roles, then every scene (chart box, axis, labels, grow timing, highlight and notes, transition) on the tempo grid, and the loop seam. Read reference/data-design.md, reference/engine.md and reference/springs.md.
4. Build and measure. Copy templates/film.html to videos/<film>/src/film.html and transcribe DESIGN.md into its FILM block, data first (edit nothing below it; the build copies the title, the background and the canvas size into the page head). Fetch the fonts, build, and read the measured layout:

   node "${CLAUDE_SKILL_DIR}/scripts/fonts.mjs" videos/<film>
   node "${CLAUDE_SKILL_DIR}/scripts/build.mjs" videos/<film>
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" layout videos/<film>    # datasets, sizes, plot geometry, label boxes
   

   Put text baselines on the 8 px grid from the reported cap heights, check the datasets it prints against BRIEF.md, then write the final numbers into DESIGN.md and FILM together. For each extra format, add a patch to FILM.formats: a taller chart and bigger type at 9:16, the title beside a wider plot at 16:9 (engine.md, Formats). See reference/fonts.md and reference/core.md.
5. Stills and critique. node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" stills videos/<film> runs the automated critique: the numbers (bound to data, sourced, on screen with their source, landed at rest, no free numbers), honest charts (zero baselines, axes, data springs, slices and wholes, colours, direct labels), and the picture (glyph coverage, words per beat, live area, collisions, contrast, palette roles, the loop, blank frames, composition), then the palette gate, and writes stills plus stills/contact.png. Read the contact sheet and the full-size stills; fix and repeat until it passes and looks right. Run it again with --format 9:16 or --format 16:9 for each other delivered format (stills in stills/9x16/, stills/16x9/). See reference/review.md.
6. Render and verify.

   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" loopcheck videos/<film>   # hold loop: every diff must be 0
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" render videos/<film>      # MP4, GIF, poster
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" verify videos/<film>      # ffprobe facts, tags, decoded pixels
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" mp4frames videos/<film>   # decoded review frames + PSNR
   

   Run loopcheck, render, verify and mp4frames once per delivered format, each with its --format flag (outputs renders/<film>-9x16.mp4, preview-9x16.gif, poster-9x16.png). Look at stills/mp4/contact.png and the growth, highlight and transition frames full size. Report the files, their sizes, the critique counts and the verify, loopcheck and mp4frames lines. See reference/render.md and reference/loops.md.

Pass criteria

• Every number on screen is formatted from FILM.data, every dataset cites a Facts row, and the source line is on screen whenever a number is.
• Bars and columns start at zero; every value sits inside its axis; a donut's parts make its whole; no legends, dual axes or 3D.
• Values bound to data move on ζ = 1 springs; labels count on their bar's own spring in fixed slots; every value has landed in its scene's rest still.
• One finding a beat, stated in at most 4 words; the accent on the mark the finding is about; something moves on every beat; transitions vary (circle, wipe, cut, overlap).
• Every mark at least 3:1 on its background, a chart's colours at least dE 15 apart (8 under CVD simulation); display type at least 3:1, labels and small print at least 4.5:1.
• Every label and mark inside the live area, baselines on the grid, no label colliding with a label or a mark.
• The composition passes at every delivered format, and each format looks designed for its frame: a taller chart and bigger type at 9:16, the title beside a wider plot at 16:9.
• Motion blur on every moving frame, one sample on still ones, never across a cut or a wipe's swap.
• The deliverable MP4 is H.264, yuv420p, BT.709-tagged in the stream, faststart, exactly DUR x FPS frames.

Known pitfalls

• A critically damped count shows its last digit late: about 1.4 s after COUNT starts for a 5-digit number (the table in engine.md). Start counts early in their scene, or the landed check fails.
• enter moves the element, grow moves the data. A chart with only enter shows its values from its first frame; a grow on an underdamped spring fails the critique.
• Labels are laid out in slots from the widest value they will show, and placed by their final value: during a count a centred number grows leftward from its final right edge.
• A face with proportional figures looks loose in fixed slots (a narrow 1 in a digit-wide slot). Inter and IBM Plex have tabular figures by default.
• A donut's centre counts its slice as the sweep crosses it: put that slice first, or the centre sits at 0 % while the others sweep.
• The source line types from the scene's first data (a chart's axis, a counter's entrance) and leaves when the last of its charts starts to leave; at a cut it starts with its cursor, and a scene that ends on a cut or a wipe keeps it to the end.
• A highlight cross-fades between two fills for about 0.15 s, and its accent frame is the landing. Keep the base fill a neutral, so the fade cannot pass through a third hue.
• A note's anchor rides its data point: a note that starts while its bar still grows swings its leader. Start notes after the chart lands.
• A retarget keeps one axis for both datasets, so a retarget to a much larger dataset leaves the first one's bars short. When the scales differ, cut to a new chart.
• In a hold loop nothing of the first scene may show at t 0, not even a typing cursor: its first entrance starts on a 16th after 0.
• At 9:16 a donut cannot simply grow: its side labels need room outside the ring. Move it off centre, away from its labels, or keep it the size it is.
• Negative numbers print with a true minus (U+2212). The template's faces have it in their Latin subsets; check the cmap if you change faces.