# Choreography

> How motions relate in space and time — origins, relationships, sequencing, staggering, and enter/exit symmetry.

A single motion answers "how does this move?" **Choreography** answers "how do these moves relate?" It's what turns a collection of animated elements into a scene a person can read at a glance. Choreography is mostly about **orientation** (Principle 9): showing where things come from, where they go, and how they're connected.

## Origins [#origins]

Every `reveal`, `conceal`, `navigate`, and `morph` has an **origin** — the place it is spatially connected to.

| Origin kind | Meaning | Example |
|---|---|---|
| **Trigger** | The element that caused it | A menu grows out of its button |
| **Edge** | A side of the viewport or container | A toast slides up from the bottom; a sheet from its edge |
| **Self** | Its own center | A centered dialog |
| **Shared** | An element present before and after | A thumbnail that becomes a full image |

### Origin rules *(normative)* [#origin-rules-normative]

1. Surfaces anchored to a trigger originate at the trigger. Their transform origin points toward it, so the motion visibly "comes out of" the thing you pressed.
2. Exits return toward the origin they came from. A toast that entered from the bottom leaves to the bottom.
3. Centered modal dialogs originate from themselves. They are a deliberate break from context, not a continuation of it.
4. If an element exists both before and after a change, it **persists** — it moves or morphs rather than disappearing and reappearing.

## Relationships [#relationships]

Elements in a scene relate to each other in a few recurring ways. These come largely from Willenskomer's UX in Motion principles, which identify relationships between interface objects as one of the main ways motion supports usability.

- **Parenting.** Children move with their parent. A card's contents don't animate independently while the card is moving; they ride along.
- **Grouping.** Things that belong together move together, sharing tempo and direction.
- **Leading and following.** The element that matters most moves first; supporting elements follow slightly after. This is Disney's *follow-through and overlapping action*, applied to interfaces — a principle Rauno Freiberg singles out as one of the most useful for making UI feel natural rather than robotic.
- **Covering.** A surface moving over another (a sheet over a page) reads as being in front. The surface beneath may dim or recede slightly, but should not move much on its own.

## Sequencing and staggering [#sequencing-and-staggering]

When multiple elements change together, interanimate defines how they order.

### Stagger [#stagger]

A **stagger** offsets the start of each element in a group so they enter as a cascade rather than all at once.

- Stagger offsets are small — tens of milliseconds per item, not hundreds.
- The total stagger is capped, so a long list doesn't take seconds to finish. Beyond a few items, the remainder enter together.
- Stagger is **decorative**. It never delays interactivity: every item is usable the moment it's visible.
- Stagger is reserved for `occasional` and `rare` moments. Lists a person sees constantly simply appear.

### Ordering rules *(normative)* [#ordering-rules-normative]

1. **Make room, then arrive.** When an item is inserted, neighbors move aside before the item enters.
2. **Leave, then close the gap.** When an item is removed, it exits before neighbors move in.
3. **Outgoing before incoming.** In a navigation, the outgoing view begins leaving before (or as) the incoming view arrives — never after.
4. **Primary first.** The element a person is most likely to look at moves first.
5. **Nothing waits on decoration.** No ordering rule may delay a state change or block input.

## Symmetry [#symmetry]

Reversible transitions are symmetric. Open and close, expand and collapse, forward and back use mirrored paths, so a person can predict where something will go by remembering where it came from. Apple's fluid-interface guidance notes the same point: reversible motion should retrace its path.

Symmetry is about **path**, not **timing**. Exits are still faster than entrances (Principle 4).

## Direction in navigation [#direction-in-navigation]

`navigate` always carries a direction, and direction maps to space consistently across an application:

| Direction | Typical meaning | Spatial mapping |
|---|---|---|
| **Forward / back** | Deeper or shallower in a sequence | Mirrored lateral movement |
| **Up / down** | Into or out of a level of hierarchy | Content rises over, or settles back beneath |
| **Lateral** | Between peers (tabs) | Crossfade or a short lateral shift matching tab order |

The mapping is chosen once per application and held. A person who learns that "forward" moves left-to-right should never see it move right-to-left.

## Under reduced motion [#under-reduced-motion]

Choreography still applies — relationships and ordering are about meaning, not movement. Under reduced motion:

- Origins are expressed by *where* things fade in, not by movement from there.
- Staggers collapse to simultaneous.
- Ordering rules still hold (outgoing before incoming, leave before close the gap), using effect transitions.
- Shared-element morphs become crossfades in place.