Motion is the part that never makes it into the document
A brand guideline will spend nine pages on the logo and give you clearspace to the millimetre. It will name the exact ink you print in. Then it gets to the website, the app and the launch film, and it says the brand should feel "confident and modern", and that is the whole specification.
The reason is boring. A PDF cannot move, so motion had nowhere to live, so it became a paragraph of adjectives. Everyone involved knew it was thin and nobody had a better place to put it.
Adjectives do not survive the handoff
Here is what happens to "snappy". The designer means about 300 milliseconds with a hard brake at the end. The developer reads it on a Tuesday, reaches for the default in whatever library the project uses, and ships 150 milliseconds of ease-out. Both of them did their job. The brand still moves like every other site built that quarter.
The gap is not effort or taste, it is units. Colour survives the handoff because it is written as a hex value. Type survives because it is a named family at a named weight. Motion arrives as a mood, so it gets rebuilt from scratch by whoever is closest to the keyboard.
The fix is to write motion the way you already write colour. Four numbers do almost all of it.
What a motion spec is actually made of
Strip away the vocabulary and a moving element on a screen is described by four things.
- Duration
- How long it takes, in milliseconds. The single most argued-about number and the easiest one to write down.
- Easing
- How the speed changes across that time. This is where the personality lives, and it is expressible as four numbers.
- Distance
- How far it travels before it settles. Usually far smaller than people guess.
- Stagger
- The delay between one element and the next when a group moves together. It is what separates a list that feels alive from one that lands like a slab.
Specify those four and a developer can rebuild your motion without asking you a single question. Leave any of them to interpretation and you have written adjectives again.
Easing is the personality, and it is four numbers
Nothing in the physical world starts and stops at a constant speed. A door swings and slows as it closes. A card dealt across a table decelerates into place. Linear motion reads as mechanical because nothing you have ever touched moves that way.
On the web the curve that describes this is a cubic bezier, and it is written as four numbers. They are the coordinates of two control points that bend a line between the start and the end. You do not need the maths. What you need to know is that those four numbers are as specifiable as a hex code, and that changing them changes the entire character of the brand.
Two curves with the same duration can feel completely different. A curve that starts fast and brakes late reads as decisive. A curve that eases gently at both ends reads as considered. A curve that overshoots past its target and settles back reads as playful, and on the wrong brand it reads as a toy.
Drift
Punch
Reveal duration 800ms easing cubic-bezier(0.3, 0.9, 0.1, 1) distance 12px, upward stagger 60ms between children
That is the whole specification for one move. Somebody can copy it straight out, and it will still be right in three years when the site gets rebuilt by people who never met you.
Duration comes in three bands, not one number
The mistake is picking a single duration for the brand. What you want is three bands, because the right length depends entirely on how often the user sees the move.
Something that fires on every keystroke or hover should be almost instant, because the hundredth time you see it you are not admiring it, you are waiting for it. Something that happens once per page visit can afford to be a real gesture. The rule of thumb that holds up: the more often it fires, the less it animates.
- Micro
- Hover, press, focus, a caret. Around 120–200ms for a calm brand and lower for a fast one.
- Interface
- A menu opening, a panel expanding, a view swapping. Around 350–500ms.
- Reveal
- Content entering as you scroll, a hero landing on load. Around 700–1000ms, and this is the only band where slow is allowed to be the point.
Enter
Scaling in, opening. Content arriving into view.
When you are unsure, it is too slow. Motion that felt right while you were building it is almost always long by the time somebody uses the product for the tenth time.
Distance is smaller than you think
A reveal that travels eighty pixels reads as a slide. A reveal that travels twelve reads as the content settling into place, and it is the second one that people describe as expensive. Most entrance motion on a well-built site moves between eight and sixteen pixels.
Write the distance down, because it is the number developers most often invent. And write which properties move: transform and opacity only, never width, height, top or margin. Those reflow the page and turn a nice idea into a stuttering one on a mid-range laptop.
Stagger is what makes a group feel alive
When several things arrive at once they read as one slab dropping in. Delay each one behind the last by a few tens of milliseconds and the same group reads as a sequence with a leading edge. That delay is the stagger, and it is a brand decision.
A tight stagger of around 45ms makes a group read as one gesture with texture. A looser 90ms gives each item its own beat and suits a slower, more editorial brand. The direction matters too: starting from the centre and spreading outwards feels different from running left to right.
Move
Reordering, shuffling. The system responding to a gesture.
Four personalities, fully specified
These are the four motion personalities Vessa ships, with their real values. They are a useful starting point even if you never touch the product, because they show what a complete spec looks like when you stop describing and start specifying.
Glide
The view moves between fixed points. Near shapes sweep, far ones barely shift.
Drift. Calm and considered. Elements settle into place like paper coming to rest.
Punch. Decisive and athletic. Motion starts hard and brakes late, like a sprinter into the line.
Elastic. Playful and physical. Elements overshoot their mark and spring back, full of energy.
Editorial. Slow and stately. Motion at the pace of turning a page in a well-made book.
Write it so a developer can paste it
A specification that has to be retyped will be retyped wrong. The test of a motion section is whether the person implementing it can copy a value out and be finished. In CSS that means the transition written out in full.
.element { transition: transform 800ms cubic-bezier(0.3, 0.9, 0.1, 1), opacity 800ms cubic-bezier(0.3, 0.9, 0.1, 1); } /* stagger children by 60ms via transition-delay */
And for anything sequenced or scroll-linked, where CSS runs out, the same values as code. The curve is registered once by name and then referred to everywhere, which is exactly how you already treat a colour token.
gsap.registerPlugin(CustomEase); CustomEase.create("drift", "M0,0 C0.3,0.9 0.1,1 1,1"); gsap.from(".element", { y: 12, opacity: 0, duration: 0.80, ease: "drift", stagger: 0.06 });
Note that the duration, the curve and the distance in those two blocks are the same numbers. That is the entire point. The guideline is not describing the move, it is handing over the move.
Reduced motion is part of the spec, not a nice-to-have
Some people get motion sick from parallax and large travel. Their operating system has a setting for it which every browser exposes, and honouring it costs one media query. A brand guideline that specifies motion without specifying its reduced variant has handed the developer an accessibility decision they should not be making alone.
The rule that works: remove parallax, scroll-linked movement, autoplay loops and large travel, and keep functional feedback as plain opacity. Nothing should ever end up invisible because motion was switched off. Write that sentence into the guideline and it stops being a debate.
What to leave out
A motion section gets worse the longer it gets. You do not need a named animation for every component, and a library of forty transitions will be ignored the same way a forty-page PDF is ignored. Specify the handful of moves that carry the brand, name the curve and the bands, and let the people building make sensible choices inside those constraints.
The other thing to leave out is video of the motion with no values attached. A screen recording proves the move existed once. It does not tell anybody how to rebuild it, and it ages badly the moment the product changes.
Where this ends up living
All of the above is writable in any format you like. The catch is that a document which cannot move can only ever describe motion, and a description is the thing that failed in the first place. The values need to sit next to the move actually playing, on a page the developer can open and copy from.
That is what Vessa is for. The motion section of a published guideline plays each specimen next to its curve, and hands over the duration, easing, distance and stagger as CSS and GSAP that a developer pastes straight in. VANTA is a full one, live, if you want to read a finished example rather than take my word for it.