Motion
Motion is small, springy, and quick: it confirms what you did and never makes you wait.
Every animated change looks finished in under 200ms, continuous loops aside, and movement uses a spring so it feels like a thing with weight. The vocabulary below is short on purpose. A component names a duration and a spring from it instead of inventing numbers, so everything in the system moves at one tempo.
Tokens
Durations
Published as CSS variables so every animation engine shares the same numbers.
| Sample | Token | Value | Job |
|---|---|---|---|
| --motion-fast | 100ms | State feedback in colour and opacity: hover, press, focus, a check appearing. | |
| --motion-base | 150ms | Morphs, enters, and exits. |
Springs
Two presets from the motion library, exported by the motion item.
| Sample | Token | Value | Job |
|---|---|---|---|
| Playful | springBounce | visual duration 150ms, bounce 0.3 | Morphs and enters that stay inside the element’s own box: a scale, a translate, a thumb travelling, a check drawing in. |
| Calm | springSettle | visual duration 150ms, bounce 0 | Every exit, and every enter that moves its neighbours: an alert or a field error growing in, the progress fill. |
Kinds and engines
Four kinds of animation, each with one engine. State feedback, morphs, and enters and exits stay under 200ms.
| Sample | Token | Value | Job |
|---|---|---|---|
| CSS | State feedback | CSS transitions, 100ms | Hover, press, focus, check. Colour and opacity only. |
| motion | Morph | motion, springBounce | A component reshapes itself: a button taking a spinner, a switch thumb travelling. |
| motion | Enter and exit | motion, springBounce in, springSettle out | A surface or element arriving or leaving. Anything that displaces its neighbours enters on springSettle. |
| CSS | Continuous | CSS keyframes, theme animate-* utilities | A loop that never stops: spinner, skeleton, indeterminate progress. |
Continuous loops
Loops are exempt from the 200ms limit because they never finish. Slower than these reads as broken and faster reads as alarming.
| Sample | Token | Value | Job |
|---|---|---|---|
| Loop | animate-spinner | 800ms, linear | The spinner rotates once per cycle. |
| Loop | animate-skeleton-pulse | 2s, ease-in-out | The skeleton fades between full and half opacity. |
| Loop | animate-switch-thumb-pulse | 800ms, ease-in-out | A loading switch pulses its thumb at the spinner’s tempo. |
| Loop | animate-progress-indeterminate | 2s, ease-in-out | The indeterminate progress segment travels the track at the skeleton’s tempo. |
Documented exceptions
The sticker is the one decoration in the system, and its two motions are allowed to run longer than 200ms.
| Sample | Token | Value | Job |
|---|---|---|---|
| Loop | animate-sticker-boil | 450ms step loop, three frames | The sticker’s hand-drawn lines jitter like a cartoon: each frame shows for 150ms, then the next takes over. It runs for as long as the sticker is on the page, unless the caller holds the sticker still with boil={false}. |
| Scroll | animate-sticker-pop | scroll timeline, from entry 10% to cover 35% | The sticker grows from small and tilted, overshoots slightly, and settles, at the speed the reader scrolls. It reverses on the way back. |
Properties and layout
Animate transform, opacity, and colour. Layout animation is fine through motion’s layout prop, which turns a size change into a transform. A component that animates layout on its own state wraps itself in a LayoutGroup so it does not re-measure when an unrelated sibling changes.
Usage rules
- DoLet movement that stays inside an element’s own box bounce a little, such as a check mark or a switch thumb.A little overshoot inside its own bounds reads as playful and disturbs nothing around it.
- DoSettle without a bounce for exits and for anything whose size pushes its neighbours.A bounce on a height change makes the content below overshoot and snap back, which looks like a glitch. A leaving element should not wobble.
- DoChange colour and opacity with a short fade.A colour has nowhere to overshoot to, so a quick fade is all the feedback it needs.
- Don’tBounce a loop that never stops, such as a spinner or a loading pulse.A bounce is for movement that comes to rest. A loop keeps one steady rhythm so it reads as waiting, not as an event.
- Don’tLet a progress fill overshoot its value.A fill that overshoots misreports how much work is done.