Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-020
Related:
docs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/runbooks/studio-resilience-and-error-ux-runbook.mddocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical visual and interaction rules for partial failure and degraded mode across OSHUN customer and admin surfaces.
The core requirement is:
- preserve orientation
- preserve trust
- preserve progress when possible
- explain what still works
- show the next safe action
A failure state should never make the product feel more broken than the actual underlying condition.
2. Definitions#
2.1 Partial Failure#
A partial failure means one capability, section, or dependency has failed while the broader surface can still function.
Examples:
- one domain feed fails inside an otherwise working shell
- search suggestions fail but typed search still works
- one panel in an admin workspace cannot load while the rest of the cockpit is still available
2.2 Degraded Mode#
Degraded mode means the product intentionally limits capabilities to preserve safety, continuity, or responsiveness.
Examples:
- cached fallback content replaces live content
- write actions queue until connectivity returns
- one provider path is disabled while another remains available
- admin incident workflows remain active with reduced observability or control
2.3 Unavailable#
Unavailable means the user cannot use the intended surface right now and needs retry, fallback, or redirection.
2.4 Crash Boundary#
A crash boundary is the last-resort containment surface when rendering or runtime failure escapes normal error handling.
3. Core Rules#
3.1 Fail Locally Before Failing Globally#
If a single panel, domain, or task can fail without breaking the rest of the shell, keep the failure local.
Do not replace an entire shell with a full-page error if:
- one section failed
- one domain dependency failed
- one action failed and can be retried
3.2 Preserve What Still Works#
Every degraded state should make the following explicit:
- what failed
- what still works
- what the user can do next
If the message only says something is broken, it is incomplete.
3.3 Recovery Must Be Visible#
Every meaningful failure or degraded state needs at least one visible recovery path:
- retry
- continue with fallback
- queue for later
- switch surface
- go back safely
3.4 Calm Beats Drama#
Most recoverable failures should feel calm, not catastrophic.
Use visual escalation only when:
- data loss risk exists
- a security boundary is involved
- an operator must escalate immediately
- the user cannot safely continue
4. Canonical State Ladder#
| State | When to use | User promise | Default dominant action |
|---|---|---|---|
silent retry |
transient issue likely to self-recover quickly | no disruption unless delay becomes meaningful | none |
inline partial failure |
one block or section failed | the broader surface still works | retry section / continue elsewhere |
local degraded mode |
fallback is active inside a section or route | reduced capability, preserved continuity | continue with fallback / retry |
screen-level degraded mode |
the intended route is usable only in limited mode | preserve progress with visible limits | continue in degraded mode / switch route |
surface unavailable |
the route or domain is currently not usable | try again or move to another safe path | retry / switch surface |
global offline or shell-wide degradation |
connectivity or platform dependency affects many flows | shell still works where possible, writes may queue | retry connectivity / sync later |
crash boundary |
rendering/runtime failure escaped normal handling | the shell or route can be reset safely | retry / return to stable shell |
5. Visual Posture Rules#
5.1 Tone Ladder#
Use tone based on recoverability, not on fear.
- neutral/info: queued, syncing, low-risk fallback
- warning: partial failure, limited capability, degraded mode
- danger: blocking failure, destructive risk, unrecoverable error, explicit data integrity risk
Do not use danger styling for every retryable network issue.
5.2 Layout Posture#
Partial failure surfaces should preserve the surrounding layout whenever possible.
Preferred patterns:
- inline state block in the failed section
- lightweight panel replacement
- persistent shell with local notice
- slim global offline banner for shell-wide connectivity issues
Avoid jumping straight to:
- full-screen empty voids
- modal interruptions for recoverable states
- complete shell replacement when the shell still works
5.3 Message Anatomy#
Customer-facing failure states should usually include:
- clear title naming the impacted surface
- one sentence explaining the impact
- one sentence naming what still works or what fallback is active
- one dominant action
- one safe alternate path
Operator-facing failure states should include:
- affected workflow or surface
- current severity or degradation state
- active capability limits
- next recovery or escalation step
- auditability or ownership context when relevant
6. Customer Rules#
6.1 Customer Partial Failures#
Customer partial failures should be:
- specific
- calm
- actionable
- continuity-preserving
Examples:
- "Live activity is temporarily unavailable. Showing local fallback timeline."
- domain route unavailable with a retry path and alternate domain links
- offline mode showing cached content and queued-action posture
6.2 Customer Degraded Mode#
Degraded mode for customer surfaces must emphasize continuity:
- cached content stays readable
- queued actions are acknowledged
- users know whether a write will sync later
- alternate domains remain reachable when possible
6.3 Customer Crash Boundaries#
Crash boundaries should:
- reassure the user their broader session is still safe
- offer a retry
- avoid technical overload by default
- keep detail behind disclosure when needed
7. Admin And Operator Rules#
7.1 Admin Partial Failures#
Admin partial failures must be more explicit than customer ones.
They should name:
- impacted workflow
- affected capability
- current severity
- whether degraded mode is active
7.2 Admin Degraded Mode#
Operator degraded mode is not just a softer error state. It is a controlled operating posture.
It must make visible:
- blocked capabilities
- fallback path or manual override availability
- recovery action type
- escalation or ownership state when required
7.3 Admin Unavailable States#
If an operator route becomes unavailable:
- keep the cockpit shell available
- preserve navigation to adjacent workspaces
- surface the next safe path, not just the failure
Admin should never strand the operator in a dead-end full-page error without a route back into working operations.
8. Action Rules#
8.1 One Dominant Recovery Action#
Every failure block gets one dominant next step:
Try againContinue with fallbackSync nowOpen incident workspaceReturn to shell
Do not present five equivalent recovery buttons.
8.2 Retry Must Mean Something#
Retry actions should be shown only when the underlying action is genuinely retryable.
If retry is not safe or not meaningful, the primary action should instead be:
- queue for later
- switch to fallback
- escalate
- go back
8.3 Alternate Paths Matter#
When one domain or route is unavailable, the state should offer at least one alternate working path when possible.
The current domain route fallbacks and shell-level alternative-domain links are valid canonical patterns.
9. Copy Rules#
9.1 Name The Broken Thing#
Say what failed:
- domain
- panel
- sync
- search
- audio
- queue
- workflow
Avoid generic copy such as:
- "Something went wrong" for every condition
- "Unexpected error" when the failure is actually understood
9.2 State The Preservation Promise#
Where true, say explicitly:
- your data is safe
- your actions were queued
- cached content remains available
- other domains still work
- the rest of the shell is still available
9.3 Keep Technical Detail Secondary#
Technical detail belongs in:
- expandable detail sections
- operator-only contexts
- audit or diagnostics surfaces
Default customer states should not lead with stack traces or internal codes.
10. Explicit Anti-Patterns#
These are non-canonical for OSHUN V1:
- full-screen error replacement for a single failed module
- bright destructive styling for recoverable offline states
- failure states that do not say what still works
- retry buttons with no alternate path
- degraded mode that hides capability limits
- blank skeletons that never resolve into a visible fallback state
- shell crash states that trap the user without recovery or safe navigation
11. Current Implementation Targets#
These rules should directly govern and refine the current failure-state surfaces already present in the repo:
apps/oshun/web/src/components/DomainDegradation.tsxapps/oshun/web/src/components/OfflineBanner.tsxapps/oshun/web/src/components/DomainErrorBoundary.tsxapps/oshun/web/src/design-system/components/ErrorState.tsxapps/oshun/web/src/components/DomainRouteExperience.tsxapps/oshun/mobile/src/offline/GlobalOfflineBanner.tsxapps/oshun/mobile/src/components/OshunErrorBoundary.tsxapps/oshun/mobile/src/__tests__/nonfunctional/api-resilience.test.tsapps/oshun/web/src/components/studio/StudioResilienceErrorUxWorkspace.tsx
12. Exit Standard#
A partial failure or degraded-mode surface is correct only when:
- the failure scope is accurate
- the rest of the product remains usable where possible
- the user understands what still works
- the next safe action is obvious
- the visual treatment matches the actual severity
If the state feels vague, dead-end, or more alarming than the real condition, it is not acceptable for V1.