Animate

Animate: Motion and Transitions

Add purposeful motion to a UXSpec — $animations, onEnter choreography, and timing tokens. Motion should communicate, not decorate.

When to Use

When a spec feels static or abrupt. When state transitions need smoothing. When the user asks for animation, micro-interactions, or polish.

Where Motion Adds Value

1. State transitions — entering/exiting a state should feel intentional, not instant. A form appearing, a loading spinner replacing a button, an error banner sliding in.
2. Feedback — button presses, toggle switches, form submissions. The user did something; acknowledge it.
3. Spatial relationships — where did this element come from? Where did it go? Motion answers these questions.
4. Hierarchy — staggered reveals communicate reading order. The first thing to animate is the first thing to notice.

Timing Reference

Define these as $tokens.timing values so they're consistent across the spec.

Easing

• Use: ease-out-quart, ease-out-expo — natural deceleration, things arrive smoothly.
• Avoid: bounce, elastic — feel dated and gimmicky. linear — feels mechanical.
• Exits: Use ease-in or ease-in-out — things accelerate away.

$animations Block

Named keyframe definitions referenced from $visual.onEnter:

"$animations": {
  "slide-up": {
    "$description": "Content slides up and fades in on state entry",
    "duration": "{timing.entrance}",
    "easing": "ease-out",
    "keyframes": {
      "0":   { "opacity": 0, "translateY": 16 },
      "100": { "opacity": 1, "translateY": 0 }
    }
  }
}

onEnter Choreography

Each $visual can specify what happens when the state is entered:

"onEnter": {
  "focus": "email-input",
  "animation": "slide-up"
}

Decisions:

• One hero moment per state. Don't animate everything. Pick the most important element or the container itself.
• Stagger reveals for lists or multi-element layouts: 50–100ms delay between items. More than 5 items? Animate the container, not each item.
• Focus and animation together. If a state entry moves focus, the animation should guide the eye to the focus target.

Reduced Motion

Always design a reduced-motion alternative. This isn't optional.

• Replace slide/scale animations with simple opacity fades or instant transitions.
• Keep functional motion (focus movement, scroll-to) but remove decorative motion.
• Note the alternative in $description: "On reduced motion: content appears instantly with no slide."

Anti-patterns

• Animating every state transition the same way — motion becomes noise
• Durations > 500ms for feedback — user waits for the UI to catch up
• Entrance animations that block interaction — never make the user wait to click
• Motion without purpose — if removing the animation changes nothing about comprehension, remove it
• Forgetting exit animations — abrupt disappearance after smooth entrance feels broken

Principle

Motion in a UXSpec is metadata, not decoration. It tells the implementer how a state change should feel. A spec without motion isn't wrong — but a spec with thoughtful motion communicates more clearly what the designer intended.