Motion format 0.3

Status: Draft · Version: motion/0.3 · what each version added: §10

What a motion is on disk: the files, their fields and the rules any tool can rely on. This document only grows: a later version adds to it and never changes the meaning of what is here.

#1. What a motion is

A motion is a reusable look for narrated and explanatory video: how a film looks (ground, colour, type) and how it moves (how things arrive, change and leave). It is written so that a person or an agent can make a new film in it with any engine.

A motion holds no film. It has no story, script, scene list, timings or end card. A sample made in it is one example among many.

#2. Files

A motion is a directory named after its slug. A copy taken into a project may sit in a directory of another name (motion/); its slug still names it:

<slug>/
  motion.json      identity, authorship and licence          required
  MOTION.md        how it looks and moves, for agents        required
  tokens.json      colours and faces, in the DTCG format     required
  poster.jpg       one representative frame                  required
  CREDITS.md       fonts, assets and sources                 required
  MOTION.<lang>.md a translation of MOTION.md                optional
  <tool>/          files one tool needs (§7)                  optional

No other file may sit at the top of a motion. Names are exact and case-sensitive.

Where many motions are kept together, a scoped motion's directory sits in a directory named after its scope with an @ before it: @ana/ledger-pencil/ (§3, Identity).

#3. motion.json

A JSON object with these members and no others, except extension members (§7).

#Identity

A motion's id is @<scope>/<slug> when it has a scope, and <slug> when it does not: @ana/ledger-pencil, red-pencil. Two motions under different scopes may have the same slug. Only the owner of a GitHub account publishes under its scope; what an unscoped id means is for the collection that holds it to say (motionhub accepts none: every motion there has a scope). Tools name, fetch and credit a motion by its id.

#Building on another motion

A motion made from another names it in basedOn, by its id and the version it started from: "basedOn": [{ "id": "red-pencil", "version": "1.0.2" }]. This is the credit tools show and follow; CREDITS.md still says what was taken and what changed, as its licence asks. A tool does not require a motion named in basedOn to be at hand.

An SPDX value is an SPDX license expression, for example "CC-BY-4.0" or "MIT".

{
  "spec": "motion/0.3",
  "scope": "ana",
  "slug": "lab-notebook",
  "version": "1.0.0",
  "name": { "en": "Lab Notebook", "zh-CN": "实验手记" },
  "line": { "en": "A squared notebook page where the diagram is drawn stroke by stroke as it is explained." },
  "authors": [{ "name": "Ana", "github": "ana" }],
  "license": { "text": "CC-BY-4.0", "code": "MIT" },
  "tags": ["hand-drawn", "line-art", "light"]
}

#4. tokens.json

The motion's values in the Design Tokens Format Module of the W3C Design Tokens Community Group (DTCG), version 2025.10. Any tool that reads DTCG reads it.

• It has a color group and a font group, each with at least one token.
• color tokens are of type color; font tokens are of type fontFamily. A group may set $type once for its members.
• A token name contains no $, {, } or ., and is written in English (it is an identifier).
• Every colour and face the motion relies on is a token. A token's $description says what it is for, in any language.
• Other groups are allowed and are read as plain DTCG. For timing, use duration tokens and cubicBezier tokens; seconds, not frames.
• Values are literal or DTCG aliases ("{color.ink}"). No value refers to a file or a URL.

{
  "color": {
    "$type": "color",
    "ground": { "$value": { "colorSpace": "srgb", "components": [0.98, 0.98, 0.96], "hex": "#FBFAF5" }, "$description": "the page" },
    "ink": { "$value": { "colorSpace": "srgb", "components": [0.11, 0.16, 0.28], "hex": "#1B2A47" }, "$description": "every line and word" },
    "accent": { "$value": { "colorSpace": "srgb", "components": [0.81, 0.31, 0.2], "hex": "#CF4F33" }, "$description": "the one result, never decoration" }
  },
  "font": {
    "$type": "fontFamily",
    "display": { "$value": ["Shantell Sans", "LXGW WenKai", "cursive"] },
    "sans": { "$value": ["Atkinson Hyperlegible Next", "Noto Sans SC", "sans-serif"] }
  },
  "duration": { "$type": "duration", "enter": { "$value": { "value": 0.6, "unit": "s" } } },
  "easing": { "$type": "cubicBezier", "arrive": { "$value": [0.22, 1, 0.36, 1] } }
}

#5. MOTION.md

Markdown, at most 16 KB, in the language lang names. It is what an agent follows to make a film in this motion, so it describes the look and the motion, never a particular film.

It has a level-two heading for each of these five topics. The heading starts with the English word, which tools match without regard to case; any words may follow it (## Motion 动法).

Any other sections may follow, in any order. A number in the text says where it comes from when that matters: measured, from a source, or chosen.

MOTION.<lang>.md is a translation of MOTION.md into the language <lang> (a BCP 47 tag). It follows the same rules and says nothing MOTION.md does not.

#6. poster.jpg and CREDITS.md

• poster.jpg is a JPEG frame of a film made in the motion: between 960 and 3840 pixels wide, at most 500 KB. It shows the look, not a title card.
• CREDITS.md names every font, image, sound, model or other asset the motion's files use or require, with its licence and where it comes from, and any work the motion learned from. A motion that uses none says so.

#7. Extensions

Everything that belongs to one tool lives in that tool's space, and every other tool ignores it.

• Directories. A tool keeps its files in a directory named after it (react/, remotion/): 2 to 40 characters of a-z, 0-9 and single hyphens.
• Members. A tool keeps its own motion.json members under one member named x-<tool>, for example "x-remotion": { "fps": 30 }.
• Rule. A tool reading a motion ignores directories and x- members it does not know, and does not report them. It never writes into another tool's space.

What several tools come to share moves into a later version of this format.

#8. Languages

#9. Versions

A motion's version changes whenever any of its files change. A published version is never changed: a fix is a new version. A film that uses a motion keeps the copy it took.

spec names the version of this format. A tool that meets a spec it does not know does not guess its meaning. A tool that reads a version reads every version before it: a motion/0.1 motion is a motion/0.2 motion without a scope, and a motion/0.2 motion is a motion/0.3 motion without basedOn.

#10. Versions of this format