Compact, non-interactive label for status and metadata — a pill at radius.full in font.size.caption at font.weight.medium. If it filters, navigates, or dismisses, it is a button or link wearing different clothes.
One sm/md/lg dialect. Heights ride the icon scale until large, which steps onto the control scale and up to font.size.copy-sm.
| Example | Size | Modifier | Height | Usage |
|---|---|---|---|---|
| Small | Small | --sm | size.icon.md | Dense metadata: table cells, list rows |
| Medium | Medium | ds-badge | size.icon.lg | The default — cards, headers, detail rows |
| Large | Large | --lg | size.control.sm | Higher-emphasis labels, feature areas |
The unmarked badge is neutral. Four functional statuses take complete pairs from status.*. Extended semantic channels such as Disputed use category.accent, never a borrowed functional status hue. Inverted is the high-emphasis neutral.
| Example | Intent | Modifier | Roles | Usage |
|---|---|---|---|---|
| Neutral | Neutral | — | metadata.bgmetadata.text | The default — categories, counts, plain metadata |
| Success | Success | --success | status.success.bgstatus.success.text | Completed, active, healthy |
| Warning | Warning | --warning | status.warning.bgstatus.warning.text | Degraded, expiring, needs attention |
| Error | Error | --error | status.error.bgstatus.error.text | Failed, blocked, invalid |
| Info | Info | --info | status.info.bgstatus.info.text | In progress, informational |
| Disputed | Category accent | --accent | category.accent.bgcategory.accent.text | Extended semantic channel beyond the functional four |
| Inverted | Inverted | --inverted | text.primarytext.inverse | High-emphasis neutral: "New", version tags |
Subtle is the default tier; --solid compounds with functional statuses and --accent for moments that must not be missed. Neutral has no solid tier — its high-emphasis form is --inverted.
| Example | Emphasis | Modifier | Roles | Usage |
|---|---|---|---|---|
| Success | Subtle | — | status.{intent}.bgstatus.{intent}.text | The default status treatment |
| Success | Solid | --solid | status.{intent}.solid-bgstatus.{intent}.solid-text | Must-not-miss: destructive outcomes, live states |
Same leading/trailing vocabulary as Button: the modifier pulls the icon-side padding in one spacing step below the text side. Badge and Chip share the dedicated size.pill-icon 12/14/16px ladder, keeping metadata glyphs quieter than the general icon scale; icons are decorative here and the label carries the meaning.
Functional rows descend through solid large/medium/small, then build through subtle small/medium/large; neutral and inverted each have one supported emphasis. Category accent remains in the intents table because the unbranded starter maps that extension point to neutral. Toggle the page theme to compare the same role pairs on light and dark UI.
| Example | Size | Modifier | Icon | Padding | Usage |
|---|---|---|---|---|---|
| Small | --sm--leading-icon | size.pill-icon.sm | space.1-5space.2 | Dense status rows | |
| Medium | --leading-icon | size.pill-icon.md | space.1-5space.2 | The default iconed badge | |
| Large | --lg--leading-icon | size.pill-icon.lg | space.2space.3 | Feature-area labels | |
| Small | --sm--trailing-icon | size.pill-icon.sm | space.2space.1-5 | Dense rows: a locked or private marker | |
| Medium | --trailing-icon | size.pill-icon.md | space.2space.1-5 | The default trailing qualifier — a fact after the label | |
| Large | --lg--trailing-icon | size.pill-icon.lg | space.3space.2 | Feature-area labels with a qualifying glyph |
A badge is a statement, not a control.
| Verdict | Rule |
|---|---|
| Do | Take status colors as a pair from the status roles — background and text arrive together. |
| Do | Default to subtle; reserve --solid for states that must not be missed, and expect few per view. |
| Do | Keep the label to one or two words, sentence case — a badge that needs a sentence is an Alert. |
| Do | Mark badge icons decorative (aria-hidden="true") — the label carries the meaning. |
| Don’t | Make a badge interactive — a removable filter or clickable tag is Chip, which shares the pill recipe, never this contract. |
| Don’t | Pair a status background with a foreground it wasn’t issued with, or reach into raw ramps. |
| Don’t | Ship an icon-only badge — there is none; a lone glyph with meaning is an icon, not a badge. |