Eve library

OSHUN V1 Interaction Feedback Rules

Guide

Revision 1

On this page

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.md
  • docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md
  • docs/adr/ADR-0064-oshun-shell-domain-accent-behavior.md
  • docs/adr/ADR-0016-oshun-studio-color-system-and-token-governance.md
  • libs/oshun/design-tokens/src/tokens.ts
  • apps/oshun/web/src/design-system/tokens.ts
  • apps/oshun/web/src/design-system/components/Button.tsx
  • apps/oshun/web/src/design-system/components/IconButton.tsx
  • apps/oshun/web/src/design-system/components/Dropdown.tsx
  • apps/oshun/web/src/design-system/components/Tag.tsx
  • apps/oshun/web/src/design-system/components/Sidebar.tsx
  • apps/oshun/web/src/design-system/components/Badge.tsx
  • apps/oshun/web/src/design-system/components/Toast.tsx
  • apps/oshun/web/src/design-system/components/ErrorState.tsx
  • apps/oshun/web/src/components/OfflineBanner.tsx
  • apps/oshun/mobile/src/feedback/haptics.ts
  • apps/oshun/mobile/src/components/OshunErrorBoundary.tsx
  • docs/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.tsx and ConfidenceBadge.tsx
  • status toasts, warnings, and retry controls in Toast.tsx, OfflineBanner.tsx, and ErrorState.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:

  • hover and press are transient
  • selection is persistent while context remains active
  • success should decay into a quieter resting state
  • warning can persist without theatrics
  • blocking-error is reserved for true stops or hard failures
  • retry lives between warning or error and 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:

  • actionConfirmation
  • success
  • warning
  • lock

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.tsx and IconButton.tsx: keep hover and press subtle; avoid making routine interaction feedback look semantic
  • Sidebar.tsx and other active-nav controls: keep selection durable and calm, distinct from warning and success
  • Dropdown.tsx and Tag.tsx: reserve danger coloring for genuinely destructive items and remove buttons
  • Toast.tsx: separate calm success/info from warning and error without repeating loud icon animations on persistent notifications
  • ErrorState.tsx and apps/oshun/web/src/app/error.tsx: quiet blocking-error motion so recoverable failures do not feel catastrophic by default
  • OfflineBanner.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