# OSHUN V1 Motion Hierarchy Rules

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-060`  
Related:

- `docs/releases/v1/design/motion-language.md`
- `docs/releases/v1/design/customer-visual-thesis.md`
- `docs/releases/v1/design/admin-visual-thesis.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.md`
- `apps/oshun/web/src/components/ShellLayout.tsx`
- `apps/oshun/web/src/components/DomainTransition.tsx`
- `apps/oshun/web/src/components/QuickActionsTrayPanel.tsx`
- `apps/oshun/mobile/src/components/MobileAssistantSheet.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical motion hierarchy for OSHUN V1 across
entrances, state changes, sticky context, split-view transitions, and
reduced-motion fallbacks.

The repo already has:

- timing and easing guidance in `docs/releases/v1/design/motion-language.md`
- route and page entrance behavior in `ShellLayout.tsx`
- domain-switch overlays in `DomainTransition.tsx`
- trays, sheets, and assistant-panel motion on web and mobile

What is still missing is the hierarchy between those motions. Without that
hierarchy, individually reasonable animations start competing for attention.

## 2. Current Repo Signals And Gap

Current implementation review shows:

- the shell already uses page-enter animation and sidebar-width transitions
- domain transitions already use a stronger overlay and morph posture
- trays, sheets, dropdowns, and local controls already use fast transform and
  opacity transitions
- reduced-motion behavior exists in some components but is not yet one canonical
  product ladder

This task establishes the ladder that decides which motions are dominant, which
must stay quiet, and which collapse first under reduced motion.

## 3. Core Doctrine

### 3.1 Motion Must Rank Itself

The user should always be able to tell whether motion is:

- confirming a tiny interaction
- revealing local state
- preserving context
- moving between panes
- entering a new route

These motions cannot all feel equally strong.

### 3.2 The Screen Gets One Primary Motion Event At A Time

If a route entrance is already happening, sticky bars, list rows, chips, and
decorative flourishes must quiet down.

### 3.3 Context Preservation Beats Spectacle

Motion should help the user keep their place, especially for:

- sticky headers
- drawers and trays
- split views
- evidence or study flows
- operator workspaces

### 3.4 Reduced Motion Is A Real Mode, Not A Lower Quality Version

Reduced motion should preserve structure and causality while removing travel,
stagger, and ornamental loops.

## 4. Canonical Motion Ladder

| Level | Motion type                     | Canonical role                                                            | Typical duration band               |
| ----- | ------------------------------- | ------------------------------------------------------------------------- | ----------------------------------- |
| `L1`  | interaction feedback            | confirm hover, press, toggle, and selection                               | `100-150ms`                         |
| `L2`  | local state change              | reveal inline detail, filter expansion, row update, loading-to-ready swap | `150-250ms`                         |
| `L3`  | sticky context adjustment       | condense or reveal pinned context without stealing attention              | `150-250ms`                         |
| `L4`  | panel and split-view transition | drawers, sheets, inspectors, side panels, pane resize/rebalance           | `200-400ms`                         |
| `L5`  | route or domain entrance        | page enter, shell handoff, domain transition, full-attention scene change | `300-500ms`                         |
| `L0`  | ambient/decorative loop         | background presence only, never primary                                   | continuous but visually subordinate |

Interpretation rules:

- `L5` is the strongest motion event, but it should be infrequent.
- `L4` must preserve spatial understanding, not imitate `L5`.
- `L1-L3` should never read like route transitions.
- `L0` should never compete with `L1-L5`.

## 5. Entrance Rules

### 5.1 Route And Page Entrances

Use `L5` only for:

- initial route load
- domain switch
- full-attention scene change

Rules:

- One structural entrance per route.
- Prefer opacity plus small-axis travel over theatrical multi-axis movement.
- The first actionable content must appear early in the sequence.
- Child-module stagger must stay subordinate to the route itself.

### 5.2 Section Entrances

Use `L2` or quiet `L4` for section reveals.

Rules:

- Avoid replaying a full route-style entrance for every module in the viewport.
- On dense operator surfaces, section entrances should often be disabled or
  nearly instant.
- Scroll-triggered reveals should be used sparingly and never gate reading.

## 6. State-Change Rules

### 6.1 Interaction Feedback

Use `L1` for:

- hover
- press
- selected state
- small chip, tab, or button changes

Rules:

