Motion Doctrine

The law that decides how every Motionly shot performs. Read before composing animation; it supersedes general motion advice.

The catalog tells you what Motionly can do. This tells you what it should do. Read it before composing animation — these rules supersede general motion advice, and the engine enforces several of them.

The failure this prevents: shots authored in isolation, where every object gets the same entrance, every group appears at once, and the frame sits breathing between its entrance and its exit.

1. Arrivals

An arrival is a finite event. It is not a reaction, and it is not idle motion — those are separate, later animations.

Reveal binary. Opacity snaps to full inside the first frame; the movement carries the entrance. A gradual fade fights the snap of its own motion and makes an arrival read as a dissolve. Motionly’s layout and beat arrivals emit a keyframe step for exactly this reason.

Never .inOut on an arrival. power4.out is the default; expo.out for a punchier front. An arrival decelerates into rest — it does not accelerate first.

Overshoot is a rare, explicit choice. Bouncy back.out and elastic.out are the most recognizable tell of machine-made motion. spring.soft and friends exist for deliberately playful registers only, never for product, enterprise, or serious work. When unsure, settle smoothly.

2. Cascades

A group entrance is a wave, not a queue.

Gaps shrink. Each successive gap is smaller than the last, so the group accelerates and the final item snaps. Equal gaps read as a roll call. Motionly decays gaps by 0.84 per step.

Velocity varies by weight. The focal subject travels further and settles longer than its support. Identical travel and duration across a group is the single most common reason a composition looks generated.

	Focal	Support
Travel	64px	40px
Duration	0.62s	0.46s

The group lands inside one beat. The whole cascade window is capped at 0.5s regardless of item count — a twenty-logo wall still reads as one arrival. Motionly scales the stagger down automatically to hold this.

3. Sustained motion

Every beat between its entrance and its exit is owned by exactly one route.

Route	What it is
stagedReveals	Content held back and paid off in stages; the frame keeps gaining information
cameraIntent	A mapped camera path: establish, travel, arrive
uiLife	The product behaves over time: progress advances, counts tick, highlights step
sequence	Elements act out a beat: a card files into a stack, a result assembles
cursorLed	A cursor walks the eye to a control and its click ignites the next beat
hold	Deliberate stillness — the only route that may hold a composed frame still

Idle drift is not sustained motion. Float, breathe, drift, and glow pulse read as “the video is waiting.” A beat that finishes entering with seconds left is a planning problem, and the fix is more story, not more wobble. This is why no Motionly showcase enables float by default — it is opt-in.

The test: pause anywhere in the beat. Something meaningful must be mid-flight — a reveal landing, the camera traveling, the product doing what the narration says. The inspector reports any stretch longer than 1.4s where nothing is in flight, and infinite loops deliberately do not count as coverage.

Stillness before climax. Schedule 0.3–0.75s between a major action and its result. A beat that jumps straight from action to result loses the result.

4. Continuity

Transform, don’t fade. Beats never clear the composition; objects persist and change. The transition into a beat is sharedElement, objectMorph, layoutMorph, cameraMove, or continuous — never a frame fade.

Direction is meaning. Pick one dominant direction for a film and use it for ordinary progression. A change of direction needs a visible cause — a click, an impact, a chapter boundary. Consecutive shots moving in opposing directions read as an error, not as variety.

Pair the two sides of a cut. When a shot genuinely changes, pair transitionOut on the outgoing side with transitionIn on the incoming side, same treatment and direction. Motionly’s sceneSlide and sceneZoom are designed to be used in pairs.

Cause precedes effect, on the same frame. A reaction fires at the moment of its cause, not “shortly after.” Reactions scale with implied mass: large elements rebound slower, small ones snap.

5. Timing budget

These are the numbers the engine and the inspector use.

Rule	Value
Single entrance	≤ 0.8s
Focal arrival	0.62s / 64px
Support arrival	0.46s / 40px
Total cascade window	≤ 0.5s
Gap decay per step	0.84
Stillness before climax	0.3–0.75s
Longest move before it reads as drift	2.8s
Shortest move that registers	0.08s
Longest stretch with nothing in flight	1.4s
Exit duration	≈ 75% of its entrance
Default arrival curve	power4.out
Default settle curve	power3.out

A buildup longer than one entrance is a staggered group, not one slow element.

6. Anti-patterns

Don’t	Instead
Fade an arrival in	Snap opacity, let the motion carry it
Give every item in a group the same entrance	Scale travel and duration by weight
Space a cascade evenly	Shrink each successive gap
Let a cascade run past one beat	Tighten the stagger; the group is one arrival
Bouncy overshoot as the default entrance	power4.out; overshoot only for playful registers
.inOut on an entrance	Mirror it: power4.out
Idle float to fill remaining time	Assign a sustained-motion route, or add story
A beat that holds still without saying so	route hold
Fade or wipe between shots	Transform: shared element, morph, or camera
Change direction without a cause	Keep the current, or spend a visible force
A reaction a few frames after its cause	Same-frame ignition
Action straight into result	Schedule stillness before the climax
One slow element for a long buildup	A staggered group
Decorative shapes standing in for a product	A showcase with the real asset
Hand-placed coordinates where a layout fits	Declare the layout and parent the children

Verifying

npm run inspect:motion -- path/to/project.motion --expect-duration=<seconds>

The inspector evaluates every frame, then audits pacing, cascades, coverage, and geometry. Findings are advisory by default; add --strict to fail on any of them. It cannot judge taste, brand fit, or whether the story works — inspect the rendered frames for that.