Badge and Tag — short signals

Both are compact, but their roles differ. In a DS, split their API and visuals so the product does not mix “order status” with “category filter.”

Role difference

	Badge	Tag
Meaning	Status / count / indicator	Label, category, filter
Interaction	Usually none (or rare click)	Often removable / selectable
Examples	“New”, “3”, “Failed”	“React”, “UX”, filter chips

Badge answers “what state is this entity in?” Tag answers “which labels does it belong to?”

Badge API

<Badge tone="success" size="sm">Active</Badge>
<Badge tone="danger" variant="subtle">Expired</Badge>
<Badge tone="neutral" variant="outline">Beta</Badge>
<Badge tone="accent" pill>12</Badge>

Tone should be semantic: success | warning | danger | info | neutral, not “green/red” in props — themes and dark mode will thank you.

Variants: solid | subtle | outline. Sizes: sm | md. Do not make a badge larger than card body text — it is a label, not a heading.

Tag API

<Tag>Design system</Tag>
<Tag onRemove={handleRemove}>React</Tag>
<Tag selected onClick={toggle}>TypeScript</Tag>

For removable:

<span className="tag">
  React
  <button type="button" className="tag__remove" aria-label="Remove React tag">
    <Icon icon={Close} decorative />
  </button>
</span>

The remove button name should include the tag value — otherwise ten “Remove” buttons are indistinguishable.

Color and a11y

Do not convey meaning only with color: duplicate with text or an icon.
Badge text-to-background contrast — WCAG AA.
Counters in badges (“9+”) are read by screen readers; for icon-only status without text — aria-label.

Composition patterns

<Card.Title>
  UX course
  <Badge tone="info" size="sm">New</Badge>
</Card.Title>

<div className="tag-list" role="list">
  {tags.map((t) => (
    <Tag key={t} role="listitem" onRemove={() => remove(t)}>{t}</Tag>
  ))}
</div>

Limit text length (truncation + title/tooltip with the full value) — long tags break filter grids.

Practice

Badge: tones × variants in a Storybook matrix.
Tag: default, selected, removable.
Document Do/Don’t: when badge, when tag.
Check contrast of every tone on light/dark surfaces.