Choreography

Overview

Choreography is what happens when more than one element has somewhere to be. It is the difference between an interface that appears to rearrange itself and one that appears to shatter and reassemble.

The organising idea is continuity: an element that exists before a transition and after it is the same element, and should be seen to move rather than to disappear and be replaced by something similar. Almost every choreography rule below is a consequence of that one, and the health-specific ones are consequences of the fact that on these screens the thing being moved is often a number somebody is anxious about.

Choreography is often confused with stagger. Stagger is one technique inside it, and it is the technique most often used badly.

How it works

Morph, do not swap. When a card opens into a detail view, the card becomes the detail view: its container grows, its title stays put and grows with it, its value stays put. It does not fade out while a new screen fades in. The reader's eye stays on the number the whole way, and that is the point, because they tapped it wanting to know more about it and should never have to find it again on the other side.

Practically this means a transition is authored as one element changing wherever the two states share a real element, and as an enter/exit pair only when they genuinely share nothing.

Depth on overlay, not translation across. A surface arriving on top of another is a change in depth. The arriving surface comes forward; the surface underneath recedes slightly and dims. Nothing slides sideways, because sideways means "you have gone somewhere else" and the reader has not. They are still on the results screen, with a sheet over it, and the interface should say so. This also makes the way back obvious, and it is what the layering contract is expressing visually.

One thing moves at a time. If two regions of the screen both animate, the reader has to choose which to watch and will usually choose wrong. Where a transition genuinely involves two regions, one leads and the other follows, with the follower starting as the leader settles rather than at the same instant.

Stagger is for lists, is short, and is capped. A list of tiles appearing may stagger, because a small delay between items in reading order expresses the order the reader should scan them in. Three rules keep it from becoming a performance: the per-item delay is a small fraction of the item's own duration; the total stagger is capped so a long list does not take a second to appear, with items past the cap arriving together; and staggering never applies to something already on screen. A list that re-staggers on every filter change is exhausting.

Order carries meaning, so order by importance. On a health screen, if anything staggers, the reading arrives before the chart and the chart arrives before the history. Never the reverse, and never in DOM-convenient order that happens to put the least important thing first.

Exits do not choreograph. Everything leaving leaves together, quickly. There is no reason to stagger a dismissal, and a staggered exit is the animation most likely to still be running when the next screen wants to start.

Using it

Ask what the reader is following. Good choreography has exactly one subject. If you cannot say which element the reader's eye is meant to be on, the sequence has more than one and needs cutting.

Do not choreograph a change in a value. Continuity is for position and container, not for content. If a reading updates to a new number, the number is replaced cleanly and in place, with no morph between digits. A morphing digit implies the value passed through the intermediate states, and it did not.

Do not choreograph around a status change. Nothing sweeps, ripples or cascades outward from a tile that has become urgent. Escalation is colour, icon and word, and a choreographed escalation is motion carrying urgency by the back door. See Motion, health rule 1.

Keep the whole sequence inside a single perceptual moment. A transition that takes longer than roughly the time it takes to look from one side of a phone to the other stops being a transition and becomes a scene. If a sequence needs more time than that, it is doing too much.

Tokens

Choreography consumes the same durations and easings as everything else, plus the stagger step and its cap. All of them are generated from tokens/motion.json by scripts/build-tokens.mts.

Accessibility impact

• Large-area coordinated movement is the highest vestibular risk in the system. Several elements moving in concert across a large part of the viewport is precisely the pattern that provokes symptoms, which is why depth-on-overlay is a small scale change and why nothing pans the screen.
• Stagger delays the last item, and somebody is reading the last item. Under reduced motion the stagger is removed entirely and everything appears together; the reading order is then carried by the DOM, where it belonged all along.
• Continuity must not be the only signal of identity. A morph tells a sighted reader that this detail view is that tile. A screen-reader user gets that from the heading, the accessible name and the announcement on arrival. All three must be correct with the animation removed.
• Focus moves once, at the end. A morphing transition must not move focus part-way through, and must land it on the new surface's heading or first control when it completes. Focus that moves mid-sequence is how somebody using a screen reader ends up narrating an element that no longer exists.
• Nothing in a sequence may block input. Each stage accepts interaction, and interrupting the sequence reverses it rather than queueing another.

Related

• Using motion has the five jobs the elements in a sequence are each doing, and their durations.
• Layering and elevation is the stacking contract that depth-on-overlay is the visual expression of.
• Reduced motion says what a morph, a stagger and a depth change each become when a reader has asked for less.