Status: Draft v1.0 Owner: OSHUN Design + Mobile Engineering Last Updated:
February 16, 2026 Related: docs/releases/v1/design/ux-principles.md,
docs/releases/v1/design/motion-language.md
1. Purpose#
This document defines haptic feedback usage rules for OSHUN mobile experiences.
This version standardizes haptic behavior for:
- success
- warning
- lock/restriction
- action confirmation
2. Haptic Design Principles#
- Haptics should confirm intent, not create noise.
- High-intensity patterns are rare and meaningful.
- Critical signals must be distinguishable by feel.
- Haptics must always have visual/textual fallback.
3. Intent-to-Pattern Mapping#
3.1 Success#
Intent:
- Confirm successful completion of meaningful actions.
Examples:
- Completed meditation session
- Successful save/bookmark action
- Completed daily Arete check-in
Recommended pattern:
- Short positive multi-pulse or
mediumimpact - Duration budget: <= 120ms felt output
Do not use for:
- Routine navigation taps
- Non-committal previews
3.2 Warning#
Intent:
- Alert user to caution state without hard failure.
Examples:
- Weak connectivity affecting freshness
- Approaching limit/threshold
- Incomplete required step before continue
Recommended pattern:
- Distinct two-pulse warning waveform
- Stronger than selection, weaker than error/lock
Do not use for:
- Informational-only banners
- Repetitive periodic reminders
3.3 Lock/Restriction#
Intent:
- Communicate blocked action or access restriction.
Examples:
- Premium-gated action without entitlement
- Permission denied
- Temporarily unavailable action due to state constraints
Recommended pattern:
- Heavy single impact or short error-style burst
- Must pair with explicit reason text and recovery action
Do not use for:
- Recoverable warnings
- Background sync delays
3.4 Action Confirmation#
Intent:
- Confirm explicit user command was accepted.
Examples:
- Toggling setting
- Pressing primary CTA
- Mode switch with immediate state change
Recommended pattern:
selectionorlightimpact for standard controlsmediumfor high-importance confirmations
Do not use for:
- Every list item tap in dense scrolling views
- Repeated stepper increments at high frequency
4. Intensity Levels and Limits#
4.1 Intensity Levels#
light: low-friction confirmations and micro-feedbackmedium: standard confirmations and success cuesheavy: lock/restriction and rare high-importance outcomes
4.2 Frequency Controls#
- Max 1 haptic event per user gesture by default.
- Avoid back-to-back pulses within 300ms except deliberate multi-pulse patterns.
- Suppress non-critical haptics during rapid repeated interactions.
4.3 Priority Resolution#
When multiple haptic intents compete in one interaction:
- lock/restriction
- warning
- success
- action confirmation
Only highest-priority haptic should fire.
5. Accessibility and User Controls#
- Respect system haptics/reduced-motion preferences.
- Provide in-app haptic toggle and intensity preference where supported.
- Never rely on haptics as sole communication channel.
- Ensure all haptic-signaled outcomes have visible and screen-reader feedback.
6. Platform Notes#
- iOS and Android implementations may differ physically; semantic intent must remain consistent.
- Use existing platform-safe primitives already present in codebase
(
selection,light,medium,heavy,success,warning,error). - Treat haptics as best-effort; app behavior must remain correct when haptics are unavailable.
7. Anti-Patterns#
- Haptic on every touch event in scrollable lists
- High-intensity haptics for low-stakes actions
- Identical haptics for success and lock outcomes
- Triggering haptics before action result is known
8. Validation Checklist#
- Each major flow maps haptic intent to one defined category.
- Distinct outcomes (success vs warning vs lock) are distinguishable.
- Haptic behavior is tested on at least one iOS and one Android device.
- Accessibility settings and disabled-haptic behavior are verified.
9. Current Mobile Shell Implementation#
apps/oshun/mobile/src/feedback/mobileFlowFeedback.tsis the canonical mobile-shell mapping for the launch-critical flows covered in V1.- Current mapped shell flows:
- assistant open, prompt send, and action handoff
- domain switcher open and domain select
- quick actions tray open and core launch
- home refresh start and completion
apps/oshun/mobile/src/feedback/haptics.tsnow defaults to the app-level haptics preference fromapps/oshun/mobile/src/preferences/mobileExperienceSettings.tsunless a caller explicitly overrides it.- Dismiss-only gestures such as sheet backdrop taps should avoid extra haptics unless the close itself is the primary outcome.