AI rules

How to use MOTION.md with Claude Code and Cursor.

MOTION.md tells an AI coding agent how your app moves. With it, a new component gets the same motion as the rest of the app, without hand-tuning. It is complete on its own: the agent needs no other file to follow it.

What is in it

1. Personality. One paragraph from your knob values, for example "Snappy: quick and responsive, with a hair of overshoot, and moderate travel."
2. Hard rules. For example: every clickable element uses press; never write a raw duration or easing; never animate opacity with a spring.
3. Which recipe to use. A table from interface element to recipe: dialogs use overlay, toasts use notify, and so on.
4. Tokens. Every value, with its name in motif.ts and motif.css.
5. Reduced motion. What changes when the user asks for less motion.
6. Wrong vs right. A short example of each.

Claude Code

1. Put MOTION.md and motif.ts (or motif.css) in your repo. The repo root is a good place for MOTION.md.
2. Add this line to your CLAUDE.md, so every session loads the rules:

Follow @MOTION.md for all motion and animation.

3. Ask for components as usual, for example: "Build a confirmation dialog for deleting a project." The agent picks the overlay recipe and imports its values from motif.ts.

Cursor

1. Put MOTION.md and motif.ts (or motif.css) in your repo.
2. Add a project rule in .cursor/rules/ that applies to every request and tells the agent to follow MOTION.md. You can also paste the contents of MOTION.md into the rule.

Codex

1. Put MOTION.md and motif.ts (or motif.css) in your repo.
2. Add the same line to AGENTS.md at the repo root. Codex reads it before each task.

Keep it current

When you change the knobs, export all files again. The header of each file holds a link that re-opens your exact knobs in the playground.