# OSHUN V1 Ergonomic Budgets

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.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/releases/v1/specs/layout-density-tiers.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/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: `44x44` minimum, `48x48` preferred
- web touch contexts: `44x44` minimum
- 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: `8px` minimum
- dense repeated action rows: `12px` preferred
- destructive vs non-destructive neighbors: `16px` preferred 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:

- `0` repeated critical taps in Hard Zone
- `1` occasional 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 `480px`
  of 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 `320px` of 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:

1. select item in far-left table
2. move to far-right toolbar to act
3. move back to far-left table to continue
4. 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:

1. select or focus item
2. inspect essential context
3. approve / reject / escalate
4. 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 `3` additional steps when safe

Typical acceptable sequence:

1. choose bulk action
2. review summary or policy warning
3. 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-050` minimal chrome rules
- `V1-UX-051` layout density tiers
- `V1-UX-052` scan-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.tsx`
- `apps/oshun/mobile/app/(tabs)/explore.tsx`
- `apps/oshun/mobile/app/(tabs)/_layout.tsx`
- `apps/oshun/web/src/components/ShellLayout.tsx`
- `apps/oshun/web/src/components/QuickActionsTrayPanel.tsx`
- `apps/oshun/web/src/components/search/SearchResultsView.tsx`
- `apps/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.
