What is MOTION.md

MOTION.md is an open format for how a film looks and moves. It is a Markdown file your agent reads before it draws anything, so the film it makes for your story keeps one look from the first frame to the last. One file is enough to start. A directory around it can add ready-made React components, which your agent uses first.

You may already give your agent files like it:

#Start with one file

Put this at your project's root, as MOTION.md:

---
spec: motion/0.5
name: Harbour Chart
tokens:
  color:
    paper: "#EFE6D2"
    sea: "#1F4E5F"
    buoy: "#C8553D"
  font:
    title: ["Fraunces", "serif"]
    label: ["IBM Plex Mono", "monospace"]
  duration:
    draw: 1.4s
---

# Harbour Chart

## Essence

An old nautical chart in two inks: thin lines and small labels, never a photo or 3D.

## Colour

`paper` is the ground, `sea` is every line and word, and `buoy` is the one mark in a frame.

## Type

`title` for the one heading in a frame, `label` for everything else.

## Motion

Lines draw on from left to right over `draw`. Nothing bounces.

## Avoid

- A second red mark → keep one per frame.

The front matter holds its exact values, so an agent never has to guess a colour. An agent with the motionhub skill looks for MOTION.md at your project's root, and then at motion/MOTION.md:

/motionhub make a film about <your topic>

Two commands help. The first checks the file, and the second writes its values out as tokens.json, for a binding or a theme:

npx @motionhub/cli check MOTION.md --format-only
npx @motionhub/cli tokens --out tokens.json

#Add components

A MOTION.md can lead a directory, the way a SKILL.md can bring scripts:

clay-world/
  MOTION.md     the look, in words
  tokens.json   the exact values, as W3C design tokens
  react/        its components, ready to use
    parts/      slice.tsx, figure.tsx, world.tsx and more
  motion.json   its id, version, authors and licence
  poster.jpg    one frame of a film made in it
  CREDITS.md    every font and asset it needs

• Components come first. Where a motion has them, your agent uses them rather than drawing the look again. They run in Remotion and HyperFrames through a binding, and in any other React engine you bind them to.
• The words and tokens govern. MOTION.md says what each piece is for and what to avoid, and the tokens say exactly which colour, face and easing to use. Anything the components do not draw is made from these, in any engine.

In a directory, the values live in tokens.json alone, and every motion on motionhub is a directory.

#What it says

Every MOTION.md has five sections, so an agent always knows where to look:

A motion with components also has a Components section, saying what each one is for. Any other sections may follow, and two are recommended: Treatments, a recipe for each kind of frame, and Self-audit, what to check before a film is finished.

It describes a look and never a particular film. It has no story, script, scenes or timings: you bring those.

#An example

From Clay World, a look on motionhub:

# Clay World

## Essence, and what it is not

- Everything is a rounded, hand-pressed form of matte clay, slightly out of true, thumb-dented; no sharp edge, no gloss.
- Things have weight: what falls stretches, squashes flat, throws up crumbs and jolts the camera.

## Colour roles

- One saturated clay leads a frame. Never pure white or black, a gradient on a form, or a glow.

The whole file goes on to its type, its motion and what to avoid.

#Use one, or write your own

To make a film in a look from motionhub, follow Use a motion. To publish a look of your own, ask your agent from the project whose look you want to share. It writes the whole directory that motionhub needs:

/motionhub share this project's look as a motion

Share a motion has the rest.

#The definition

The format is defined in the specification: MOTION.md in section 5, one file in section 11 and components in section 12. The format is still a draft, and it only grows: a later version never changes the meaning of what an earlier one says.

#Propose a change

The format is open, and changes to it are made in the open:

• Open an issue to say what should change and why.
• Edit the specification to open a pull request from your browser. Add a Signed-off-by: Your Name <you@example.com> line to the commit message, or the checks refuse it.

Or from a terminal:

gh issue create --repo motionhub-dev/motions --title "MOTION.md: <your change>"