Offline state

Problem Context

• The app can detect a missing, intermittent, captive, or unreachable connection that affects current work.
• Some content, drafts, settings, help, forms, or records may remain useful from cache or local storage.
• Users may start or continue work offline and need to understand whether it is local, queued, blocked, stale, or ready to sync.
• Connectivity can return while queued actions still need upload, server validation, conflict handling, or failure recovery.

Selection Rules

• Choose offline state when connection loss changes what users can read, edit, save, submit, refresh, upload, export, or share.
• State the scope of the outage: whole app, current page, one record, one action, one attachment queue, or one data source.
• Label cached data with its last successful update time or source when freshness affects decisions.
• Label local changes as saved on this device, queued, waiting to sync, or sync failed rather than simply Saved.
• Allow safe local actions such as editing drafts, reading cached content, copying text, or exporting a local backup when available.
• Disable or explain online-only actions such as Submit, Refresh, Share, Export, Payment, or Invite when they cannot complete.
• Provide manual reconnect or retry check when users need control, and automatic reachability checks when appropriate.
• Use error state when a specific operation failed even though the broader app may still be online.
• Use loading spinner only while an operation is actively pending and before the app knows it is offline.
• Use sync state after the connection returns and the main question becomes whether queued changes are reconciling, complete, failed, or conflicting.

Required States

• Online normal state with no offline warning.
• Offline banner or local status that names affected scope.
• Cached read-only state with last updated timestamp.
• Local draft saved state that is not yet server-synced.
• Queued action state for saves, photos, messages, uploads, or submissions.
• Online-only action unavailable state with explanation.
• Reconnecting or checking connection state.
• Reconnected and syncing handoff state.
• Sync failed or conflict-ready state that preserves local work.
• No offline fallback state when nothing useful can be shown except a controlled offline page.

Interaction Contract

• The offline indicator appears only when connectivity affects the current task or a global app capability users can reasonably act on.
• The UI never claims a server save, upload, payment, invite, or submit has completed while the app is offline.
• Safe local work remains available and clearly local; unsafe online-only actions are disabled, queued, or routed to an explained fallback.
• Retry connection checks update status to still offline, reconnected, server unreachable, syncing, or failed instead of doing nothing.
• Queued work remains visible until it syncs, fails, is cancelled, exported, or enters conflict resolution.
• Stale cached data is labeled with last updated time and does not silently replace current data after reconnect without reconciliation.
• Focus and announcements communicate major connectivity transitions without interrupting every transient network fluctuation.

Implementation Checklist

• Define connectivity sources: browser online state, server reachability, API health, service-worker cache availability, and per-feature offline capability.
• Inventory which content and actions are available online, cached read-only, editable locally, queued for later, or unavailable.
• Write state copy that names the affected object and save location, such as saved on this device or 2 photos queued.
• Persist local drafts and queued actions with stable IDs, timestamps, user-visible status, and retry or cancel options.
• Use service workers, cache storage, local storage, IndexedDB, native storage, or platform queues according to product architecture.
• Keep stale labels, last-updated times, disabled action explanations, and reconnect controls visually close to affected content.
• Announce offline, reconnected, queued, sync failed, and conflict-needed transitions through appropriate status messaging.
• Test airplane mode, flaky network, captive portal, server timeout, refresh while offline, app restart, background return, duplicate queued actions, and multi-device conflicts.

Common Generated-UI Mistakes

• Showing only a browser-style offline page when useful cached or local content exists.
• Using a spinner forever during connection loss.
• Claiming a server save or submit succeeded while the work is only local.
• Disabling every control instead of only online-only actions.
• Hiding stale-data timestamps or presenting cached data as current.
• Clearing queued changes after reconnect failure.
• Treating offline, server outage, permission failure, and validation error as the same message.

Critique Questions

• What can users still do without network, and what must wait?
• Which content is cached, how old is it, and does freshness matter for this decision?
• Where exactly are local edits stored, and how will users know they are not yet synced?
• What does Retry connection test: device network, server reachability, or a specific API?
• What happens after reconnect if queued work fails validation or conflicts with newer server data?
• Can users recover local work by retrying, cancelling, exporting, or contacting support?