Skip to content
flyingsalmon

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.

SampleTokenValueJob
--motion-fast100msState feedback in colour and opacity: hover, press, focus, a check appearing.
--motion-base150msMorphs, enters, and exits.

Springs

Two presets from the motion library, exported by the motion item.

SampleTokenValueJob
PlayfulspringBouncevisual duration 150ms, bounce 0.3Morphs and enters that stay inside the element’s own box: a scale, a translate, a thumb travelling, a check drawing in.
CalmspringSettlevisual duration 150ms, bounce 0Every 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.

SampleTokenValueJob
CSSState feedbackCSS transitions, 100msHover, press, focus, check. Colour and opacity only.
motionMorphmotion, springBounceA component reshapes itself: a button taking a spinner, a switch thumb travelling.
motionEnter and exitmotion, springBounce in, springSettle outA surface or element arriving or leaving. Anything that displaces its neighbours enters on springSettle.
CSSContinuousCSS keyframes, theme animate-* utilitiesA 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.

SampleTokenValueJob
Loopanimate-spinner800ms, linearThe spinner rotates once per cycle.
Loopanimate-skeleton-pulse2s, ease-in-outThe skeleton fades between full and half opacity.
Loopanimate-switch-thumb-pulse800ms, ease-in-outA loading switch pulses its thumb at the spinner’s tempo.
Loopanimate-progress-indeterminate2s, ease-in-outThe 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.

SampleTokenValueJob
Loopanimate-sticker-boil450ms step loop, three framesThe 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}.
Scrollanimate-sticker-popscroll 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

  • Do
    Let 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.
  • Do
    Settle 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.
  • Do
    Change 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’t
    Bounce 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’t
    Let a progress fill overshoot its value.A fill that overshoots misreports how much work is done.

  • Principles

    The mood that small, springy motion serves.
  • Button

    A morph through its loading state.
  • Sticker

    The one place motion runs long, on purpose.