0032. Transitions are kinds of navigation, and each target plays its own movement
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: none
Context
Moving between screens should feel like an app: on iOS a pushed screen slides in from the trailing edge, on Android it rises and fades, tabs switch without movement. The web needs a sensible default now; native will use the platform's own transitions later. If pages described the movement (durations, curves), native could not honour the platform's.
Decision
The navigator decides a kind for each navigation, and each target maps the kind to its own movement (TransitionKind in packages/client/src/navigation.ts):
| Kind | When | Web |
|---|---|---|
push | A link inside a screen, navigate(path), browser forward | New screen slides in 36% from the trailing side and is opaque by 30% of the way; the old one drifts 16% back and dims (320 ms) |
pop | back(), browser back | The same movement in reverse, the leaving screen on top |
switch | A link in a layout's own markup, such as a tab bar | Crossfade (180 ms) |
replace | navigate(path, { replace: true }), a guard's redirect | Crossfade (180 ms) |
none | The first screen | None |
Only the part that changes moves: when two routes share layouts, the transition plays inside the deepest shared layout's <slot />, so a tab bar never slides. With prefers-reduced-motion: reduce, every kind is a 120 ms crossfade with no movement. A navigation during a transition finishes the running one at once. Pages cannot set a transition yet.
Alternatives considered
| Option | Why not |
|---|---|
| The View Transitions API | Not in every browser we target, and snapshots of whole documents fight with the screen stack keeping covered screens mounted |
A transition= attribute on links | Couples markup to web movement; kinds cover the cases the examples need |
| Decide push or switch by path depth | Wrong for tab bars whose tabs are at different depths; where the link sits says what the user meant |
| No movement on the web | The brief asks for app feel; reduced motion still gets none |
Consequences
Native targets need only map five kinds. A per-link or per-page override, and shared-element morphs (the glossary's morph), can be added later as new information on a navigation without changing pages that do not use them.