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.mddocs/releases/v1/specs/ergonomic-budgets.mddocs/releases/v1/scope/action-placement-rules.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/adr/ADR-0056-oshun-mobile-shell-relationship-model.mddocs/releases/v1/reports/current-state-redesign-inventory.mdapps/oshun/mobile/app/_layout.tsxapps/oshun/mobile/app/(tabs)/_layout.tsxapps/oshun/mobile/app/(tabs)/index.tsxapps/oshun/mobile/src/components/MobileAssistantLauncher.tsxapps/oshun/mobile/src/components/MobileAssistantSheet.tsxapps/oshun/mobile/src/components/QuickActionsTray.tsxapps/oshun/mobile/src/components/DomainSwitcherEntry.tsxapps/oshun/mobile/src/__tests__/nonfunctional/accessibility-ci.test.tsdocs/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.mddefines the Primary, Stretch, and Hard Zone model for one-handed portrait usage.OSHUN_V1_ERGONOMIC_BUDGETS.mdsets launch budgets such as0repeated critical taps in the Hard Zone and a25%viewport cap for consecutive primary tap travel.OSHUN_V1_MINIMAL_CHROME_RULES.mddeclares the bottom tab bar as the primary persistent control surface of the mobile shell.ADR-0050defines 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
44x44ptminimum on iOS,48x48dpon Android, and8ptminimum 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
44x44ptcomfortable 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-side65%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