status
A status says where one object stands, such as a host, an episode or a title, in a few words of its own. Each status has one of five states, and the state decides its colour, its symbol and what a screen reader hears.
when to use
- To show where one object stands: a host is “unreachable”, an episode is “on its way”, a title is “held”.
- Once per object, in a row of a list or in a cell of a table.
- Inside a sentence, shown as text: storage-01 is “healthy”.
when to use something else
- For a tag, a label or a count that isn't a state, such as “gpu”, “v2.4.1” or “12 episodes”. Use a badge. A badge says what something is, or how many there are, not how it is doing.
- For a condition of the whole page or list, such as “105 titles can't be checked”. Use a banner above the content. It says it once, for everything below it, instead of a status in every row.
- To confirm an action that just finished, such as “8 episodes queued”. Use a toast: a short confirmation of what people just did.
- For a list with nothing in it, or one that couldn't load. Use an empty state in place of the list. There is no object there to give a status to.
- For a status and its reason in a data table. Use the status cell. It shows this same status, with a detail line under it.
anatomy
- Chip. A small, square frame with a thin border in the state's colour, on a faint tint of it. It stays on one line, and never grows wider than the space it sits in. Shown as text, it has no frame and no fill.
- Glyph. A small symbol before the words, a different shape for each state, drawn in the state's colour. Screen readers skip it.
- State word. By default for warnings and errors only: a word that screen readers hear before the text, such as “error:”. It isn't shown on screen.
- Text. The few words of the status, in monospace and lowercase, in the state's colour. When there is no room, it ends in an ellipsis.
variants and states
There are five states. Pick the state by what the status means for the person, not by the colour you would like to see.
| state | glyph | colour | a screen reader hears | use it for |
|---|---|---|---|---|
| Neutral | A dash | Grey | The text | A plain fact: “missing”, “queued”, “not checked yet” |
| Information | A bar with a dot | Blue | The text | Under way, or worth knowing: “on its way”, “syncing” |
| Success | A check | Green | The text | Done and good: “held”, “saved”, “healthy”. Not for a problem |
| Warning | A triangle with a bar | Amber | “warning:” and the text | Works, but someone should look: “connection firewalled”, “degraded”, “can't be checked” |
| Error | A cross | Red | “error:” and the text | Failed or blocked, and needs action: “needs attention”, “unreachable” |
A chip's tint and frame come in the same state's colour. A status is neutral unless it is given another state, so a status whose state was forgotten never looks as if it means something.
why there is no colour setting
The state is the meaning. The colour, the glyph and the word a screen reader hears all follow from it, so they can't disagree, and the same meaning looks the same on every screen.
A colour setting would let a failure show in green. A badge has a tone, and nothing stops a badge from saying “failed” in green; a status can't.
When a status looks wrong, the state it was given is wrong. Change that state in the vocabulary, the one table of states described below, not the colour.
as a chip or as text
A status can drop its frame and its fill and be shown as text, for dense rows and for running text. The glyph stays, so the state never rests on colour alone.
without the glyph
The glyph can be left out, or replaced by one of your own, which screen readers skip in the same way. Without the glyph, only the words and the colour carry the state, so keep it unless the words say the state on their own.
the vocabulary
Write down every value an object can take, with its state and its words, once, in one table, and take every status from that table. Status vocabulary shows how to write one.
Several values can share a state and its words. In the sample backlog, four steps (queued, grabbed, downloaded and waiting) all show as information, with the words “on its way”. Say what the person needs to know, and keep the specifics for the detail line of a status cell.
| value | renders |
|---|---|
| open | open |
| firewalled | warning: connection firewalled |
| checking | checking |
| down | error: unreachable |
| unknown | not checked yet |
sorting by status
A list sorted by status puts the most urgent first: error, then warning, information, neutral and success. The hosts below are sorted that way.
| host | status |
|---|---|
| api-7f9c | error: unreachable |
| worker-2 | warning: degraded |
| db-0 | syncing |
| worker-3 | not checked yet |
| storage-01 | healthy |
Use the same order when one object has several conditions at once: show the most severe one, and say the rest in the detail line.
behaviour
A status only shows a state. It takes no focus, has no keys of its own and doesn't move. When it changes, it doesn't announce the change.
The details of how it is built are on its React page.
accessibility
- Each state has a glyph of its own shape, so the state never rests on colour alone, as WCAG 1.4.1 asks. Screen readers skip the glyph; the words carry the meaning.
- Warnings and errors are read with their state first, from a word that is hidden on screen: “error: needs attention”. Neutral, information and success statuses read only their text.
- That first word can be translated, given to a calmer state as well, or left out. Leave it out only where the text would say it twice.
- The lowercase look is only a style. Write the text exactly as it should be read.
- It isn't a live region: a status that changes in place isn't announced. When someone needs to hear the result of what they did, confirm it with a toast. When the change affects the whole list, use a banner.
Today:
- Text that runs out of room ends in an ellipsis, and nothing shows the rest. Keep the words short. Where they can still be cut, give the status the full text as its tooltip too.
content
- Name the state in the object's own words: “held”, “on its way”, “needs attention”, “connection firewalled”. One to three words, lowercase, with no full stop.
- Say it once: one status per object, from one table. The same value reads the same words on every screen.
- Leave colour words, such as “red” and “green”, out of the words and out of the code. The names of the states belong in the vocabulary table, not in the text.
- Why it is so, or what happens next, goes in a detail line under the status, in a status cell, not in the status itself: “needs attention”, with “every source that answered timed out” under it.
- Keep it honest: success is for what is done and good, not for a problem. “connected, but firewalled” works but needs a look, so it is a warning.
do and don't
related
- Status vocabulary: one table per object, and which state each kind of value gets.
- Table cells: the status cell, this status with a detail line under it, for data tables.
- Badge: tags, labels and counts that aren't a state.
- Banner: a condition of the whole page or list, with a way forward.
specs
| state | in code | text and glyph | chip | read before the text |
|---|---|---|---|---|
| Neutral | state="neutral" (the default) |
--state-neutral |
--state-neutral-bg fill, --state-neutral-border frame |
Nothing |
| Information | state="information" |
--state-information |
--state-information-bg fill, --state-information-border frame |
Nothing |
| Success | state="success" |
--state-success |
--state-success-bg fill, --state-success-border frame |
Nothing |
| Warning | state="warning" |
--state-warning |
--state-warning-bg fill, --state-warning-border frame |
warning: |
| Error | state="error" |
--state-error |
--state-error-bg fill, --state-error-border frame |
error: |
| setting | in code | what it does |
|---|---|---|
| Chip or text | appearance="chip" (the default) or appearance="text" |
As text: no frame, no fill, no padding, and the text at 12px. |
| Glyph | icon: true (the default), false, or a node of your own |
false hides the glyph. Your own node takes its place and is aria-hidden the same way. |
| State word | stateLabel: a string, or false |
A string replaces the word read first (stateLabel="fehler" reads “fehler: failed”) and, on a calm state, adds one. false leaves it out. |
| Text | text, or children |
The words. text wins when both are given; it is what lets a vocabulary entry spread in. |
| Full text on hover | title |
The browser's own tooltip, for words that can be cut. |
- Chip:
inline-flex, 20px tall, padding 0 8px (--s-2at the sides), a 1px frame, square (border-radius: 0). - Layout: glyph and text 6px apart,
white-space: nowrap,max-width: 100%(never wider than its parent). - Glyph: 12px, drawn in the state's colour (
currentColor), in anaria-hiddenspan. Each state has its own shape, for WCAG 1.4.1 (use of colour). - Text: JetBrains Mono 11px (12px as text), line-height 1, letter-spacing 0.02em, lowercased with
text-transform, in--state-*. It ends withtext-overflow: ellipsiswhen there is no room. - State word: a visually hidden
warning:orerror:in front of the text, by default for those two states only. - Vocabulary:
defineStates(table)returns a frozen copy of the table, each value mapped to{ state, text }, and every status spreads its entry in:<Status {...LINK[row.link]} />. With the value type as its type argument (defineStates<LinkValue>(…)), TypeScript makes the table cover every value. - Severity:
STATE_SEVERITYranks the states for sorting, most urgent first:error4,warning3,information2,neutral1,success0.STATESlists the five states,neutralfirst. - Motion and focus: none. It isn't a live region, so a change in place isn't announced.