Eve library

OSHUN V1 Error, Outage, and Fallback Copy Guidance

Guide

Revision 1

On this page

Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-040
Related:

  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/readability-standards.md
  • docs/releases/v1/scope/partial-failure-and-degraded-mode-rules.md
  • docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md
  • docs/releases/v1/runbooks/studio-resilience-and-error-ux-runbook.md
  • apps/oshun/web/src/design-system/components/ErrorState.tsx
  • apps/oshun/web/src/components/OfflineBanner.tsx
  • apps/oshun/web/src/offline/GlobalOfflineBanner.tsx
  • apps/oshun/web/src/components/DomainRouteExperience.tsx
  • apps/oshun/web/src/components/DomainDegradation.tsx
  • apps/oshun/mobile/src/components/OshunErrorBoundary.tsx
  • apps/oshun/mobile/src/offline/GlobalOfflineBanner.tsx
  • apps/oshun/mobile/src/i18n/strings.ts
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical copy rules for errors, outages, degraded mode, and fallback behavior across OSHUN V1.

The copy standard exists so failure states feel:

  • calm
  • precise
  • trustworthy
  • action-oriented
  • proportional to impact

Failure copy must never make the product feel more broken than it is, and it must never hide risk that the user actually needs to understand.

2. Current Repo Signals, External Scan, And Gap#

The current repo already contains useful baseline language:

  • web and mobile offline banners use explicit titles such as Offline mode active, Syncing queued actions, and Queued actions pending
  • the shell offline banner already says You are offline. Some features may be unavailable.
  • web and mobile crash surfaces use calm recovery wording such as You can safely retry and continue your session.
  • domain route and degradation surfaces already distinguish temporarily unavailable, offline fallback, queueing, and alternate routes
  • partial-failure and state-ladder docs already separate offline, degraded mode, local error, screen unavailable, and crash boundary

External implementation research reinforces several patterns:

  • GOV.UK guidance sharply separates user-fixable validation errors from service-side failures the user cannot fix.
  • GOV.UK error guidance favors plain language, specific recovery instructions, and preserving the user's entered data rather than clearing it.
  • Atlassian error-message guidance emphasizes short titles, one to two sentences of body copy, next-step clarity, and avoiding filler such as repeated apologies.
  • Atlassian Statuspage incident guidance stresses communicating early, stating known impact, updating on a predictable cadence, and owning the problem even when an upstream dependency caused it.
  • Atlassian Statuspage templates consistently name the condition in plain language: Service disruption, Trouble logging in, Elevated API Errors, Connectivity issues.

Inference from those sources plus the repo state:

  • OSHUN has most of the structural resilience grammar already.
  • OSHUN still needs one copy contract explaining how failure language should sound, what promises it may or may not make, and how to write messages for each failure tier.

3. Canonical Thesis#

OSHUN failure copy should do five things in order:

  1. name the user-visible condition
  2. explain the practical impact
  3. say what still works, if anything
  4. present the best next action
  5. keep technical detail behind a deeper layer unless the user truly needs it

The default posture is:

  • direct, not dramatic
  • honest, not overconfident
  • useful, not ornamental

4. Core Rules#

4.1 Name The Condition The User Can Observe#

Prefer:

  • Offline mode active
  • Tara is temporarily unavailable
  • Queued actions pending
  • Syncing queued actions
  • This section could not load

Avoid:

  • Unexpected exception
  • Service layer failure
  • Provider transport error
  • An error occurred

4.2 Say What The User Can Still Do#

If fallback, cache, or queueing is active, say so explicitly.

Good:

  • Cached content is still available.
  • Your action is queued and will sync when connection returns.
  • You can continue in another domain while this one recovers.

Bad:

  • Limited functionality
  • Some systems are impacted

The second set is too vague to guide recovery.

4.3 Never Over-Promise Safety Or Recovery#

Do not promise:

  • data is safe
  • nothing is lost
  • retry will work
  • sync will succeed soon

unless the system truly guarantees that claim.

Use controlled wording instead:

  • Your action is queued locally and will sync when connection returns.
  • You can try again now or continue with cached content.
  • We have reported this issue automatically.

Avoid:

  • Your data is safe and will be available when the service recovers.
  • Nothing was lost.
  • This will be fixed shortly.

4.4 Differentiate User Errors From Service Problems#

User-fixable issues should tell the user what to correct.

Service-side problems should tell the user what changed in the service and what path remains available.

Do not use form-field error language for outages, permissions, or missing service capacity.

Examples:

  • user-fixable: Enter your note title
  • service-side: Notes are temporarily unavailable. Try again or return to your library.

4.5 Keep Titles Short And Bodies Shorter#

Default target:

  • title: 3 to 6 words
  • body: 1 to 2 sentences

If the state needs more explanation, move detail into:

  • expandable technical details
  • a linked incident or status surface
  • a dedicated admin diagnostics panel

4.6 Use One Dominant Recovery Action#

The main action should tell the truth about what it does.

Preferred labels:

  • Try again
  • Sync now
  • Continue with fallback
  • Return to library
  • Open incident workspace

Avoid weak or generic buttons such as:

  • OK
  • Dismiss
  • Continue

unless that really is the only honest action.

4.7 Avoid Automatic Apology Language#

Do not default to:

  • Sorry
  • Oops
  • Please try again

for routine retryable failures.

Empathy is appropriate for meaningful disruption, but OSHUN should still sound steady and operational, not flustered.

4.8 Technical Details Belong Behind Disclosure#

Codes, traces, provider names, and stack details should not lead the primary message unless the audience is explicitly operator-facing.

Customer primary copy should describe impact.

