micro-motion

name	micro-motion
description	Use when an interface needs purposeful feedback, transitions, or reduced-motion behavior, especially when animation risks jank, interruption bugs, or hidden no-JS content.

Micro-Motion

Motion confirms a change, its origin, or what to notice next. If it answers none of those, cut it.

Non-negotiables (the rules that keep motion feeling good)

• Prefer compositor-safe properties. Start with transform and opacity. Color, filter, SVG, or measured layout transitions are valid when the purpose requires them and a performance trace shows the target device can sustain the interaction.
• Ease by direction. Ease-out enters, ease-in exits, ease-in-out moves; linear is for a purposeful continuous loop only.
• Design reduced motion as an equivalent state. Keep labels, choices, focus, and final content; remove spatial movement.
• Let JavaScript opt individual elements into waiting states only after the observer is ready. Static CSS must not leave content hidden when JavaScript fails, initializes late, or restores from the back-forward cache.
• Make looping motion controllable and never scroll-jack.

Easing & duration tokens

Use semantic duration/easing tokens: acknowledgement 120–160ms, insertion/menu 160–220ms, confirmation/route 220–320ms. Treat these as starting bands and test on the target device. Motion never delays committed state, focus, or the next keyboard action.

Settle before styling

Define the usable end state and interruption policy before choosing an entrance. A superseded save, route, insertion, or dismissal must converge on the newest state without a stale overlay, announcement, focus jump, or success message. Motion reflects state ownership; it does not decide it. If ownership or focus recovery is unknown, hand off to component-states before choreographing.

The reduced-motion contract

Define the project-level reduced-motion policy once, then let components reference it. For progressive reveals, content starts visible. After the observer is attached, JavaScript marks only offscreen pending elements; never hide an element already intersecting the viewport. It removes the marker on reveal and on page restoration. Gate spatial movement behind no-preference:

/* JavaScript marks only non-intersecting elements after the observer is ready. */
.reveal[data-reveal="pending"] { opacity: 0; }
.reveal:not([data-reveal="pending"]) { opacity: 1; }
@media (prefers-reduced-motion: no-preference) {
  .reveal[data-reveal="pending"] { transform: translateY(12px); }
  .reveal { transition: opacity var(--dur-base) var(--ease-out),
                        transform var(--dur-base) var(--ease-out); }
  .reveal:not([data-reveal="pending"]) { transform: none; }
}

For a legacy retrofit only, the emergency global kill switch in references/principles.md is permitted after documenting why the primary pattern cannot be used; it removes useful transitions, so it is not the default.

Decision order

1. Name the user-facing purpose: acknowledgement, continuity, spatial origin, or attention.
2. Name trigger, settled state, focus timing, and what wins when interrupted.
3. Choose the smallest property, duration, and easing that communicate that purpose.
4. Define reduced-motion and no-JS/restoration equivalents.
5. Replay rapid repeat, cancellation, navigation, and stale async completion.

For async feedback, tag each request and let only the current owner update status or its live announcement. For routes and overlays, cancel superseded animation and make the destination DOM and focus authoritative. For list changes, preserve readable DOM order even when visual movement is interrupted.

How to deliver

Deliver a compact choreography table: interaction, purpose, trigger, duration/easing, settled state, interruption rule, and reduced equivalent. Add one global safety row for JS-disabled and restoration behavior. Default to CSS; use a library when gestures, springs, or layout coordination justify its runtime and ownership complexity.

Self-check

• Properties are compositor-safe, or an intentional alternative has a target-device trace
• Durations/easings are tokens (--dur-*/--ease-*); entrances ~200–300ms ease-out (custom curve, not linear)
• prefers-reduced-motion path tested (motion off or cross-fade) — content never depends on it
• Page reads complete with JS disabled, delayed initialization, and bfcache restore; pending markers are added only to offscreen elements after observer ownership and cleared on pageshow
• Rapid repeat, cancellation, stale completion, and navigation converge on the current usable state without stale focus, status, or layers
• No scroll-jacking or uncontrolled loops; flashing stays below the safety threshold
• Evidence names the tokens, settled state, reduced equivalent, and replay result

Contract (generated)

Canonical detail: contract.json.

• Route: An interface needs purposeful transition, feedback, choreography, or reduced-motion behavior.; avoid: The request is only static visual styling or decorative animation without an interaction purpose.
• Exclude: Do not add motion without a user-facing purpose. (+2 in contract.json)
• Stop / handoff: Stop when no purpose or interruption policy exists. (+1 in contract.json); receives [component-states, design-system-interview, deslop-ui, tasteroll] -> sends [a11y-pass, tastecheck-pass]
• Output: purposeful motion choreography and token plan
• Evidence: table_with_evidence with status, reason, remediation, evidence, provenance.