Motion Language
Inherits skills/00-house-rules/SKILL.md. The implementation is scripts/stingers.py; the
gallery that renders all of it is scripts/build_stinger_gallery.py.
The one distinction that matters
A scene explains. A stinger gestures.
| scene | stinger | |
|---|---|---|
| length | 8–15s | 2–4s |
| carries | an argument you must read | one idea you already heard |
| face | hidden or PiP | hidden — you cut TO it |
| how many | 3–6 in a 10-minute video | one every 20–40s |
| if you removed it | the point stops landing | the video gets flatter, not wrong |
Getting this backwards is the common failure. A three-item list with real content is a compare
scene; the same list as steps is decoration. If a viewer needs to read it, it is not a stinger.
Stingers are cut to, not laid over. They own the frame for their few seconds. A full-frame graphic with the speaker still visible behind it reads as a mistake, and 3 seconds without his face costs nothing.
The vocabulary
Five elements. Everything in the library is a combination of them, which is what makes unrelated animations read as one system.
| ground | Near-black with a soft radial lift. Never flat #000 — a true black frame reads as a dropout, not a design. |
| glass | Translucent fill ~4.5% ink, 1px border ~14%, radius 26. Depth comes from the border and an inner highlight, never a drop shadow on the card. |
| sheen | A low-angle specular sweep across a card as it settles. This is the signature move — it is what makes a flat rectangle read as a physical object. |
| path | Thin dashed curves at ~10% ink. Things travel along paths. Nothing teleports. |
| state | A row of small dots carrying system state. Colour change on that row says "and then it broke" without a word of copy. |
Stagger is 120–160ms. Under 100ms siblings read as one object; over 200ms the viewer starts waiting.
Every stinger holds its last frame. It is cut against speech, so ending on any frame after the payoff must be safe. Nothing loops; nothing ends on an empty stage.
The library
{ "kind": "converge", "from": "everything feeds into one place", "dur": 3.4,
"chips": ["skill.md", "prompt", "context", "tool", "rule", "doc"] }
| kind | the sentence it belongs under | dur |
|---|---|---|
converge | "All of this feeds into one place." Chips travel dashed paths into a glowing core; the state dots fill as it takes load. | 3.0–3.6 |
overload | "And then it stopped working." The same core cracks red. Shares converge's geometry so the two cut together as one story. | 2.4–3.0 |
steps | "There are three of these." Numbered glass cards, staggered, sheen on each. The most reusable and the most overused. | 2.6–3.2 |
swap | "This, not that." A is struck through and retires upward; B arrives beneath it. Both stay legible. | 3.0–3.6 |
countup | "It was forty-three percent." A number climbs, scale growing with the value, over a visible source line. | 2.6–3.4 |
beats | Three short phrases, percussive. Each gets a different entrance on one shared beat grid. | 2.4–3.2 |
surround | "You're buried in tools." Labelled chips ring a held centre, then close in. The centre never moves. | 3.2–4.0 |
photo | A found image, treated. Glass card, slow Ken Burns, caption, credit line. | 2.8–4.0 |
clip | The same card holding footage instead of a still. No Ken Burns — it already moves. | 2.4–3.0 |
Use them in composition.json exactly like a scene — same from / at / dur anchoring, same
hard error if the phrase does not resolve.
B-roll: the photo / clip stinger
Two treatments, and full picks between them. full is opt-in; omit it and you get the card.
full: true — B-ROLL | full: false — CITATION | |
|---|---|---|
| frame | full-bleed, no card | glass card, sheen, slow drift |
| text on frame | a lower third naming what the shot is | caption and credit line |
| source on frame | never | required |
| use for | footage and stills that carry a moment | a screenshot, a chart, a pricing page, a document |
B-roll is full screen and carries no source reference. Standing instruction from the human,
2026-08-14. It takes the whole frame the way B-roll does in every edit anyone has watched. The
only text permitted over it is a lower third saying what the shot is, never where it came
from. Attribution still happens — in the drop's _FINAL/ATTRIBUTION.md, which fetch_stock.py
writes at download time and no edit can skip. Pexels and Pixabay both make on-frame credit
optional, so the ledger satisfies the licence on its own and the frame stays clean.
This supersedes the paragraph that used to live here for B-roll, which said a full-bleed clip
"reads as a different video" and put everything in a card. That reasoning still holds for the
citation case and only for it: when the viewer is meant to read the asset as evidence you are
quoting, full: false and the source line goes back on the frame.
The builder still defaults to the card, and that is deliberate. Flipping the default would
silently re-treat every photo scene already written against it — drop-005's
working/stingers/plan.json among them — and a spec that rendered a card yesterday must render
the same card today. New work asks for "full": true; skills/executive-animator always does.
The one-word change in st_photo is all it takes if the card is ever retired outright.
One geometry note: full-bleed uses object-fit: cover, so give it a source that is already
16:9. A 2.19:1 crop shown full-frame loses 221px off each side, which is how a diagram ends up
with its first and last column sliced off while every gate reports a correct box.
One builder, two names. photo for a still, clip for footage; it branches on the file
extension, so the name only exists to make a spec readable. What actually changes:
photo | clip | |
|---|---|---|
| element | <img> | <video muted playsinline> with framework timing |
| Ken Burns | yes, 1.00 → 1.07 across the card | none |
Footage gets no Ken Burns. The clip supplies its own motion, and a scale ramp on top of real motion is precisely what makes stock read as stock. A still is motionless and needs the drift to stay alive; a clip does not.
// B-roll. Full screen, lower third says what it is, no source on the frame.
{ "kind": "clip", "from": "everything is moving at once", "dur": 3.0,
"src": "broll/cut-data-flow.mp4", "caption": "Everything moving at once" }
// Citation. A document the viewer reads as evidence, so the card and the credit come back.
{ "kind": "photo", "full": false, "from": "the pricing page changed", "dur": 3.2,
"src": "assets/pricing.png", "caption": "Anthropic pricing, Aug 2026",
"credit": "ANTHROPIC.COM · FETCHED 2026-08-13" }
The lower third sits at cap_left / cap_bottom, defaulting to 96 / 186 — landscape, which
clears youtube_long's 96 left and 132 bottom. A 9:16 caller must pass its own cap_bottom:
reels reserves 520 at the bottom and the karaoke band occupies y 1150-1400, so the landscape
default lands a caption under the progress bar. There is no pair that is right in both frames.
src resolves relative to the spec file and the builder copies it into the project's
assets/, so a path that is wrong fails loudly at build rather than as an empty card. Get both
from scripts/fetch_stock.py, which prints the block ready to paste.
Attribution is a ledger obligation, not a frame obligation. Every tier-3 asset gets its row
in the drop's _FINAL/ATTRIBUTION.md, written by fetch_stock.py at download time — that is
what config/broll-policy.md requires and it is not optional. Whether the credit also appears
on the frame is a design decision, and for B-roll the answer is no. On a citation card it stays,
renders at WCAG AA, and an attribution nobody can read is not an attribution.
Resolve every image in tier order first. A photo is tier 3: reach for it only when your own
footage and a tier-2 overlay both genuinely have nothing. The Ken Burns runs on the <img> inside
the clipping card, never on the card itself.
⚠ Do not copy the long third-party-video insert pattern. The reference this language came from
runs 50 seconds of someone else's interview footage. config/broll-policy.md forbids that
outright, and no amount of good motion design makes it ours. Photos with attribution are fine;
lifting half a video is not.
The wider menu — what to reach for when nothing above fits
Two upstream corpora exist and both are bigger than this library. Read from them rather than inventing motion.
hyperframes-animation skill — 48 atomic rules + 22 scene blueprints. Load it with
Skill(hyperframes-animation), then open rules-index.md and read the one rule you need at
rules/<name>.md. The house default is compose 2–4 atomic rules on one paused timeline; a
blueprint is for when you want a whole 4–5 phase shot.
The block registry — 373 installable blocks: npx hyperframes catalog --query "<concept>",
then npx hyperframes add <block>.
Situation → rule
Curated for a talking-head explainer. These are the rules that survive our format; the rest of the 48 mostly assume a product UI or a driven cursor we do not have.
| when the line is… | rule | why it fits |
|---|---|---|
| a number, a stat, a percentage | counting-dynamic-scale, stat-bars-and-fills | already implemented as countup; use the rules directly for bars, rings, star fills |
| a punchy list, rapid-fire | kinetic-beat-slam, waterfall-entry | implemented as beats; waterfall-entry is the gentler cascade |
| a definition or a term landing | gradient-text-sweep, depth-scatter-assemble | the glyphs never move in the first; the second assembles them from depth |
| "here's the shape of it" (a diagram) | svg-path-draw | the outline draws itself. Measure with getTotalLength() at setup |
| "it's surrounded / buried / connected" | radial-surround, avatar-cloud-network, orbit-3d-entry | implemented as surround; the other two add connection lines and 3D entry |
| one idea replacing another | scale-swap-transition, card-morph-anchor, morph-swap | implemented as swap; card-morph-anchor morphs the container itself |
| "look closer at this" | depth-of-field-blur, coordinate-target-zoom, viewport-change | rack focus, or a virtual camera on a .world wrapper |
| emphasis on a spoken word | asr-keyword-glow, css-marker-patterns | glow synced to word timestamps — we already have measured word times |
| a hard, percussive accent | chromatic-glitch, particle-burst, motion-blur-streak | use sparingly; one per video at most |
| a calm landing beat | titlecard-reveal (blueprint), ambient-glow-bloom | low motion is the payload, not a deficiency |
| any entrance at all | spring-pop-entrance | the canonical pop. When in doubt, this |
Blueprints worth knowing
Most of the 22 are product-launch ad shapes. Four map onto what we actually make:
kinetic-type-beats— the workhorse. The words carry the shot, no set, no surface.dataviz-countup— when the data carries the argument.comparison-split— two capabilities weighed at once (ourcomparescene is a flat cousin).titlecard-reveal— the breather beat, exactly one restrained move.
Skip cursor-ui-demo, device-surface-showcase, cta-morph-press, prompt-type-submit-generate
and the rest of the demo family unless we are actually showing a product UI. They are excellent
and they are not our format — a talking-head explainer that suddenly performs a fake app demo
reads as an ad.
The contract every upstream rule assumes
Worth knowing before you copy one in, because breaking these does not fail the check — it fails the render:
- ONE paused GSAP timeline on
window.__timelines. Never autoplay, never a second timeline. - Seek-safe both directions —
fromTowith explicit from-states, absolute values, never relative+=. State must be a pure function of timeline time. - Deterministic — no
Math.random(), noDate.now(). Index-derived pseudo-random only. Finite repeats, neverrepeat: -1. - Transforms and paint only.
width/height/top/lefttweens are forbidden; use scale/translate proxies or masks. - Group staggers capped so an arrival reads as one beat —
items × stagger ≤ ~0.5s. - Pre-calculate layout constants. Never derive a position at tween time; the renderer samples in parallel and the measurement desyncs.
Adding a new concept
- Search the registry first —
npx hyperframes catalog --query "<concept>". 373 blocks exist.radial-surround,morph-swap,split-tilt-cardsandparticle-image-revealare close cousins of things in this library and may be a better starting point than new code. - Build it from the five elements above. A concept that needs a sixth element is either a scene, or a sign the vocabulary needs a deliberate extension — not an exception.
- Add it to
KINDSinscripts/stingers.py. - Render the gallery and look at all of them together. That is the only way to tell whether a new one joined the family or just landed next to it.
python3 scripts/build_stinger_gallery.py <out> --photo <image>
cd <out> && npx hyperframes check
python3 scripts/probe_frames.py <out> --plan --grid sheet.png
Three defects this library already caught
Each passed a clean hyperframes check before anyone looked at a frame:
- GSAP cannot animate
::after. It resolves targets withquerySelector, which never returns a pseudo-element, so every sheen silently did nothing. The sheen is now a real child element (SHEEN_EL). If you add a card, put it inside. - GSAP replaces the whole transform on its first tween. A
transform:translateY(-50%)in the stylesheet is thrown away the momentyanimates, and the element jumps half its height. Centre in GSAP withyPercent, or centre in CSS — never half in each. - A shared centre is not a comparison.
swaporiginally faded A under B at one position; the struck-through headline bled through and collided with B's tag. Two things being compared need two places to be.
Checklist
- It is a gesture, not an argument — under 4 seconds
- It is the literal subject of the sentence under it, not decoration
- Built from the five elements; the sheen is a real element
- Holds its last frame safely
- B-roll is full-bleed with no source text on the frame; only a citation card carries a credit
- Full-bleed source is already 16:9, so
covercrops nothing - Every tier-3 asset has its row in
_FINAL/ATTRIBUTION.md, whatever the frame shows - Gallery rendered and every frame looked at