Core model

interanimate has one model for both animation and interaction. This page defines its building blocks. The Glossary collects every term in one place.

The central idea#

Everything that moves is a value. Values are moved either by a person (interaction) or by a behavior (motion). Control passes between the two without a seam.

A card's horizontal position is a value. While someone drags the card, the interaction owns that value and sets it directly. When they let go, a motion takes ownership and carries it to rest — starting from the exact position and velocity the interaction left behind. If they grab it again mid-flight, ownership passes back. The value never jumps, and nobody waits.

That hand-off is the heart of the framework. Every other concept exists to make it reliable, expressive, and accessible.

The five layers#

interanimate is organized as five layers. Each higher layer is expressed entirely in terms of the layer below, and each layer is usable on its own. This is how the framework is both opinionated and general-purpose: the intent layer makes the right thing easy, and the lower layers make anything possible.

┌───────────────────────────────────────────────┐
│ 5. Intents        what this moment means      │  ← opinionated front door
├───────────────────────────────────────────────┤
│ 4. Choreography   how moments relate          │
├───────────────────────────────────────────────┤
│ 3. Tokens         shared scales of feel       │
├───────────────────────────────────────────────┤
│ 2. Motions & Interactions                     │
│    what moves values, and who's in control    │
├───────────────────────────────────────────────┤
│ 1. Values         the continuous state        │  ← unopinionated foundation
└───────────────────────────────────────────────┘
        Preferences & Environment (cross-cutting)

Layer 1 — Values#

A value is any continuously changing quantity that affects what's on screen: a position, a scale, an opacity, a color, a progress fraction, a scroll offset.

Every value has, at every instant:

• a presentation value — what is on screen right now;
• a velocity — how fast and in which direction it is changing;
• a target — where it is currently headed (which may be the presentation value, if it's at rest);
• an owner — the one motion or interaction currently in control of it.

A value has exactly one owner at a time. Ownership transfer always carries the presentation value and velocity forward (Principle 6).

Values belong to a channel:

• Spatial channels describe physical-feeling change: position, size, scale, rotation, shape. These feel wrong without momentum, so they default to springs.
• Effect channels describe visual qualities: opacity, color, blur, shadow strength. These have no inertia, so they default to timed easing.

The spatial/effect distinction is the single most important classification in the framework. It decides physics, reduced-motion substitution, and performance strategy.

Layer 2 — Motions and Interactions#

These are the two kinds of owner a value can have.

A motion is a behavior that moves a value toward a target over time without a person's direct control. interanimate defines three kinds:

An interaction is a person directly controlling a value through input — a drag, a scroll, a pinch, a slider. An interaction owns its values for as long as the input is active, and hands them back to a motion when the input ends.

The full rules for each are in the Motion model and Interaction model.

Layer 3 — Tokens#

Tokens are shared, named scales that describe how motion feels, so that teams speak in perceptual terms instead of milliseconds and stiffness constants. There are three:

• Tempo — how long a motion feels (instant → deliberate).
• Character — how much it overshoots (flat, smooth, lively, bouncy).
• Frequency — how often a person will see it (constant, frequent, occasional, rare), which caps the other two.

A token resolves to concrete parameters for whatever motion type is in use: a tempo of standard means one thing for a spring and a compatible thing for a tween. See Tokens.

Layer 4 — Choreography#

Choreography describes how multiple motions relate in space and time: where something originates, which elements move as a group, what follows what, and how exits mirror entrances. It turns individual motions into a coherent scene. See Choreography.

Layer 5 — Intents#

An intent is a declaration of what a moment means — "this is press feedback," "this is revealing a panel," "this is a navigation forward." An intent bundles a purpose, channels, tokens, choreography rules, and a reduced-motion behavior into a single named default.

Intents are the framework's front door. Most product code should only ever need intents. See Intents.

Cross-cutting: Preferences and Environment#

Two inputs affect every layer and are resolved before any motion starts:

• Preferences — what the person has asked for. Primarily motion preference (full or reduced), sourced from the operating system and optionally overridden in-app. Preferences are never overridden by an intent, token, or author.
• Environment — what the context can support: input modality (touch, fine pointer, keyboard), whether hover exists, device capability, and current performance headroom.

Apple's own guidance is an example of why environment matters: the same material can respond to direct touch with more emphasis than to a trackpad. interanimate treats modality as a first-class input to resolution, not a special case.

Resolution#

When something is about to move, interanimate resolves what actually happens in a fixed order. Each step can only reduce what the previous step allowed — never increase it.

1. Intent — what does this moment mean, and what's its default motion?
2. Author overrides — has the author adjusted tempo, character, origin, or choreography?
3. Frequency cap — does the frequency tier permit this tempo and character?
4. Environment — does the input modality or device warrant adjustment? Is there performance headroom?
5. Preference — does the person prefer reduced motion? If so, substitute per the intent's reduced behavior.

The result is a concrete set of motions on concrete values. Because preference is always last and can only reduce, no author choice can override a person's request for less motion.

Ownership rules (normative)#

1. A value has exactly one owner at a time.
2. Any new owner starts from the value's current presentation value and velocity.
3. An interaction always takes ownership from a motion immediately on input start. A motion never takes ownership from an active interaction.
4. When an interaction ends, ownership passes to a motion chosen by the intent (typically a spring to a resolved target, or decay followed by a spring).
5. A motion that is replaced is not "cancelled" from the person's point of view: there is no visible discontinuity.
6. Changes to underlying state happen immediately. Motion represents state changes; it never delays them.

How this maps to the web platform (informative)#

interanimate's model is defined independently of any rendering mechanism, but it is designed to map onto what the platform already offers. Same-document view transitions reached Baseline status across major browsers in late 2025, and scroll-driven animations are now shipping in all three major engines. These are natural targets for the navigation and scroll-linked parts of the model. Where a native mechanism can't honor a rule — most importantly, velocity-preserving interruption on gesture-driven values — the model's rules take priority. Rendering strategy is out of scope for this specification and will be defined separately.