# OSHUN V1 Form-Entry Ergonomic Rules

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

- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/scope/action-placement-rules.md`
- `docs/releases/v1/scope/one-handed-mobile-ergonomic-rules.md`
- `docs/releases/v1/scope/dense-data-admin-ergonomic-rules.md`
- `docs/releases/v1/specs/shared-component-accessibility-standards.md`
- `apps/oshun/web/src/design-system/components/FormField.tsx`
- `apps/oshun/web/src/design-system/components/SearchInput.tsx`
- `apps/oshun/web/src/design-system/components/ReviewDecisionControl.tsx`
- `apps/oshun/web/src/design-system/components/__tests__/FormField.test.tsx`
- `apps/oshun/web/src/components/studio/StudioBellonaBuildQueueTrackingWorkspace.tsx`
- `apps/oshun/web/src/components/studio/StudioHathorEconomyModelingWorkspace.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical ergonomics rules for form entry in OSHUN V1,
especially:

- inline filters
- search
- note-taking and comment capture
- approval and signoff controls
- multi-step review and wizard flows

The goal is not to make every input surface look like a generic enterprise form.

The goal is to make entry-heavy OSHUN workflows feel:

- calm
- explicit
- low-friction
- keyboard-credible
- easy to recover from when the user makes a mistake

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

The current repo already contains strong form-entry primitives:

- `FormField.tsx` already establishes explicit labels, field-level hint text,
  inline error messaging, character counts, focus emphasis, and multiline note
  support.
- `SearchInput.tsx` already supports a visible search affordance, clear action,
  loading state, shortcut hint, and result-count feedback.
- `ReviewDecisionControl.tsx` already uses label-first approval capture with
  helper text explaining the consequence of each review state.
- `StudioBellonaBuildQueueTrackingWorkspace.tsx` already demonstrates search
  focus shortcuts, inline filters, queue wizards, advanced settings disclosure,
  approval actions, and signoff-note capture.
- `StudioHathorEconomyModelingWorkspace.tsx` already demonstrates list search,
  filter controls, wizard templates, notes fields, collaboration comments with
  mentions, and production signoff owner plus notes.
- Existing tests already verify label rendering, error semantics, character
  count behavior, hint behavior, and end-to-end operator workflows across
  wizard, collaboration, and signoff paths.

External implementation guidance reinforces the same baseline:

- W3C’s current form tutorials emphasize visible labels, keeping instructions
  close to the field, and avoiding placeholder-only naming.
- W3C validation guidance emphasizes clear error identification, forgiving input
  formats where possible, and confirm/review/undo affordances for important
  submissions.
- GOV.UK’s current form guidance continues to favor short label text, direct
  field-specific error messages, and character count support only when a real
  limit exists.
- USWDS search guidance says search terms should persist into the results view,
  search should not require a hidden advanced mode for common tasks, and the
  search field should remain large enough for meaningful entry.
- W3C and USWDS step guidance both treat progress indicators as useful for
  genuinely sequential multi-step flows, not as decorative chrome for short or
  non-linear forms.

Inference from those sources plus the repo state:

- OSHUN already has the right low-level input primitives.
- OSHUN still needs one canonical rule set that explains how filters, search,
  notes, approvals, and review steps should behave as one family instead of as
  separate local implementations.

## 3. Canonical Thesis

Form entry in OSHUN should feel like guided capture, not clerical labor.

That means:

- labels are explicit
- defaults are calm
- errors are local
- progress is obvious
- repeated actions stay easy

The user should never have to infer:

- what a field is for
- whether a filter is active
- what an approval decision means
- whether notes will matter later
- what step they are on in a review flow

## 4. Core Rules

### 4.1 Labels Name The Job, Placeholders Fill The Gap

Every meaningful input must have a persistent visible label.

Placeholder text may:

- show an example
- show a pattern
- suggest expected tone or format

Placeholder text must not:

- carry the only field name
- replace review-step instructions
- hide approval meaning

### 4.2 Instructions Belong At Field Level When The User Needs Them

Put helper text directly under the field when it explains:

- requirement
- consequence
- allowed format
- review scope
- recovery path

Do not move essential instructions into:

- distant banners
- modal footnotes
- tooltip-only disclosure

### 4.3 Errors Must Be Local, Specific, And Recoverable

