# MOTION & TRANSITION SPEC
**Kidunaverse Design Round 2 · what Flutter/Flame must render · July 7, 2026**

The rule underneath all of it: **motion is weather, not reward.** Nothing loops to attract attention; nothing bounces; nothing celebrates. Things settle, rise, recede, and seal. Every animation is interruptible; every one has a static fallback (reduced-motion and battery-saver render the final frame).

---

## 1. The ground (Flame, constitutive)

The one place the game engine is a reason, not plumbing.

- **Layered gradient field:** 2–3 radial gradients over espresso, positions drifting on a ~60s noise loop ("breathing"). Amplitude is a realm variable (Cosmic Humanity barely moves; Fellowship of Play swells).
- **Realm temperature:** the gradient hues are the grounding state's realm mix (≤12% hue into espresso — see REALM-EXPRESSION.md). Rendered as a shader uniform so drift is a continuous crossfade, not a repaint.
- **Activity glow:** the ember (Kiduna mark) modulates brightness with org-wide activity, low-pass filtered over ~10 min. A pulse, never a spike.
- **Weather tint:** the Sentinel's read as a faint tint band high in the field (amber = harmony drifting warm). Tint only; never an icon, never a number on the ground.
- **Ember particles:** ≤12 gold particles, reserved for signature moments (code signed, seal committed, room sealed). 2–3s, gravity-soft, then gone. Never ambient.
- **Budget:** ≤1 shader pass + particles; must idle under 5% GPU on a mid Android phone; static fallback is the blended gradient's final frame.

## 2. Drift (grounding change)

- **Trigger:** grounding state change from the server (reading deep, replying, working, room convening). Never a tap target.
- **Duration/curve:** 800–1400ms, `easeInOutCubic`, duration scaling with "distance" (how different the two configurations are).
- **What interpolates, in loose sync (deliberately not lockstep — neighborhoods arrive unevenly):** ground hue mix → token chip crossfade (old fades under, new fades over, 400ms, offset +200ms) → grounding line text swap (fade through 0, offset +400ms) → type mood (display scale/tracking, 600ms).
- **Interruptible & reversible:** the state is a float blend between configurations; a reversal mid-flight retargets, never snaps.
- **Blends are legal states:** the member can *stand between* two realms indefinitely (reading BiHome inside a Service Alliance errand). Engine requirement: ground shader accepts two realm configs + weight.
- **Forbidden:** any border flash, toast, breadcrumb, or "entering X" copy. Drift makes no sound.

## 3. The Account rendering

- **Compose-on-look:** on attention, claims settle top-down — 8px rise + fade, 180ms each, 40ms stagger, no spring. Ink drying, not cards dealing.
- **While the Renderer streams:** a quiet caret in the ally's voice line; never a skeleton screen (skeletons promise content and train waiting).
- **Correction print:** the correction block types its first line (300ms), then settles. The one place type "arrives," because corrections are the accountability ritual.
- **Sealing:** when the member scrolls past the rendering's foot, the foot stamps its artifact line (opacity 0.6→1, 200ms). No sound, no particle.

## 4. The deck (Docket)

- **Arrival:** when the deck becomes non-empty, the paper edge slides up 12px from the bottom, once, with a real shadow, 350ms `easeOutQuart`. It then *rests*. No pulse, no loop, no idle motion ever.
- **Open:** pull up (or tap) — cards fan from the edge with mild spring (stiffness 220, damping 26, no overshoot >4px). The Thread dims to 0.85 and scales 0.97 beneath.
- **Flip:** card flips on Y, 500ms, to its context back.
- **Press-and-hold signature:** radial gold fill, 1000ms linear (the deliberate second — never shortened). Haptic ramp through the hold; on commit, a single heavy haptic + gold seal stamp (scale 1.06→1.0, 250ms) + ≤12 ember particles. Release before commit rolls back at 2× speed — abandoning a signature costs nothing.
- **Card exit:** signed cards exit upward, "filed," 300ms. Skipped cards slide under the deck.
- **The door:** the last card's exit is followed by the deck edge sliding away and the ground brightening +4% for one breath (2s), then settling. Emptiness is announced by *light*, not copy.

## 5. Rooms (summons → room → seal)

- **The bell:** the summons rises *from the ground* — ground brightens toward the convening realm's hue, app chrome dims out (300ms), the summons sets in Goudy like a title card (text fades up 400ms). No ringtone by default; the Contract may grant sound.
- **In the room:** one shared surface, identical for all present. Presence marks (members and allies) arrive as small lights settling into an arc. Code strikes render one by one — each a short gold line drawn to the founder's mark (240ms each, sequential; nineteen codes = a visible, countable act of witness).
- **The seal:** the room's content condenses — scale toward a single mark (600ms `easeInCubic`), which stamps (as §4) and then *drops* into the Thread as an artifact line. The room is gone; there is no "room history."
- **Engine requirement:** rooms are a synchronized scene (server-timed cues) — Flame renders cue-driven sequences where all clients see the same strike at the same moment. Latency masking by cue windows, not by desync.

## 6. The Vigil (lens)

- **Open:** from a citation/card-back tap or by asking. The Thread scales to 0.96 and dims 0.8 (250ms); the lens slides over with 8% translucency — home visibly persists beneath.
- **Live content:** working-set lines stream as they change (fade-swap, 150ms). HEARTS strip flexes as values move — continuous, not stepped.
- **Close:** swipe down or lean-out; the lens recedes (250ms), the Thread returns to 1.0. **No residue:** no history entry, no scroll restoration on reopen, nothing persisted.

## 7. Making (birth)

- **The shape card** (ally proposing the thing) settles like a claim.
- **Birth:** on the member's strike (press-and-hold, §4 semantics — a birth is a code act), the made-thing's card gains its name in Goudy and its code chip in one stamp. One ember moment. It then exists in the Thread like any other real object.
- Never: progress bars, spinners, "deploying…" — the Registrar's latency is masked by the ally's sentence ("She's live. I put her where the river crew will find her.").

## 8. Global grammar

| Gesture | Meaning | Everywhere |
|---|---|---|
| pull down from top | the Contract | yes |
| pull up from bottom edge | the deck (only if it exists) | yes |
| press-and-hold, 1s | signature (codes, votes, seals, births) | the only way to sign |
| tap a citation | the Vigil lens | yes |
| swipe lens down | lean out, no residue | yes |
| scroll | time (the Thread) | the only scroll |

Timing tokens: `settle 180ms` · `overlay 250ms` · `object 350ms` · `flip 500ms` · `drift 800–1400ms` · `hold 1000ms` · `seal 600ms`. Curves: `easeOutQuart` for arrivals, `easeInCubic` for departures, `easeInOutCubic` for drift. Springs only on the deck, damped, never on type.
