motion.md

An open, tool-neutral way to describe a brand's motion language — so a person or an AI can match it.

Status: request-for-comment — now with numbers. The thesis and the shape came first; as of August 2026 one leg of the bet is measured rather than argued. See What's been measured. The parts that are still unproven are marked as such, and disagreement is still the useful part.

---

The problem

Design systems govern color, type, and spacing with tokens — portable, named, machine-readable values that any tool and any AI can read. Motion is the one foundation that never got the same treatment. It lives in a PDF, a Notion doc, or a 47-slide deck: it describes motion, but it doesn't govern it.

That gap is why off-the-shelf AI motion "never works" for a brand with a real motion identity — with nothing to match against, it animates a careful brand like PowerPoint. The fix isn't a better model. It's giving motion the same legible, portable substrate the rest of the design system already has.

The wager. The defensible bet isn't documenting motion — proprietary tools already do that. It's that one tool-neutral token schema can capture brand choreography across radically different motion engines — an After Effects bézier, a Cavalry easing, a spring — without flattening them into mush — and that an AI briefed on it then matches brand motion where vanilla AI fails. This can lose: if no single schema holds across tools without lossy compromise, motion.md collapses into just another per-tool format and the premise is dead. The whole project is an attempt to prove that bet true (or kill it cheaply).

Appetite. An open standard, but built in days-scale probes, not a spec committee — one adapter at a time, easiest tool first (Cavalry, because .cv is already JSON), proving the schema on real motion before widening. If the round-trip doesn't hold early, that's the signal to stop, not to spec harder.

What motion.md is

Two layers, deliberately separated:

1. A token vocabulary — named, machine-readable motion values: durations, easings, springs, multi-step sequences, transition patterns, pacing ranges. Built on top of the W3C Design Tokens standard where it already covers the primitives (duration, cubicBezier, transition), and extending it where the standard stops.
2. The motion.md artifact — a per-brand document (the motion sibling of design.md) that pairs those tokens with prose principles, do/don'ts, intent, and a reference library. It's written to brief a junior editor and an AI equally well.

Tokens are the what; the artifact is the why and when.

Why a new standard instead of an existing one

The W3C Design Tokens spec (stable, 2025) defines the motion primitives — a single property easing from A→B. It explicitly leaves out of scope the layer where brand motion actually lives:

