Motion System

Beats, layouts, and showcases: select complete motion design ideas instead of placing primitives.

Motionly’s motion system is a component layer above the native engine. Instead of positioning rectangles and inventing keyframes, you select named blocks and the engine supplies the geometry, spacing rhythm, hierarchy, and choreography.

prompt / author
  → beats            pacing and focus
  → layouts          composition
  → showcases        product presentation
  → semantic components / archetypes
  → .motion AST → scene graph → evaluator → renderer

Every block lowers to ordinary Motionly elements — group, overlay, image, text, transition, and animations. Nothing new reaches the renderer, and the result stays fully editable source.

Where the code lives

The registry/ folder holds generated JSON manifests only — a searchable index for motionly catalog and motionly add. The implementation is TypeScript in src/:

Block	Implementation	What it owns
Layouts	src/motion-system/layout.ts	12 deterministic solvers, 8px rhythm, stagger math
Showcases	src/motion-system/showcase.ts	Device geometry, screen crop, glare, entrance, idle, push
Beats	src/motion-system/beats.ts	Time windows, camera framing, storyboard plan
Transitions	src/motion-system/transitions.ts	Shared element, object morph, layout morph, camera
Asset intelligence	src/motion-system/asset-intelligence.ts	Classification → recommended presentation
Selection metadata	src/motion-system/metadata.ts	The index the AI selects from
UI components	src/semantic/component-structures.ts	Per-type builders: dashboard, browser, terminal, pricing card, laptop, editor
Vector sources	src/semantic/vector-registry.ts	Licensed glyphs, sizes, capabilities, part names
Lowering	src/semantic/motion-lowering.ts	AST → AST pass that expands the three block kinds
Registry generator	scripts/generate-registry.ts	Emits registry/**/registry-item.json from the catalog

Run npm run registry:generate after changing a definition; the JSON is a build artifact, never edited by hand.

Beats

A beat is a change in focus, not a slide. Beats never clear the composition, so objects persist and transform across the whole film.

beat intro {
  duration 5s
  focus title
  label "Brand introduction"
}

beat reveal {
  duration 7s
  focus product
  zoom 1.25
  label "Product reveal"
}

Property	Meaning
start	Absolute start. Omit to run directly after the previous beat.
duration	Beat length. Omit to share the remaining canvas time evenly.
focus	Focal element the camera frames.
zoom, cameraX, cameraY	Camera framing for this beat.
route	What keeps the beat performing. See below.
transition	Transition into the beat.
from, to	Endpoints for paired transitions.
transitionDuration, easing	Transition timing.
label	Storyboard label, kept on the scene for the editor.

Attach content to a beat with beat NAME. The block’s entrance delay resolves from the beat start, so timing is a storyboard decision instead of a pile of hand-tuned delays.

Routes

Every beat is owned by exactly one sustained-motion route. Idle drift is not sustained motion — see the Motion Doctrine.

Route	What it is
stagedReveals	Content held back and paid off in stages
cameraIntent	A mapped camera path: establish, travel, arrive
uiLife	The product behaves over time: progress advances, counts tick
sequence	Elements act out a beat: a card files into a stack
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 frame still

The route is inferred when omitted: a camera move becomes cameraIntent, two or more attached blocks become stagedReveals, and anything else is an explicit hold. An authored route is validated against what the beat actually contains — claiming cameraIntent without moving the camera is a compile error, because a route is a claim about how the beat performs.

Layouts

A layout solves composition. Declare it, then give each child parent NAME; the solver assigns position, size, and a staggered entrance.

layout capabilities {
  type bentoGrid
  columns 3
  gap 40
  beat features
}

component planCard {
  parent capabilities
  type pricingcard
}

Available types: heroLayout, splitLayout, bentoGrid, featureGrid, masonryGrid, deviceStack, logoWall, comparisonLayout, timelineLayout, carousel, gallery, floatingCollage.