Error copy should use the language of the field label and state the fix
directly.

Good:

- `Signoff owner is required.`
- `Notes must stay under 500 characters.`
- `Choose an approval decision before continuing.`

Bad:

- `Submission failed.`
- `Invalid input.`
- `Please correct the highlighted fields.`

Global summaries are acceptable for long forms, but each blocked field still
needs its own inline error state.

### 4.4 Keep Entered Work Whenever Feasible

Validation failures must not wipe:

- search terms
- filters
- note drafts
- approval selections
- wizard step data

Important review flows should preserve work across:

- inline validation
- route-level refresh when feasible
- permission or policy rechecks that do not invalidate the entered value

### 4.5 One Primary Commit Per Entry Region

Each form region should expose one dominant commit action.

Examples:

- `Save wizard changes`
- `Apply collaboration update`
- `Approve signoff`
- `Add comment`

Do not present three peer commit buttons with equal emphasis at the bottom of
the same entry region.

## 5. Filters And Search

### 5.1 Filters Start Small And Stay Legible

Follow the existing OSHUN filter ladder:

1. one or two inline primary filters
2. compact supporting filter controls
3. overflow into drawer, panel, or sheet only when complexity is real

The filter region should support narrowing the result set, not replace the
result set.

### 5.2 Active Filters Must Be Obvious

The surface must make all of these easy to see:

- which filters are active
- what search term is active
- how to clear or reset the state
- how the result scope changed when count feedback exists

Hidden filter state is non-canonical.

### 5.3 Search Must Preserve Query Continuity

Search terms should persist while the user:

- scans results
- changes adjacent filters
- opens a detail panel
- returns from a review action

The clear action should be explicit and one step away.

### 5.4 Search Input Must Be Real Working Space

Search inputs should be wide enough for meaningful terms, not token-width stubs.

If the surface is search-heavy:

- keep search visible without opening another panel
- allow keyboard focus shortcuts on desktop where the workflow benefits
- keep the query visible after submission

### 5.5 Placeholder Copy In Search Is Secondary

Search placeholder text may suggest scope such as:

- `Search by queue, owner, or lane`
- `Search economies, IDs, or owners`

It must not be the only accessible name for the field.

## 6. Notes, Comments, And Multiline Capture

### 6.1 Multiline Fields Need A Declared Purpose

Notes fields should answer one explicit question:

- rationale
- evidence summary
- handoff context
- risk note
- reviewer feedback

Do not label a high-consequence textarea simply `Notes` when the workflow
actually needs something narrower such as `Signoff notes` or
`Reason for changes requested`.

### 6.2 Notes Should Encourage Decision-Useful Content

Use helper text or placeholder examples when the downstream reader needs a
particular kind of note.

Preferred guidance patterns:

- what evidence was reviewed
- what changed
- what risk remains
- who needs to act next

Avoid empty motivational filler such as:

- `Add any thoughts here`
- `Write something helpful`

### 6.3 Character Counts Must Reflect A Real Limit

Show character count only when:

- the field has a meaningful limit
- the user is likely to approach that limit
- the limit changes whether the note can be saved

Do not add counters to every textarea by default.

### 6.4 Mention And Collaboration Entry Must Stay Comprehensible

When comments support mentions:

- keep the mention syntax or picker local to the field
- show the parsed mentions after submission
- do not hide critical routing consequences in an invisible parser

The author should know who the note is trying to involve before they submit it.

## 7. Approval And Signoff Controls

### 7.1 Approval Choices Must Explain Consequence

Approval controls should pair the decision label with helper text describing the
outcome.

Examples:

- `Approved` plus what happens next
- `Changes requested` plus what must be revised
- `Rejected` plus whether the item returns or closes

The user should not need domain memory to decode the approval vocabulary.

### 7.2 Dangerous Review Actions Require Separation

Positive commit actions and negative review actions must not blur together.

Separate:

- `Approve`
- `Request changes`
- `Reject`
- `Revoke`

with spacing, ordering, or confirmation structure that makes accidental
selection unlikely.

### 7.3 Signoff Requires Identity, Evidence, And Status

A signoff surface should keep these visible together:

- current owner or reviewer
- note or rationale capture
- current status
- commit action

If the user has to bounce between distant panels to understand who is signing,
what evidence exists, and what the current gate state is, the signoff surface
has failed.

