badge

A badge tags an item with a short fact, such as “gpu”, “12 episodes” or “v2.4.1”, so people can scan a list and tell items apart. The state of an object, such as “running”, “failed” or “needs attention”, is a status instead.

when to use

• To tag an item with a short attribute that helps people scan a list and tell items apart: “gpu”, “read-only”, “4k”, “hdr”.
• For a count beside the thing it counts: “12 episodes”, “3 new”.
• For a short label that stays true for as long as the item exists: a version, such as “v2.4.1”, or a “default” marker.

when to use something else

• For the state of an object. Use a status. It shows each state in the colour of its meaning, with a glyph of its own, and it announces warnings and errors in words. A badge's tone is only a colour: nothing stops a badge from saying “failed” in green.
• For a message about the page or a task, such as a save that worked or a list that could not load. Use a banner, or a toast for something that just finished.
• As a button, or to filter a list. A badge is static: it can't take focus or be pressed. Use a button, or filter tabs to filter a list.
• For a count on a tile. A tile on the home page has a badge of its own.

anatomy

1. Frame. A small square frame with a thin border, a little taller than its text. A neutral badge sits on a slightly lighter panel. A badge with a tone sits on a faint tint of its colour, and its border mixes that colour with the usual border colour.
2. Dot (optional). A small square in the label's colour, just before the text. It is hidden from assistive technology.
3. Label. One or two words in small monospace, slightly spaced out and in lowercase. It never wraps.

variants and states

There are four tones. Neutral is the usual one, and the right choice for most tags. A tone is only a colour, so use one where it helps people find a label, and keep what it means the same everywhere.

There is no red tone. An error is a state: a status for one object, a banner for the page.

A badge can have a dot: a small square in the label's colour, before the text. The dot adds no meaning of its own, because it only repeats the tone, and it makes a badge look like a status light. Use it as a colour key, where the same colour appears nearby, as in a legend. If you reach for it to show a state, you want a status.

Next to the item it describes, a badge carries a tag or a count:

Badges also carry versions, markers such as “default”, and counts:

behaviour

• A badge is static: it has no focus, no keys and no action of its own. tab passes over it.
• It never wraps, and it has no maximum width: a long label runs out of its container rather than breaking onto a second line.

The full keyboard map is on the badge's React page.

accessibility

• A screen reader reads a badge's text along with the words around it.
• The tone is never announced, and neither is the dot. The words carry the meaning: “read-only” is read out, the amber is not.
• The lowercase look is only a style, so screen readers read the text as you wrote it.
• A bare number is read without its subject: just “12”. Keep a count right next to what it counts, or say what it counts: “12 files”.
• The text of every tone has enough contrast on its own tint to be read easily. The frame is only decoration.

content

• One or two words, in lowercase, with no full stop: “gpu”, “read-only”, “3 new”.
• Say what the item is, not what it is doing right now. “running” is a state; “gpu” is a tag.
• Use digits for counts: “12”, not “twelve”.
• Don't repeat the column or field name in every badge: “gpu”, not “label: gpu”.

do and don't

related

• Status: the state of an object, in words, a glyph and the colour of its meaning.
• Status vocabulary: which states exist, and what to call them.
• Table: badges as tags in a cell.
• Tile: the count badge of a tile on the home page.

specs

• Contrast: every tone's text meets 4.5:1 on its own tint; green is the closest, at about 4.9:1. The frame is decorative.
• Element: a plain span with no role. It takes no focus and has no keys, so tab skips it.