Badge

A small label for marking status, category, or count. Badges are visual atoms — they describe, they don't act.

When to use

Use a badge to call out a piece of metadata next to a heading, list item, or table row: a status (Active, Archived), a category (Beta, New), or a small count.

If the badge needs to be interactive — clickable to filter, dismissible to remove a tag — the AUTHOR wraps it in a <button>. The badge component itself stays purely visual.

Variants

Sizes

Single size for v1.0. Future versions may add -s and -l.

Anatomy

<span class="badge">Default</span>
<span class="badge -accent">Beta</span>
<span class="badge -danger">Critical</span>
<span class="badge -warning">Pending</span>
<span class="badge -success">Active</span>
<span class="badge -info">Info</span>
<span class="badge -muted">Archived</span>

<span> is the appropriate semantic element — inline text content, not a button or link.

Tokens used

• color.accent, color.danger, color.warning, color.success, color.info, color.border-muted, color.surface-raised
• color.ink-strong, color.ink-inverse, color.ink-regular
• font.overline-s typography
• radius.tag
• space.inset-element-s, space.inset-element-m

Tier 3 (component-specific): none. Badge consumes semantic tokens directly — the relationship is canonical, no per-component refinement needed.

Accessibility

• Use <span>, never <button> or <a> unless the badge IS the control.
• Don't rely on color alone to convey meaning — the label text carries the meaning, the color reinforces it.
• For interactive contexts, wrap the badge in a real button/link with an accessible name.

Edge cases

• Long labels — badges are designed for 1–3 words. Wrapping is prevented (white-space: nowrap); the author truncates upstream.
• Empty badge — don't render an empty badge as a dot indicator; use a dedicated Indicator pattern instead.

Do

• Keep labels short — one or two words ideal.
• Match variant to severity: -danger for critical, -warning for pending, -muted for archived.
• Use uppercase per the overline-s token — the component handles text-transform automatically.

Don't

• Don't stack multiple variants on a single badge.
• Don't use -danger for decorative red — reserve it for genuine errors.
• Don't make a badge clickable by adding onclick; wrap it in a button instead.

Related

• Avatar — companion element for representing users/entities
• Button — when a badge needs to be interactive, wrap it