motion-design

Motion Design

Motion is the strongest attention tool an interface has. Used well, it explains what happened. Used by default, it becomes a tax users pay on every visit.

Start here

1. Read references/_shared/experience-core.md.
2. Read references/_shared/experience-operating-contract.md; meaningful motion changes require

rendered or explicitly unverified evidence. Hand off only an unresolved material concern.

1. Keep references/_shared/motion-events.md open. Every animation must map to one of its events.

<!-- core-brief:start · GENERATED FROM shared/philosophy/core-brief.md by npm run sync. Do not edit here. --> Core rules in brief. These apply even before you open references/_shared/experience-core.md. Read that file (the full rules and evidence levels) before a full review, repair, or build.

• Verdict before adjectives. Do not write "clean," "modern," "great idea," or "looks good" until

an observation earns it. The user's enthusiasm is not evidence; test the proposal against the goal.

• Evidence levels on findings. E1 rendered, E2 measured, E3 source, E4 documented,

E5 screenshot, E6 assumed. If files, a browser, or a terminal are available, look or measure before claiming. Otherwise, name the checks you did not run.

• Composition is not alignment. Empty space needs a stated job, and sparseness is never fixed

with filler (stats, tips, promos, decoration).

• Personality can come from the environment and causal product behavior. A standard control

changes only if the change makes the task faster or more reliable.

• Every treatment has a job. Every gradient, card, shadow, and animation needs one. No pattern

is wrong by category, so keep one that does a job.

• Count steps before and after. If the software already knows an answer, do not ask for it.

Keep safeguards on money, deletion, and publishing. Automate mechanics, not judgment.

• Check real states, not the showcase: empty, dense, long content, loading, error, a small

screen, the keyboard path.

• Route selectively. Consider the relevant experience skills; activate another only when it

can resolve a material concern. No change and no handoff are valid outcomes.

• Render meaningful work when a runnable surface exists. Inspect before and after, stress real

states, and say NOT VERIFIED IN RENDERED OUTPUT with the reason when rendering is skipped.

• Load depth conditionally. A direction, composition, workflow, control, state, motion, or

anti-slop branch must load its required reference before recommendation or edit; unrelated work must not load the whole library.

• A large specification is a bigger evidence base, not a bigger checklist. Preserve exact

numbers, exceptions, and locked decisions; keep recommendations, examples, and deferred items from becoming requirements; compress for reasoning, re-open the source for precision. <!-- core-brief:end -->

Use this when

• Everything fades, slides, or scales in the same way regardless of meaning.
• Important changes (a score, an accepted answer, a moved task) happen without users noticing.
• A live, playful, or interactive product feels flat.
• Motion is slow, blocks input, stutters, or ignores reduced-motion settings.
• A product needs motion tokens or a motion language.

Do not use this when

• The real problem is missing states → state-design first.
• The request is "add some animation" to a static page with no events. The right answer may be

very little motion; say so.

Mandatory conditional loading

If motion is proposed, MUST load references/event-motion.md and references/_shared/empty-and-lifecycle-states.md and map each animation to an event. If it affects layout, duration, or accessibility, MUST load references/reduced-motion-and-performance.md. If the surface is runnable, MUST run the rendered motion check or report NOT VERIFIED IN RENDERED OUTPUT.

Checkpoints

1. For every existing animation: which event from the motion-events taxonomy does it explain?

None → remove it (page load, "element exists," and hover on non-interactive content are not events). references/anti-patterns.md lists the usual suspects.

1. For every meaningful state change with no motion: would users miss it (someone else's action,

a reorder, a transfer)? Yes → give it event motion (references/event-motion.md; anchor references/_shared/motion-that-explains.md).

1. For every motion you add: how often does it play? Many times per session → under ~150 ms

and subtle. Longer than ~400 ms → it must be a rare moment and skippable.

1. Does any motion delay input? Yes → make it interruptible (references/tokens-sequencing-interruption.md).
2. Does every meaningful motion have a reduced-motion alternative that keeps the information?

No → add it before finishing (references/reduced-motion-and-performance.md).

1. Does anything animate layout properties (width, height, top, left, margin) or use

transition: all? Yes → switch to transform/opacity or FLIP. Run scripts/scan-motion.mjs.

1. When a browser is available, run `scripts/check-motion-rendered.mjs`: it lists the animations that actually run, with and without reduced motion. Anything still running under reduced motion is a defect unless it carries essential information another way.
2. Choose one motion language from references/_shared/motion-languages.md derived from the product's world, and name its tokens before specifying events.

1. Character and restraint: motion can create energy while explaining change. Match its snap, elasticity, or spatial movement to the product and action frequency; use a short causal response for a signature product moment. Do not turn “unnecessary motion” into a ban on personality. A no-motion decision is valid when feedback remains clear; reduced motion retains the information.

Workflow

1. Inventory events on the surface: what happens, who causes it, how often, how important.
2. Audit existing motion in the rendered product and in code:

   node scripts/scan-motion.mjs src/

Signals, not verdicts: layout-property animation, transition: all, long or infinite animations, missing prefers-reduced-motion.

1. Apply checkpoints 1–3 to decide what stays, goes, and gets added.
2. Specify each important event with the event spec format in

references/tokens-sequencing-interruption.md (trigger, origin, destination, responders, beats, tokens, reduced-motion alternative).

1. Load depth as needed:

1. Implement with CSS transitions / Web Animations API or platform equivalents; a library only

when it earns its weight. Tokens defined once.

1. Verify: normal and slowed speed; rapid and simultaneous triggers; reduced motion on;

CPU throttling.

Execution rules

• Remove motion from non-events before adding motion to events.
• One motion language: shared tokens, consistent directions (mirrored in RTL where directional).
• No large auto-playing motion or parallax on utility surfaces.
• Nothing flashes more than three times per second.

Precedent

Platform guidance and the few observable product behaviors are collected in references/_shared/motion-guidelines.md (Apple HIG and Material transitions, labeled as documentation). Motion is hard to observe in static research; treat that module as guidance.

Failure modes

• Animation soup; choreography tax; celebration inflation; unexplained change; no off switch; jank.

Completion criteria

• Every remaining animation maps to a named event, or is ambient motion with a stated job.
• Meaningful silent changes now have proportionate motion.
• Durations and easings come from tokens.
• Reduced-motion alternatives preserve the information.
• Motion is interruptible and did not add jank (checked, or listed as unverified).
• The event map and motion language record reduced-motion behavior. Hand off only unresolved

concerns; runnable motion was rendered and checked, or is explicitly marked NOT VERIFIED IN RENDERED OUTPUT.

References

• references/event-motion.md — philosophy, event recipes, spatial continuity
• references/tokens-sequencing-interruption.md — tokens, event spec format, interruption
• references/feedback-celebration-ambient.md — feedback, celebration, ambient
• references/reduced-motion-and-performance.md — accessibility and performance
• references/anti-patterns.md — motion slop in practice
• scripts/check-motion-rendered.mjs — running animations under normal and reduced motion
• references/_shared/ — generated copies: experience-core.md, experience-operating-contract.md,

motion-events.md, motion-that-explains.md, motion-languages.md, motion-guidelines.md