### 7.4 Review Capture Must Support Undo Or Reversal Where The Workflow Allows

For approvals, signoffs, and high-consequence updates, the preferred recovery
model is one of:

- explicit revoke
- undo history
- editable pending state before final submission

Irreversible review submission should be rare and must be signaled plainly.

## 8. Multi-Step Review And Wizard Flows

### 8.1 Use Steps Only When The Flow Is Truly Sequential

Step indicators or named stages are justified when the user must progress
through `3+` distinct ordered stages.

Do not add step chrome to:

- short one-screen forms
- optional advanced-settings disclosure
- non-linear review cockpits

### 8.2 Each Step Needs Its Own Task Framing

Every step in a wizard or review flow should answer:

- what this step is for
- what input is required here
- what the next action will do

The step label alone is not enough.

### 8.3 Advanced Settings Are Secondary, Not Hidden Requirements

Advanced fields may live behind:

- `details`
- accordion disclosure
- secondary panel

only when the common path can complete without them.

Required fields should not be buried in `Advanced settings`.

### 8.4 Review Flows Need Persistent Orientation

In long review flows, keep visible:

- current object or record
- current step or decision state
- primary commit action
- defer or cancel path when relevant

If the user scrolls far enough to lose the object identity or primary commit,
use the sticky-action rules defined elsewhere in OSHUN.

### 8.5 Backward Movement Must Be Safe

Users should be able to move back through a multi-step review without losing
already valid input, unless the data model explicitly forbids that retention.

Resetting previous steps on harmless navigation is non-canonical.

## 9. Desktop And Mobile Ergonomics

### 9.1 Desktop Should Reward Keyboard Use

For dense admin and studio workflows:

- search focus shortcuts are encouraged
- Enter should submit only when the default action is obvious
- multiline note capture must preserve newline entry rather than hijacking Enter
- roving selection, filter changes, and approval editing must not trap focus

### 9.2 Mobile Should Compress Chrome Before Fields

On mobile:

- keep the active input and commit action inside a comfortable reach band
- avoid stacking large banners above short forms
- collapse optional metadata before shrinking field tap size
- avoid top-only commit placement for repeated note or approval loops

### 9.3 Filter And Search Regions Must Not Consume The First Viewport

This rule applies even more strictly on mobile and tablet.

If the user lands on a filtered list and the first screen is mostly controls
instead of results, the form-entry ergonomics are wrong.

## 10. Canonical Patterns

### 10.1 Search Plus Filter Bar

Use:

- one visible search field
- one or two adjacent filters
- explicit clear or reset action
- immediate feedback on changed result scope when available

Avoid:

- advanced-search detours for common narrowing
- filter state hidden in a secondary drawer by default
- placeholder-only search naming

### 10.2 Review Decision Cluster

Use:

- object identity
- decision control with helper text
- required rationale field when the workflow needs it
- clear dominant commit action
- visible current status

Avoid:

- orphaned approve buttons without state explanation
- rationale fields disconnected from the decision they justify
- status hidden far from the entry control

### 10.3 Wizard With Optional Advanced Settings

Use:

- short introduction
- ordered required fields first
- advanced disclosure after the common path
- preserved values across template changes when those values remain valid
- explicit save and cancel actions

Avoid:

- hiding required fields in advanced disclosure
- opening a wizard that does not establish current mode or target object
- resetting entered notes or selections on minor validation errors

## 11. Acceptance Criteria

A new or revised OSHUN entry-heavy surface is not complete until all of these
are true:

- every meaningful field has a persistent accessible name
- helper text is local when required for task completion
- validation errors are field-specific and recoverable
- search and filter state remain visible and clearable
- note and approval capture preserve entered work during recoverable failures
- multi-step progress appears only when the flow is truly step-based
- desktop keyboard and mobile reachability both remain credible

## 12. Delivery Checklist For Coding Agents

For any OSHUN search, filter, notes, approval, or wizard surface:

- reuse `FormField`, `SearchInput`, and `ReviewDecisionControl` semantics before
  inventing new input behavior
- prefer explicit labels over placeholder-only naming
- keep high-value filters inline before adding drawers or modals
- add or update tests for validation, draft preservation, and decision-state
  behavior
- verify search, filter, approval, and note-entry behavior at desktop and mobile
  widths
