Eve library

OSHUN Motion Language

Guide

Revision 1

On this page

Status: Draft v1.0 Owner: OSHUN Design + Frontend Engineering Last Updated: February 16, 2026 Related: docs/releases/v1/design/ux-principles.md, docs/releases/v1/design/ergonomics-requirements.md

1. Purpose#

This document standardizes motion behavior in OSHUN across mobile, web, and PWA to ensure consistency, legibility, and performance.

This version covers:

  • duration tokens
  • easing tokens
  • sequencing and staggering rules
  • reduced-motion fallback behavior

2. Motion Principles#

  • Motion must clarify state changes, not decorate screens.
  • Fast interactions should feel responsive, not abrupt.
  • Large transitions should preserve orientation and continuity.
  • Motion must not block task completion.

3. Duration Tokens#

Durations are specified in milliseconds (ms).

Token Value Usage
instant 0 No animation / reduced-motion fallback
fastest 75 Micro-feedback on tiny UI updates
faster 100 Control-state changes
fast 150 Button, chip, and card feedback
normal 200 Default UI transitions
medium 300 Surface entrance/exit
slow 400 Large panel/sheet transitions
slower 500 Full-screen route changes
slowest 700 Rare emphasis transitions

Standards:

  • Primary interactive feedback should remain in 100-200ms range.
  • Full-screen transitions should target 300-500ms.
  • Avoid durations > 700ms for core product actions.

4. Easing Tokens#

Use cubic-bezier/easing curves consistently by intent.

Token Value Intent
linear linear Continuous loops/progress
easeIn cubic-bezier(0.4, 0.0, 1.0, 1.0) Exits / acceleration
easeOut cubic-bezier(0.0, 0.0, 0.2, 1.0) Entrances / deceleration
easeInOut cubic-bezier(0.4, 0.0, 0.2, 1.0) State changes with in/out balance
emphasizedDecelerate cubic-bezier(0.05, 0.7, 0.1, 1.0) Priority entrances
emphasizedAccelerate cubic-bezier(0.3, 0.0, 0.8, 0.15) Priority exits

Standards:

  • Entrance animations default to easeOut.
  • Exit animations default to easeIn.
  • Transform-and-opacity transitions default to easeInOut.
  • Spring/bounce curves are restricted to intentional playful contexts and must not be used in critical information flows.

5. Sequence and Stagger Rules#

5.1 Transition Order#

When multiple UI elements change in one interaction:

  1. Structural container transition starts first.
  2. Primary content transitions second.
  3. Secondary metadata and ornaments transition last.

This order preserves orientation and prevents cognitive overload.

5.2 Stagger Tokens#

Token Value Usage
tight 30ms Dense list updates
normal 50ms Standard card/list reveal
relaxed 75ms Larger content groups
loose 100ms Hero/section reveal

Standards:

  • Max recommended stagger count for one sequence: 8 elements.
  • Total reveal window for core content should remain <= 400ms.
  • Staggers should not delay first actionable element visibility.

5.3 Layered Motion Limits#

  • Avoid simultaneous multi-axis movement on the same element.
  • Prefer combined opacity + translate over complex transform stacks.
  • Avoid parallax or camera-like effects in dense information views.

6. Pattern Library (Default Recipes)#

6.1 Tap Feedback#

  • Duration: 100-150ms
  • Easing: easeOut
  • Motion: subtle scale/opacity or elevation shift

6.2 Card Entrance#

  • Duration: 200-300ms
  • Easing: easeOut
  • Motion: translateY(8-16) + opacity

6.3 Modal/Bottom Sheet#

  • Duration: 300-400ms
  • Easing: easeOut entrance, easeIn exit
  • Motion: vertical translation + backdrop opacity

6.4 Route Transition#

  • Duration: 300-500ms
  • Easing: easeInOut
  • Motion: horizontal or subtle fade-through, not both heavily

6.5 Loading Indicators#

  • Duration: 1000ms loop max
  • Easing: linear for continuous loops
  • Rule: loops must pause/stop immediately when content is ready

7. Reduced Motion Requirements#

  • Respect platform reduced-motion settings by default.
  • Replace non-essential movement with instant state updates.
  • Preserve functional cues using opacity/color/state changes.
  • For reduced-motion mode:
    • route transitions: instant or <= 100ms fade
    • list stagger: disabled
    • decorative loops: disabled

8. Performance Requirements#

  • Target 60fps for core transitions on representative devices.
  • Prefer transform/opacity animation paths over layout-thrashing properties.
  • Avoid long-running animations on heavily interactive screens.
  • Motion regressions must be tested on at least one mid-range Android profile.

9. Governance#

  • Motion token changes require design + frontend sign-off.
  • Any exception to duration/easing defaults must be documented in PR notes.
  • Motion standards are reviewed quarterly against performance and accessibility outcomes.

10. Current Mobile Shell Implementation#

  • apps/oshun/mobile/src/motion/mobileMotion.ts codifies the documented duration and easing tokens for mobile.
  • apps/oshun/mobile/src/components/DraggableBottomSheet.tsx implements the shared bottom-sheet recipe for assistant, domain-switcher, and quick-actions surfaces.
  • apps/oshun/mobile/app/_layout.tsx routes stack transitions through the shared reduced-motion-aware route transition helper.
  • apps/oshun/mobile/src/accessibility/useReducedMotionPreference.ts combines system reduce-motion with the in-app reduced-motion preference from apps/oshun/mobile/src/preferences/mobileExperienceSettings.ts.