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.mddocs/releases/v1/scope/motion-hierarchy-rules.mddocs/releases/v1/specs/shared-component-accessibility-standards.mddocs/releases/v1/scope/interaction-feedback-rules.mddocs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.mdapps/oshun/web/src/hooks/useReducedMotionPreference.tsapps/oshun/web/src/design-system/globals-v2.cssapps/oshun/web/src/components/ShellLayout.tsxapps/oshun/web/src/components/DomainTransition.tsxapps/oshun/web/src/components/QuickActionsTrayPanel.tsxapps/oshun/web/src/components/assistant/AssistantPanel.tsxapps/oshun/web/src/components/RecommendationCarousel.tsxapps/oshun/web/src/components/domains/tara/BreathworkTimer.tsxapps/oshun/web/src/components/routines/RoutineSummaryDashboard.tsxapps/oshun/web/src/design-system/components/Confetti.tsxapps/oshun/mobile/src/accessibility/useReducedMotionPreference.tsapps/oshun/mobile/src/components/DraggableBottomSheet.tsxapps/oshun/mobile/src/recommendations/RecommendationCarousel.tsxdocs/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:
<= 120msmeans 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.tsxDomainTransition.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
disableAnimationonly 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.tsxOverlaySheet.tsxDraggableBottomSheet.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.cssapp/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-motionthrough 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.