Marcus Andrey Study
Ler em português Library

Motion and Interaction · Step 7 · 5 min read

Documenting motion in a design system

Motion is the hardest part of a design system to write down, because a still page can't show it. What a motion section contains, how to document one pattern on one card, why every spec needs a live demo and a reduced-motion line, and how to start small.

Motion that isn't written down gets rebuilt from memory, a little differently each time. Tokens give you the values. Documentation gives people the reasons, the patterns and the limits, so a designer who joins next month makes the same choice you would. And because motion happens in time, the documentation has to move too.

What you'll be able to do after reading:

  • Plan the motion section of a design system
  • Document one motion pattern on one card
  • Decide where motion lives: its own section, the component pages, or both
  • Start with a first version and improve it in use

1. One pattern, one card

Bottom sheet: open and close

Purpose
Show that the sheet comes from below and goes back there, so people know the page is still underneath.
Trigger
Tap on "Filters". Closes on the close button, a tap on the scrim or Esc.
What moves
The sheet slides up (transform); the scrim fades in (opacity). Nothing else.
Open
motion.enter-large: 350 ms, cubic-bezier(0, 0, 0, 1)
Close
motion.exit-large: 250 ms, cubic-bezier(0.3, 0, 1, 1). Exits are faster.
Reduced motion
No slide. Sheet and scrim fade, 150 ms, motion.easing.standard.
Don't
Bounce the sheet, or animate its height.
Owner · changed
Design system team · v2.3, close shortened from 350 ms
Try the pattern

Your system asks for reduced motion, so you are seeing the fallback: a 150 ms fade.

One motion pattern, documented on one card: why it moves, what triggers it, which tokens, what happens under reduced motion, and who owns it. The demo next to it runs the same values.Example spec and live CSS: Marcus Andrey, CC BY 4.0.

The core unit of motion documentation is a pattern: one thing that moves, for one reason. The card in the figure answers the questions a designer, a developer and a reviewer will ask, in the order they ask them. The demo next to it runs the same tokens, so the page can't drift from the code.

Every motion pattern card has the same fields:

Field What it answers
Purpose Why it moves. What people would lose without it
Trigger What starts it, and what ends or reverses it
What moves The properties, ideally only transform and opacity (see Motion performance)
Tokens The semantic token for each direction, never raw values
Reduced motion What happens instead (see Designing a reduced-motion version)
Don't The one mistake people keep making with it
Demo The real thing, running
Owner and change log Who to ask, and what changed when

2. What the motion section contains

Val Head's advice for design systems is a good outline. Start by talking to the people who will use it: where animation trips them up, how they hand it off today, what they wish they had. Then write principles, set durations and curves, and add tokens, code and demos (Val Head, Including Animation In Your Design System, Smashing Magazine, 2019).

A motion section usually has five parts:

  1. Principles. Three or four short statements about why your product moves, like Fluent's "functional, natural, consistent, appealing" (Fluent 2, Motion). They give reviewers something better than taste to argue with.
  2. Tokens. The durations and curves from Motion tokens, each with its job and its reduced value.
  3. Patterns. The cards: enter and exit, expand and collapse, page transitions, feedback.
  4. Accessibility. How reduced motion works across the system, with the WCAG criteria it meets (see WCAG and motion).
  5. Performance. Which properties are allowed, and how to check (see Motion performance).

3. Show, don't tell

A curve on a page is a picture of a number. People need to see it run. Val Head puts it plainly: "Never underestimate the power of showing instead of telling."

  • Live demos in the docs, built with the real tokens, so they change when the tokens change.
  • A short video or GIF where live code isn't possible, labelled with the token names.
  • A do and a don't, side by side, playing at the same time.
  • A reduced-motion toggle on each demo, or instructions to switch the system setting, so readers see both versions.

4. Where motion lives

Two places, and most good systems use both:

  • A motion section for principles, tokens and patterns that cross components: page transitions, choreography.
  • A motion line on each component page: "Menu: opens with motion.enter, closes with motion.exit, fades under reduced motion." That's where people actually look.

Keep the list of named patterns small. Each one is something you have to maintain, demo and test on every platform, a point Val Head makes too.


5. Start small, ship, improve

Don't wait for a complete motion language. Head's advice is to "work in stages instead of waiting for your motion guidelines to be perfect". A first version that helps:

  1. The token table, with reduced values.
  2. Three pattern cards for the motion your product uses most: usually a menu, a sheet or dialog, and button feedback.
  3. One paragraph on reduced motion.

Then review it after a month of real use: which questions did people still ask? Those are the next cards.


6. Common mistakes

  • Principles with no tokens, or tokens with no principles.
  • Durations written in the docs that differ from the ones in code.
  • Static screenshots of motion, with no demo.
  • No reduced-motion field, so every team invents its own fallback.
  • Motion documented only in a separate section that nobody opens from the component page.
  • Waiting until it's complete, so it never ships.

7. Vocabulary

Term Meaning
Motion pattern One recurring movement with one purpose, documented on its own
Pattern card The page or block that specifies one pattern
Motion principles Short statements of why and how the product moves
Live demo The pattern running in the docs, built with the real tokens
Change log A dated list of what changed in the system and why

8. Try it (no tools needed)

  1. Choose one thing that moves in your product.
  2. Fill in the card from section 1 on paper, field by field.
  3. Which field was hardest to fill? That's the decision nobody made.

Reflection questions: Where would a new designer on your team look first for motion guidance, the motion section or the component page? What's there now?


9. If you already practise

  • Generate the token tables in the docs from the token file, so they can't go stale.
  • Make the reduced-motion field required in your pattern template.
  • Link each pattern card to its code, and each component's code back to its card.
  • Ask the engineers which motion questions they get most; write those cards first.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Motion tokens · What public motion guidelines teach · Motion in design system governance · Lottie, Rive and handing off motion · What a design system is · Handoff to developers · Motion spec sheet

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close