Duolith docs

0055. Elements move by themselves when shows and lists change, and motion= names a preset

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: none (WP12)

Context

An app feels like an app when things that appear, disappear or move do so smoothly. Pages should not need to describe movement to get that, and on native the platform's own feel should win, so pages cannot be handed durations and curves either. Shows and lists are where the view changes shape after it is built, so they are where movement belongs.

Decision

  • Automatic motion. When a <show> swaps its side, or a <list> adds, removes or reorders rows, the change moves:
    • an element that comes plays in (on the web: a 200 ms fade with a 6 px rise);
    • an element that goes stays drawn where it was, out of the layout, inert and hidden from assistive technology (data-leaving on the web), and plays out before it is removed;
    • every element beside the change that moved (the container's children, and the elements beside each of its ancestors up to the screen) glides from its old place to its new one (FLIP, 260 ms).
  • A show's or list's first build never moves: the screen arriving is the router's transition to play (decision 0032).
  • Presets. motion="..." on an element names the movement it plays as it comes and goes: fade, scale, slide-up, slide-down, slide-left, slide-right, spring, or none to switch automatic motion off. On a list it is every row's. The names are listed in spec/language/elements.yaml (motions); an unknown name is E0240, and a preset written as an expression is E0245, so each target can prepare its movement at build time. spring is a damped spring sampled into CSS linear() on the web.
  • Reduced motion. With prefers-reduced-motion: reduce, nothing glides to a new place, and every preset is a 120 ms fade.
  • Elements positioned out of the layout (fixed or absolute, such as a full-screen viewer) only move when they name a preset, and nothing moves automatically inside the overlay layer: overlays play their own movement (decision 0034).
  • Native is built in the engine adapter (packages/engine/src/motion.tsx): the same preset names, and automatic insert, remove and move, as animations Lynx runs, with reduced motion a short fade and no glide. They are CSS animations Lynx runs on both platforms rather than each platform's own layout animations, so iOS and Android move alike; whether that feels native enough is a device check (native/DEVICE-CHECKLIST.md). The solver planned for crates/runtime is not needed for this (decision 0054).

Alternatives considered

OptionWhy not
Motion only where a page asks for itMost apps would never ask, and would feel static
Durations and curves in markupCouples pages to the web's movement; native could not use the platform's own
Animate height of the show itselfExpensive, and fights content that sizes itself; moving the neighbours (FLIP) gives the same impression with transforms only
Keep leaving elements in the layout while they fadeThe rows around them would jump twice: once when the fade ends, again as they close up

Consequences

Tests that count elements straight after a show flips or a list shrinks see the leaving element until it has played out; they select :not([data-leaving]), finish the animations, or emulate reduced motion. Two existing browser tests were adjusted that way. Scroll-linked motion stays out of scope.