Skip to content
Motion

When animation is documentation

Some motion explains. The rest is set dressing. The motion contract draws the line: a state change animated is a state change taught.

Intermediate1 min read (computed · recorded 7)updated 2026-09-12motiona11ycontracts

by Motif Editors

revised 2026-09-12First publication in bank-3 batch 4.

Key takeaways
  • Motion that explains state is documentation; the rest is set dressing.
  • Write the reduced-motion branch first — it tests what the motion said.
  • A static version that confuses means the motion was load-bearing.

The line

Animation is documentation when removing it loses information: the accordion that shows where the panel went, the toast that shows which action succeeded, the number that counts to show a total was reached. Animation is decoration when removing it loses only delight — which is fine, but label it.

The motion contract in this repo (docs/motion-contract.md) makes the scene itself declare which one it is, in its own body, next to the reduced-motion branch. A contract nobody can find is a suggestion.

The reduced-motion branch is the test

Writing the static branch forces the question: what did the motion actually say? If the static version is confusing, the animation was load-bearing documentation and the static version needs the information some other way — a label, a rule, a highlight. Motion never removes content that only it revealed.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.