Badge

When to use it

Use a badge for a short, categorical value attached to something else: a status, a count, a label. The word inside it should be one or two words that a reader can take in without reading — "Paid", "Draft", "3 open".

white-space: nowrap is set deliberately. A badge that wraps to two lines has stopped being a badge, so if the text is long enough to wrap, the text is wrong rather than the badge.

<h3 class="cluster cluster-tight">Invoice INV-2291 <span class="badge badge-good">Paid</span></h3>
<p class="text-sm cluster cluster-tight">Same badge in small text <span class="badge badge-good">Paid</span></p>

Tones

Six looks. Each sets background, color and border-color and changes nothing else, so a tone never resizes a badge or moves what is around it.

<span class="badge">Neutral</span>

<span class="badge badge-brand">Brand</span>

<span class="badge badge-good">Good</span>

<span class="badge badge-warn">Warn</span>

<span class="badge badge-bad">Bad</span>

<span class="badge badge-solid">Solid</span>

Leading dot

.badge-dot adds a ::before circle in currentColor, which means it takes the tone's text colour automatically and no extra markup is involved. It reads as a status light rather than a label.

<span class="badge badge-dot badge-good">Live</span>
<span class="badge badge-dot badge-warn">Degraded</span>
<span class="badge badge-dot badge-bad">Down</span>
<span class="badge badge-dot">Unknown</span>

The dot is decorative and carries no meaning of its own. Colour alone is not a status — the word beside it is what a colour-blind reader and a screen reader both rely on. Never ship .badge-dot with no text in it.

In context

Badges are almost always inside something else. The two places they earn their keep are the end of a table row and beside a title.

<div class="table-wrap">
  <table class="table">
    <thead><tr><th scope="col">Invoice</th><th scope="col">Status</th></tr></thead>
    <tbody>
      <tr><th scope="row">INV-2291</th><td><span class="badge badge-good">Paid</span></td></tr>
      <tr><th scope="row">INV-2292</th><td><span class="badge badge-warn">Pending</span></td></tr>
      <tr><th scope="row">INV-2293</th><td><span class="badge badge-bad">Overdue</span></td></tr>
    </tbody>
  </table>
</div>

Classes

Generated from src/07-components.css by tools/docs/extract.mjs.

Tokens

The badge reads the status ramps directly. Each tone uses the 100 step for its fill and the 700 step for its text, which is the pairing Deck uses everywhere a tint needs readable text on it.

Accessibility

• A badge is a <span> with no role. A screen reader reads the text and nothing more. That is usually right — "Paid" in a status column reads as "Paid" — but it also means the badge does not announce what it is a status of. Give the column a header, or add .sr-only text.
• Colour is never the message. The tone is a second signal on top of the word. A badge whose only content is a colour has no accessible name at all.
• Not a live region. Changing a badge's text with JavaScript announces nothing. If a status change needs to be heard, put it in a .toast or an element with aria-live.
• Contrast. The 100/700 pairing clears 4.5:1 in both themes. .badge-solid uses --text-on-brand, which is computed against the brand rather than hard-coded, so it stays readable if the brand hue is changed.
• It is not interactive. There is no focus style, because there is nothing to focus. A badge that needs to be clicked is a .chip or a .btn-sm.

Right to left

The badge uses gap and padding shorthands with no side-specific values, so dir="rtl" needs nothing. The dot moves to the right-hand side on its own because it is a flex child rather than a positioned element.

<span dir="rtl" class="badge badge-dot badge-good">مدفوعة</span>
<span dir="rtl" class="badge badge-warn">قيد الانتظار</span>

Reduced motion

Nothing about a badge animates or transitions, so prefers-reduced-motion changes nothing here. This section exists because every component page has it; for this component there is genuinely nothing to say.

Printing

Print stylesheets usually strip backgrounds, which would turn every badge into plain text and lose the status. src/99-print.css lists .badge among the elements that keep their fill, with print-color-adjust: exact, so a printed invoice still shows Paid as green.

Overriding it

The badge has no local custom properties; the tones set background and color directly. Override in app.components, which beats every Deck layer regardless of specificity.

@layer app.components {
  .badge {
    border-radius: var(--r-full);
    text-transform: uppercase;
    letter-spacing: .04em;
  }
}

Adding a tone of your own is four declarations and needs no Deck class: background, color, border-color: transparent, and nothing else.

When not to use it

• Not for something clickable. Use .chip, which has a hover state, a focus ring and a 44px target, or a .btn-sm. A badge with a click handler is an unfocusable control.
• Not for a removable filter. That is .chip with a remove button. Badges have no affordance for being dismissed.
• Not for a count on an icon. Use .indicator, which positions itself over its parent. A badge is inline and will sit beside the icon rather than on it.
• Not for a sentence. white-space: nowrap means a long badge pushes its container wide instead of wrapping, and on a phone that is a horizontal scrollbar. If it is a sentence, it is an .alert.
• Not as a heading-level label. A badge in an <h1> inherits the heading's size through em and becomes very large. That is the em sizing working correctly; it is still usually not what you want. Wrap it in a <small> or use .text-sm on the badge's parent.