# Principles

> The twelve principles of interanimate, each with its rule, rationale, how the framework enforces it, and where it comes from.

These twelve principles are the normative core of interanimate. Every default, token, and intent in the framework traces back to at least one of them. When two principles conflict, the earlier pillar wins: **Respond** over **Continue** over **Respect** — with one exception: a person's motion preference (Principle 11) is never overridden by anything.

Each principle has four parts:

- **Rule** — the short, testable statement.
- **Why** — the reasoning and evidence.
- **In the framework** — how interanimate makes the rule the default.
- **Sources** — where it comes from (see [Research & references](/docs/references)).

---

## Pillar I — Respond [#pillar-i--respond]

### 1. Respond first, animate second [#1-respond-first-animate-second]

**Rule.** Acknowledge every input within 100 ms, on the *start* of the input (press, touch-down, key-down), not its completion. Motion may follow the acknowledgment; it may never replace or delay it.

**Why.** Long-standing HCI research places the threshold for a response feeling instantaneous — and for the user feeling they are directly manipulating something — at about 0.1 s. Past roughly 1 s, the user's flow of thought breaks. Apple's fluid-interface work makes the same point from the design side: directness collapses the moment lag appears, so feedback belongs on touch-down. On the web, Google's Interaction to Next Paint metric treats 200 ms or less from input to next paint as good responsiveness.

**In the framework.** The press state of every interactive intent resolves on input start. No intent introduces an artificial wait before its first visible frame. Animations never gate the underlying state change: the state updates immediately and motion *represents* the change rather than *delaying* it.

**Sources.** Miller (1968) and Nielsen's response-time limits; Apple, *Designing Fluid Interfaces* (WWDC 2018); web.dev, *Interaction to Next Paint*.

### 2. Purpose or nothing [#2-purpose-or-nothing]

**Rule.** Every motion names exactly one primary purpose: **feedback**, **orientation**, **state**, **attention**, or **delight**. Motion without a nameable purpose does not exist.

**Why.** Apple's guidelines say plainly not to add motion for its own sake. Emil Kowalski's work argues that the best animation is sometimes none at all — his example is a launcher that opens with no animation and feels exactly right because of it. Issara Willenskomer's UX in Motion framing makes the same distinction: UI animation is decoration; motion design is in service of usability.

**In the framework.** Purpose is part of every [intent](/docs/intents). There is no "animate this because" escape: if you use the raw layer, you still declare a purpose, and the framework uses it to decide reduced-motion behavior, frequency budgets, and whether bounce is allowed.

**Sources.** Apple HIG, *Motion*; Kowalski, *You Don't Need Animations* and *Great Animations*; Willenskomer, *The UX in Motion Manifesto*.

### 3. Frequency sets the budget [#3-frequency-sets-the-budget]

**Rule.** The more often a person sees a motion, the less of it there should be. High-frequency and keyboard-initiated actions get no motion.

**Why.** A 300 ms flourish is charming the first time and a tax the five-hundredth. Apple's guidelines advise generally avoiding motion on interactions that happen frequently. Kowalski's decision framework turns this into tiers: actions seen a hundred or more times a day — keyboard shortcuts, command palettes, core navigation — never animate; actions seen tens of times a day get at most near-imperceptible motion; occasional surfaces like modals and toasts get standard motion; and rare moments like first-run and success states are where any "delight budget" lives.

