# OSHUN V1 Reduced-Motion Behavior Rules

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

- `docs/releases/v1/design/motion-language.md`
- `docs/releases/v1/scope/motion-hierarchy-rules.md`
- `docs/releases/v1/specs/shared-component-accessibility-standards.md`
- `docs/releases/v1/scope/interaction-feedback-rules.md`
- `docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md`
- `apps/oshun/web/src/hooks/useReducedMotionPreference.ts`
- `apps/oshun/web/src/design-system/globals-v2.css`
- `apps/oshun/web/src/components/ShellLayout.tsx`
- `apps/oshun/web/src/components/DomainTransition.tsx`
- `apps/oshun/web/src/components/QuickActionsTrayPanel.tsx`
- `apps/oshun/web/src/components/assistant/AssistantPanel.tsx`
- `apps/oshun/web/src/components/RecommendationCarousel.tsx`
- `apps/oshun/web/src/components/domains/tara/BreathworkTimer.tsx`
- `apps/oshun/web/src/components/routines/RoutineSummaryDashboard.tsx`
- `apps/oshun/web/src/design-system/components/Confetti.tsx`
- `apps/oshun/mobile/src/accessibility/useReducedMotionPreference.ts`
- `apps/oshun/mobile/src/components/DraggableBottomSheet.tsx`
- `apps/oshun/mobile/src/recommendations/RecommendationCarousel.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical reduced-motion behavior for OSHUN V1 across
major animated surfaces on web and mobile.

The repo already has partial reduced-motion handling in global CSS, the web and
mobile reduced-motion hooks, recommendation carousels, bottom sheets, Tara
breathwork, dashboard widgets, assistant motion, and confetti. What is still
missing is one canonical reduction model that answers a simple question:

When OSHUN learns that a user prefers reduced motion, what exactly changes?

This document provides that answer.

## 2. Current Repo Signals And Gap

Current implementation review shows:

- web global styles already collapse transition and animation duration under
  `prefers-reduced-motion`
- shared design-system CSS already disables most animation and shimmer intensity
- the assistant panel defines its own reduced-motion override block
- web and mobile recommendation carousels already remove hide animations when
  reduced motion is active
- the mobile bottom sheet already shortcuts dismissal animation when reduced
  motion is active
- Tara breathwork already reads reduced-motion preference and adapts ritual
  animation behavior
- dashboard and chart surfaces already define reduced-motion keyframe
  alternatives
- confetti already treats reduced motion as a signal to suppress extra sensory
  output

The gap is consistency:

- some surfaces use the shared reduced-motion hook while others rely on CSS only
- some surfaces fully simplify motion while others merely shorten duration
- some high-motion shells, such as route and domain transitions, still expose
  only manual animation-disabling controls instead of a canonical
  user-preference contract
- there is not yet one product-wide matrix that says which motions disappear,
  which remain as quick fades, and which should remain structurally visible

## 3. Core Doctrine

### 3.1 Reduced Motion Means Simplify, Not Slow Down

Reduced motion is not the same animation at half speed.

The system must remove:

- travel
- bounce
- parallax
- stagger
- looping ornament

before it merely reduces duration.

### 3.2 Preserve Causality, Not Spectacle

Users still need to understand:

- what changed
- where it changed
- whether work is in progress
- whether a panel opened, closed, or completed

Reduced motion must preserve that clarity without asking the eye or vestibular
system to track large movement.

### 3.3 Continuous Loops Collapse First

The first things to disappear are:

- pulsing halos
- decorative shimmer
- confetti
- waveform bounces
- glow loops
- idle ambient animation

### 3.4 Structural Surfaces May Keep Quiet Opacity Continuity

When motion is still useful for orientation, reduced-motion behavior may retain:

- instant state swap
- opacity-only reveal
- very short anchored fade

It should not retain:

- cross-screen travel
- spring overshoot
- multi-step morphs
- delayed cascade entrances

### 3.5 Reduced Motion Is Cross-Platform

Web and mobile must use the same product intent even when the implementation
mechanism differs.

## 4. Canonical Reduced-Motion Ladder

| Motion family                    | Default behavior                                  | Reduced-motion behavior                                                  |
| -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| decorative ambient loops         | shimmer, glow, pulse, idle flourish               | disabled entirely                                                        |
| staggered entrances              | cards, rows, chips, message cascades              | show immediately with no stagger                                         |
| route and domain transitions     | fade, scale, slide, overlay sweep, icon morph     | instant swap or opacity-only handoff <= `120ms`                          |
| panels, drawers, sheets          | edge travel, spring settle, backdrop fade         | anchored reveal with opacity-only or near-instant translation <= `120ms` |
| inline interaction feedback      | hover lift, ripple, tiny scale                    | color, border, or opacity change only                                    |
| progress and chart draw-ins      | bars grow, rings draw, counters pop               | render final state immediately or with minimal opacity cue               |
| celebratory feedback             | confetti, bursts, trophy pulses, check draws      | no confetti or burst; use text, icon, or static status confirmation      |
| voice and typing indicators      | waveform bounce, dot bounce, mic pulse            | static label, quiet opacity pulse, or no animation                       |
| carousels and scrolling emphasis | auto-advance, animated removal, momentum flourish | no auto-advance, instant removal, no ornamental scroll-linked motion     |

Interpretation rules:

- `<= 120ms` means quick continuity, not a second animation system.
- If the surface still feels animated when screen-recorded at normal speed, it
  is probably not reduced enough.
- Motion hierarchy still applies, but reduced motion collapses each level to a
  simpler form.

## 5. Major Surface Rules

### 5.1 Shell, Route, And Domain Transitions

Examples in current repo:

- `ShellLayout.tsx`
- `DomainTransition.tsx`

Rules:

- Page-enter, domain-enter, and domain-switch motion must collapse to either an
  immediate swap or a short fade-through.
- No slide, scale, overlay expansion, or icon morphing remains in reduced
  motion.
- Sticky shell aids such as scroll-to-top and progress indicators may remain,
  but their reveal should be opacity-only and non-bouncy.
- Components that currently expose `disableAnimation` only for tests or manual
  control are incomplete until that switch can be driven by the actual user
  preference in production.

### 5.2 Drawers, Sheets, Trays, And Command Surfaces

Examples in current repo:

- `QuickActionsTrayPanel.tsx`
- `OverlaySheet.tsx`
- `DraggableBottomSheet.tsx`
- assistant sheet/panel surfaces

Rules:

- Reduced motion removes spring behavior, overshoot, and long swipe-settle
  animations.
- A sheet may still appear from the logical edge, but movement must be short,
  anchored, and optional enough that a simple opacity reveal would feel
  equivalent.
- Backdrop changes must stay quieter than panel changes.
- Drag-to-dismiss may remain as an input gesture, but dismissal completion must
  not rely on a long closing animation.

### 5.3 Assistant And Conversational Surfaces

Examples in current repo:

- `AssistantPanel.tsx`

Rules:

- Typing dots, voice waveforms, relevance reveals, tool-action flourish, and
  engagement banners must lose bounce, stagger, and pulse-first emphasis.
- The panel itself may still appear with a short anchored reveal, but not with
  springy side travel.
- Voice capture and speech playback states must stay understandable through
  text, icon, and status language even when waveform motion is absent.
- The assistant FAB must not pulse repeatedly under reduced motion.

### 5.4 Recommendation, Browse, And Discovery Surfaces

Examples in current repo:

- web `RecommendationCarousel.tsx`
- mobile `RecommendationCarousel.tsx`

Rules:

- Card removal, feedback acknowledgement, and section reveal should become
  immediate or opacity-only.
- Auto-advance or scroll-linked flourish is non-canonical under reduced motion.
- Horizontal carousels must remain fully operable through touch, keyboard, or
  explicit navigation without relying on animated momentum cues.

### 5.5 Ritual, Breathing, And Recovery Surfaces

Examples in current repo:

- `BreathworkTimer.tsx`

Rules:

- The ritual must stay understandable through timer, phase label, progress ring,
  and haptic or audio cues without requiring the user to follow expanding or
  contracting circles.
- Breathing guidance should switch from kinetic coaching to stable visual
  posture plus explicit time and phase copy.
- Celebration and streak motion should collapse to static acknowledgement.
- Reduced motion must not remove the functional rhythm of the exercise, only the
  sensory load of animated coaching.

### 5.6 Dashboards, Charts, And Progress Surfaces

Examples in current repo:

- `RoutineSummaryDashboard.tsx`

Rules:

- KPI entrances, count-up motion, row slides, ring draws, and bar growth should
  render at final value or reveal through a short opacity change.
- Live data updates may retain a tiny visual acknowledgement, but must not
  replay onboarding-style motion every refresh.
- Analytics surfaces should feel calmer, not deader. The data still needs a
  readable freshness cue even when animation is gone.

### 5.7 Celebration, Feedback, And Reward Surfaces

Examples in current repo:

- `Confetti.tsx`
- success bursts and celebration patterns in shared/global styles

Rules:

- Confetti, burst particles, shake, trophy pulses, and similar flourish are off
  by default in reduced motion.
- Success still needs acknowledgement through language, icon change, status
  chips, or a quiet checkmark.
- Optional sound should also be treated as suspect when it exists only to
  intensify a celebration effect.

### 5.8 Loading, Skeleton, And Idle States

Examples in current repo:

- `globals-v2.css`
- `app/globals.css`

Rules:

- Shimmer becomes static or a very gentle opacity change.
- Loading indicators must stop the moment content is ready.
- Idle decorative motion cannot remain active just because it is background
  rather than interactive.

## 6. Implementation Rules

### 6.1 One Preference Source Per Platform

- Web motion surfaces should use `prefers-reduced-motion` through CSS,
  `useReducedMotionPreference`, or both when JS behavior must change.
- Mobile motion surfaces should use the platform accessibility preference hook.
- Product surfaces must not invent route-local reduced-motion toggles that drift
  away from the OS signal unless a later product requirement explicitly adds a
  synced in-app override.

### 6.2 CSS-Only Collapse Is Not Always Enough

CSS duration clamping is a useful fallback, but it is insufficient when the
behavior itself must change.

Examples:

- hiding a carousel item should skip the wait time, not simply animate faster
- confetti should not start at all
- assistant waveforms should switch to non-animated state indicators
- domain transitions should choose a simpler transition path, not just a shorter
  version of the original

### 6.3 No Stagger In Reduced Motion

Stagger is almost always ornamental for reduced-motion users.

If a surface still needs progressive disclosure, reveal structurally important
content immediately and defer only non-essential detail.

### 6.4 No Loop Without A Functional Reason

If an animation loops, teams must be able to answer:

- what functional information does the loop communicate
- what is the non-animated equivalent
- why a static state would be insufficient

If those answers are weak, the loop is non-canonical under reduced motion.

## 7. Verification Standard

Reduced-motion readiness is complete only when:

- the affected surfaces read the platform preference through the canonical
  mechanism for that platform
- motion-heavy features collapse to the behavior defined in this document
- the final state remains legible without animation
- any automation or screenshots used for signoff include at least one explicit
  reduced-motion check for the changed surface

For current OSHUN V1 work, teams should treat reduced-motion QA as mandatory
for:

- shell transitions
- overlays and sheets
- assistant motion
- carousels and browse flows
- ritual or coaching surfaces
- dashboards with animated metrics
- celebratory success states

## 8. Definition Of Done

A major animated surface satisfies the OSHUN V1 reduced-motion standard only
when:

- the user preference is detected automatically
- travel, stagger, and looping ornament are removed
- continuity remains clear through state, opacity, text, or structure
- success, loading, and progress cues still communicate meaning
- the reduced-motion path feels intentionally designed rather than accidentally
  broken

Reduced motion is complete only when the calmer version still feels like the
same product, but no longer asks the body to track unnecessary movement.
