# OSHUN Ergonomics Requirements

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/specs/personas.md`

## 1. Purpose

This document defines ergonomic requirements for one-handed usage and thumb-zone
interaction in OSHUN.

This version covers:

- one-handed operation standards
- thumb-zone placement requirements

## 2. Ergonomic Design Assumptions

- Most primary sessions are short and mobile-first.
- A meaningful percentage of sessions occur in motion or context switching.
- Users alternate between left-hand and right-hand grip across sessions.
- Device diversity includes compact phones, large phones, and foldables.

## 3. Thumb-Zone Model

For portrait mobile layouts, define three zones per active hand:

- Primary Zone: naturally reachable area for repeated actions.
- Stretch Zone: reachable with mild thumb extension.
- Hard Zone: requires grip shift or second hand.

Practical reference grid (portrait):

- Primary Zone: lower 55% of screen height and hand-side 65% of width.
- Stretch Zone: middle 30% of height and opposite-side lower region.
- Hard Zone: top 15% of height and opposite-side upper corner.

Notes:

- Safe area insets are part of zone calculations.
- Foldables/tablets should default to two-hand assumptions unless one-hand mode
  is explicitly active.

## 4. One-Handed Interaction Requirements

### 4.1 Primary Action Reachability

- The dominant action on core shell surfaces must be in the Primary Zone.
- High-frequency controls (`continue`, `play`, `save`, `next`) must remain in
  Primary or Stretch Zone.
- No core journey should require repeated taps in Hard Zone.

### 4.2 Navigation Placement

- Global navigation controls should anchor to lower screen regions when
  possible.
- Primary tab navigation must remain comfortably reachable with one thumb.
- Domain switcher entry must be reachable without grip shift from Home.

### 4.3 Cross-Hand Neutrality

- Core actions must be usable for both left- and right-hand grip patterns.
- Avoid permanently biasing key actions to only one side.
- If side bias exists, provide mirrored layouts or alternate entry points.

### 4.4 Session Continuity in Motion

- Critical flows should tolerate imperfect taps and short interruptions.
- Confirm destructive actions; avoid accidental activation near edges.
- Maintain clear recovery if interaction is interrupted mid-flow.

### 4.5 Top-Area Usage Constraints

- Top-bar controls are reserved for low-frequency or contextual actions.
- Do not place repeated session-critical actions in top-right corners.
- Pull-to-refresh should always have an equivalent explicit control path.

## 5. Thumb-Zone Requirements by Surface

### 5.1 Home

- Primary CTA and top recommendation action: Primary Zone.
- Continue/resume strip actions: Primary Zone.
- Secondary controls (filter/sort): Stretch Zone preferred.

### 5.2 Explore/Search

- Search invocation must be reachable with one thumb from initial state.
- Domain filters and result actions should avoid Hard Zone clustering.
- Quick-save actions on cards should be reachable without grip shift.

### 5.3 Activity

- Timeline item primary actions: Primary or Stretch Zone.
- Retry/recover actions for failed items: Primary Zone.

### 5.4 Profile/Settings

- Frequently toggled preferences (notifications, theme) in reachable rows.
- Deep account/legal settings may appear outside Primary Zone.

## 6. Acceptance Criteria

- 90%+ of taps in critical flows occur in Primary or Stretch Zone.
- Core shell journeys can be completed one-handed on representative devices.
- Left-hand and right-hand usability validation is completed before release.
- No critical action requires repeated top-corner interactions.

## 7. Validation Method

- Conduct ergonomic walkthroughs on small, medium, and large phones.
- Run one-hand task tests for left- and right-grip scenarios.
- Record missed-tap hotspots and adjust control placement accordingly.
- Include ergonomic verification in design QA checklist per release.

## 8. Implementation Notes

- This document intentionally separates ergonomics from tap-target/motion/haptic
  specs, which are defined in adjacent tasks.
- Where standards conflict, accessibility and safety requirements take
  precedence.

## 9. Tap Targets and Spacing Standards

### 9.1 Minimum Target Size

- iOS interactive controls: minimum `44x44 pt`.
- Android interactive controls: minimum `48x48 dp`.
- Web/PWA interactive controls: minimum `44x44 CSS px` for touch contexts.
- Icon-only controls must still meet platform minimum target area.

### 9.2 Preferred Target Size

- Primary actions: target `48-56` logical pixels square equivalent.
- Repeated quick actions: prefer `>= 48` logical pixels in shortest dimension.
- Edge-adjacent controls should include extra safe hit padding when possible.

### 9.3 Inter-Target Spacing

- Minimum spacing between adjacent touch targets: `8 dp/px`.
- Preferred spacing in dense action rows: `12 dp/px`.
- Critical/destructive action separation: `>= 16 dp/px` and clear visual
  differentiation.

### 9.4 Exceptions

- Inline text links may be smaller than control minima when semantic text links
  are appropriate.
- Exception usage must include alternate enlarged hit area where practical.

## 10. Gesture Affordance Requirements

### 10.1 Required Gesture Support

- Tap: primary activation pattern for all core actions.
- Long press: optional secondary actions only, never sole path to critical
  features.
- Swipe: permissible for convenience actions (dismiss/archive/navigate), not as
  exclusive mechanism for critical completion.
- Pull-to-refresh: optional convenience with explicit refresh alternative.

### 10.2 Discoverability Rules

- Hidden gestures must include visible onboarding hints or first-run cues.
- Any gesture with side effects must provide clear visual feedback.
- Gesture-only controls must provide an accessible non-gesture alternative.

### 10.3 Error Prevention

- Destructive swipe actions require confirmation or undo window.
- High-impact actions must not trigger on minor incidental drags.
- Horizontal and vertical gestures should avoid conflict in nested scroll
  contexts.

### 10.4 Accessibility Alignment

- Gesture interactions must remain operable via assistive technologies.
- Keyboard and switch-access alternatives are required on web/PWA.
- Voice-control reachable controls should map to visible, labeled targets.
