Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-053
Related:
docs/releases/v1/design/ergonomics-requirements.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/releases/v1/specs/layout-density-tiers.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical ergonomic budgets for OSHUN V1 across:
- tap distance
- thumb reach
- pointer travel
- scroll fatigue
- repeated admin actions
The older ergonomics baseline in
docs/releases/v1/design/ergonomics-requirements.md establishes one-handed and
tap-target fundamentals. This document adds the V1 budget layer that product,
design, and engineering teams must use to decide whether a flow is operationally
acceptable.
These are launch budgets, not aspirational guidelines.
2. Why Budgets Matter#
An interface can be visually polished and still feel physically tiring.
OSHUN V1 must avoid:
- repeated mobile taps in hard-to-reach zones
- desktop pointer ping-pong across wide layouts
- excessive scrolling before first useful action
- operator flows that make reviewers repeat the same motion loop dozens of times
The correct question is not only "can the user complete the task?" It is "can the user complete the task repeatedly without fatigue, grip shifts, or travel waste?"
3. Canonical Budget Summary#
| Budget | Canonical V1 target |
|---|---|
| Minimum touch target | 44x44 CSS px / pt minimum, 48x48 preferred for repeated actions |
| Minimum spacing between touch targets | 8px minimum, 12px preferred in dense action rows |
| Mobile hard-zone tap budget | 0 repeated critical taps per screen; 1 occasional contextual tap maximum |
| Mobile primary-action reach budget | primary actions must remain in Primary or Stretch Zone; not Hard Zone |
| Consecutive mobile tap travel budget | repeated primary taps should usually shift no more than roughly 25% of viewport height between steps |
| Desktop object-to-action pointer travel | high-frequency actions should usually sit within 320px of the object in dense operator views, 480px in calmer customer views |
| Scroll-to-first-value budget | first meaningful content or action must appear in the initial viewport on core flows |
| Scroll-to-primary-action budget | primary action should be visible immediately or after no more than one viewport of scroll |
| Repeated admin loop budget | common queue/review loops should complete in <= 4 atomic interactions per item when safe |
| Bulk admin loop budget | after selection, bulk action completion should require no more than 3 additional steps when policy allows |
4. Tap Distance Budgets#
4.1 Target Size#
All interactive surfaces must meet these minimums:
- mobile touch controls:
44x44minimum,48x48preferred - web touch contexts:
44x44minimum - repeated quick actions: prefer shortest dimension
>= 48
Critical and repeated actions should not ship at bare-minimum size unless there is a hard space constraint and a larger invisible hit area compensates.
4.2 Inter-Target Distance#
Spacing requirements:
- adjacent touch targets:
8pxminimum - dense repeated action rows:
12pxpreferred - destructive vs non-destructive neighbors:
16pxpreferred plus clear visual differentiation
If two controls are easy to hit accidentally in motion, they are too close.
4.3 Step-To-Step Travel#
For multi-step mobile flows:
- repeated next-step taps should remain vertically close to one another
- moving the user from bottom action to top confirmation and back again should be treated as a budget breach
Canonical threshold:
- consecutive primary taps should usually move no more than
25%of viewport height between steps
If a flow exceeds that threshold, use sticky actions, progressive disclosure, or local action placement.
5. Thumb Reach Budgets#
5.1 Mobile Reach Zones#
OSHUN uses the existing three-zone mobile model:
- Primary Zone
- Stretch Zone
- Hard Zone
For V1:
- primary actions must stay in Primary or Stretch Zone
- repeated actions must stay in Primary Zone whenever feasible
- top-corner reach should be reserved for low-frequency contextual controls
5.2 Hard-Zone Budget#
Per screen:
0repeated critical taps in Hard Zone1occasional contextual Hard Zone interaction maximum
Examples of acceptable Hard Zone use:
- opening a settings sheet once
- dismissing a banner occasionally
Examples of unacceptable Hard Zone use:
- repeated continue/save/approve actions
- repeated filter toggles
- row-by-row admin decisions on mobile
5.3 Cross-Hand Neutrality#
If a core mobile flow is strongly biased to one side:
- provide a mirrored affordance
- provide a bottom-anchored alternative
- or restructure the action placement
No launch-critical flow should assume a right-handed grip as the only normal case.
6. Pointer Travel Budgets#
6.1 Customer Desktop And Web#
For standard desktop customer surfaces:
- the primary action for a selected object should usually appear within
480pxof that object - search, save, continue, and open actions should not require corner-to-corner travel across the viewport
6.2 Dense Operator Surfaces#
For queues, tables, and cockpit views:
- high-frequency actions should usually sit within
320pxof the acted-on row, selection summary, or detail pane - pointer round-trips between selection region and action region should be minimized
- repeated workflows must prefer inline actions, sticky action bars, keyboard shortcuts, or inspector-side actions over distant page-level buttons
This aligns with the admin PRD requirement for keyboard-driven queue triage, side-by-side evidence review, and safe bulk actions.
6.3 Budget Breach Pattern#
This is a breach:
- select item in far-left table
- move to far-right toolbar to act
- move back to far-left table to continue
- repeat dozens of times
If the workflow repeats, pointer travel must compress.
7. Scroll Fatigue Budgets#
7.1 First Value#
On core customer and operator flows:
- first meaningful content or first meaningful action must appear in the initial viewport
Users should not scroll before they understand the surface.
7.2 Primary Action#
On launch-critical flows:
- primary action visible immediately is preferred
- if not immediately visible, it should appear within one viewport of scroll
For long forms or long reviews, sticky footers or sticky summary/action bars should preserve reachability.
7.3 Filter And Browse Fatigue#
Filter chrome must not push first results too far down the page.
Canonical rule:
- after visible filter controls, at least part of the first result set should still appear in the initial viewport for browse-heavy flows
7.4 Operator Scroll Fatigue#
For queues, incidents, and approval work:
- selection context, key status, and next action should stay co-located
- the user should not need to scroll a full additional viewport just to confirm or complete the currently selected item
If a cockpit requires repeated long scroll jumps between evidence and approval controls, it is not operator-grade.
8. Repeated Admin Action Budgets#
8.1 Per-Item Loop Budget#
Common queue, review, and incident loops should complete in <= 4 atomic
interactions per item when policy allows.
Typical acceptable loop:
- select or focus item
- inspect essential context
- approve / reject / escalate
- optional confirm or rationale entry
If a common loop requires more steps, the workflow should justify the extra friction with safety or compliance need.
8.2 Bulk Action Budget#
After multi-select:
- bulk action should require no more than
3additional steps when safe
Typical acceptable sequence:
- choose bulk action
- review summary or policy warning
- confirm
If the system forces row-by-row repetition where a safe bulk path is possible, the ergonomics budget is being wasted.
8.3 Keyboard And Alternate Path Budget#
Repeated admin actions must have an acceleration path:
- keyboard shortcut
- inline row action
- sticky action strip
- bulk action rail
Pointer-only repetition is not acceptable for the canonical operator cockpit.
8.4 State Preservation#
Repeated loops must preserve:
- current filters
- current selection context when safe
- current scroll position when safe
- current sort/view mode
Resetting the operator to the top of a queue after each action is a hard ergonomic failure.
9. Breakpoint Guidance#
9.1 Mobile#
- thumb reach budgets dominate
- sticky actions are often necessary
- filters and helpers must compress aggressively before content does
9.2 Tablet#
- treat tablet as transitional, not as stretched phone
- preserve reachable action clusters
- do not assume all desktop pointer-travel budgets disappear
9.3 Desktop#
- pointer travel and repeated admin loops dominate
- wide layouts must keep actions near the data they modify
- persistent toolbars should reduce travel, not add ornamental distance
10. Relationship To Other UX Rules#
This document is the ergonomics budget layer.
It works with:
V1-UX-050minimal chrome rulesV1-UX-051layout density tiersV1-UX-052scan-first content hierarchy rules
It does not replace the deeper one-handed mobile rule set that follows later in the backlog. It sets the measurable limits that future component and layout rules must respect.
11. Implementation Contract#
These budgets should directly govern current and future surfaces including:
apps/oshun/mobile/app/(tabs)/activity.tsxapps/oshun/mobile/app/(tabs)/explore.tsxapps/oshun/mobile/app/(tabs)/_layout.tsxapps/oshun/web/src/components/ShellLayout.tsxapps/oshun/web/src/components/QuickActionsTrayPanel.tsxapps/oshun/web/src/components/search/SearchResultsView.tsxapps/oshun/web/src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx
Any high-frequency flow that breaches these budgets must either be redesigned or document an explicit launch exception.
12. Exit Standard#
A flow meets the OSHUN V1 ergonomics budget only when:
- repeated actions stay physically easy
- mobile actions avoid hard-zone repetition
- desktop travel feels local instead of cross-canvas
- first value and first action arrive before fatigue starts
- operator loops retain pace under repetition
If the product feels tiring after ten repetitions, it is not within budget.