Tag | Sodium design system

Styles

When to use it

Use: A row or a header names what a thing is: an environment, an engine, a tier, a region.
Use: A static outcome that never moves, such as a check that passed on a past run.
Use: A count beside a name: open incidents, unread alerts.
Not for: Work that moves from queued to running to done. Use Status.
Not for: The person removes or picks the label. Use Combobox.
Not for: A key the person presses. Use Kbd.

7 rules

Must: Keep ok, warn and fail for outcomes, each with the word that names it; name kinds of thing with neutral or outline. Because colour means an outcome in Sodium, so a green environment tag reads as a check that passed.
Never: Paint a Tag in the sodium yellow, as a fill, an edge or the word. Because yellow marks the one action on the screen, so a yellow tag beside the slab reads as a second one, and on white its word is 1.4:1.
Must: Write the label in sentence case; the tag sets the capitals. Because a screen reader spells typed capitals letter by letter, while the role only changes how the word looks.
Never: Give a Tag an onClick or render it as a button. Because it has no hover wash or focus ring, so nobody can tell it is pressable; use a Button with size="sm".
Should: Keep the label to one or two words; a longer phrase is a description.
Should: Pass a number as count, not as children, so it groups its digits and caps at max.
Should: Use size="sm" inside a 32px row or beside a mono value; the default elsewhere.

4 checks

: Words on their grounds: ink on the well 16.4:1 (14.5:1 dark), text-2 on the page 7.8:1, each status word 5.2:1 or better on its tint in both themes.
: The capitals come from CSS, so a screen reader reads the sentence-case source.
: A capped count keeps the exact number as text for a screen reader and as the title on hover.
: A Tag is not focusable and not announced as a control.

4 edge cases

Long label: Never wraps; the box clips at its end when the row is narrower, which is why the label stays at two words.
Count past max: Shows 99+; the exact number is in the title and read aloud.
Dark theme: The tints turn deep and the words light; the edges stay in the status colour.
Forced colours: Every variant keeps a CanvasText edge, so the box still reads.

5 props

variant: 'neutral' | 'outline' | 'ok' | 'warn' | 'fail' default 'neutral'
size: 'default' | 'sm' default 'default'
count: number
max: number default 99
render: ReactElement

16 tokens