mobile-motion-patterns

name	mobile-motion-patterns
description	Motion design rules for the Agenta mobile app (web/mobile) — the shared presets in src/lib/motion, when to animate, and reduced-motion requirements. Use when adding any animation or transition under web/mobile, animating navigation, sheets, skeletons, or list/chat surfaces.

Mobile motion patterns

All animation in web/mobile uses the motion package through the shared presets module src/lib/motion/presets.ts. Components never define their own durations, easings, or springs.

The presets

Consume via the hook (reduced-motion aware — this is mandatory):

import {useMotionPresets} from "@/lib/motion/presets"

const {sharedAxisPush, sheetSlideUp, crossfade, reduced} = useMotionPresets()

• sharedAxisPush — list → chat navigation (and any parent → child screen push). Forward uses custom={1}, back uses custom={-1}; the back gesture/button reverses the same preset. Wrap sibling screens in <AnimatePresence custom={direction} initial={false}>.
• sheetSlideUp — spring-based bottom sheets (project drawer). Pair with a crossfade scrim.
• crossfade — skeleton → content swaps. Skeleton and content must occupy identical geometry so the fade causes zero layout shift.

Rules

• Animate navigation, containment, and state swaps — not decoration. No attention-seeking motion, no animating properties that trigger layout (animate transform/opacity only).
• Reduced motion is not optional. useMotionPresets() returns instant variants when prefers-reduced-motion is set; any animation built outside the presets module must justify itself in review AND handle reduced motion itself (prefer extending the presets module instead).
• Message entrance/streaming (WP3b+): subtle and consistent with the playground's feel — entrance is a small fade/rise on the preset tokens; text streaming is never per-character animated.
• New shared patterns go INTO presets.ts (one exported preset + doc comment), not into a component file.