Badge

Docs draft

Component story Figma component set ↗React component ↗DSDS entity ↗

When to use it

useApplied filters, selected values, removable selections — chips the user manipulates.

avoidRead-only metadata. If it never responds to a pointer, it is a Tag. tag

avoidStandalone actions. A chip belongs to a collection; a lone chip that submits something is a Button. button

Variants

type · label / label-with-close / two-button — Mirrors the old matrix 1:1. In code the axis is derived from props: onClick = Label behavior, onRemove = Label with Close, both = Two Button (split pill, separate targets).

States

default — The default resting appearance.

hover — Pointer is over the control.

focus — Holds keyboard focus and shows the focus ring.

close hover — Pointer is over the close control.

close focus — The close control holds keyboard focus.

Guidelines

mustThe close affordance always gets an accessible name (default: Remove). — An icon-only button inside a chip is invisible to screen readers otherwise.

must-notDo not title-case chip labels; write them as the value they represent. — Sentence-case ruling; the old TITLE transform is dead.

API

Prop	Type	Description
`children`	`ReactNode`	Badge label content.
`onClick`	`() => void`	Makes the chip a button.
`onRemove`	`() => void`	Adds the close affordance; with onClick it splits the pill.
`removeLabel`	`string`	Accessible label for the remove button.

Design specifications

radius	radius.full
height	space.28
padding-x	space.12
padding-x-inner-seam	space.8
gap	space.4
label	type.label-lg
fill-rest	color.bg.secondary
fill-hover	color.bg.pressed
text	color.text.primary
close-glyph	Icon / Close at 16 (24-grid master, scales via constraints)
close-rest	color.text.secondary
close-hover	color.text.primary
optical-nudge	label line-height 24 (not 22) inside the 28px chip — DM Sans reads ~1px high when geometrically centered; the line-height route nudges glyphs only, leaving icons at true center

Accessibility

Enter / Space — Activates the focused segment (chip or close).

Tab — Split pills expose two stops: chip, then close.

color.text.primary on color.bg.secondary — Contracted at ≥ 4.5:1 by the build gate.

color.text.primary on color.bg.pressed — Contracted at ≥ 4.5:1 by the build gate.

Close renders a real button with an aria-label. Static badges are spans and take no focus.