Eve library

OSHUN Haptics Guidelines

Guide

Revision 1

On this page

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.