How to Document UI Motion Without Guessing the Easing
Turn a UI motion reference into a usable note: trigger, starting state, transition, end state, interruptions and a reduced-motion alternative.
Direct answer
Document UI motion as a change between states, not as a style label. Record the trigger, what moves, what stays fixed, the end state and what happens if the action is interrupted. Keep observed timing separate from proposed values, and include the reduced-motion behaviour you need to verify.
Describe what the motion explains
A useful motion note begins with a relationship: a card expands into its detail, a panel enters from its controlling button, or a status change confirms an action. “Smooth and premium” gives the next designer little to work with. “The selected card stays visually connected to its expanded detail” names something they can inspect.
Google's design account of meaningful motion describes movement as a way to communicate relationships, change and feedback. Use that as a question for a reference: what would be harder to understand if the transition were removed? If the answer is unclear, record that uncertainty rather than inventing a purpose.[1]
Record the transition as a small sequence
Keep a short recording when motion itself is the evidence, plus stills for the starting and ending states. Name the action you performed. If you only received a clip, say that you did not operate the interface. You cannot infer every interaction from a recording of one successful run.
Separate the motion of the interface from movement caused by scrolling, a camera or the recording itself. Note whether you are viewing normal-speed playback. If playback speed or frame rate is unknown, do not turn the clip's apparent duration into an exact implementation value.
- Start: the visible arrangement before the action.
- Trigger: click, key activation, scroll, load completion or another event.
- Change: the elements that move, resize, fade or remain anchored.
- End: the settled state and the next available action.
- Interruption: what happens on cancellation, repeated activation or a reversal.
- Timing evidence: measured, declared by the source, approximate or unknown.
Do not promote a visual impression into an easing specification
A transition may appear to accelerate, decelerate or overshoot. Record that observation in plain language. The exact easing curve is not established by the impression alone. If you inspect an implementation or receive a motion specification, keep that evidence separate from the clip and record which version it describes.
For your own prototype, you may choose a duration or curve. Label it “proposed for our design”, then check the result in context. A proposed value is a design decision, not a recovered fact about the reference. This also gives an AI coding agent permission to implement the proposal without pretending to reverse-engineer the source.
Worked example: an expanding card
This example is fictional. A selected card grows into a larger detail panel while the surrounding cards stay still. The title remains visible during the change. The clip ends with a close control in the panel. It does not show keyboard use, a second activation during the transition or a reduced-motion setting.
The note should preserve that boundary. The visible continuity of the title is an observation. “Keep the title anchored in our prototype” is a proposal. Whether focus moves correctly or rapid input cancels the transition remains a test question.
- Purpose to explore: preserve the connection between the chosen card and its detail.
- Observed in the fictional clip: the card enlarges; the title remains visible; neighbouring cards stay still.
- Timing: appears to slow towards the end; exact duration and easing unknown.
- Interruption check: activate, then close before the opening transition finishes.
- Reduced-motion proposal: show the detail without spatial travel while preserving the title and close action.
Keep a reduced-motion counterpart in the handoff
The prefers-reduced-motion media query exposes a user's device preference for reducing motion. MDN describes using it to remove, reduce or replace non-essential movement. Record whether you actually checked that preference in the reference; a normal-motion clip does not reveal the alternative.[2]
WCAG's Animation from Interactions criterion, at Level AAA, addresses disabling interaction-triggered motion unless that animation is essential. This is one accessibility consideration, not a complete assessment of a component. Keep the underlying information and actions available when you propose an alternative.[3]
Finish the note with the unknowns someone must check in the prototype: keyboard operation, focus, rapid input and the reduced-motion version. The UI state checklist can hold the before-and-after states, while this motion note explains the change between them.[4]
Questions designers ask
Is a GIF enough to document a UI animation?
It can show a sequence, but it may omit the trigger, input conditions and playback details. Pair it with a note that identifies what is observed and what the file cannot establish.
Should a motion reference include exact milliseconds?
Only when you have a reliable measurement or a source specification. Otherwise use an approximate description and mark exact timing as unknown. Label any value you choose for your prototype as proposed.
Does reduced motion mean removing every visual change?
No. Document an alternative that preserves the information and available actions while reducing unnecessary movement. Check the result in the actual interface.
Sources checked
- Making motion meaningful — Google Design
- prefers-reduced-motion — MDN Web Docs
- Understanding Animation from Interactions — W3C
- UI state checklist — Sesavu