motion-md

Give your AI coding agent a motion personality.

MOTION.md is a plain-text file that defines how your product moves. AI coding agents (Claude Code, Cursor, Codex) read it before generating animated components — ensuring every transition feels consistent and on-brand, no matter who wrote it.

npx motion-md init

One command. Two files in your project root. Every agent, every component, every animation — consistent from day one.

What it creates

your-project/
  MOTION.md    ← your motion personality (enter, drawer, press, stagger...)
  SKILL.md     ← teaches agents motion implementation principles

If you have a CLAUDE.md or AGENTS.md, it's updated automatically to tell your agents to read both files.

Quick start

# Scaffold with the default preset
npx motion-md init

# Or pick a brand personality
npx motion-md init --preset linear     # Fast & confident
npx motion-md init --preset notion     # Calm & considered
npx motion-md init --preset duolingo   # Playful & springy
npx motion-md init --preset stripe     # Trustworthy & smooth
npx motion-md init --preset figma      # Instant & direct

# Validate your MOTION.md
npx motion-md validate

# Generate motion-tokens.ts (TypeScript projects)
npx motion-md sync

Presets

| Preset | Personality | |------------|------------------------------------------------| | default | Balanced — purposeful, nothing overdone | | linear | Fast & confident — snappy, precise | | notion | Calm & considered — smooth, restrained | | duolingo | Playful & springy — bouncy, celebratory | | stripe | Trustworthy & smooth — weighted, premium | | figma | Instant & direct — near-zero motion |

The format

---
motion:
  drawer:
    duration: 400ms # medium4
    easing: cubic-bezier(0.05,0.7,0.1,1)
    slide-from: right
    exit-duration: 220ms
---

## Drawer

Panels open with deliberate weight — this is a context shift,
not a tooltip. The exit is 55% of enter duration.

Each recipe block defines one interaction pattern. The description below the values tells agents why — so they can make consistent decisions even for patterns not explicitly listed.

Full format reference: SPEC.md

TypeScript integration

npx motion-md sync

Generates lib/motion-tokens.ts from your MOTION.md:

import { motionTokens } from '@/lib/motion-tokens'

// In Framer Motion:
<motion.div
  animate={{ x: 0 }}
  transition={{
    duration: motionTokens.drawer.duration,  // 0.4
    ease: motionTokens.drawer.ease,          // [0.05, 0.7, 0.1, 1]
  }}
/>

// Press feedback:
<motion.button
  whileTap={{ scale: motionTokens.press.scale }}  // 0.97
  transition={{ duration: motionTokens.press.duration }}
/>

Add to package.json to keep tokens in sync:

"scripts": {
  "sync:motion": "motion-md sync",
  "check:motion": "motion-md validate"
}

Using with agents

Once MOTION.md and SKILL.md are in your project root, prompt your agent:

Read MOTION.md and SKILL.md then build me a settings drawer component.

The agent reads your motion spec and implements the component using the exact values you defined — not its own defaults.

Claude Code

MOTION.md in the project root is read automatically when your CLAUDE.md references it. Run npx motion-md init — it updates CLAUDE.md for you.

Cursor

Run npx motion-md init — it creates .cursor/rules/motion-md.mdc which enforces motion token usage on every AI edit.

Codex / other agents

Reference MOTION.md from your AGENTS.md:

## Motion system
Read MOTION.md before generating animated components.

Learn more

Learn more at https://craftedby.ai/motion-md

CI integration

# .github/workflows/ci.yml
- name: Validate MOTION.md
  run: npx motion-md validate

Keeps your motion spec valid across the whole team.

Spec

The full MOTION.md format specification is in SPEC.md. The spec is MIT licensed — use it, build tools around it, publish your own MOTION.md files.

Contributing

Contributions welcome. See SPEC.md for the format.

Issues: https://github.com/edmill/motion-md/issues

License

MIT © edmill