• Springs / physics-based motion (stiffness/damping, not a bézier)
• Keyframe / multi-step sequences (anticipation → action → follow-through; overshoot-and-settle; staggers)
• Named motion patterns (a brand's signature reveal — a reusable choreography, not a raw curve)
• Intent (why something moves: clarify, guide, confirm, warn, celebrate, reveal)

motion.md is a superset: adopt DTCG for the primitives so tokens stay interoperable, and standardize the choreography layer on top. (We're also raising this gap upstream in the DTCG working group — the goal is convergence, not a fork.)

Real prior art at the choreography layer, and where it stops. DesignMD's Motion catalog and LottieFiles' Motion System both already ship named spring presets, easing curves, and stagger/transition patterns — copy-ready, MCP-servable, genuinely useful. Both are built the same way: reverse-engineered from observing already-public products (Stripe, Linear, Airbnb, and so on). That's the right tool when the brand you want is already famous enough to watch. It's the wrong tool for a brand that isn't public yet — there's nothing to reverse-engineer from a motion language that only exists in someone's own project files. motion.md's bet is the tier underneath: tokens measured from a brand's real source material, not inferred from what ships. The two aren't competing for the same brand; they're solving different ends of the same problem.

Tool-neutral on purpose

This standard is not pinned to any one app or runtime. Not After Effects, not Premiere, not Lottie, not Cavalry, not whatever AI-native motion tool ships next year. The motion stack is being reshuffled fast; a standard that hard-codes one tool's internals inherits that tool's mortality.

The model:

        motion.md  (tokens + brand artifact — tool-neutral)
              ▲                         │
   extract    │                         │   apply / QA / generate
              │                         ▼
   ┌──────────┴───────────┐   ┌──────────────────────────┐
   │ adapters (per tool)  │   │ consumers (per tool/AI)  │
   │ AE · Cavalry · …     │   │ review skills · gen · …  │
   └──────────────────────┘   └──────────────────────────┘

Each tool gets an adapter that reads its motion (keyframes, easing, timing) and emits the same neutral token JSON. If one schema cleanly absorbs, say, an After Effects bézier handle and a Cavalry easing and a spring, the vocabulary is proven tool-neutral. That shared output contract is the whole game.

What's been measured

A working pipeline now takes an After Effects project, extracts every animated property, compiles it to a motion.md token block, and then rebuilds the animation from that token block alone, in a different runtime, and diffs the rebuild against After Effects' own frame-by-frame output.

The token block is the only thing that crosses between the two arms. So anything the rebuild can't reproduce was dropped at the token layer — which is exactly the thing this project needs to measure and the one thing it can't fake. (The pipeline is applied work and stays private. The conversion rules and the numbers don't need to be.)

Fidelity:

• One composition — five of seven animated properties reproduce After Effects exactly. Worst case 0.235% of its own range. 59.16 dB PSNR between the two rendered arms.
• An 11-composition family — 71 animated properties, worst error 0.0541%, nothing over 0.5%.

Springs — bounce ≡ 1 − dampingRatio, exactly. Confirmed two independent ways against a shipping tool: its own physics→normalized converter returns it with zero error across 14 mass/stiffness/damping combinations, and inverting the curves it emits recovers it to 3.2 × 10⁻⁵. The designer-facing form and the physics form are the same information. That closes an open question this README used to carry. (Posted upstream.)

Three findings the spec now carries because of this, all tool-neutral:

• The After Effects curve conversion. AE doesn't store control points — it stores a (speed, influence) pair per keyframe side. The conversion, and the fact that spatial Position is walked by arc length through a bezier in space rather than interpolated per-axis, are both in AUTHORING.md. Per-axis interpolation gets the speed wrong even when the path is straight, and it looks fine while doing it.
• Emit keyframe times as frame numbers, not rounded seconds. At 30fps every frame boundary is a repeating decimal; four-decimal seconds land a rebuild a few thousandths off at exactly the keyframe. That change alone cut the worst positional error 25×. Cheapest accuracy in the pipeline.
• A limit of the token form, recorded honestly. A segment whose endpoint values are equal but which carries non-zero tangent speed encodes real drift, and a unit cubic-bezier collapses when its endpoints match. CSS and web runtimes inherit the same limit. It's in spec/tokens.md as a known limit, not quietly rounded away.

What this doesn't prove. Two source tools producing the same token JSON is the actual neutrality test, and Cavalry is still untested — so this is one leg, not the proof. And fidelity isn't usefulness: nothing here shows that a motion.md makes a human or an AI match a brand better. That's bar 2 below and it hasn't been run.

Method, math, and the defects each rule came from: knowledge/research/2026-08-21-token-roundtrip-fidelity.md.

The hard part

Three things could sink this:

• The schema might not hold. AE handles, Cavalry's easing, and springs are genuinely different math. (First data point: the AE leg came back clean — see above. Cavalry is the one that matters and it hasn't run.) The bet is that one representation absorbs all three without flattening — but it might not, and the rabbit hole is "fixing" that by quietly lowering every motion to a bézier, which would technically validate while destroying the thing that made the motion branded. If the schema can't stay faithful across tools, the honest move is to say so.
• Choreography may be irreducibly per-brand. DTCG punted on named patterns and sequences for a reason — they're hard to generalize. It's possible the choreography layer only ever expresses one brand's motion and doesn't standardize. That would still be useful (a per-brand motion.md is valuable on its own) but it wouldn't be a standard.
• A standard with no users is a doc. Adoption isn't in our control. The DTCG-convergence path is the hedge, but the working group may decline, and external implementers may never show up. We treat that as a real risk, not an afterthought.
• A native tool format could become the de-facto standard. Figma now ships motion with timeline, easing variables, and CSS/JSON/motion.dev export (Config 2026) — the way their design variables quietly became the design-token default. If their motion JSON becomes the format everyone targets, a separate open spec gets steamrolled. The hedge is the founding constraint: stay tool-neutral, align primitives to DTCG, treat Figma as adapter #1 (ride the rails), and own the cross-tool, brand-choreography layer a single-app vendor has no reason to build.

Non-goals

• Not a renderer or a player. It describes motion; it doesn't draw it.
• Not an interchange or runtime format. Delivery formats — a tool's native scene file, an exported clip, a vector animation — carry one finished animation. motion.md carries the language a thousand of them should share. It composes with whatever you deliver in; it doesn't compete with it.
• Not AI-generated motion-from-nothing. The near-term value is making motion legible (so humans stay consistent and AI can brief/QA against it). Generation is a downstream maybe, not the premise.

How we'll know it worked

Concrete bars, not vibes:

1. The round-trip holds. A known motion — a settle, an overshoot, a staggered entrance — authored both in Cavalry and in After Effects, extracted through their adapters, produces the same token JSON, with no lossy flattening. This is the tool-neutrality proof; without it, nothing else matters. (Half-cleared: After Effects → tokens → a different runtime is measured and near-exact. The second source tool is the missing half.)
2. The brief beats vanilla. In a blind review, an AI given a brand's motion.md catches motion violations that the same AI without it misses. That's the whole reason-for-being, made testable.
3. Someone else picks it up. An adoption signal outside our own walls: the DTCG working group engages the choreography proposal, or at least one external implementer files an issue or uses the format. A standard is only a standard if it travels.

Open questions

• Does the choreography layer (named patterns, intent) generalize across brands, or is it irreducibly per-brand? (Determines whether this is a standard or a great per-brand artifact.)
• Where exactly is the line between motion.md and DTCG — how much pushes upstream vs. stays a documented superset?
• Spring representation: which model — designer-facing or physics? Answered: both, they convert exactly (bounce ≡ 1 − dampingRatio). The live question underneath it is harder — when is a spring finished? Tolerance, method, and reference are each a silent per-tool choice, which means a spring's duration doesn't survive a copy between tools. Should a spec make that threshold normative?
• Is intent a token property, or only an annotation in the artifact layer?
• Does Figma's motion JSON become the de-facto format — and if so, do we converge on it the way we converge on DTCG, or stay deliberately above it? Does Figma Motion read/write DTCG-style tokens, or only its own variables?

Status & roadmap

• Thesis + layered model (this doc)
• Token vocabulary v0 — primitives (DTCG-aligned) + first choreography types (spring, keyframe sequence) — primitives locked to DTCG; spring pinned to params with an exact designer↔physics conversion; sequence/base/track group shaped by real extraction. Remaining: the time-unit rule written up as normative, and pattern/intent.
• motion.md artifact template (prose + tokens + reference library)
• Reference adapter: Figma Motion (JSON / motion.dev export, MCP-readable) — round-trip validated twice by hand through the Plugin API (keyframes, then springs); no packaged adapter yet. Read the authoring model, not the export: the export flattens springs.
• Reference adapter: Cavalry (.cv is JSON-native + scriptable)
• Reference adapter: After Effects (ExtendScript → token JSON) — the non-token-native case. Built and measured: extraction → tokens → rebuild in a different runtime, near-exact. The implementation is applied work and stays private; the conversion rules are public in AUTHORING.md.
• Interop: map the token schema cleanly to/from motion.dev (Figma's web-motion export target)
• Validator / CLI (does a motion.md / token file conform? lint · export to DTCG)
• Authoring guide (AUTHORING.md, v0) + examples/ (format-by-example)
• Generic authoring skill in .agents/skills/ (procedure + gates that travel with the format)
• DTCG upstream: choreography token-type discussion — issue #429 is open and live; the spring-threshold findings went back into that thread rather than staying here.

History

This didn't start as a public spec. It began as internal R&D — exploring whether a brand's motion language could be codified the same way design.md codifies its visual one — inside a creative agency, starting June 2026. The open, tool-neutral standard was forked out to live here on 2026-06-19, once it was clear the schema itself (not any one brand's application of it) was the reusable, general part; the applied side — real-brand motion.md files, tool-specific extraction, client source material — stays in a private repo, deliberately. Same split as Throughline: fork the neutral spec out, keep the applied work private.

August 2026 — it stopped being a document. An extraction pipeline got built on the applied side and run against real source material: .aep → tokens → rebuild → diff. That produced the first numbers this repo has ever had, plus a second Figma round-trip that pinned the spring conversion. Everything client-specific stayed on the private side; the math, the rules, and the aggregate results are here and upstream.

The dated build log lives in knowledge/journal/ — real sessions, real dates, including the AE↔Figma Motion round-trip that drove the sequence/base/track group refinements in the current token vocabulary. Also live and public: DTCG community-group issue #429, raising the choreography-token gap upstream — the convergence path this spec is betting on, not a fork for its own sake.

Contributing

This is a request for comment as much as a spec. If you build motion systems — in any tool — the disagreement is the useful part. Open an issue: where does this break for your pipeline, your tool, your brand?

License

The specification and documentation are CC-BY-4.0 — implement it freely in any tool; attribution appreciated. Reference tooling added later (adapters, validator) will carry Apache-2.0 — the conventional spec/code split for an open standard.

---

motion.md is the motion sibling of design.md. Knowledge is the asset.