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.mddocs/releases/v1/scope/partial-failure-and-degraded-mode-rules.mddocs/releases/v1/scope/motion-hierarchy-rules.mddocs/releases/v1/scope/minimal-chrome-rules.mdapps/oshun/web/src/components/Skeleton.tsxapps/oshun/web/src/design-system/components/EmptyState.tsxapps/oshun/web/src/design-system/components/ErrorState.tsxapps/oshun/web/src/components/OfflineBanner.tsxapps/oshun/web/src/components/DomainRouteExperience.tsxapps/oshun/web/src/components/DomainDegradation.tsxapps/oshun/mobile/src/offline/GlobalOfflineBanner.tsxapps/oshun/mobile/src/library/UnifiedLibraryView.tsxapps/oshun/mobile/src/notifications/NotificationCenter.tsxdocs/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
ErrorStateuses 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:
emptyis not an error.offlineis not automaticallydanger.errorshould not erase working content unless the content itself is invalid.skeletonshould 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, prefersilent 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
L0or quietL2fromOSHUN_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 wrongmessaging 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 mimicryEmptyState.tsx: keep illustrations optional and avoid floating-icon posture for operational emptiesErrorState.tsx: remove or reserve shake-heavy motion for only exceptional blocking states; default recoverable errors should use quieter entranceOfflineBanner.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