Motion Craft

Motion Craft

Every animation must serve feedback ("it worked"), continuity ("that's where it went"), or hierarchy ("look here"). An animation serving none of the three is removed, not tuned. When in doubt: shorter, subtler, or none.

1. Duration budgets

Numbers first; taste second. Defaults for product UI:

| Surface | Budget | |---|---| | Hover / press feedback | 90-160ms | | Tooltip, micro popover | 80-200ms | | Dropdown, select, small panel | 150-250ms | | Accordion, tab switch | 160-240ms | | Card / list item entrance | 180-350ms | | Modal, drawer, sheet | 200-400ms | | Route / page transition | 240-500ms |

• **Standard interactions stay under 300ms; nothing in product UI exceeds

500ms.** A 180ms dropdown reads as more responsive than a 400ms one.

• Exit = 65-75% of entrance. Leaving is confirmation, not an event.

The rows above bound ENTRANCES; a rule-derived exit may drop below its row - that is the intent, not a violation.

• Distance scales duration: 100px is the base; 200px ~1.3x, 400px ~1.6x,

full-screen ~1.8-2.0x. Small moves at long durations read as lag.

• Frequency scales duration DOWN. An action done 100 times a day

approaches instant. Hard sub-rule: never animate keyboard-initiated actions - they repeat hundreds of times daily and animation makes them feel disconnected from the keystroke. ❌ "the command palette fades in over 250ms - it looks polished in the demo." ✅ keyboard-opened palette appears instantly; its pointer-opened twin may animate.

• Trigger for this section: any duration you are about to write, or any

existing duration outside the table. Done when every duration in the diff sits inside its row's budget or carries a written justification.

2. Easing

| Direction | Curve | Why | |---|---|---| | Enter | ease-out | fast start = instant feedback, soft landing | | Exit | ease-in | soft start, fast leave | | On-screen move / morph | ease-in-out | smooth both ends | | Spinners, progress, marquee | linear | mechanical processes read linear |

• **Never linear for finite point-to-point movement; never ease-in for

entrances.** Continuous mechanical motion - spinners, progress bars, marquee loops - is the linear exception the table names, not a contradiction of it. An ease-in dropdown at 300ms feels slower than ease-out at the same 300ms: it delays movement in the exact frames the user watches most closely.

• Named defaults: Material 3 standard cubic-bezier(0.2, 0, 0, 1); M3

emphasized-decelerate cubic-bezier(0.05, 0.7, 0.1, 1); Core Animation's kCAMediaTimingFunctionDefault / CSS ease is cubic-bezier(0.25, 0.1, 0.25, 1) - Apple's HIG publishes principles, not bezier tokens, so any "Apple HIG curve" value circulating online is reverse-engineered, not vendor-published. Two mislabels to refuse: (0.4, 0, 0.2, 1) is Material 2's standard routinely pasted as "M3", and (0.25, 0.1, 0.25, 1) labeled "the Apple HIG default" is the CSS ease curve wearing a vendor costume.

3. Springs and gesture physics

• Spring parameters below are Framer Motion-convention coefficients

