| name | brand-motion-guidelines |
| description | This skill should be used when the user asks to "write motion guidelines", "create a brand motion system", "define easing and timing tokens", "document our animation principles", "build a motion language like Slack/IBM/Klarna", "set up entrance/exit/transition rules", or "add a reduced-motion / accessibility section". It outputs a fill-in-ready brand motion guidelines document. |
| version | 0.1.0 |
Brand Motion Guidelines
Author a brand motion system — the document that defines how a brand or product moves, the way mature design systems (Slack, IBM Carbon, Klarna, Material) do it. Output is a fill-in-ready template covering principles, easing/timing tokens, a motion library, logo rules, feedback states, accessibility, and do/don't examples.
When to use
Use when a brand or product needs a documented motion language, when animation feels inconsistent across a team, when defining named easing/duration tokens for designers and engineers, or when adding a reduced-motion/accessibility standard. The output is a structured doc, not code.
Decision tree — scope the system, then pick the token
Two judgments: how big a system does this brand actually need, and which token a given motion should use. Don't build a 7-part system for a landing page; don't ship a one-pager for a multi-team design system.
How many surfaces/teams will use this?
├─ One site / one campaign → lightweight: principles + tokens + a short
│ library. Skip deep logo/state sections unless relevant.
├─ A product (app/web) → full 7-part doc; tokens are mandatory.
└─ A brand across product + marketing + broadcast → full doc PLUS a
Motion Personality preset (see motion-art-direction) so every medium matches.
Picking the token for a given motion:
duration: larger element / longer travel → longer token
(instant<fast<base<slow<slower)
easing: entrance → decelerate · exit → accelerate (and shorter)
within-view move → standard · brand moment → emphasized
continuous loop → linear · playful accent → spring (sparingly)
Rule of thumb: if a motion can't name the token it uses, it's a one-off — and one-offs are what make a system feel inconsistent.
What a motion system contains
A complete motion guidelines doc has seven parts. Author them in order:
- Motion principles — 3-5 named beliefs that govern every animation.
- Timing & easing tokens — named durations and curves, so motion is consistent and engineer-implementable.
- Motion library — entrance, exit, and transition patterns mapped to tokens.
- Logo animation rules — how the mark may and may not move.
- Feedback & state motion — loading, success, error, hover, focus.
- Accessibility — reduced-motion, photosensitivity, focus visibility.
- Do / Don't — concrete examples that make the rules unambiguous.
Tokens are the core
Everything else references the tokens. Define durations and curves once, as named tokens; the library and components reuse them. This is what makes a motion system implementable rather than decorative.
Sample duration tokens (fill in / adjust)
| Token | Value | Use |
|---|
duration-instant | 100ms | Micro-feedback (toggle, tap) |
duration-fast | 150ms | Hover, small state change |
duration-base | 250ms | Standard UI transition (default) |
duration-slow | 400ms | Larger surfaces, modals, page sections |
duration-slower | 600ms | Hero/brand moments, full-screen |
Rule of thumb: the larger the element/distance, the longer the duration. Most UI motion lives at 150-400ms; under ~100ms reads as instant, over ~500ms feels sluggish for routine UI.
Sample easing tokens (curves)
| Token | cubic-bezier | Feel / use |
|---|
ease-standard | (0.4, 0.0, 0.2, 1) | Default; element moving within view |
ease-decelerate (ease-out) | (0.0, 0.0, 0.2, 1) | Entrances — fast in, settle |
ease-accelerate (ease-in) | (0.4, 0.0, 1, 1) | Exits — ease in, speed off |
ease-emphasized | (0.2, 0.0, 0, 1) | Expressive/brand moments |
ease-spring | spring(stiffness, damping) | Playful overshoot (use sparingly) |
Principle: entrances decelerate (objects arrive and settle), exits accelerate (objects leave with intent), and nothing important uses linear easing — linear feels mechanical and is reserved for continuous loops (spinners, progress).
Motion library (map patterns to tokens)
| Pattern | Tokens | Behaviour |
|---|
| Fade in | duration-base + ease-decelerate | Opacity 0→1 |
| Scale + fade in | duration-base + ease-decelerate | 0.96→1 scale, opacity 0→1 |
| Slide up in | duration-slow + ease-decelerate | Y +8/16px → 0, fade in |
| Fade out | duration-fast + ease-accelerate | Opacity 1→0 (exits faster than entrances) |
| Modal open | duration-slow + ease-emphasized | Scale + fade, backdrop fades in |
| Page/section transition | duration-base + ease-standard | Cross-fade or shared-element move |
| List stagger | duration-fast per item, 30-50ms offset | Items cascade, not all at once |
Default rule: exits are shorter than entrances; staggers use small offsets (30-50ms) so groups feel alive without dragging.
The template (fill in)
[BRAND] MOTION GUIDELINES Version: ___ Owner: ___
1. PRINCIPLES
We move to: [principle 1 — e.g. "Guide attention, never steal it"]
[principle 2 — e.g. "Fast by default, expressive on purpose"]
[principle 3 — e.g. "Every motion has a reason"]
[principle 4] [principle 5]
2. TIMING TOKENS
instant ___ms · fast ___ms · base ___ms · slow ___ms · slower ___ms
3. EASING TOKENS
standard ____ · decelerate ____ · accelerate ____ · emphasized ____
4. MOTION LIBRARY
Entrances: [list patterns + tokens]
Exits: [list patterns + tokens]
Transitions:[list patterns + tokens]
5. LOGO ANIMATION
Allowed: [reveal style, duration token, when it may animate]
Never: [stretch, distort, rotate freely, recolour, exceed ___ms]
6. FEEDBACK & STATE MOTION
Loading: [spinner/skeleton rules + when each]
Success: [confirmation motion]
Error: [shake/colour rules — never colour alone]
Hover/Focus: [token + visible focus requirement]
7. ACCESSIBILITY
Reduced motion: [what happens — see section below]
Photosensitivity: max 3 flashes/sec; no full-screen strobing.
Focus: focus indicators never animate away or disappear.
8. DO / DON'T
✅ [do] ❌ [don't]
Logo animation rules (fill in)
State explicitly what is allowed and forbidden. Typical baseline:
- Allowed: a reveal/build using
duration-slow-slower + ease-emphasized; gentle settle; one signature build kept consistent everywhere.
- Never: stretch/squash the mark out of proportion, free-rotate, recolour outside the palette, animate every appearance (reserve it for key moments), or exceed the agreed max duration.
Feedback & state motion
- Loading: skeletons for content layout; spinners only for short, indeterminate waits; show progress for waits over ~1s.
- Success/error: pair motion with a label or icon — never communicate state by colour or motion alone (accessibility).
- Hover/focus:
duration-fast + ease-standard; focus state must be clearly visible and must not animate itself out of view.
Accessibility (required section)
- Reduced motion: honour the user's "reduce motion" setting. Replace movement/parallax/large transforms with simple opacity cross-fades or instant state changes. Keep essential meaning; remove decorative motion. (Conceptually maps to
prefers-reduced-motion.)
- Photosensitivity: no more than 3 flashes per second; avoid full-screen high-contrast strobing.
- No meaning by motion/colour alone: always pair with text or icon.
- Focus visibility: never let an animation hide or remove the focus indicator.
Worked examples
GOOD — a token-anchored library entry:
Modal open: duration-slow (400ms) + ease-emphasized; scale 0.96→1, backdrop fades in. Close: duration-base (250ms) + ease-accelerate.
Every value is a named token, the close is shorter than the open, the easing matches the intent (emphasized for a brand moment in, accelerate to leave). An engineer can implement it directly and it will match every other modal.
ANTI-PATTERN — the "vibes" guideline:
"Animations should feel smooth, modern, and delightful. Use nice easing and keep things snappy but not too fast."
Why it fails: no named tokens, no values, no entrance/exit rule, nothing implementable — "smooth" and "snappy" contradict and every engineer interprets them differently, so the product ends up inconsistent (the exact problem the doc was meant to solve). The fix: replace adjectives with the token tables, map each pattern to tokens, and give do/don't pairs with concrete millisecond values.
Common mistakes
| Symptom | Why it happens | Fix |
|---|
| Motion inconsistent across screens | Hand-tuned one-off values, no tokens | Define tokens once; every pattern references them |
| Doc sounds nice, can't be built | Principles written as adjectives, not values | Pair every principle with a numeric token rule |
| Everything bounces | Spring/overshoot used everywhere | Reserve spring/emphasized for brand moments only |
| Exits feel sluggish | Exit duration ≥ entrance | Make exits one step shorter; accelerate them |
| Animation breaks accessibility | No reduced-motion / colour-only states | Add the required accessibility section; pair motion with text/icon |
| Logo animates differently everywhere | No logo rules | State one signature reveal + an explicit "never" list |
| Token values renamed constantly | Names are literal (duration-250) | Name by purpose (duration-base) so values can change |
Deliverable spec — what a good motion guidelines doc contains
The output is a structured document (template in references/full-template.md), not code. A complete doc has all seven parts, and:
- 3-5 named principles, each with a one-line rule (not adjectives).
- Duration and easing tokens with values/curves — the implementable core.
- A motion library mapping every pattern to tokens.
- Explicit logo allowed/never rules.
- Feedback/state motion (loading, success, error, hover, focus).
- A required accessibility section (reduced-motion, photosensitivity, focus, no meaning-by-colour-alone).
- Concrete do/don't pairs that remove ambiguity.
Before you finish — checklist
Related frameworks
This doc is the system-of-record for a brand's motion; two sibling skills supply the upstream theory and the per-project feel — reference and apply them, don't duplicate their tables:
animation-principles — your principles section should encode the Three Pillars (intent → tone → craft); the Primary/Secondary/Ambient motion layers explain why a hero move and ambient drift get different tokens; the 1/3 Rule justifies stagger limits (don't move everything at once). Cite these; keep the canonical tables there.motion-art-direction — for a brand spanning product + marketing + broadcast, pick a named Motion Personality preset and state it at the top of the doc, then derive token values to match (snappier preset → shorter durations; premium preset → longer, smoother). The motion-language spec lives there.
Quick reference
| Decision | Default |
|---|
| Default UI duration | duration-base 250ms |
| Entrance easing | decelerate (ease-out) |
| Exit easing | accelerate (ease-in), shorter than entrance |
| Linear easing | only for loops (spinners/progress) |
| Stagger offset | 30-50ms per item |
| Logo animation | reserved, consistent, never distort |
| State feedback | motion + label/icon, never colour alone |
| Reduced motion | swap transforms for fades/instant |
Reference files
references/full-template.md — the complete fill-in motion guidelines document with every section expanded and example copy.references/token-reference.md — full duration and easing token tables with values, cubic-bezier curves, and usage notes.references/dos-and-donts.md — a library of concrete do/don't pairs and worked principle examples (Slack/IBM/Material-style).
