media-driven-motion
Skill1 starsChanged 52 days agoApache-2.0View on GitHub
Use when motion should come from footage, a frame sequence or a rendered scene rather than from interpolating CSS properties.
In this repository45 other files it gives its agents.
- docs/agents.mdAGENTS.md
- 3d-game-assetsSkill
- accessibility-evidenceSkill
- accessible-componentsSkill
- agent-memorySkill
- agent-orchestrationSkill
- code-qualitySkill
- code-reviewSkill
- colour-systemsSkill
- component-architectureSkill
- design-judgmentSkill
- design-reviewSkill
- design-tokensSkill
- engineering-disciplineSkill
- information-architectureSkill
- interaction-designSkill
- interface-copySkill
- interface-statesSkill
- layout-compositionSkill
- methodology-feedbackSkill
- micro-interactionsSkill
- mobile-performanceSkill
- motion-designSkill
- motion-physicsSkill
- multiplayer-game-publishingSkill
- platform-androidSkill
- platform-appleSkill
- platform-webSkill
- procedural-surfacesSkill
- public-api-integrationSkill
- rendering-performanceSkill
- responsive-architectureSkill
- reverse-engineeringSkill
- scroll-experiencesSkill
- seo-and-metadataSkill
- ship-readinessSkill
- skill-discoverySkill
- surface-and-depthSkill
- test-driven-developmentSkill
- theming-systemsSkill
- typographic-systemsSkill
- ui-generation-workflowSkill
- vishwakarma-studiosSkill
- visual-feedback-loopSkill
- webgl-experiencesSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Ask one question: does the thing being shown exist independently of the page?
- Distinctive: line 45
Write the answer down before writing code.
- Distinctive: line 115
Every sampled source is unavailable to a meaningful share of traffic: no-JS, Save-Data, a metered connection, a decode failure, a print, a …
- Distinctive: line 332
Run these checks against your own output.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!--
Generated by Vishwakarma. Do not edit this file directly.
Edit the source skill and run `vishwakarma sync` to regenerate.
-->Media-Driven Motion
A page can move in two fundamentally different ways, and only one of them survives contact with a viewer who has seen the alternative.
Interpolated motion computes the in-between states. A start, an end, a curve. Its total information content is those three things, which is why it looks the same on every site that uses it and why no amount of easing refinement fixes the feeling that nothing is happening.
Sampled motion replays states that already existed: frames a camera recorded, frames a renderer produced, a surface lit by a light somebody placed. Ninety frames of a turntable are ninety measurements of an object. The viewer cannot articulate the difference and does not need to — weight, contact shadows, motion blur, the way a highlight crawls across a curve are all present in one and absent from the other.
Both are correct in their place. Interface state changes — a panel opening, a value updating, a row reordering — should be interpolated, because there is no real event to sample. The failure is using interpolation for a subject that exists.
1. Classify the subject first
Ask one question: does the thing being shown exist independently of the page?
- It exists, and can be photographed — a product, a person, a place, a material, a process. Sample it. Recorded frames or a frame sequence. A still image with a fade is a downgrade of something you could have had.
- It would exist, but cannot be photographed — an unbuilt object, a cutaway, an impossible camera move, a material under light you cannot rent. Render it. A real scene, real lights, and the camera on a scroll-driven path.
- It is the interface itself — disclosure, navigation, state. Interpolate it, and follow
motion-designandmicro-interactions. Sampled motion here is decoration with a payload.
Write the answer down before writing code. Almost every generated page that reads as fake got this wrong once, at the hero, and then repeated the mistake down the page.
2. Scroll is a clock, not a trigger
A scrubbed sequence needs a time, not an event. That time is a number in 0..1 derived from position — never accumulated from scroll deltas, because an accumulator disagrees with the page after a fling, a fragment jump, a find-in-page hit, or a reload at that offset.
@vishwakarma/scroll already computes it. Two ways in, and the choice is not cosmetic:
import { useProgressBinding, useScrollProgress } from '@vishwakarma/scroll'
// Per-frame, no React render. Correct for media. Note native: false.
const binding = useProgressBinding(ref, {
native: false,
onProgress: (p) => { targetRef.current = p },
})
// React state, quantised to 200 steps by default. Correct for a caption or a step index.
const { ref: sectionRef, progress } = useScrollProgress({ step: 0 })native: false is mandatory for a media scrub. The onProgress subscription is created
only on the scripted path; when the binding resolves to the native CSS-timeline driver the effect
returns early and the callback never fires. The page then works in Firefox and does nothing in
Chrome — a failure that looks like bad animation rather than a bug.
useScrollProgress quantises by default (step: 0.005, 200 distinct values). A 240-frame
sequence driven by it renders 200 of its frames and duplicates the rest, and it re-renders a
React subtree per step. It is the wrong hook for frames and the right one for a chapter label.
3. The three frame sources, and what each actually costs
| Recorded video | Frame sequence | Rendered scene | |
| Bytes for ~5 s | 0.5–4 MB | 2–15 MB | 0.3–3 MB of assets |
| Per-frame cost | seek + decode | decode or blit | full draw |
| Frame-accurate scrub | hard | exact | exact |
| Jump to arbitrary point | slow | instant if resident | instant |
| Reacts to input, theme, data | no | no | yes |
| Scales to any viewport | no | no | yes |
Video is the cheapest bytes-per-frame by a wide margin and the worst at being scrubbed. Sequences are the opposite. A rendered scene is the only one that can respond to anything. Choose on the scrub requirement, not on file size: a hero that must land exactly on a frame is a sequence, a background that merely needs to move is a video.
4. Budget the frame count before authoring it
Frames are not free at any of the three stages, and the constraint that bites is decode and resident memory, not transfer.
A decoded frame occupies width × height × 4 bytes regardless of its compressed size. At
1600×900 that is 5.76 MB per frame, so a 90-frame sequence held decoded is 518 MB — impossible.
Sequences therefore hold a sliding window around the current index and release the rest.
Compute the window from the budget, not from taste, and do the arithmetic before commissioning
the frames. frame-sequences.md has the method.
5. The still is the real content
Every sampled source is unavailable to a meaningful share of traffic: no-JS, Save-Data, a metered
connection, a decode failure, a print, a crawler, reduced motion. Under
prefers-reduced-motion: reduce a scrub must resolve to a chosen frame — the one that best
carries the message, not frame zero — in normal document flow, at the same reserved aspect ratio.
Ship that still first, reserve its space, and upgrade to the sequence after first paint.
webgl-experiences owns the same rule for canvases and the arithmetic behind it.
6. Named recipes
A shot has four independent parameters — subject treatment, camera path, time behaviour,
light — and a named recipe is one combination of them, fixed so it can be asked for by name
and executed the same way twice. cinematic-recipes.md defines the grammar and specifies the
named shots; /bullettime means subject timescale near zero while the camera orbits at speed,
not "make it dramatic".
Two things the grammar buys. A name can be checked: if /orbit_sweep specifies a locked
target, a shot whose subject drifts out of frame is a defect rather than a matter of taste. And
a name composes — a sequence is a list of recipes with scroll spans, which is a timeline you
can review before building it.
7. When the clock is not the scroll
Everything above is paced by the reader: they stop, reverse, and it never runs without their
intent. A timed camera flight — an intro that plays on load and carries the viewer through
several environments — is paced by the machine, and that single difference creates obligations
scroll never had. It must be skippable, it must not be what the page is waiting on, and under
prefers-reduced-motion it must not play at all.
It also cannot hold its world in memory. A flight that visits four environments at medium-tier
quality is four times over the texture budget, so exactly one is resident and the others are
loaded and disposed around it. The transitions therefore have to hide a swap —
camera-flights.md has how, including the form where the thing you fly through is also the
section's title card.
Boundaries. scroll-experiences owns the scroll mechanism, thrash, pinning and the progress
geometry — its rules apply in full here and are not repeated. motion-design and
motion-physics own interpolated motion. webgl-experiences owns mounting, tiering and
fallback for a canvas; this skill owns only what drives its timeline. mobile-performance owns
the field gates the byte budgets answer to. design-judgment owns whether the effect should
exist; ship-readiness owns whether a demo is real.
Rules
MUST NOT — Do not route per-frame scrub values through React state, and do not drive a frame index from the default quantisation of useScrollProgress.
Why: A setState per scroll frame re-renders a subtree 60 times a second to change one number React does not need. useScrollProgress also quantises to 0.005 by default, which is 200 distinct values — a 240-frame sequence driven by it renders 200 frames and duplicates the rest.
Exceptions:
- Values a human reads rather than frames — a chapter label, a percentage, a step index — which is exactly what useScrollProgress is for.
MUST NOT — Do not clear the canvas or draw a placeholder when the requested frame is not resident; hold the last drawn frame.
Why: A held frame reads as a pause in the motion, which is a normal thing for motion to do. A cleared canvas or a spinner reads as a broken page, and it appears precisely during the fast scrolls where the window cannot keep up — so the worst impression lands on the most common interaction.
MUST — Give a timed camera flight a visible, keyboard-reachable skip from its first frame, and end it on any click, key or scroll.
Why: A machine-paced sequence advances whether or not the viewer wants it to, which is the one thing scroll-driven motion never does. Someone who starts interacting has already said they are finished watching, so continuing to hold the viewport is taking time they declined to give.
MUST — Ship the flight’s resting composition as real markup and never let the flight be the largest contentful paint or a gate on interactivity.
Why: The resting state is what every no-JS, Save-Data, print, crawler and reduced-motion visitor receives, and what everyone else sees if the flight never loads — so it is the page, and the flight is an enhancement over it. A sequence that owns first paint also adds its entire load time to the moment a visitor decides whether to stay.
MUST — Under prefers-reduced-motion: reduce, do not play a camera flight at all; render its resting composition directly.
Why: Elsewhere this catalogue freezes motion rather than removing it, because a frozen surface is still a surface. A flight is the exception: full-viewport camera movement through space is precisely the vestibular trigger the preference exists for, and its resting composition is already a complete design rather than a degradation.
MUST — Cross between environments by flying through an occluder that fills the frustum, with the next environment already rendered and the old one disposed after.
Why: Only one environment fits the texture budget, so a multi-environment flight is a sequence of swaps and each swap needs somewhere to hide. Loading at the crossing puts the hitch at the moment attention is highest, and disposing during it competes with the frame that most needs the budget. An occluder that carries the section title makes the concealment content rather than machinery.
Incorrect:
setEnvironment(next) // swap in the open; one stalled frame is a visible cutCorrect:
await next.warmup(); flyThrough(occluder); queueMicrotask(() => previous.dispose())MUST — Keep navigation, filters and inputs in the DOM above the canvas rather than as geometry inside the scene.
Why: DOM chrome stays selectable, focusable, translatable and findable while the world moves behind it, and survives an environment swap untouched. Geometry carrying an interface loses all of that and has to be rebuilt every time the scene changes. The test is whether the navigation still works with the canvas deleted.
MUST — Specify a named shot by its four grammar parameters plus a check a reviewer can run, and never by an adjective.
Why: Subject, camera, time and light are independent, so a name that does not fix all four leaves the shot undetermined and it will be built differently each time. The check is what makes the name enforceable: "does the subject bounding box stay within a few per cent across the sweep" is reviewable, while "smooth camera" gives a reviewer nothing to decide.
MUST — Budget a sequence by its most expensive beat against the lowest tier shipped, and shorten the sequence rather than degrading every beat.
Why: Tier budgets apply per rendered frame, so one beat needing two shadow casters gates the whole sequence at high tier. Turning every beat down until the expensive one fits produces a sequence where nothing reads, whereas three beats that work is a shot; five that do not is a defect distributed evenly.
MUST — Derive scrub time from a clamped 0..1 progress value computed from scroll position, never from accumulated scroll deltas or an elapsed-time clock.
Why: An accumulator or a clock makes the frame shown a function of scroll history, so a fling, a fragment link, find-in-page, and a reload at the same offset all produce different frames at the same position. Position-derived progress gives the same pixels in all four cases by construction.
MUST — Pass native: false when using useProgressBinding onProgress to drive media, and verify the scrub in a browser that supports scroll timelines.
Why: useProgressBinding creates its scroll subscription only when the resolved driver is script; on the native CSS-timeline path the effect returns before subscribing, so onProgress is never called. The scrub therefore works in Firefox and does nothing in current Chrome and Safari, and the failure presents as lifeless motion rather than as an error.
Exceptions:
- Effects expressed entirely in CSS from the --vk-scroll-progress custom property, which is what the native path exists to serve and needs no callback.
Incorrect:
useProgressBinding(ref, { onProgress: (p) => { video.currentTime = p * d } })Correct:
useProgressBinding(ref, { native: false, onProgress: (p) => { target.current = p } })MUST — Keep at most one video seek in flight: store the latest target and issue the next seek only after the seeked event.
Why: Assigning currentTime requests an asynchronous seek. Issuing one per scroll frame produces more requests than the decoder can service, so most are discarded or serviced late and the picture arrives after the scroll has moved on — the trailing-then-jumping symptom that reads as broken animation.
Incorrect:
onProgress: (p) => { video.currentTime = p * video.duration }Correct:
if (!seeking) { seeking = true; video.currentTime = target.current * video.duration }MUST — Re-encode video intended for scrubbing with a keyframe interval of 5 to 10 frames, and pay for the size increase by cutting resolution, duration or frame rate.
Why: Inter-coded frames are reconstructed from the preceding keyframe, so a seek costs one decode per frame since that keyframe. A playback encode with keyframes every few seconds turns a scrub into a decode storm no amount of client code can fix. Keyframes are intra-coded, so a scrub encode is typically 3 to 6 times the size at equal quality.
MUST — Size a frame-sequence window by dividing a stated memory ceiling by width x height x 4, and lower the resolution if the result is under about eight frames.
Why: A decoded frame occupies width x height x 4 bytes regardless of its compressed size, so 120 frames at 1600x900 is 691 MB and cannot be held. A lead of fewer than eight frames cannot absorb a fast scroll, so the sequence visibly stalls — which means the resolution, not the window, is what has to change.
MUST — Decode sequence frames with createImageBitmap and blit with drawImage; do not rely on new Image() decoding during scroll.
Why: An img element decodes on the main thread at paint time, which places a multi-millisecond decode inside the frame budget exactly while the page is scrolling. createImageBitmap decodes on a browser-owned thread and returns a bitmap that blits in well under a millisecond.
MUST — Call close() on every ImageBitmap evicted from the window, and abort in-flight decodes when the scroll direction reverses.
Why: An ImageBitmap holds memory outside the JavaScript heap that garbage collection does not reclaim promptly, so a window that drops references without closing them grows until the tab is killed — on a phone first. Un-aborted decodes for the old direction also occupy the decode queue ahead of the frames now needed.
MUST — Call requestRender from useOnDemandRender after writing scroll progress to a ref that a scene reads, and use renderFor only for motion that continues after input stops.
Why: With frameloop on demand the renderer draws only when asked, and only React state changes ask automatically. Progress written to a ref bypasses the reconciler, so the camera moves and the canvas never redraws — a scene that is correct in memory and frozen on screen. A single frame is also not enough for damped motion, because the request for the second frame would have come from the second frame.
MUST — Express every scroll-driven scene value as a pure function of progress, and seek baked animation with mixer.setTime rather than mixer.update.
Why: An integrated value depends on the sequence of frames that produced it, so a reload, a fragment jump or a fling gives a different scene at the same scroll position. setTime is idempotent and seekable; update accumulates delta and drifts, and the drift is invisible until someone scrubs backwards.
Exceptions:
- A bounded convergence toward the derived target inside the frame callback, where the gap is capped so a jump snaps rather than animating across the path.
MUST — Ship a deliberately chosen frame as the section’s real content, at the same reserved aspect ratio, and make it the largest contentful paint element.
Why: Every frame source is unavailable to a substantial share of traffic: no-JS, Save-Data, decode failure, print, crawlers, reduced motion. A poster that is frame zero rather than the frame that carries the message wastes the one image most of those visitors will see, and an unreserved ratio shifts the page twice.
MUST — Under prefers-reduced-motion: reduce, attach no scroll binding and allocate no window: render the chosen still, or for a scene the chosen composition, in normal document flow.
Why: A full-bleed scrubbed sequence is a stronger vestibular trigger than the fades the preference was invented to suppress, and a binding left attached with its output ignored still costs a layout read and a callback every frame. Reduced motion means still, not absent, so a scene stays rendered and inspectable rather than being replaced by an image.
SHOULD NOT — Do not add motion that is uncorrelated with user action or system state — ambient float, drifting particles, looping gradients — to carry the impression of liveness.
Why: Motion that correlates with nothing carries no information, so attention habituates to it within seconds and then discards it, while it continues to cost frames on every device and comfort for motion-sensitive users. The impression of liveness it is reaching for comes from sampled detail, which this actively competes with for budget.
Exceptions:
- Motion that is itself the subject — a visualisation of a live system, an art piece — where the movement is the content rather than a signal that content exists.
SHOULD — Write a composed sequence as a list of recipes with scroll spans before building it, and return the final beat to the first beat’s framing.
Why: A five-line timeline is cheap to change and a built one is not, so the review belongs before the work. A sequence that ends somewhere other than where it started leaves the viewer mid-shot at the end of the scroll, which reads as unfinished because there is no resolution to the movement.
Exceptions:
- A sequence whose end state is the page’s next section, where the final framing is a deliberate hand-off rather than a return.
SHOULD — When the subject of a section exists and can be photographed or rendered, drive its motion from frames rather than from a CSS transition on a still.
Why: An interpolated transition contains only its two endpoints and its easing curve, so it can describe the element but never the subject. A frame source contains an independent measurement per frame, which is where weight, contact shadow, motion blur and material response come from — none of which can be approximated by a transform.
Exceptions:
- Interface state changes — disclosure, navigation, a value updating — where no real event exists to sample and interpolation is the correct mechanism.
- A section whose byte or decode budget cannot accommodate any frame source, where a deliberately composed still with no motion beats a fake one.
Incorrect:
<img src="/croissant.jpg" className="fade-up" /> // a photograph with a property on itCorrect:
<FrameSequence frames={72} src="/croissant/{i}.webp" /> // 72 measurements of the objectSHOULD — Use a frame sequence rather than video when the scrub must land on an exact frame, runs backwards as often as forwards, or measures over 100 ms of seek latency on a mid-tier phone.
Why: A resident decoded frame is addressable in constant time in either direction, while a seek is asynchronous, direction-sensitive and priced by distance from the nearest keyframe. Sequences trade bytes for determinism, which is the property a hero needs and the one video cannot provide.
Exceptions:
- Long or full-bleed background motion where exactness does not matter and the byte difference does.
Before reporting completion
Run these checks against your own output. Answer each question explicitly rather than assuming the answer, because the point of the exercise is to notice what you did not notice while building.
Confirm the page’s motion carries real information and that its frame sources are affordable, scrubbable and degradable — measured on a real mid-tier phone. (blocking)
- List every moving thing on the page and classify each as sampled or interpolated. For each interpolated one, does its subject exist independently of the page?
- With every transition, transform and scrub removed, what can no longer be understood? If the answer is nothing, the motion was decoration.
- For each moving thing, where did its frames come from — a camera, a renderer, or two states a designer chose? Is any answer "the animation library"?
- Is every scrub time a clamped function of scroll position, giving identical pixels after a reload, a fragment jump, a find-in-page hit and a slow scroll to the same offset?
- Does the scrub work in a browser that supports scroll timelines, and not only in one that does not — that is, was native: false actually passed?
- On a real mid-tier phone, what is the measured gap between requested and presented media time during a fast scroll, and is it under 100 ms?
- For a sequence: what memory ceiling was stated, what is width x height x 4, how many frames does that allow, and is the lead at least eight frames?
- Is every evicted ImageBitmap closed, and do in-flight decodes abort when the scroll direction reverses?
- During the fastest scroll you can perform, does the canvas ever clear or show a placeholder rather than holding the last drawn frame?
- For a scene: is every scroll-driven value a pure function of progress, and does the canvas actually redraw — requestRender called — after progress is written to a ref?
- Is the poster or first frame a deliberately chosen frame rather than frame zero, and is it the largest contentful paint element at the same reserved aspect ratio?
- Under prefers-reduced-motion: reduce, is the binding detached and no window allocated, with the chosen still or composition rendered in normal flow?
- With JavaScript unavailable and the media element deleted from the DOM, does the section still carry its whole message?
Further reference
These are not loaded by default. Read one only when its question is the question you currently have.
references/camera-flights.md— How does one continuous camera path cross several environments without cuts, where does the swap hide, and what does a machine-paced sequence owe that a scroll-paced one does not?references/cinematic-recipes.md— What exactly does /bullettime or /explodeview specify, how do I name a new shot, and what does each one cost against the scene budget?references/scrubbed-footage.md— How do I drive a video element from scroll without it lagging, how must the file be encoded to be scrubbable, and how do I know the pixels match my target?references/frame-sequences.md— How many frames can I afford, how do I decode them without blocking the main thread, how big a window do I hold in memory, and when is a sprite atlas better?references/scene-timelines.md— How do I turn scroll progress into a camera path or animation time in a scene, and why does my scroll-driven scene stop updating?references/sampled-or-interpolated.md— How do I tell whether a page’s motion carries real information, and what are the specific tells that it does not?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