Properties: type, columns, gap, width, height, itemWidth, itemHeight, order (linear, center-out, reverse), stagger, beat, parent, delay, layer.

An authored value always wins. Set x on one child and the solver fills in the rest. Fixed-aspect children such as semantic components are fitted inside their slot rather than stretched to fill it.

The layout also owns the group’s arrival motion: gaps shrink across the cascade so it accelerates, travel and duration scale by composition weight (the focal tile arrives with more presence than its support), opacity snaps rather than fades, and the whole group lands inside one beat however many items it holds. Those numbers are in the Motion Doctrine.

Showcases

A showcase turns one real asset into a finished product presentation.

import "/assets/dashboard.png" as dashShot

showcase product {
  type dashboardShowcase
  media dashShot
  headline "Every metric, live"
  behavior push highlight
  beat reveal
}

Type	Presents
productHero	One asset with a glow bed and headline
phoneShowcase	Mobile screen with bezel, notch, glare
browserShowcase	Web product with chrome, traffic lights, URL pill
laptopShowcase	Desktop product on a laptop with base and shadow
appWindow	Native app window with a slim titlebar
dashboardShowcase	Dashboard with sidebar rail and camera push
screenshotPresentation	Frameless media with elevation and reflection
uiWalkthrough	Window, step chip, and a focus ring on the acting region

Properties: type, media, headline, caption, label, width, behavior, accent, surface, focusX, focusY, beat, parent, delay, duration, layer.

Behaviors are float (idle drift), push (camera push on the subject), highlight (focus ring), and still (suppress idle motion).

The screen clips its media, so a tall capture crops instead of distorting. With no media, the showcase renders an honest “Add product media” empty state.

Transitions

Transitions transform what is on screen; they never fade the frame.

Kind	Behavior	Needs from/to
sharedElement	One element hands off to another	yes
objectMorph	One subject becomes another	yes
layoutMorph	An arrangement rearranges into another	yes
cameraMove	The camera reframes the persistent composition	no
continuous	Nothing cuts; the composition keeps evolving	no
cut	Explicit hard change	no

When a beat changes focus and names no transition, the planner defaults to cameraMove. When focus is held, it defaults to continuous. Paired kinds are never inferred, because both endpoints must exist for the scene graph to accept the project.

Asset intelligence

Imports are classified into logo, icon, screenshot, ui, illustration, photo, video, avatar, chart, or unknown. Filename intent wins, then declared type, then geometry — a portrait capture is a phone screenshot, a landscape one is a desktop interface. Each kind maps to the showcases that frame it and, for groups, the layouts that arrange it.

Examples

Everything comes by default. Blocks are compiled into the engine — there is no install step, no dependency to add, nothing to fetch. Write this and it works:

layout features {
  type bentoGrid
  columns 3
}

Each layout and showcase folder in registry/ additionally holds a worked example composition, purely so you can read one or start from it:

npx @coppsary/motionly catalog --type layout      # list blocks; [example] marks those with one
npx @coppsary/motionly catalog --show bentoGrid   # print the example, write nothing
npx @coppsary/motionly add bentoGrid              # copy it in as a starting file

add is a convenience that copies that example into compositions/. Skipping it costs you nothing.

These examples are generated from the definitions, so they cannot drift, and the test suite audits every one against the doctrine with zero tolerance — the catalog is held to the rules it publishes.

Checking a project

npm run inspect:motion -- path/to/project.motion --strict

Beyond validity, the inspector audits motion quality: entrances over budget, cascades that queue instead of accelerate or spread past one beat, stretches where nothing is in flight, elements with no area, elements never inside the canvas, and similarly sized unrelated elements stacked on each other. Findings are advisory unless --strict is given.

Working with archetypes

archetype remains valid and unchanged for slide-style shots. Use beats, layouts, and showcases when the composition should persist and evolve; use archetypes for a self-contained shot with its own scene root.