# Motion — Required Evidence

Scope: animation, transitions, loading motion, expansion, dismissal, and movement in Fractal product interfaces.

## Required invariants

- Use named duration and easing tokens for every motion specification and implementation.
- Raw milliseconds, seconds, easing keywords, and cubic-bezier values may appear only in the token definitions below and in `motion.css`.
- Motion explains state, location, causality, or progress. If it communicates none of those, remove it.
- Closing and dismissal are no slower than opening.
- Respect `prefers-reduced-motion: reduce`; remove nonessential motion and preserve immediate state feedback.
- Never animate data in a way that changes its apparent value or delays comprehension.

## Duration tokens

These definitions are the only place in evidence where raw duration values are canonical.

| Token | Value | Use |
| --- | --- | --- |
| `--duration-fast` | `120ms` | Hover, press, toggle, color, border, and opacity feedback |
| `--duration-normal` | `200ms` | Tooltip, dropdown, disclosure, small reveal, and exit |
| `--duration-slow` | `300ms` | Modal, side panel, and page-level transition |
| `--duration-ambient` | `1500ms` | Restrained continuous branded or loading motion |
| `--stagger-step` | `60ms` | Delay between related entering items |

## Easing tokens

These definitions are the only place in evidence where raw curves are canonical.

| Token | Value | Use |
| --- | --- | --- |
| `--ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | Elements entering or direct interaction feedback |
| `--ease-in` | `cubic-bezier(0.7, 0, 0.84, 0)` | Elements exiting |
| `--ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | Repositioning and oscillation |

Continuous linear movement is allowed only for progress or shimmer. If needed, add and use a named `--ease-linear` token rather than writing the raw keyword at a call site.

## Pattern selection

| Interaction | Duration | Easing | Properties |
| --- | --- | --- | --- |
| Hover, press, toggle | `--duration-fast` | `--ease-out` | Color, border-color, opacity, or transform |
| Scroll-aware header/footer divider | `--duration-fast` | `--ease-out` | Opacity; show only when content continues behind the fixed region |
| Tooltip or dropdown enter | `--duration-normal` | `--ease-out` | Opacity and transform |
| Tooltip or dropdown exit | `--duration-normal` | `--ease-in` | Opacity and transform |
| Disclosure expand/collapse | `--duration-normal` | `--ease-in-out` | Grid track, height when necessary, and opacity |
| Modal or side panel enter | `--duration-slow` | `--ease-out` | Opacity and transform |
| Modal or side panel exit | `--duration-normal` | `--ease-in` | Opacity and transform |
| Page-level transition | `--duration-slow` | `--ease-in-out` | Opacity and restrained transform |
| Skeleton or progress loop | `--duration-ambient` | named linear token | Background-position or transform |

## Property rules

Prefer `transform` and `opacity`. Color and border-color transitions are valid for state feedback. Background-position is valid for shimmer. Height or grid-track animation is allowed for a disclosure when it helps the user track expanding content.

Do not animate width, top, left, or layout geometry for decoration. Do not animate box-shadow; shadows express elevation and do not change on interaction. Do not use blur except for an explicitly expressive non-product surface where the effect has a documented purpose.

## Interaction rules

- Hover changes color or surface only. Do not scale or lift elements on hover.
- A single-step primary or danger action may use the documented pressed scale with `--duration-fast` and `--ease-out`.
- A multi-step trigger such as a dropdown does not press-scale; the opened surface is the feedback.
- Panels enter from their spatial origin so movement explains where they came from.
- Stagger only a small group of related items. Use `--stagger-step`, preserve reading order, and avoid making later content wait unnecessarily.
- Loading motion must not imply determinate progress unless progress is actually measured.

## Reduced motion

Under reduced motion:

- remove ambient loops, parallax, drift, and stagger;
- make entrances and exits immediate or near-immediate while preserving visibility changes;
- retain non-motion state signals such as color, text, icons, and focus treatment;
- do not remove the content or action that the animation normally reveals.

## Forbidden outcomes

- Raw duration or easing values outside the token definitions.
- Bounce or spring motion in product UI.
- Scale or translate effects used only to make a surface feel lively.
- Motion that competes with reading, chart interpretation, or a current task.
- A transition on every property via `transition: all`.
- Essential information available only after an animation completes.