- Feedback should feel immediate.
- Use subtle scale, opacity, elevation, or color change.
- Do not combine bounce, glow, and travel on routine controls.

### 6.2 Inline State Swaps

Use `L2` for:

- accordion reveal
- filter expansion
- inline success or warning update
- loading-to-ready transitions

Rules:

- The structural frame should stay stable.
- Avoid long fade delays before content becomes readable.
- Replace shimmer or loop states as soon as real content is ready.

## 7. Sticky Context Rules

Sticky context includes:

- pinned headers
- progress bars
- persistent compare controls
- active routine bars
- contextual summary rails

Use `L3`.

Rules:

- Sticky context should slide, compress, or fade with minimal travel.
- It should feel like the same object changing posture, not a new object
  entering.
- Sticky transitions must be shorter and quieter than route or sheet motion.
- When sticky context appears during scroll, it must not trigger secondary
  staged reveals nearby.

## 8. Split-View And Panel Rules

Split-view transitions include:

- inspector open/close
- drawer or tray open/close
- evidence rail expansion
- compare-mode pane introduction
- side-panel width rebalance

Use `L4`.

Rules:

- Preserve one anchored region while the other region moves.
- Favor width, translate, and opacity changes over complete redraw theatrics.
- A split-view change should never feel like leaving the page.
- When introducing a secondary pane, the primary content should remain visually
  stable enough to preserve orientation.

### 8.1 Width Rebalance

- Pane resizing should feel smooth but dry.
- Use moderate spring or standard easing, never bouncy showmanship.
- Width rebalance should usually complete inside `200-300ms`.

### 8.2 Drawer And Sheet Behavior

- Backdrop fades are subordinate to the panel movement.
- The panel should enter from the nearest logical edge.
- Small sheets and trays should feel lighter than full modals.
- Nested drawer or stacked-sheet motion is non-canonical by default.

## 9. Reduced-Motion Rules

Reduced motion collapses the system as follows:

| Motion type                | Reduced-motion behavior                                                    |
| -------------------------- | -------------------------------------------------------------------------- |
| `L1` interaction feedback  | color or opacity change only; avoid scale where possible                   |
| `L2` local state change    | instant or near-instant fade; no stagger                                   |
| `L3` sticky context        | direct appear/disappear or minimal fade; no noticeable slide distance      |
| `L4` panel/split-view      | instant state change or <= `100ms` fade; preserve clear focus and layering |
| `L5` route/domain entrance | instant update or minimal fade only                                        |
| `L0` ambient loops         | disabled or frozen still frame                                             |

Rules:

- No parallax, pulse loops, floating objects, or repeated shimmer in
  reduced-motion mode.
- Functional structure must still be obvious without travel animation.
- Reduced motion should be honored consistently across customer and admin
  surfaces.

## 10. Concurrency Rules

### 10.1 One Dominant Motion Window

At any given moment:

- only one `L5` event may be primary
- `L4` events should suppress nearby decorative reveals
- `L1-L2` feedback may continue, but should stay small

### 10.2 Suppression Rules

When `L5` route or domain motion runs:

- disable or reduce list stagger
- suppress sticky-bar entrance theatrics
- avoid starting panel transitions unless essential

When `L4` panel motion runs:

- keep internal item stagger minimal
- do not also animate the page container heavily

## 11. Customer Versus Admin Translation

### 11.1 Customer Motion

- More atmospheric but still restrained.
- Entrance easing may feel softer and more embodied.
- Ambient motion is allowed when it supports presence.

### 11.2 Admin Motion

- Shorter, drier, and more operational.
- Prioritize confirmation, status change, and context preservation.
- Decorative entrances and theatrical transitions are off-thesis.

## 12. Anti-Patterns

The following are non-canonical for OSHUN V1:

- route entrances plus heavy child stagger plus ambient motion all at once
- sticky headers that drop in like modals
- split-pane transitions that feel like a full page replacement
- hover and press states that use oversized scale or glow
- reduced-motion mode that only slows motion down instead of simplifying it
- decorative loops on dense evidence or operator surfaces

## 13. Acceptance Standard

A redesigned surface satisfies `V1-UX-060` only when all are true:

- its motions map clearly to the canonical ladder
- route, panel, sticky, and local feedback motions do not compete
- split-view and sheet transitions preserve orientation
- reduced-motion behavior is explicitly defined and calmer than the default
- the surface still feels coherent when all non-essential motion is removed
