Communitygithub.com

motion-language

Shows an agent how to plan, build, or cut "motion language" so the concrete output is usable copy or a script. The procedure moves through Motion Language, The one distinction that matters, The vocabulary. Use it when a new assignment calls for this craft.

What is motion-language?

motion-language is a Claude Code agent skill that shows an agent how to plan, build, or cut "motion language" so the concrete output is usable copy or a script. The procedure moves through Motion Language, The one distinction that matters, The vocabulary. Use it when a new assignment calls for this craft.

Works with✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/lucasaerb/workless-video-editor/tree/HEAD/skills/motion-language

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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.

scenestinger
length8–15s2–4s
carriesan argument you must readone idea you already heard
facehidden or PiPhidden — you cut TO it
how many3–6 in a 10-minute videoone every 20–40s
if you removed itthe point stops landingthe 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.

groundNear-black with a soft radial lift. Never flat #000 — a true black frame reads as a dropout, not a design.
glassTranslucent 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.
sheenA 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.
pathThin dashed curves at ~10% ink. Things travel along paths. Nothing teleports.
stateA 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"] }
kindthe sentence it belongs underdur
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
beatsThree 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
photoA found image, treated. Glass card, slow Ken Burns, caption, credit line.2.8–4.0
clipThe 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-ROLLfull: false — CITATION
framefull-bleed, no cardglass card, sheen, slow drift
text on framea lower third naming what the shot iscaption and credit line
source on frameneverrequired
use forfootage and stills that carry a momenta 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:

photoclip
element<img><video muted playsinline> with framework timing
Ken Burnsyes, 1.00 → 1.07 across the cardnone

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…rulewhy it fits
a number, a stat, a percentagecounting-dynamic-scale, stat-bars-and-fillsalready implemented as countup; use the rules directly for bars, rings, star fills
a punchy list, rapid-firekinetic-beat-slam, waterfall-entryimplemented as beats; waterfall-entry is the gentler cascade
a definition or a term landinggradient-text-sweep, depth-scatter-assemblethe glyphs never move in the first; the second assembles them from depth
"here's the shape of it" (a diagram)svg-path-drawthe outline draws itself. Measure with getTotalLength() at setup
"it's surrounded / buried / connected"radial-surround, avatar-cloud-network, orbit-3d-entryimplemented as surround; the other two add connection lines and 3D entry
one idea replacing anotherscale-swap-transition, card-morph-anchor, morph-swapimplemented as swap; card-morph-anchor morphs the container itself
"look closer at this"depth-of-field-blur, coordinate-target-zoom, viewport-changerack focus, or a virtual camera on a .world wrapper
emphasis on a spoken wordasr-keyword-glow, css-marker-patternsglow synced to word timestamps — we already have measured word times
a hard, percussive accentchromatic-glitch, particle-burst, motion-blur-streakuse sparingly; one per video at most
a calm landing beattitlecard-reveal (blueprint), ambient-glow-bloomlow motion is the payload, not a deficiency
any entrance at allspring-pop-entrancethe 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 (our compare scene 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 — fromTo with explicit from-states, absolute values, never relative +=. State must be a pure function of timeline time.
  • Deterministic — no Math.random(), no Date.now(). Index-derived pseudo-random only. Finite repeats, never repeat: -1.
  • Transforms and paint only. width / height / top / left tweens 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

  1. Search the registry first — npx hyperframes catalog --query "<concept>". 373 blocks exist. radial-surround, morph-swap, split-tilt-cards and particle-image-reveal are close cousins of things in this library and may be a better starting point than new code.
  2. 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.
  3. Add it to KINDS in scripts/stingers.py.
  4. 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:

  1. GSAP cannot animate ::after. It resolves targets with querySelector, 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.
  2. GSAP replaces the whole transform on its first tween. A transform:translateY(-50%) in the stylesheet is thrown away the moment y animates, and the element jumps half its height. Centre in GSAP with yPercent, or centre in CSS — never half in each.
  3. A shared centre is not a comparison. swap originally 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 cover crops nothing
  • Every tier-3 asset has its row in _FINAL/ATTRIBUTION.md, whatever the frame shows
  • Gallery rendered and every frame looked at

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Related Skills