States are the work
beginner·7 min·Markdown for agents
What this lesson teaches
Design every state a screen can be in, not just the happy one, and treat tables and charts with the same care as a landing page.
This inbox has six tabs. The first one is the screen everybody designs. Click through the other five:
The happy path: the one state everyone designs.
Loading, empty, error, offline, half-loaded. Every one of those is a screen a real person will see, often more often than the perfect one. And every one needs its own design and its own words.
The happy path is the easy part
The is the screen with everything going right: data loaded, user signed in, content present. Designers draw it, engineers build it, agents generate it. Then real people show up on a slow train, with an empty account, with an expired session, and the product looks broken.
Most "this feels broken" reports trace back to a state nobody designed, not to a bug in the happy path. So fixing states is some of the highest-value design work there is.
The states to check, every screen
You will not need all of these for every screen, but you should be able to say why each one does not apply:
| State | What is happening |
|---|---|
| Loading | The data is on its way |
| Empty | Nothing here yet: new account, zero results |
| Partial | Some content loaded, some still coming |
| Error | Something failed, like the server or the network |
| Offline | No connection at all, different from one failed request |
| No permission | Signed in, but not allowed to see this |
| Stale | Showing saved data from a while ago |
| Over limit | A plan limit reached; read-only |
| First run | Onboarding, sample data |
Each needs real copy, not "Error: something went wrong", and a designed way to get from one to the next without a flash.
✕ One message for everything
"No data." Shown when the inbox is empty, and when the server is down. The person cannot tell whether they are caught up or whether their mail is gone.
✓ Empty and error, apart
Empty: "You're all caught up. New mail will show up here." Error: "We couldn't load your mail. Your messages are safe. Try again." Different look, different words, a way forward.
Data is content
There is a second place the craft usually stops: tables, charts and lists. Teams spend a week on a hero image and half an hour on the table people look at every single day. That is backwards. In most working software, data is the content.
| Name | Type | Value | Change |
|---|---|---|---|
| Acme Corp | Annual | 12,480.00 | +4.1% |
| Globex | Monthly | 1,120.50 | −0.8% |
| Initech | Annual | 9,999.00 | +11.2% |
| Umbrella | Monthly | 711.10 | +0.3% |
| Hooli | Annual | 48,200.00 | +2.6% |
- Numbers left-aligned in proportional digits: impossible to compare.
- Heavy borders on every cell, zebra stripes: the spreadsheet look.
- “Value” of what? In what?
Right-align numbers, left-align text
Numbers compare when their last digits line up. Text reads from the left.Use tabular figures
font-variant-numeric: tabular-numsgives every digit the same width, so a column of amounts lines up and values stop jittering when they change.Quiet the lines
Heavy borders on every cell and zebra stripes are the spreadsheet look. Use space and a hairline divider, like1px solid rgba(0,0,0,0.06).Label with meaning
"Value" says nothing. "Revenue, USD" says what and in what unit.
Charts follow the same rules. Pick two to four colors from your palette instead of the library's rainbow. Remove default (extra gridlines, legends nobody needs). Make tooltips useful: the exact value, the date and a comparison, not "y: 47". Animate the chart drawing in once, on first load; updates should be instant.
Charts may have a little personality. Tables and lists should be predictable.For tools people use all day, density matters too. Power users want compact rows (about 28px), casual users want comfortable ones (about 44px); offer both. Let people edit a cell in place and move with the arrow keys, the way every spreadsheet already works.
For this screen, list every state it can be in: loading, empty, partial, error, offline, no permission, stale, over limit, first run. For each, say whether it applies. For the ones that do, build it with real copy (no "something went wrong") and make sure empty and error look and read differently.
Review this table as content: right-align numeric columns with tabular-nums, left-align text, replace cell borders and zebra stripes with a 6% hairline between rows, make the header say what each column is and in what unit, and keep the header visible on scroll.
Quick check
An inbox shows the same 'No data' message when it is empty and when the server fails. What is wrong?
In the skill
The nodes your agent reads when it does this work.
- States are the workLoading, empty, error, partial, offline, permission-denied. The real design surface is the states, not the happy path.
philosophy/states-are-the-work - Data is contentTables, charts, lists, dashboards deserve the same typography, alignment, and whitespace care as marketing pages.
philosophy/data-is-content
Connected lessons
What this lesson builds on and leads to, across every course.