status vocabulary

Most items in our apps have a status: a download is on its way, an episode is missing, a host can't be reached. People read these statuses all day, so they should mean the same thing every time, in every app.

A status vocabulary makes sure they do. It is a short table, written once for each kind of item, that lists the statuses the item can have, in the item's own words, and gives each one a meaning.

where it applies

• Every list, row, card or page that shows the state of things: items in a backlog, hosts, jobs, sources, downloads.
• Before the screen is designed. The vocabulary decides the tabs, the counts, the confirmations and the empty states, so it comes first.

Some things look like statuses but aren't:

• A label, a tag or a count that isn't a state is a badge.
• Something about the whole page, like “105 titles can't be checked”, is a banner; see message handling.
• The result of something people just did, like “8 episodes queued”, is a toast.

anatomy

1. The meaning. One of five: neutral, information, success, warning or error. It decides the colour, and the small shape in front of the words, so a status never relies on colour alone. Colour explains what each meaning stands for, and what it isn't used for.
2. The words. The status in the item's own words, two or three of them: “missing”, “on its way”, “needs attention”.
3. The detail (optional). One line on why, or on what happens next: “nothing found · again in 6h”. Technical errors go behind it, in a tooltip or under details, not in it.

A screen reader reads warnings and errors with their meaning first: “error: needs attention”.

writing a vocabulary

1. List every value the system has. For a backlog: wanted, queued, searching, grabbed, downloaded, waiting, failed and held.
2. Group them by what people need to know, not by how the system works: missing (nothing is under way), on its way (something is), needs attention (a person has to act), and held.
3. Give each group one meaning. The words decide it: “on its way” is information, not success, because nothing is done yet.
4. Write the detail for each value. Queued becomes “queued for a search and grab”; waiting becomes “waiting for the catalog”.
5. Put it all in one table, and show every status from it. The status component's React page shows how to write that table in code, so a reviewer can see in one place that “connection firewalled” is a warning.

one status, end to end

An item reads the same wherever it shows up. The row says “on its way”, the tab that holds it says “on their way”, its group counts it among what is on its way, and the confirmation after a grab says it was queued. It doesn't say “success” in one place and “pending” in another.

If an item can be in several states at once, its vocabulary isn't finished yet.

sorting by status

Some lists are best sorted by urgency, the most urgent first: errors, then warnings, information, neutral, and successes last. The five meanings come with this order built in, so a status column can sort this way without extra work.

examples

do and don't

accessibility

Statuses are text, not buttons, so the keyboard passes over them. The small shape is decoration: a screen reader reads the words, and for warnings and errors, the meaning first. In a table, the full detail is there for screen readers even where the screen cuts it short after two lines.

related

• Status and table cells: the components, live.
• Colour: what each meaning stands for.
• Worklist: tabs and counts built from the vocabulary.
• Principles: 2, the outcome is the status.