> ## Documentation Index
> Fetch the complete documentation index at: https://motionly.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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.