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.mddocs/releases/v1/design/customer-visual-thesis.mddocs/releases/v1/design/admin-visual-thesis.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.mdapps/oshun/web/src/components/ShellLayout.tsxapps/oshun/web/src/components/DomainTransition.tsxapps/oshun/web/src/components/QuickActionsTrayPanel.tsxapps/oshun/mobile/src/components/MobileAssistantSheet.tsxdocs/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:
L5is the strongest motion event, but it should be infrequent.L4must preserve spatial understanding, not imitateL5.L1-L3should never read like route transitions.L0should never compete withL1-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
L5event may be primary L4events should suppress nearby decorative revealsL1-L2feedback 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