# OSHUN Haptics Guidelines

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 `medium` impact
- 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:

- `selection` or `light` impact for standard controls
- `medium` for 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-feedback
- `medium`: standard confirmations and success cues
- `heavy`: 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:

1. lock/restriction
2. warning
3. success
4. 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.ts` is 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.ts` now defaults to the app-level
  haptics preference from
  `apps/oshun/mobile/src/preferences/mobileExperienceSettings.ts` unless 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.
