pisakhov/x-motion

X Motion

Make motion that communicates something specific. Taste is contextual: a quiet technical demonstration and an exuberant music ident need different decisions. A capable renderer is not a guarantee of good design. The work earns its quality through art direction, execution, observation, and revision.

This is an original, portable motion-design method inspired by the design-agent discussion in LangChain's article. It does not depend on LangChain code or services and implies no affiliation.

Working contract

• Follow the host project's instructions and the user's actual scope. This skill grants no permission to publish, spend, call models, obtain credentials, or use unlicensed assets.
• Use one visual thesis and one dominant focal point at a given moment. Complexity may support the thesis; it must not compete with it accidentally.
• Design the type, spacing, image treatment, motion, and sound as one system. Do not decorate a weak idea into apparent sophistication.
• Choose tools for the job and available environment. No particular model, framework, or rendering engine is required.
• Separate technical evidence from aesthetic judgment. Never invent a taste score, audience reaction, or approval. Never claim to have watched a video when only its stills were inspected.
• Keep assets local and their provenance explicit. Pin dependencies. Keep generated renders out of version control unless the project deliberately requires them.

Choose the smallest useful process

Small edit: a copy correction, timing adjustment, asset swap, or isolated easing fix may bypass a new brief, storyboard, and animatic. Preserve the approved direction; inspect the affected beat and its neighbors, rerender, and run relevant checks. Escalate to the full process if the change alters the message, hierarchy, or narrative.

New composition or substantial redesign: follow the stages below. Scale the artifacts to the assignment; a six-second title does not need a production bible. If crucial intent is missing, ask a focused question. When questions are unavailable, label a conservative assumption and avoid irreversible work.

1. Brief → visual thesis

Establish audience, intended takeaway, viewing context, duration, aspect ratio, deliverables, required copy/assets, brand constraints, accessibility needs, and whether sound can carry meaning. Mark hard requirements separately from preferences.

Write a thesis in this form:

For [audience], make [idea] feel [specific quality] through [visual mechanism], so they understand or do [outcome].

Name the organizing metaphor, dominant subject, typographic role, and motion logic. A list such as “premium, cinematic, clean” is not a direction. Explain which choices make those words tangible. Use references to identify principles, not to reproduce another work's identity.

Read Art direction for brief resolution, reference analysis, and a coherent visual language.

2. Storyboard → readable argument

Plan beats before polishing frames. For each beat, record:

Time range	What the viewer learns	Focal point / key frame	Transition and reason	Audio cue
Start–end	One message	Subject and hierarchy	What changes, and why	Event or deliberate silence

Draw or render representative frames with real copy and realistic asset proportions. Give reading and recognition enough time; do not distribute every beat evenly by habit. Confirm the opening promise, the causal links between beats, and the final takeaway. Validate critical copy or direction with the human when needed before expensive production.

Read Typography before locking composition or text timing.

3. Animatic → test time cheaply

Build rough timed frames, blocks, or low-detail motion. Use scratch sound only when lawful and clearly labeled. Test the full runtime at its intended speed, not just by scrubbing.

Check whether attention arrives where the information does, whether text can be read, and whether the ending has room to land. Fix structure here. Surface uncertainty about the direction instead of polishing it away.

Read Animation and camera for temporal design and deterministic scene construction; read Audio when sound is part of the piece.

4. Production → intentional execution

Refine approved beats with final typography, assets, lighting or graphic treatment, motion curves, transitions, and sound. Preserve the thesis. Each added effect must have a job: reveal, connect, emphasize, orient, or resolve. If it does none of these, remove it or justify its expressive role.

Optional HTML renderer contract

When using the X Motion HTML renderer, each composition exposes:

window.motion = { width: 1920, height: 1080, duration: 8, fps: 30, poster: 5.5 };
window.renderFrame = function (tSeconds) {
  // Set every animated property from this timestamp and fixed scene data.
  // Repeated calls, including calls out of order, produce the same frame.
};
window.renderAudio = async function ({ sampleRate }) {
  // Optional. Build the score in an OfflineAudioContext and return its AudioBuffer.
};

These numbers are illustrative, not design defaults. Width and height are pixels; duration, poster and tSeconds are seconds; fps is the frame rate. poster is optional and names the frame used as the thumbnail. Match them to the brief.

• Calculate state directly from the supplied timestamp. No wall-clock time, autonomous CSS animations, accumulating simulation steps, network assets, or unseeded randomness.
• Load and decode local assets and fonts before capture. Do not introduce asynchronous frame mutations after renderFrame returns; verify the host renderer's readiness mechanism.
• Define behavior at beat boundaries and beyond the active interval. Test repeated timestamps and backward seeks.
• The frame function defines visuals, not audio playback. Sound comes only from renderAudio: one or two channels, rendered offline, identical on every call. HTML media playback is never captured.

Resolve this skill directory's real location first, following any installation symlink into the full X Motion clone. The repository root is ../.. relative to that resolved skills/x-motion directory, not relative to the user's current working directory. Change to that repository root before running these commands; composition paths below are relative to it.

Export storyboard PNGs and manifest.json (no video by default). Add --times 0.5,2,4.25 to choose the stills and --audio to also export sound.wav with loudness figures:

node scripts/render.mjs path/to/scene.html --out renders/name-storyboard --audio

Export storyboard PNGs, full frames, poster.webp, film.mp4 (with the score muxed as AAC when renderAudio exists) and manifest.json:

node scripts/render.mjs path/to/scene.html --out renders/name-video --video

Use a fresh output directory for each revision. Inspect manifest.json and the actual outputs before reporting success: it records a frame determinism check, an audio determinism check, integrated loudness, true peak and clipped samples. Video encoding requires ffmpeg. In another host, preserve deterministic timestamp semantics and adapt the export command.

5. Critique → revise → deliver

When feedback names a published video ID, read Gallery feedback. Resolve the exact film, preserve its identity and feedback, and publish revisions under new linked IDs. Carry forward scoped lessons, not every clip-specific instruction as a universal rule.

Inspect rendered artifacts, not only source. View the storyboard for composition and play the video for rhythm; listen to the exported audio when present. If playback or listening is unavailable, state exactly what remains unreviewed.

Use Critique and delivery to separate measurable failures from subjective concerns. Address the highest-impact issue first. Limit the critique/revision loop to three iterations per direction. If the direction remains unresolved, stop, explain the competing concerns, and ask the human to choose or clarify before continuing. A technical pass is not aesthetic approval.

Deliver the artifact location, source location, export specifications, verification evidence, known limitations, and unresolved approval questions. Report what you actually observed. Do not publish externally without authorization.

Reference map

Load only the references needed for the current stage:

• Art direction: intent, taste, references, visual thesis.
• Animation and camera: timing, staging, transitions, deterministic rendering.
• Typography: hierarchy, readable kinetic type, font handling.
• Audio: cue maps, synchronization, silence, export checks.
• Critique and delivery: evidence, bounded revision, handoff.
• Gallery feedback: immutable IDs, chat feedback, keep/improve/discard, and scoped learning.