deckhearth/docs/MOTION_SYSTEM.md

Motion system — Deck Hearth

Reference for the motion-token surface and the prefers-reduced-motion contract. Motion tokens are defined in styles/globals.css alongside the design-tokens and consumed as var(--motion-duration-…) / var(--motion-ease-…).

Why bother

Motion shapes how an app feels more than any other surface. Loose animations (random durations, jittery easings, no reduced-motion respect) read as amateur. The 4-tier taxonomy here exists so every new animation lands in one of four buckets — never an arbitrary duration — and every animation is reduced-motion safe by default.

Duration taxonomy

Four discrete durations + an instant escape hatch. Pick the bucket that matches the meaning, not the visual feel.

Token	Value	Use	Examples
--motion-duration-instant	0ms	Theme/route transitions where any duration is wrong; hover state for keyboard-only users	Color flips on data-theme change
--motion-duration-quick	150ms	Hover, focus, micro-feedback. Snappy enough that users don't perceive it as animation	Button hover scale, focus-ring fade-in
--motion-duration-default	250ms	Default for state transitions. The token most CSS transition: blocks should reach for	Card hover, link color, glass-surface opacity
--motion-duration-slow	400ms	Entering/exiting layout surfaces. Slow enough to read; fast enough not to feel sluggish	Modal scale/opacity, sidebar drawer slide, popover open
--motion-duration-deliberate	600ms	Hero moments, celebration, onboarding. Use sparingly — feels heavy if overused	Empty-state illustrations, scanner success confetti

Rule of thumb: if you can't justify why a duration is not default, use default.

Easing taxonomy

Three curves. Two ease-outs (one calm, one playful) plus linear for progress indicators.

Token	Curve	Use
--motion-ease-out	cubic-bezier(0.16, 1, 0.3, 1)	Default for entrances + state changes. Decelerates softly — reads as "settling."
--motion-ease-spring	cubic-bezier(0.34, 1.56, 0.64, 1)	Slight overshoot for delight (button press, modal open). Use only when the motion is the point — sparingly.
--motion-ease-linear	linear	Progress indicators (spinners, loading bars). Any non-linear curve here implies state change, which is wrong for a progress affordance.

Composition recipes

Recipe	CSS
Default hover	transition: all var(--motion-duration-quick) var(--motion-ease-out);
Default state change	transition: var(--motion-duration-default) var(--motion-ease-out);
Modal enter	transition: opacity var(--motion-duration-slow) var(--motion-ease-out), transform var(--motion-duration-slow) var(--motion-ease-spring);
Sidebar slide	transition: transform var(--motion-duration-slow) var(--motion-ease-out);
Loading spinner	animation: spin var(--motion-duration-deliberate) var(--motion-ease-linear) infinite;

The prefers-reduced-motion contract

WCAG 2.2 SC 2.3.3 Level AAA: provide a mechanism for users to disable non-essential motion. Operating systems already expose this preference; @media (prefers-reduced-motion: reduce) reads it and we honor it.

The site-wide rule in styles/globals.css collapses every animation

• transition to 0.01ms when the user has reduced motion enabled. End-states are preserved (vs animation: none which can flicker).

When motion is essential

Some motion is essential to communicate state — a loading spinner indicating in-flight work, an actively-scanning camera reticle. For those, add the .motion-essential class to the animating element (or to a parent — children inherit via .motion-essential *):

<div class="motion-essential">
  <svg class="animate-spin">…</svg>
</div>

Use this only when stopping the animation would hide meaningful state. A purely decorative bounce or shimmer is NOT essential — leave it to collapse with reduced motion.

Current motion-essential consumers

None yet — when sub-convoy #5 (liquid-glass-card-surfaces) lands the scanner reticle as a glass-aware motion, it will be the first documented consumer.

Audit of existing animations

These keyframes pre-date the motion taxonomy and continue to play under the per-class rules in styles/globals.css:

Animation	Duration (legacy)	Status
mythic-sparkle	4s infinite	Decorative, collapses under reduced motion. Reconciled with glass in #5.
rare-shimmer	3s infinite	Decorative, collapses under reduced motion.
uncommon-twinkle	2.5s infinite	Decorative, collapses under reduced motion.
enchanted-rainbow	3s infinite	Decorative, collapses under reduced motion.
float (logo)	4s infinite	Decorative, collapses under reduced motion.
fire-glow (page background)	12s infinite	Scheduled for deletion by cleanup-legacy-design-css (#8). Replaced by localized ember-float on landing hero only.
ember-float	10s linear infinite	Kept for landing hero accent. Collapses under reduced motion.

Adding a new animation

1. Pick a duration token — never a literal ms value.
2. Pick an easing token — never a literal cubic-bezier.
3. Test with the OS reduced-motion preference toggled ON. The animation should collapse without breaking the layout.
4. If the animation is essential, wrap in .motion-essential and document the why in a code comment.

Related convoys

• .convoys/motion-system-pass.md — this convoy.
• .convoys/liquid-glass-design-tokens.md — token surface motion lives in.
• .convoys/cleanup-legacy-design-css.md — deletes the legacy page-level fire-glow background animation.