Skip to content
Documentation

ADR-004: Motion & Interaction

Decision

Central motion tokens govern all animation. Interactive controls never move their own layout on hover or focus, and every animation honors prefers-reduced-motion.

Key rules

  • Use motion tokens — do not define custom transition-duration or animation values. Duration tokens: fast (100ms), normal (200ms), slow (300ms).
  • Interactive controls (buttons, inputs, links) must not shift layout or move their bounding box on hover or focus.
  • Every animation MUST have a prefers-reduced-motion: reduce override that removes or collapses the motion.
  • Focus rings use the focus token: focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 — never a custom outline.
  • Hover and active states use the token pair (e.g. bg-primary → bg-primary/90) — never invent values.
  • Scope transitions to the property; never transition-all. The motion library (Motion / Framer) is opt-in for advanced choreography only.

Why

Token-governed, layout-stable, reduced-motion-safe interaction is both the quality floor and an accessibility requirement. Custom durations and layout-shifting hovers are the usual sources of janky, inaccessible motion.

Applies when

You are adding hover, focus, or active states, transitions, or any animation to a component.

  • ADR-008 — border, surface & overlay discipline.
  • ADR-005 — accessibility and release gates.