truthful product states

why

an interface is a source of truth for its visitor: whatever it shows is treated as fact. fabricated or implied state is a correctness failure, not a cosmetic one — sample content makes absence look like success, a raw error string names the transport instead of the correction, and a ritual retry button promises recovery that cannot happen. every visible claim must be backed by authoritative data or an honest uncertainty.

rule

user-facing UI must present durable facts and explicit uncertainty. do not invent activity, progress, traction, availability, or recovery success.

decide the state model before composing the screen

a screen with a remote read is a state machine, not a success component with a spinner attached. name each state from the consumer's decision: waiting, empty, blocked, recoverable failure, unavailable dependency, ready. the API contract supplies the facts; the interface chooses the safe explanation and next action.

observed condition	interface responsibility	must not imply
initial read is pending	preserve data-slot geometry with a skeleton loading representation	that a result already exists
successful read has no items	explain the absence and offer the next valid action	that data failed to load
caller is not allowed	state the authorization boundary and correction path	that retry will grant access
input or setup is invalid	identify what can be corrected	that a remote dependency is broken
a transient dependency failed	preserve the cause, offer retry when safe	that retry has already succeeded
data is ready	render authoritative facts with meaningful timestamps	more precision or freshness than the source provides

implementation boundary

a query hook exposes typed remote state; a display component maps that state to semantic UI primitives.
keep technical/provider labels, raw error payloads, and transport status out of visible copy; map them once at the product boundary.
render a retry only when the operation is safe and the failure category says retry can help. blocked or invalid states need correction, not a ritual retry button.
relative time is presentation; keep the exact timestamp in semantic metadata so a human and an agent can verify the claim.

decision record: a remote status surface

the initial implementation had one polished success view and treated every other outcome as an incidental edge case. three choices:

choice	verdict
show realistic sample content while data is absent	rejected: makes absence indistinguishable from success; hides authority failures.
render a raw exception message	rejected: exposes implementation vocabulary; does not say whether to retry, correct, or request access.
build semantic state primitives driven by a typed failure category	selected: every state has an honest claim, a bounded action, and a repeatable visual shape.

this prevents a ready-only component from fabricating a story the system has no authority to tell. full reasoning and verification matrix: semantic state surface.

verification

exercise each row of the state model on every remote surface. confirm: the empty response is not styled as an error; denied access offers no meaningless retry; a retryable dependency error preserves its cause; ready content comes only from the authoritative response.

good and bad

bad

return <ActivityFeed items={sampleActivity} />;

sample activity makes an unavailable response look like an authoritative ready state: fabricated facts are trusted, denied or failed reads are indistinguishable from success, and no state explains what to correct or whether retry can help.

good

if (query.isError) {
  return <DependencyFailureState retry={query.refetch} />;
}

the visible state names the real uncertainty and offers only the supported next action: retry because the failure category is transient, ready renders only authoritative facts, every claim verifiable against the contract that produced it.

state cluster

this file is the hub of the UI-state cluster; siblings carry the same principle into their own boundary:

file	owns
skeleton loading	the pending state's geometry.
server state and ui ownership	which owner holds each state.
TanStack Query	cache identity and freshness of the facts.
semantic state surface	the recorded decision and verification matrix.