Status

Sizes

When to use it

Use: A row, header or strip cell shows work that moves from queued to running to an outcome.
Use: A column of jobs, sorted by statusRank so failures come first.
Use: A cell where only the mark fits beside a word that already names it (StatusMark).
Not for: A label that never changes, such as an environment or an engine. Use Tag.
Not for: How far the work got. Use Progress.
Not for: The outcome needs a sentence and an action. Use Alert.

8 rules

Never: Show a status as a dot, a coloured square or a tinted word; use Status, a square mark and a word. Because a lone colour differs by hue only, which vanishes in grayscale and forced colours and says nothing to a screen reader, and a round dot is the one round part in a square system.
Must: Keep green, orange and red for ok, warn and fail; work on the way stays ink. Because colour means an outcome, so a green running row reads as done before it is.
Never: Show a warning or a running job in the sodium yellow. Because yellow marks the one action, and warning has its own orange so the two never meet.
Must: Set live on the one status the person is watching and on no other in the view. Because each live Status holds its own status region, so a page of rows reads out every job that settles.
Never: Add a pending mark or a spinner beside a running Status; its mark already steps. Because two moving marks on one row double the only loop Sodium has.
Must: Sort a status column by statusRank, failures first, never by the word. Because sorting by the word puts Failed between Idle and Queued, so failures never reach the top.
Must: Give a StatusMark with no word beside it a label. Because without one the mark is aria-hidden, so a screen reader skips the status entirely.
Should: Override the word with one to three words that keep the outcome, never a sentence.

7 states, highest first

5 checks

: The word is the status; each mark has its own silhouette (hollow, hollow with a cell, four cells, two bars, solid, half, diamond), so colour is never the only signal.
: Succeeded, Warning and Failed are 5.6:1 or better on the page in both themes, mark and word in one colour; idle and queued are text-2, 7.8:1.
: The marks are 3:1 or better against the page in light and dark (WCAG 1.4.11): ok 6.5, warn 4.3, fail 6.5 on white.
: A live status speaks once through a polite status region when it settles; the visible word is aria-hidden meanwhile.
: Status is not focusable.

6 edge cases

Long word: Wraps under itself; the mark stays centred on the first line.
Many running rows: Every running mark steps in time on one clock; show one running count in the header instead of a dozen.
Job never returns: Stays running and live stays silent; the caller sets warn after its deadline.
Right to left: The mark sits at the start, and the running cell steps the other way round.
Reduced motion: The running mark stands still with its first cell lit; the word still says Running.
Forced colours: Marks draw in CanvasText; their shapes and the word carry the meaning.

5 props

status: 'idle' | 'queued' | 'running' | 'paused' | 'ok' | 'warn' | 'fail' default 'idle'
size: 'default' | 'sm' default 'default'
live: boolean
children: ReactNode
StatusMark label: string

14 tokens