# OSHUN V1 Canonical Loading, Skeleton, Empty, Offline, and Error State Rules

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

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/scope/partial-failure-and-degraded-mode-rules.md`
- `docs/releases/v1/scope/motion-hierarchy-rules.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `apps/oshun/web/src/components/Skeleton.tsx`
- `apps/oshun/web/src/design-system/components/EmptyState.tsx`
- `apps/oshun/web/src/design-system/components/ErrorState.tsx`
- `apps/oshun/web/src/components/OfflineBanner.tsx`
- `apps/oshun/web/src/components/DomainRouteExperience.tsx`
- `apps/oshun/web/src/components/DomainDegradation.tsx`
- `apps/oshun/mobile/src/offline/GlobalOfflineBanner.tsx`
- `apps/oshun/mobile/src/library/UnifiedLibraryView.tsx`
- `apps/oshun/mobile/src/notifications/NotificationCenter.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical posture for OSHUN V1 loading, skeleton,
empty, offline, and error states across customer and admin surfaces.

The standard is not merely "handle the state." The state must also feel:

- calm
- informative
- structurally coherent
- visually premium

Premium in OSHUN means continuity, confidence, and restraint. State handling
should not collapse the page into generic placeholders, panic-colored alerts, or
dead-end emptiness.

## 2. Current Repo Signals And Gap

The current repo already includes strong raw ingredients:

- structural skeleton primitives and presets in `Skeleton.tsx`
- reusable empty-state and error-state primitives in the web design system
- shell and domain offline or unavailable states in `DomainRouteExperience.tsx`
- shell-wide offline feedback in `OfflineBanner.tsx`
- mobile offline queue visibility in `GlobalOfflineBanner.tsx`
- several grounded mobile empty states in library and notifications flows

The gap is consistency. Current implementation review shows:

- some loading states preserve structure with skeletons, while others collapse
  to plain "Loading..." text
- several skeleton presets still mimic card blocks more than canonical layout
  structure
- the current web `ErrorState` uses shake and draw-in motion that is too loud
  for many recoverable errors
- empty states vary between helpful, decorative, and underspecified
- offline posture differs noticeably between web and mobile

This document defines the one canonical product grammar for those states.

## 3. Core Doctrine

### 3.1 Preserve The Frame

When the intended layout is known, preserve it.

Users should keep their sense of:

- where they are
- what belongs on the screen
- what is temporarily missing
- what they can still do

### 3.2 Explain The State, Not The Implementation

Messages should name the user-visible condition:

- still loading
- nothing here yet
- offline but cached content is available
- this section failed, retry below

Do not lead with transport jargon, stack details, or vendor-specific failure
language.

### 3.3 Calm Is The Default

Recoverable states should feel quiet. A state becoming visible is already a
signal. It does not also need dramatic motion, flashing emphasis, or oversized
warning color.

### 3.4 Scope Must Match Impact

Use the smallest state surface that truthfully represents the issue:

- inline for one control or result block
- sectional for one module
- screen-level for one route
- shell-level only when many flows are affected

### 3.5 Premium Means Useful, Not Ornamental

State UI should avoid:

- decorative filler that does not map to real layout
- mascot-style illustrations on operational surfaces
- generic enterprise warning panels
- long apology copy

## 4. Canonical State Ladder

| State                         | Use when                                                        | Visual posture                                      | Default action posture                |
| ----------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------- |
| `silent wait`                 | likely to resolve before the user perceives delay               | no visible replacement yet                          | none                                  |
| `inline pending`              | one control, row, or action is waiting                          | preserve content, show local progress               | cancel only if meaningful             |
| `structural skeleton`         | layout is known but content is not ready                        | placeholder blocks preserve rhythm and measure      | none                                  |
| `empty`                       | load finished successfully, but there is no content to show     | calm explanatory state inside the normal layout     | create, broaden, or explore           |
| `offline/degraded continuity` | connectivity is reduced but reading, caching, or queueing works | persistent but restrained warning/info posture      | retry, sync later, or continue safely |
| `local error`                 | one section or action failed but the rest of the surface works  | inline or sectional replacement, not total takeover | retry or take safe alternate path     |
| `screen unavailable`          | intended route cannot currently function                        | route-level state with preserved shell navigation   | retry, go back, or switch surface     |
| `global offline`              | connectivity affects many shell flows                           | slim shell-level banner plus local capability notes | retry connection or sync queued work  |

Interpretation rules:

- `empty` is not an error.
- `offline` is not automatically `danger`.
- `error` should not erase working content unless the content itself is invalid.
- `skeleton` should transition into ready content or empty state, never linger
  indefinitely.

## 5. Loading And Skeleton Rules

### 5.1 Choose The Lightest Honest Loading Pattern

- Under roughly `300ms`, prefer `silent wait`.
- For local actions, prefer inline pending treatment over page replacement.
- Use structural skeletons when the user needs reassurance that the right screen
  is loading.
- Use a spinner by itself only for tiny scopes such as icon-size retry or sync
  controls.

### 5.2 Skeletons Must Preserve Real Layout

Skeletons should mirror:

- headline measure
- paragraph measure
- list rhythm
- media or chart footprint
- action placement

Skeletons should not invent extra cards, rails, or ornamental blocks that will
disappear when real content arrives.

### 5.3 Skeleton Density Rules

- Keep placeholders fewer and larger rather than many tiny fragments.
- Show enough structure to orient the user, not every eventual detail.
- Prefer 2-4 major placeholder regions on route load.
- In dense admin views, preserve columns, row height, and toolbars instead of
  rendering generic cards.

### 5.4 Skeleton Motion Rules

- Skeleton motion is background presence only.
- Use soft shimmer or low-contrast pulse, never fast sweep or bright glare.
- Continuous motion should sit at `L0` or quiet `L2` from
  `OSHUN_V1_MOTION_HIERARCHY_RULES.md`.
- Reduced-motion mode should remove shimmer and keep static placeholder blocks.

### 5.5 Loading Copy Rules

Avoid centered standalone text like:

- `Loading...`
- `Fetching data...`
- `Please wait`

Those are acceptable only when the layout is genuinely unknown or when the state
is transient inside a compact component.

## 6. Empty-State Rules

### 6.1 Distinguish Empty Types

Every empty state must declare which kind it is:

- first-run empty: no content exists yet
- filtered empty: content exists, current filter returns none
- cleared/completed empty: there is nothing left to review or act on
- unavailable empty: not canonical, this should usually be offline or error

### 6.2 Empty-State Anatomy

Most empty states should contain:

- a specific heading
- one sentence of explanation
- one dominant next step when appropriate
- one optional hint or filter-reset action

They should usually fit within the existing surface rather than replacing the
entire route chrome.

### 6.3 Tone Rules

- first-run empty should feel invitational
- filtered empty should feel corrective
- cleared/completed empty should feel resolved
- operational empty states should stay plain, not whimsical

### 6.4 Premium Empty-State Rules

- avoid giant illustrations on dense admin surfaces
- avoid floating icons on routine operational empties
- avoid generic "Nothing here" copy
- avoid multiple equal-weight CTAs

## 7. Offline And Degraded-Continuity Rules

### 7.1 Offline Must Preserve Continuity First

When cached or locally available content exists:

- keep it visible
- mark it as offline or queued
- explain write limitations
- provide retry or sync affordances nearby

Offline should not automatically collapse into a full-page blocker.

### 7.2 Shell-Level Offline Posture

Shell-wide connectivity issues should use:

- a slim persistent banner
- calm warning or neutral-info tone
- one retry or sync control
- clear copy about queued or unavailable actions

The banner should not behave like a toast that disappears before the condition
is resolved.

### 7.3 Route-Level Offline Posture

When a specific route is offline-sensitive:

- preserve shell navigation
- show fallback or cached content if safe
- name what is unavailable
- offer one dominant recovery action and one safe alternate path

### 7.4 Tone Rules

- use warning or muted-info for offline and queued states
- reserve danger for data loss risk or blocking integrity problems
- queued writes should sound acknowledged, not alarming

## 8. Error-State Rules

### 8.1 Localize Errors Aggressively

If one panel, action, or domain section fails, contain the error there.

Do not replace the whole route when:

- adjacent content still works
- the shell still works
- the user can take another safe action

### 8.2 Error-State Anatomy

Most error states should contain:

- a title naming the failed surface
- one sentence explaining impact
- one sentence about what still works or what to do next
- one dominant retry or recovery action
- optional technical detail under disclosure only

### 8.3 Motion And Escalation Rules

- recoverable errors should enter quietly
- shake, burst, or aggressive draw animations are non-canonical for routine
  retryable failures
- blocking or security-relevant states may escalate color and posture, but must
  still stay legible and controlled

### 8.4 Error Copy Rules

Prefer:

- `We couldn’t load this section. Try again.`
- `Veritas is temporarily unavailable. The rest of OSHUN still works.`
- `You’re offline. New actions will queue until connection returns.`

Avoid:

- blame-heavy apology copy
- stack traces by default
- unexplained codes without user action
- dead-end `Something went wrong` messaging with no next step

## 9. Canonical Scope Matrix

| Scope          | Loading                                  | Empty                           | Offline / degraded                              | Error                                             |
| -------------- | ---------------------------------------- | ------------------------------- | ----------------------------------------------- | ------------------------------------------------- |
| control / row  | inline pending, tiny spinner, label swap | n/a or concise inline note      | queued badge or local note                      | inline validation or retry affordance             |
| panel / module | structural skeleton or placeholder rows  | compact explanatory empty state | local continuity banner or stale-data note      | inline error block with retry                     |
| route          | full-route structural skeleton           | route-integrated empty state    | route-level fallback while shell remains active | route unavailable state with alternate navigation |
| shell          | avoid blocking shell load if possible    | rare                            | persistent offline banner                       | only for crash boundary or truly global outage    |

## 10. Customer Versus Admin Translation

### 10.1 Customer Surfaces

Customer states should optimize for reassurance and forward motion:

- cached content remains readable
- next step is obvious
- copy stays plain-language
- visuals remain soft and composed

### 10.2 Admin Surfaces

Admin states should optimize for truth and operational control:

- preserve table, queue, and toolbar geometry during loading
- name impacted workflow precisely
- show capability limits, not just sentiment
- keep keyboard and bulk-action pathways recoverable where possible

Admin may be more explicit than customer UI, but still should not devolve into
dashboard-alarm theatrics.

## 11. Anti-Patterns

The following are non-canonical for OSHUN V1:

- using empty states as loading states
- replacing structured surfaces with isolated centered spinners
- card-heavy skeleton grids for every route, regardless of actual layout
- infinite pulsing or shaking on persistent warning and error surfaces
- treating offline as full failure when queueing or cached reading still works
- using danger styling for routine retryable network issues
- offering many equal-weight recovery buttons

## 12. Implementation Alignment Checklist

Existing primitives should be aligned as follows in follow-on implementation
tasks:

- `Skeleton.tsx`: prioritize structural presets for lists, reading layouts,
  dense tables, and split views over generic card mimicry
- `EmptyState.tsx`: keep illustrations optional and avoid floating-icon posture
  for operational empties
- `ErrorState.tsx`: remove or reserve shake-heavy motion for only exceptional
  blocking states; default recoverable errors should use quieter entrance
- `OfflineBanner.tsx`: remain persistent and informative, but avoid attention
  patterns that feel toast-like or alarm-like
- mobile loading surfaces such as notifications should move from plain loading
  text toward structural placeholders where the final layout is already known

## 13. Acceptance Standard

A state handling pattern is canonical only if it satisfies all of the following:

- the user can identify what state they are in within one glance
- the surrounding layout still feels intentional
- the copy explains impact and next step
- the tone matches the actual severity
- the state does not look like generic SaaS fallback furniture
