Empty states
An empty list can mean none, couldn’t check, or not loaded yet, and every layer has to keep those apart.
The problem
Models read silence as “no”. A relationship nobody measured, a check that timed out, a list cut off at 20 items, an API that didn’t load: each one turns into “your account doesn’t have shipping data”, said with total confidence and completely wrong.
The UI has the same bug in a quieter form. One grey “Nothing here” box covers all of those cases, so a person can’t tell a real absence from a failure.
What I concluded
Unknown is its own state, at every layer. In the UI that’s a component contract with three empty states, each saying something different:
type Presence<T> =
| { state: "present"; items: T[]; total: number }
| { state: "none" } // checked, really none
| { state: "unchecked" } // couldn't check
| { state: "loading" }; // not loaded yet
switch (presence.state) {
case "none": return <Empty>No carriers.</Empty>;
case "unchecked":
return <Empty>Couldn't check carriers. <Retry /></Empty>;
case "loading": return <Skeleton aria-busy="true" />;
}
The model gets the same three states in words:
Checked, none found: Carrier, Warehouse.
Couldn't check: Return, Coupon. That's unknown, not absent.
(+14 more types not listed; none of them is absent.)
Not loaded here: teams. Don't say the account lacks them.
A failed check only counts as “none” if it could have found the thing. A plain existence scan that timed out counts in proportion to how much it covered. A query error says nothing about the data, so it lands in “couldn’t check”.
Rules
nullmeans unknown. In every payload. Never “none”, never false.- “None” is a fact. Store it as its own record, so it can be confirmed and expire like anything else.
- Truncated lists say so. “And 14 more”, plus a reminder that what isn’t listed isn’t missing.
- Totals beat zeros. “0 failed” means nothing without knowing how many there are.
- The states look and sound different. Loading sets
aria-busy. “Couldn’t check” is real text with a retry button.
What you get
Answers hedge a bit more, and they’re wrong a lot less. The worst mistake an assistant makes is confidently denying something that’s there, and that mistake needs an unknown to be read as an absence. Keep the states apart everywhere and there’s nowhere for it to happen.
Related: Knowledge store, Checkable output