# OSHUN Motion Language

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`.
