# OSHUN V1 Interaction Feedback Rules

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
