Eve library

OSHUN Ergonomics Requirements

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/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.