**In the framework.** Every intent carries a frequency tier (see [Tokens](/docs/tokens#frequency)). The tier caps tempo and character: a high-frequency intent cannot be given a slow or bouncy motion without an explicit, visible override. Keyboard-initiated input resolves to the `instant` tempo by default.

**Sources.** Apple HIG, *Motion*; Kowalski, animation decision framework (emilkowalski/skills).

### 4. Fast is a feature [#4-fast-is-a-feature]

**Rule.** Interface motion is short. Standard UI motion stays at or under ~300 ms of perceived duration; exits are faster than entrances; larger travel may take longer, but sub-linearly.

**Why.** Faster animation improves *perceived* performance — the interface feels quicker even when nothing else changes. Kowalski's budgets keep UI motion under 300 ms, with press feedback around 100–160 ms and larger surfaces like drawers allowed up to roughly 500 ms. IBM's Carbon system scales duration with the size of the change, using a non-linear scale so that large movements don't feel disproportionately slow. Apple notes that brief, precise feedback feels lightweight and often communicates better than prominent animation.

**In the framework.** The [tempo scale](/docs/tokens#tempo) is bounded. Exits automatically resolve one step faster than their matching entrance. Distance-aware tempo grows with travel but is capped.

**Sources.** Kowalski, *Great Animations*; IBM Carbon, *Motion*; Apple HIG, *Motion*.

---

## Pillar II — Continue [#pillar-ii--continue]

### 5. Never lock the user out [#5-never-lock-the-user-out]

**Rule.** No motion ever blocks input. Anything moving can be interrupted, redirected, or reversed at any instant.

**Why.** Apple calls interruptibility the single most important property of a fluid interface: thought and gesture happen in parallel, and the interface has to keep up. Apple's guidelines also say not to make people wait for an animation to finish before they can act. A modal that ignores your click until its entrance completes, or a drawer that must finish closing before it can reopen, breaks the conversation.

**In the framework.** Every motion is interruptible by definition. There is no "uninterruptible" flag. New input always wins, and the in-flight motion hands its current state to whatever comes next (Principle 6).

**Sources.** Apple, *Designing Fluid Interfaces*; Apple HIG, *Motion*; Kowalski, *Great Animations*.

### 6. Continuity of value and velocity [#6-continuity-of-value-and-velocity]

**Rule.** Motion always begins from the value currently on screen and the velocity it currently has. Nothing jumps; nothing hits a "brick wall."

**Why.** If an interrupted animation restarts from its logical target instead of its on-screen position, the object visibly teleports. If it restarts at zero velocity, it stops dead and lurches. Apple's spring work makes the point that springs are the only common animation type that preserves continuity both when starting from rest and when starting with existing velocity. When a gesture reverses, the velocity should blend rather than cut.

**In the framework.** Every animated value carries both its *presentation value* and its *velocity* at all times. Any new motion — whether triggered by state, by another animation, or by a gesture ending — inherits both. Multi-dimensional values (like 2D position) are treated as independent axes so each keeps its own velocity.

**Sources.** Apple, *Designing Fluid Interfaces*; Apple, *Animate with Springs* (WWDC 2023).

### 7. Behavior over timelines [#7-behavior-over-timelines]

**Rule.** Anything a person can touch moves with physics (springs and decay), not with fixed-duration curves. Fixed-duration curves are reserved for *effects* — opacity, color, blur — and for scripted, non-interactive sequences.

**Why.** A pre-scripted animation has no answer for new input; a spring does — new input just changes the target and the motion stays continuous. Apple has moved its platforms to springs described by two designer-friendly parameters, duration and bounce, and recommends a spring with no bounce as the versatile default. Google's Material 3 Expressive draws the same line interanimate does: springs for spatial movement, duration-and-easing for visual effects.

**In the framework.** The [motion model](/docs/motion-model) is springs-first. Spatial channels default to springs; effect channels default to timed easing. Both are described in perceptual terms (how long it *feels*, how much it bounces), never in raw physics constants at the top layer.

**Sources.** Apple, *Animate with Springs*; Apple, *Designing Fluid Interfaces*; Material 3 Expressive motion.

### 8. The hand is the source of truth [#8-the-hand-is-the-source-of-truth]

**Rule.** During direct manipulation, content tracks the input 1:1 from the exact point it was grabbed. When the input lets go, motion continues the input's intent — its velocity and projected destination — not merely its last position.

**Why.** Touch and content should move together. Snapping an object's center to the pointer on grab breaks the illusion instantly. Apple's fluid-interface work adds three refinements that interanimate adopts: *hysteresis* (require a small movement before committing to a drag direction), *momentum projection* (use release velocity to predict where a flick was headed, then settle at the target nearest that prediction), and *rubber-banding* (resist progressively past a boundary instead of stopping hard).

**In the framework.** The [interaction model](/docs/interaction-model) defines a single gesture lifecycle that every input type follows, with grab-offset preservation, hysteresis, velocity tracking, projection, and boundary resistance built in.

**Sources.** Apple, *Designing Fluid Interfaces*; Kowalski, apple-design and animation skills; Rauno Freiberg, *Invisible Details of Interaction Design*.

### 9. Every motion has an origin and a destination [#9-every-motion-has-an-origin-and-a-destination]

**Rule.** Things enter from where they come from and leave toward where they go. Paths are consistent: something that enters from an edge exits to that edge; a popover grows from its trigger; reversible transitions retrace their path.

**Why.** Motion's most valuable job is *orientation* — showing the person where something came from, where it went, and how parts relate. Kowalski's guidance has popovers scale from their trigger rather than their center, and toasts enter and exit the same edge. Apple adds that intermediate motion should hint at where things are going. Willenskomer's principles of parenting, offset and delay, and transformation are all about relationships between objects over time.

**In the framework.** Intents that reveal or conceal require — or infer — an *origin*. Exits default to the reverse of their entrance. See [Choreography](/docs/choreography).

**Sources.** Kowalski, design engineering skills; Apple, *Designing Fluid Interfaces*; Willenskomer, *The UX in Motion Manifesto*.

---

## Pillar III — Respect [#pillar-iii--respect]

### 10. Restraint by default, expression earned [#10-restraint-by-default-expression-earned]

**Rule.** The default character is calm: no overshoot, no flourish. Bounce and expressive timing are earned — by momentum the person supplied, or by a rare moment that deserves emphasis.

**Why.** IBM's Carbon system splits motion into *productive* (efficient, subtle, for getting work done) and *expressive* (vibrant, for significant moments), and reserves expressive motion for occasional, important moments. Apple's guidance on springs: a small bounce around 0.15 barely reads as bouncy, around 0.3 is clearly bouncy, and values above about 0.4 tend to feel exaggerated for UI. And overshoot feels right on a card you flicked, but wrong on a menu that simply appeared.

**In the framework.** The [character scale](/docs/tokens#character) defaults to `smooth` (no bounce). Bounce is unlocked only when (a) a gesture hands off real velocity, or (b) the intent's frequency tier is `rare`. The scale is capped below the point where bounce becomes exaggerated.

**Sources.** IBM Carbon, *Motion*; Apple, *Animate with Springs*; Kowalski, apple-design skill.

### 11. Motion is optional, meaning is not [#11-motion-is-optional-meaning-is-not]

**Rule.** Every motion has a defined reduced-motion behavior. Information conveyed by motion is never conveyed *only* by motion. A person's motion preference is never overridden.

**Why.** For people with vestibular disorders, non-essential motion can cause dizziness, nausea, and migraines. WCAG 2.3.3 asks that motion triggered by interaction can be disabled unless it is essential. Apple identifies the most problematic motion — scaling, spinning, multi-axis and multi-speed motion, peripheral movement — and recommends substitutes like dissolves, highlight fades, or color shifts. "Reduce" means *substitute*, not *remove*: the interface should still communicate state changes, just without vestibular triggers.

**In the framework.** Reduced-motion behavior is a required part of every intent, not an add-on. The framework honors the operating system preference automatically, supports an in-app override, and substitutes spatial motion with effect motion. Direct manipulation still tracks the finger — that motion is controlled by the person and is essential — but projection, bounce, parallax, and ambient motion are removed. See [Accessibility](/docs/accessibility).

**Sources.** WCAG 2.2 SC 2.3.3, 2.2.2, 2.3.1; Apple, *Reduced Motion evaluation criteria*; Apple HIG, *Motion*.

### 12. Smooth under stress [#12-smooth-under-stress]

**Rule.** Motion holds up on slow devices, under heavy load, and under rapid or adversarial input. When it can't, it degrades toward *less* motion, never toward *broken* motion.

**Why.** Rauno Freiberg's test for robustness is blunt: can you break it by scrolling fast, or when the battery is low? Most interactions are tuned on a fast laptop and fail in the real world. Dropped frames during motion read as the interface stumbling. Kowalski's performance guidance is to animate properties the browser can composite cheaply — transform and opacity — and avoid ones that force layout.

**In the framework.** Intents prefer compositor-friendly channels. Rapid repeated triggers retarget rather than queue. When the framework detects it cannot hold frame rate, it shortens or drops non-essential motion rather than stuttering through it. See [Performance](/docs/performance).

**Sources.** Freiberg, interview on robustness (UX Tools); Kowalski, design engineering skills; web.dev, *Interaction to Next Paint*.

---

## Summary card *(informative)* [#summary-card-informative]

| # | Principle | One line |
|---|---|---|
| 1 | Respond first | Acknowledge within 100 ms, on press |
| 2 | Purpose or nothing | Name the reason or don't move |
| 3 | Frequency sets the budget | Seen often → move less; keyboard → don't |
| 4 | Fast is a feature | ≤ ~300 ms; exits faster than entrances |
| 5 | Never lock the user out | Everything is interruptible |
| 6 | Continuity | Start from where it is, at the speed it's going |
| 7 | Behavior over timelines | Springs for space, curves for effects |
| 8 | The hand is truth | 1:1 tracking, then follow the gesture's intent |
| 9 | Origin and destination | Come from somewhere, go somewhere |
| 10 | Restraint by default | Calm default; bounce is earned |
| 11 | Motion is optional | Substitute, don't remove; never override preference |
| 12 | Smooth under stress | Degrade to less motion, never to broken motion |