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.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/scope/action-placement-rules.mddocs/releases/v1/scope/one-handed-mobile-ergonomic-rules.mddocs/releases/v1/scope/dense-data-admin-ergonomic-rules.mddocs/releases/v1/specs/shared-component-accessibility-standards.mdapps/oshun/web/src/design-system/components/FormField.tsxapps/oshun/web/src/design-system/components/SearchInput.tsxapps/oshun/web/src/design-system/components/ReviewDecisionControl.tsxapps/oshun/web/src/design-system/components/__tests__/FormField.test.tsxapps/oshun/web/src/components/studio/StudioBellonaBuildQueueTrackingWorkspace.tsxapps/oshun/web/src/components/studio/StudioHathorEconomyModelingWorkspace.tsxdocs/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.tsxalready establishes explicit labels, field-level hint text, inline error messaging, character counts, focus emphasis, and multiline note support.SearchInput.tsxalready supports a visible search affordance, clear action, loading state, shortcut hint, and result-count feedback.ReviewDecisionControl.tsxalready uses label-first approval capture with helper text explaining the consequence of each review state.StudioBellonaBuildQueueTrackingWorkspace.tsxalready demonstrates search focus shortcuts, inline filters, queue wizards, advanced settings disclosure, approval actions, and signoff-note capture.StudioHathorEconomyModelingWorkspace.tsxalready 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 changesApply collaboration updateApprove signoffAdd 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:
- one or two inline primary filters
- compact supporting filter controls
- 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 laneSearch 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 hereWrite 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:
Approvedplus what happens nextChanges requestedplus what must be revisedRejectedplus 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:
ApproveRequest changesRejectRevoke
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, andReviewDecisionControlsemantics 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