Operator copy may add:

  • incident ID
  • affected dependency
  • severity
  • fallback mode
  • owner or escalation path

5. Canonical Vocabulary#

5.1 Preferred Terms#

  • temporarily unavailable
  • offline
  • queued
  • syncing
  • degraded mode
  • cached content
  • fallback
  • try again
  • return
  • open status
  • open incident workspace

5.2 Terms To Avoid#

  • catastrophic
  • fatal
  • meltdown
  • oops
  • broken
  • crashed unless the surface literally hit a crash boundary
  • forbidden
  • invalid as the only explanation
  • unknown error

6. Scenario Rules#

6.1 Validation Errors#

Validation errors should:

  • refer directly to the field or question label
  • say what to change
  • preserve the entered value
  • avoid examples if the example is already visible in hint text

Good:

  • Enter your note title
  • Search term must be 80 characters or less

Bad:

  • This field is invalid
  • Answer the question

6.2 Retryable Action Failures#

Retryable failures should say the action failed, not the whole app.

Good:

  • This section could not load. Try again.
  • We could not refresh this queue. Try again or continue with the current view.

Bad:

  • Something went wrong

unless the error boundary genuinely cannot localize the failure any further.

6.3 Offline With No Queued Writes#

Copy should focus on reduced capability, not panic.

Good:

  • Offline mode active
  • Some features may be unavailable until you reconnect.

6.4 Offline With Queued Writes#

Copy should acknowledge the queued state explicitly.

Good:

  • 3 actions queued until connection returns.
  • Queued actions pending
  • Sync now

Rules:

  • state the count when available
  • make queueing sound durable and intentional, not like a silent maybe
  • do not imply the server already received the write

6.5 Sync In Progress#

Good:

  • Syncing queued actions
  • Sending 4 queued actions...

Do not say:

  • Recovered
  • Complete

until the sync actually finishes.

6.6 Degraded Mode With Fallback Active#

Degraded-mode copy must say both the limit and the preserved path.

Good:

  • Live activity is temporarily unavailable. Showing cached activity instead.
  • Search suggestions are unavailable. You can still run a full search.

Bad:

  • Reduced functionality is active.

6.7 Route Or Domain Unavailable#

When the intended route cannot function:

  • name the affected route or domain
  • say it is temporary when that is the expectation
  • offer one primary retry path and one alternate route

Good:

  • Nisaba is temporarily unavailable
  • Retry launch or switch to another domain.

6.8 Crash Boundaries#

Crash boundaries should be steady and narrow in promise.

Good:

  • Something went wrong
  • OSHUN hit an unexpected issue. You can safely retry and continue your session.

Rules:

  • reassure only what the system actually knows
  • say whether reporting happened automatically only when telemetry confirms it
  • offer retry and one safe exit path

6.9 Incident, Outage, And Status Updates#

Incident updates should follow the strongest current status-page patterns:

  • acknowledge the issue early
  • summarize known impact
  • state mitigation or fallback if known
  • state when the next update will come if there is a public cadence

Good:

  • Some users may be experiencing trouble signing in. We are investigating and will share another update in 30 minutes.
  • We are seeing elevated API errors. Cached reading remains available while we investigate.

Bad:

  • We are aware of reports
  • The vendor is having issues

without stating the impact on OSHUN users.

7. Canonical Templates#

These templates are the preferred starting point for new OSHUN surfaces.

7.1 Inline Or Section Retry#

  • Title: This section could not load
  • Body: Try again. If the issue continues, continue with the rest of the page and return later.
  • Action: Try again

7.2 Offline Banner#

  • Title: Offline mode active
  • Body: Some features may be unavailable until you reconnect.
  • Action: Retry or Sync now when meaningful

7.3 Offline Queue#

  • Title: Queued actions pending
  • Body: {count} action(s) queued until connection returns.
  • Action: Sync now

7.4 Degraded Fallback#

  • Title: {surface} is limited right now
  • Body: Live data is temporarily unavailable. Showing cached or fallback content instead.
  • Action: Try again or Continue with fallback

7.5 Route Unavailable#

  • Title: {domain} temporarily unavailable
  • Body: Retry this route or switch to another domain.
  • Action: Retry launch

7.6 Crash Boundary#

  • Title: Something went wrong
  • Body: You can retry now or return to a stable OSHUN surface.
  • Actions: Try again, Home

7.7 Incident Status Update#

  • Title: {surface} service disruption
  • Body: We are investigating an issue affecting {impact}. {fallback_or_next_update}

8. Do And Do Not Examples#

8.1 Generic Error#

  • do: This section could not load. Try again.
  • do not: An unexpected application error has occurred.

8.2 Offline#

  • do: You are offline. Some features may be unavailable.
  • do not: Network transport failure detected.

8.3 Queueing#

  • do: 2 actions queued until connection returns.
  • do not: Your changes should probably sync later.

8.4 Degraded Mode#

  • do: Live search suggestions are unavailable. You can still run a full search.
  • do not: Reduced functionality is currently in effect.

8.5 Domain Outage#

  • do: Veritas is temporarily unavailable. Retry launch or switch to another domain.
  • do not: Veritas backend dependency failed.

8.6 Crash Boundary#

  • do: OSHUN hit an unexpected issue. You can safely retry and continue your session.
  • do not: Oops. We broke something.

9. Definition Of Done#

Error, outage, and fallback copy is done for a surface only when:

  • the message names the observable condition
  • the copy distinguishes user-fixable issues from service-side failures
  • the message says what still works when continuity exists
  • the primary action is explicit and meaningful
  • the copy avoids unsupported safety or recovery promises
  • technical detail stays secondary unless the audience is operator-facing
  • incident and outage updates communicate impact, cadence, and ownership clearly