(stiffness + damping). Two unit traps: React Spring parameterizes as tension/friction, not these; and a damping ratio (where `.

• Gate hover motion behind @media (hover: hover) and (pointer: fine) -

touch devices fire false hovers on tap.

6. Reduced motion is a floor, not a feature

• Every animation ships a prefers-reduced-motion variant. Reduced means

fewer and gentler, not zero: keep opacity/color transitions that aid comprehension; drop movement - slide+fade -> fade; scale+fade -> fade; spring -> short tween; parallax and auto-playing loops -> removed. Transform-based full-screen motion is the highest-cost vestibular trigger - it is exactly what this media query exists for.

• Motion is never the only signal of a state change: pair it with a static

affordance (color, position, label) or reduced-motion users miss the change entirely.

7. Misquoted research - do not cite these wrong

These corrections are adapted from open-design's primary-literature review (Apache-2.0; adaptation notice in THIRD-PARTY-NOTICES). The papers were NOT re-opened for this pack - each line below is that review's checked claim, restated, not this pack's own reading of the source:

• "Skeleton screens feel 11% faster" - per that review, Harrison/Yeo/

Hudson (CHI 2010) measured backwards-decelerating ribbed progress bars (n=16), not skeletons; the mechanism does not transfer.

• "Doherty threshold = 400ms" - per that review, the source contains no

400ms figure; the lowest measured threshold is 300ms. And cite the source itself correctly: Doherty & Thadhani, "The Economic Value of Rapid Response Time", IBM technical report GE20-0752 (1982) - the "IBM Systems Journal 1982" venue and the "Thadani" spelling circulating online (and in the review this pack adapted) are themselves miscitations, corrected here.

• "Heer & Robertson recommend 300-1000ms transitions" - per that review,

they tested 1.25s and 2s only, and recommend roughly one second per animated stage.

• Motion confirms state changes; it must not perform them. Optimistic

UI first, animation second.

8. Pre-ship gate

Run against the built surface, not the source: trigger each interaction and watch it. Severity-tiered; every CRITICAL verified by observation before "done".

• CRITICAL: reduced-motion variant exists and was toggled on and

observed; nothing exceeds 500ms (unless the When-NOT spectacle exception was invoked in writing - the purpose test and reduced-motion floor still bind there); no spring fails to settle; no keyboard-initiated action animates; no transition: all.

• HIGH: durations inside §1 budgets; easing direction per §2; exits

faster than entrances; layout-property animation absent.

• MEDIUM: stagger within budget; transform-origin set for scale;

consistent timings across sibling components; overshoot within §4 context budget.

Done when: every CRITICAL item observed passing, HIGH items pass or carry a written exception, and any failure names the rule it broke (not "feels off").

When NOT to use this skill

• Debugging one library's API surface -> that library's docs; this file owns

budgets and judgment, not APIs.

• Static layout/type/color decisions -> ui-design-craft.
• Running a full design review with measurement and fix loop ->

design-review-gate (its motion pass applies this file's budgets).

• Marketing hero choreography on a page whose brief explicitly buys

spectacle: §1 caps may be exceeded there, deliberately and in writing - the purpose test and reduced-motion floor still apply.

Provenance

Composed 2026-07-19 for design-pack 0.1.0. Sources, all verified in their repos at composition time: Emil Kowalski's emilkowalski/skills (MIT) - duration budgets, keyboard rule, stagger numbers, Framer shorthand and CSS variable performance traps, Apple-derived projection / rubber-band / velocity handoff forms (his distillation of Apple WWDC material; formulas quoted from his files); LottieFiles motion-design-skill (MIT) - element duration table, distance-duration multipliers, exit ratio, stagger and overshoot budgets, severity-tier gate shape (their damping-units conflation is corrected here, not copied; §1's duration rows are envelope syntheses across the three motion sources, not quotes of any single table); referodesign/refero_skill (MIT) - purpose triad, easing direction table, reduced-motion mapping, transition: all ban. §7's corrections and the M2/M3 mislabel are adapted from nexu-io/open-design's craft/animation-discipline.md primary-source review (Apache-2.0; the correction items keep that review's selection, figures, and framing - an ADAPTATION carried with notice in THIRD-PARTY-NOTICES, not an ideas-only borrow). The primary papers were not independently re-opened for this pack, with one exception: the Doherty citation itself (report GE20-0752, "Thadhani") is this pack's own correction of the review's miscite. greensock/gsap-skills was surveyed and deliberately not mined: library-usage doctrine, out of scope here. Numeric values (beziers, spring pairs, budgets) are the volatile facts - re-verify beziers against the published Material 3 motion tokens (m3.material.io) and, for Apple, the SwiftUI Animation API's actual values (the HIG publishes no numeric curves); spring pairs against the Framer Motion / Motion docs - on major vendor releases. Probe status: probe-tested 2026-07-19 on a private over-budget motion-spec fixture (fresh weak-tier agent, n=1 per arm, smoke grade): the bare arm caught ~3 of 7 planted violations, loosely phrased - though it did catch the missing reduced-motion variant, recorded honestly - while the ruled arm caught 7 of 7 with budget citations, including the keyboard rule and the 500ms total-stagger cap the bare arm lacked as concepts. A round-0 run was voided for a leaked in-fixture answer key. Trail in the design-pack PR.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: F-e-u-e-r
• Source: F-e-u-e-r/opus-pack
• License: MIT

Install and usage instructions live in the source repository linked above.