Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-063
Related:
docs/releases/v1/scope/motion-hierarchy-rules.mddocs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.mddocs/adr/ADR-0064-oshun-shell-domain-accent-behavior.mddocs/adr/ADR-0016-oshun-studio-color-system-and-token-governance.mdlibs/oshun/design-tokens/src/tokens.tsapps/oshun/web/src/design-system/tokens.tsapps/oshun/web/src/design-system/components/Button.tsxapps/oshun/web/src/design-system/components/IconButton.tsxapps/oshun/web/src/design-system/components/Dropdown.tsxapps/oshun/web/src/design-system/components/Tag.tsxapps/oshun/web/src/design-system/components/Sidebar.tsxapps/oshun/web/src/design-system/components/Badge.tsxapps/oshun/web/src/design-system/components/Toast.tsxapps/oshun/web/src/design-system/components/ErrorState.tsxapps/oshun/web/src/components/OfflineBanner.tsxapps/oshun/mobile/src/feedback/haptics.tsapps/oshun/mobile/src/components/OshunErrorBoundary.tsxdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical feedback rules for:
- hover
- press
- selection
- success
- warning
- blocking-error
- retry
These rules govern both customer and admin surfaces across web and mobile.
The central requirement is clarity. OSHUN must distinguish:
- "you touched this"
- "this is currently selected"
- "this succeeded"
- "this needs caution"
- "this is blocked"
- "this is trying again"
Those meanings cannot collapse into one generic animation or one generic accent color.
2. Current Repo Signals And Gap#
The current repo already contains strong primitives:
- subtle hover, press, ripple, and loading logic in
Button.tsx - hover and active icon treatment in
IconButton.tsx - selected nav and domain states in
Sidebar.tsx - semantic badge and confidence treatment in
Badge.tsxandConfidenceBadge.tsx - status toasts, warnings, and retry controls in
Toast.tsx,OfflineBanner.tsx, andErrorState.tsx - mobile haptic intent categories in
apps/oshun/mobile/src/feedback/haptics.ts - semantic-first tone contracts in shared design tokens
The gap is consistency of meaning. Current implementation review shows:
- routine hover and press feedback is reasonably consistent, but selection, success, warning, and retry semantics are not yet governed by one hierarchy
- some error and warning surfaces still use pulse, shake, or loud animation more aggressively than their actual severity warrants
- retry states exist, but are not yet clearly defined as a temporary recovery posture distinct from failure and distinct from success
- domain accent, selection accent, and semantic status can still blur together without one canonical rule set
This document provides that rule set.
3. Core Doctrine#
3.1 Interaction Feedback And Semantic Feedback Are Different Jobs#
Interaction feedback confirms manipulation.
Examples:
- hover
- press
- focus
- selected state
Semantic feedback communicates meaning.
Examples:
- success
- warning
- blocking error
- retrying
A selected row is not a success state. A hovered chip is not a warning state.
3.2 Feedback Intensity Must Match Decision Cost#
The lighter and more frequent the interaction, the lighter the feedback should be.
Routine controls should not:
- shake
- pulse repeatedly
- flash semantic colors
- use strong glow by default
3.3 Semantic Status Outranks Domain Identity#
As already established in token governance and domain-accent ADRs:
- success, warning, danger, and info are authoritative for state meaning
- domain color may inform context or selection
- domain color must not replace semantic meaning in critical states
3.4 Retry Is A Recovery State, Not A Second Failure State#
Retry means the system is actively attempting recovery.
It should read as:
- in progress
- temporarily unavailable for input
- not yet resolved
It should not read as:
- successful
- permanently failed
- dramatically alarming by default
4. Canonical Feedback Ladder#
| Feedback type | Role | Typical channel mix | Default intensity |
|---|---|---|---|
hover |
invite interaction on pointer-capable devices | background, border, text, icon shift | very low |
press |
confirm immediate actuation | scale/opacity/compression, ripple, haptic | low |
selection |
show persistent active or chosen state | fill, border, underline, weight, accent edge | low but durable |
success |
acknowledge completed positive outcome | semantic success tone, optional icon, calm toast | medium |
warning |
signal caution, degraded state, or rework need | semantic warning tone, stable emphasis | medium |
blocking-error |
signal failed or unsafe continuation | semantic danger tone, recovery action, clear copy | high |
retry |
show active recovery attempt | spinner, disabled state, label swap | medium-low |
Interpretation rules:
hoverandpressare transientselectionis persistent while context remains activesuccessshould decay into a quieter resting statewarningcan persist without theatricsblocking-erroris reserved for true stops or hard failuresretrylives betweenwarningorerrorand eventual recovery
5. Hover Rules#
5.1 Hover Is Optional And Pointer-Only#
Hover feedback exists only for hover-capable devices. It must never be the only way the user learns a control exists.
5.2 Canonical Hover Signals#
Use one or two of:
- subtle background lift
- border clarification
- text or icon darkening
- very small scale change
- restrained accent tint on contextual controls
Recommended bounds:
- scale change up to roughly
1.02 - no major travel
- no semantic status color unless the item is already semantically dangerous
5.3 Hover Anti-Patterns#
Non-canonical:
- heavy glow on routine controls
- hover states that look identical to selected states
- hover states that borrow warning or danger color for non-danger actions
6. Press Rules#
6.1 Press Must Feel Immediate#
Press feedback should happen at input-down, not only after async completion.
Use:
- light compression
- opacity or brightness change
- one contained ripple when appropriate
- mobile selection haptic for important discrete actions
6.2 Press Should Not Create Semantic Ambiguity#
Press is mechanical confirmation, not semantic success.
Do not turn a pressed control green, amber, or red unless the control already has that semantic identity.
6.3 Mobile Haptic Rules#
The current mobile haptic model already distinguishes:
actionConfirmationsuccesswarninglock
Canonical usage:
- routine button press:
actionConfirmation - successful completion:
success - warning or elevated caution:
warning - blocked or locked state:
lock
Do not fire strong haptics for every minor tap.
7. Selection Rules#
7.1 Selection Must Be Persistent, Not Theatrical#
Selection shows what is active, chosen, filtered, armed for compare, or currently in focus context.
Canonical selection treatment:
- persistent fill or wash
- border or underline
- text-weight increase
- stable icon tint
7.2 Selection Uses Accent Before Status#
When a control is merely selected, use:
- shell accent
- domain accent
- neutral structural emphasis
Do not style selection as success unless the selection itself means a committed positive outcome.
7.3 Selection Motion Rules#
- selection enters quickly and quietly
- no repeated pulse
- no celebratory pop for routine selection
- active selection should remain readable after motion stops
8. Success Rules#
8.1 Success Should Confirm, Then Recede#
Success is acknowledgement, not celebration.
Use:
- restrained green semantic tone
- optional check icon
- concise success copy
- brief toast or inline confirmation
Then allow the surface to settle into a quiet completed or saved state.
8.2 Success Must Stay Subordinate To Higher-Risk Signals#
Shared token guidance already states that terminal success in dense operational views should stay restrained.
Implication:
- completed queue rows can be calm
- success badges should not overpower warnings or blocking failures nearby
- success toasts should disappear or quiet down quickly
8.3 Success Anti-Patterns#
Non-canonical:
- success pulse loops
- oversized green banners for routine saves
- using success styling for informational or neutral completion states that do not materially matter
9. Warning Rules#
9.1 Warning Means Caution, Degraded State, Or Rework#
Use warning for:
- pending review
- degraded mode
- queued attention
- rework required
- cautionary trust or confidence states
- connectivity or retry pressure that is not yet terminal
9.2 Warning Must Be Stable, Not Panicked#
Canonical warning treatment:
- amber or warning semantic tone
- clear but restrained contrast
- stable surface or badge
- optional icon
Avoid:
- shake
- hard red treatment
- repeated alarm pulse on persistent surfaces
9.3 Warning Versus Blocking Error#
If the user can still continue with caution or recovery, the state is usually warning, not blocking-error.
10. Blocking-Error Rules#
10.1 Blocking Error Is Reserved For Stops#
Use blocking-error when:
- the task cannot proceed safely
- the action failed definitively for now
- the route or workflow is genuinely unavailable
- the system requires explicit recovery or exit
10.2 Blocking Error Anatomy#
Canonical blocking-error feedback includes:
- danger semantic tone
- clear stop message
- one dominant recovery or exit action
- optional technical detail behind disclosure
10.3 Motion Rules For Blocking Errors#
- one quiet entrance is enough
- aggressive shake or wobble is non-canonical for routine product errors
- use stronger escalation only for truly exceptional or safety-critical stops
This rule applies to both reusable error blocks and route-level crash pages.
11. Retry Rules#
11.1 Retry Is Spatially Stable#
When a control enters retry:
- keep it in the same position
- disable duplicate input
- swap icon or label to a loading state
- show progress with spinner or subtle motion
Do not move the action, open a new modal, or change the whole surface unless scope truly changed.
11.2 Retry Tone Rules#
Retry usually borrows neutral or warning posture plus active progress.
Typical canonical pattern:
- button remains secondary or neutral
- spinner appears
- label changes to
Retrying… - surrounding warning or error context remains visible if still relevant
Retry should not become success green until recovery actually succeeds.
11.3 Retry Escalation Rules#
If retries repeatedly fail:
- escalate from retry to warning or blocking-error
- surface next safe action
- stop pretending the system is still quietly recovering
12. Toast, Banner, And Inline-Surface Translation#
12.1 Inline#
Use inline feedback for:
- field validation
- row selection
- local retry
- compact success or warning notes
12.2 Toast#
Use toasts for:
- non-blocking success acknowledgement
- non-blocking informational warning
Avoid toasts for:
- durable blocking errors
- complex retry flows
- anything the user must act on later but could miss
12.3 Banner Or Error Block#
Use banners or structured blocks for:
- persistent warnings
- offline states
- degraded states
- blocking errors with recovery action
13. Customer Versus Admin Translation#
13.1 Customer#
Customer feedback should feel reassuring and plain:
- less semantic noise
- fewer simultaneous status surfaces
- success and warning kept calm
- errors direct but not theatrical
13.2 Admin#
Admin feedback may be denser, but meaning must remain deterministic:
- selection can be more explicit
- warning and danger states may persist longer
- success must stay restrained when higher-severity signals coexist
- retry pressure should be visible before full failure
14. Anti-Patterns#
The following are non-canonical for OSHUN V1:
- using hover styling as if it were selection
- using success styling as if it were "currently selected"
- pulsing or shaking every warning and error surface
- turning retry buttons red just because the previous attempt failed
- using domain accent where semantic status is required
- letting success, warning, and danger all animate with equal strength
15. Implementation Alignment Checklist#
Follow-on implementation should align the current repo as follows:
Button.tsxandIconButton.tsx: keep hover and press subtle; avoid making routine interaction feedback look semanticSidebar.tsxand other active-nav controls: keep selection durable and calm, distinct from warning and successDropdown.tsxandTag.tsx: reserve danger coloring for genuinely destructive items and remove buttonsToast.tsx: separate calm success/info from warning and error without repeating loud icon animations on persistent notificationsErrorState.tsxandapps/oshun/web/src/app/error.tsx: quiet blocking-error motion so recoverable failures do not feel catastrophic by defaultOfflineBanner.tsx: keep retry feedback in warning-plus-progress posture- mobile feedback layers should continue to map haptics to semantic severity instead of treating all taps the same
16. Acceptance Standard#
A feedback pattern is canonical only if:
- the user can tell whether it is interaction confirmation or semantic state
- semantic status colors outrank accent identity
- selection never masquerades as success
- warning does not masquerade as failure
- retry reads as active recovery, not random motion
- blocking-error feels serious without becoming melodramatic