Duolith docs

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):

KindWhenWeb
pushA link inside a screen, navigate(path), browser forwardNew 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)
popback(), browser backThe same movement in reverse, the leaving screen on top
switchA link in a layout's own markup, such as a tab barCrossfade (180 ms)
replacenavigate(path, { replace: true }), a guard's redirectCrossfade (180 ms)
noneThe first screenNone

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

OptionWhy not
The View Transitions APINot in every browser we target, and snapshots of whole documents fight with the screen stack keeping covered screens mounted
A transition= attribute on linksCouples markup to web movement; kinds cover the cases the examples need
Decide push or switch by path depthWrong for tab bars whose tabs are at different depths; where the link sits says what the user meant
No movement on the webThe 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.