# OSHUN V1 One-Handed Mobile Ergonomic Rules

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-064`  
Related:

- `docs/releases/v1/design/ergonomics-requirements.md`
- `docs/releases/v1/specs/ergonomic-budgets.md`
- `docs/releases/v1/scope/action-placement-rules.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/adr/ADR-0056-oshun-mobile-shell-relationship-model.md`
- `docs/releases/v1/reports/current-state-redesign-inventory.md`
- `apps/oshun/mobile/app/_layout.tsx`
- `apps/oshun/mobile/app/(tabs)/_layout.tsx`
- `apps/oshun/mobile/app/(tabs)/index.tsx`
- `apps/oshun/mobile/src/components/MobileAssistantLauncher.tsx`
- `apps/oshun/mobile/src/components/MobileAssistantSheet.tsx`
- `apps/oshun/mobile/src/components/QuickActionsTray.tsx`
- `apps/oshun/mobile/src/components/DomainSwitcherEntry.tsx`
- `apps/oshun/mobile/src/__tests__/nonfunctional/accessibility-ci.test.ts`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical rules for one-handed mobile use in OSHUN V1,
with emphasis on:

- safe thumb zones
- repeated-action comfort
- bottom-edge clearance
- top-area restraint
- cross-hand neutrality

The goal is not merely to make the app reachable once.

The goal is to make core OSHUN flows comfortable when repeated, interrupted, or
used in motion on small phones.

## 2. Current Repo Signals, External Scan, And Gap

The current repo already establishes the main ergonomics baseline:

- `ERGONOMICS_REQUIREMENTS.md` defines the Primary, Stretch, and Hard Zone model
  for one-handed portrait usage.
- `OSHUN_V1_ERGONOMIC_BUDGETS.md` sets launch budgets such as `0` repeated
  critical taps in the Hard Zone and a `25%` viewport cap for consecutive
  primary tap travel.
- `OSHUN_V1_MINIMAL_CHROME_RULES.md` declares the bottom tab bar as the primary
  persistent control surface of the mobile shell.
- `ADR-0050` defines the mobile shell as five structural tabs plus a global
  assistant sheet rather than a sixth peer tab.
- Current mobile implementation already uses bottom-reachable patterns: bottom
  tabs, an assistant launcher positioned above tab chrome, draggable bottom
  sheets for assistant and quick actions, and horizontally scrollable domain
  switching chips.
- Mobile accessibility checks already require `44x44pt` minimum on iOS,
  `48x48dp` on Android, and `8pt` minimum spacing between adjacent touch
  targets.

External platform guidance points in the same direction:

- Apple’s current platform guidance emphasizes safe areas, keeping controls at
  comfortable physical sizes, and treating the regions around the thumbs as the
  right home for frequent actions.
- Apple also explicitly treats the top of the screen as a better location for
  infrequent controls such as menu actions.
- Apple’s current touch guidance continues to anchor around a `44x44pt`
  comfortable tap target and recommends testing on real devices across sizes.

Inference from those sources plus the repo state:

- OSHUN already has the shell primitives needed for one-handed quality.
- OSHUN still needs one explicit rule set describing how those primitives should
  be arranged so tabs, launchers, sheets, chip rows, and repeated action loops
  do not compete for the same thumb territory.

## 3. Canonical Thesis

One-handed mobile OSHUN should behave like this:

- navigation anchors low
- repeated actions stay low
- top areas orient rather than demand work
- grip shifts are exceptional, not routine
- left-hand and right-hand use both feel first-class

If a flow repeatedly makes the user move from bottom action to top confirmation
and back again, it fails this standard even if every control technically meets
touch-target requirements.

## 4. Zone Model

### 4.1 Canonical Portrait Zones

OSHUN uses the existing three-zone model for one-handed portrait use:

- Primary Zone: lower `55%` of screen height and thumb-side `65%` of width
- Stretch Zone: middle `30%` of height plus limited opposite-side lower reach
- Hard Zone: top `15%` of height and opposite-side upper corner

These zones are always calculated after:

- safe-area insets
- bottom tab chrome
- active bottom sheets
- assistant launcher or persistent helper clearance

### 4.2 Safe Thumb Corridors

For V1, designers should treat the lower screen as two active corridors:

- bottom primary corridor: the lowest comfortably reachable band above tab
  chrome or sheet chrome; reserved for repeated actions and shell pivots
- lower-middle continuity corridor: the band above it; reserved for repeated
  cards, chips, quick actions, and local follow-up controls

The top bar and top corners are not part of either safe thumb corridor.

## 5. Core Rules

### 5.1 Bottom-First Action Placement

Repeated high-value actions must live in the bottom primary corridor whenever
feasible.

Examples:

- continue
- save
- approve
- retry
- quick domain launch
- assistant entry

Top-right placement is allowed only for low-frequency contextual controls.

### 5.2 No Repeated Top-Bottom Ping-Pong

A core flow must not repeatedly alternate between:

- a top-located selection or confirmation step
- and a bottom-located completion step

If a flow needs both, restructure it using:

- sticky bottom actions
- inline confirmations
- bottom sheets
- local section actions

### 5.3 Persistent Chrome Cannot Steal Thumb Territory

The following mobile chrome families all compete for the same lower-space
budget:

- bottom tab bar
- assistant launcher
- quick-actions trigger
- offline or queue banners
- sticky footers
- bottom sheets

Only one family may dominate a given bottom-edge band at a time.

If multiple persistent elements are active, they must stack by priority rather
than overlap or crowd the last tappable row.

### 5.4 Top Bars Orient, They Do Not Carry The Workflow

The mobile header may contain:

- title
- lightweight context
- one low-frequency utility action

The mobile header must not contain repeated workflow-critical controls such as:

- continue
- save
- review next
- open assistant
- open the primary domain switch

### 5.5 Cross-Hand Neutrality Is Mandatory

No launch-critical mobile flow may assume a right-handed grip.

When a control is side-biased:

- provide a centered or bottom-sheet alternative
- or provide a mirrored affordance nearby

Horizontally scrollable chip rows are acceptable only when the primary action
after selection remains centered or bottom-anchored.

### 5.6 Comfort Matters More Than Raw Density

On small phones:

- compress chrome before content
- compress secondary metadata before actions
- collapse optional controls before shrinking hit areas

A surface with more information but worse grip comfort is not the better mobile
surface.

## 6. Repeated-Action Comfort Rules

### 6.1 Repeated Actions Stay In One Band

If an action is expected to happen several times in one session, it should stay
within the same lower-band region across steps.

Examples:

- triaging activity items
- saving multiple recommendations
- opening several continuity cards
- retrying a queued sync flow

The user should not have to re-hunt the main button after every step.

### 6.2 Use Sheets For Short Decision Bursts

When a mobile action requires:

- a quick choice
- a short explanation
- one to four follow-up actions

use a bottom sheet or tray before using a full-screen takeover.

This matches the current assistant and quick-action model and keeps decisions in
the lower reach band.

### 6.3 Long Lists Need Reachable Local Actions

In long feeds, lists, and review stacks:

- row-level or card-level primary actions should be reachable without stretching
  to the header
- repeated control clusters should sit at the trailing lower edge of the item or
  in a sticky summary/action region

Do not force the user to scroll back to the top for the next meaningful action.

### 6.4 Destructive Actions Need Edge Safety

Destructive or high-risk actions should not sit flush against gesture edges or
home-indicator zones without extra breathing room.

On small screens:

- destructive actions get larger spacing
- destructive actions get confirmation
- destructive actions should not be the lowest, fastest, most thumb-natural
  control in a repeated loop

## 7. Surface Rules

### 7.1 Mobile Shell

Rules:

- bottom tab bar is the primary persistent navigation surface
- assistant launcher must clear the tab bar and safe-area inset
- global banners must not block the tab bar or the lowest visible row action
- if the lower edge is crowded, helper chrome yields before core navigation

### 7.2 Home

Rules:

- continue/resume actions belong in the safe thumb corridors
- domain-switch follow-up actions must remain bottom-reachable after selection
- quick actions should open from the bottom, not from a top-corner menu

### 7.3 Explore

Rules:

- search invocation must be reachable one-handed from initial state
- chip filters may sit in the lower-middle continuity corridor
- card-save and domain-launch actions must not require grip shifts

### 7.4 Activity

Rules:

- retry, recover, and continue actions must stay low and local to the item
- timeline review should not require repeated jumps into the header
- queued or degraded notices should sit near the affected action region when
  possible

### 7.5 Library

Rules:

- preserve and resume actions stay low and local to the selected content
- long metadata sections must not push the next useful action beyond one
  comfortable scroll movement
- export, delete, and rights-management actions need extra separation

### 7.6 Profile And Settings

Rules:

- frequent toggles and session controls should sit in reachable rows
- legal, billing, and infrequent account detail can live higher or deeper
- save or confirm actions for settings changes should not require repeated
  returns to top-right controls

### 7.7 Domain Routes

Rules:

- primary in-domain follow-up actions stay in the lower half
- compare, annotate, and save affordances should open sheets or local trays when
  they expand
- top-of-screen domain context remains descriptive, not operational

## 8. Safe-Area And Device-Class Rules

### 8.1 Safe Areas Are Interaction Constraints, Not Decoration Margins

Controls must clear:

- the iPhone home indicator
- rounded corners
- notches and cutouts
- the tab bar
- any floating launcher already occupying the edge

Do not treat safe-area compliance as sufficient if the resulting control still
lands in the Hard Zone.

### 8.2 Small Phones Set The Truth

One-handed ergonomic decisions must be validated first on compact phones.

If the layout only feels comfortable on tall or large devices, it is not
launch-ready.

### 8.3 Foldables And Tablets Are Not The Baseline

Foldables and tablets may adopt more spacious layouts, but the canonical mobile
one-handed rule set is defined by portrait phone use.

## 9. Do And Do Not Examples

### 9.1 Assistant Entry

- do: keep the launcher above tab chrome and within lower reach
- do not: move assistant entry to the top-right as the only path

### 9.2 Quick Decisions

- do: open a short bottom sheet for resume/save/continue actions
- do not: push the user into a full-screen modal for every quick action

### 9.3 Headers

- do: use headers for orientation and low-frequency utility
- do not: place repeated next-step controls in the header

### 9.4 Repeated Flows

- do: keep repeated actions in one lower-band location across steps
- do not: alternate between bottom CTA and top confirmation repeatedly

### 9.5 Device Edges

- do: leave breathing room above the home indicator and around destructive
  controls
- do not: anchor high-risk actions flush to gesture edges

## 10. Definition Of Done

One-handed mobile ergonomics is complete for a flow only when:

- repeated critical taps stay out of the Hard Zone
- the flow works for left-hand and right-hand use
- primary actions remain in safe thumb corridors
- persistent chrome does not crowd the same bottom-edge territory
- repeated actions stay spatially consistent from step to step
- top bars orient the flow rather than carrying it
- the flow is validated on compact phones, not only large devices
