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-200msrange. - Full-screen transitions should target
300-500ms. - Avoid durations >
700msfor 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:
- Structural container transition starts first.
- Primary content transitions second.
- 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:
8elements. - 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 + translateover 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:
easeOutentrance,easeInexit - 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:
1000msloop max - Easing:
linearfor 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:
instantor <=100msfade - list stagger: disabled
- decorative loops: disabled
- route transitions:
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.tscodifies the documented duration and easing tokens for mobile.apps/oshun/mobile/src/components/DraggableBottomSheet.tsximplements the shared bottom-sheet recipe for assistant, domain-switcher, and quick-actions surfaces.apps/oshun/mobile/app/_layout.tsxroutes stack transitions through the shared reduced-motion-aware route transition helper.apps/oshun/mobile/src/accessibility/useReducedMotionPreference.tscombines system reduce-motion with the in-app reduced-motion preference fromapps/oshun/mobile/src/preferences/mobileExperienceSettings.ts.