Badge
Preview appears after the next Storybook update.
<Badge>Draft</Badge>When to use
Use it for
- The status of one item in a table row, a list or a card header.
- subtle (default) in lists and tables where many badges sit together; solid for the single status that must win a glance (Breaking, Build failed).
- Tone by meaning: success done or healthy, warning needs attention, danger failed or blocked, info new or changed, neutral no judgement.
- Plain-script pages that build rows as HTML strings use badgeHtml() from @bridge-ds/react/dom: the same markup, tones and sizes, without React. Never a homemade pill: the design system audit counts those as look-alikes.
Not for
- Anything clickable or removable: use Tag.
- A sentence or an explanation: use an inline Alert.
- Counts on icons: use the number in text next to the label.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
The text says the status, the tone backs it up
Someone who cannot tell green from red still reads Published and Failed.
Subtle in rows, solid for the exception
A table full of solid badges shouts. Keep solid for the one thing that must stand out.
Color as the only signal
A dot without words fails WCAG 1.4.1 and means nothing to a screen reader.
A tone that contradicts the words
Danger for New borrows urgency the user did not ask for.
Accessibility
- Static text read in reading order. No role, not focusable.
- Subtle tones use feedback text on feedback bg (4.5:1); solid tones use text.on-solid on feedback solid (4.5:1). Checked by the token build in every brand and theme.
- The dot and icon are decorative; the text carries the status.
- If a status changes while the user watches (Running to Failed), announce it with a live region; the badge itself is silent.
Content guidelines
- One or two words, sentence case: "Needs review", not "NEEDS REVIEW".
- Past participles for finished states (Published, Merged), present for ongoing (Running).
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/Badge/Badge.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Container
.badge - Size md
.md - Size sm
.sm - Leading dot
.dot - Subtle appearance (default)
.subtle.neutral - Subtle appearance (default)
.subtle.success - Subtle appearance (default)
.subtle.warning - Subtle appearance (default)
.subtle.danger - Subtle appearance (default)
.subtle.info - Solid appearance
.solid - Solid appearance
.solid.neutral - Solid appearance
.solid.success - Solid appearance
.solid.warning - Solid appearance
.solid.danger - Solid appearance
.solid.info
Motion and interaction
Badge does not animate: its states change at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/Badge/Badge.tsx, so this table cannot drift from the code. It also accepts every native <span> attribute.
| Prop | Type | Default | Description |
|---|---|---|---|
tone | 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'neutral' | Meaning of the status. The text must say it too: tone only reinforces. |
appearance | 'subtle' | 'solid' | 'subtle' | `subtle` (tinted, default) for dense lists and tables; `solid` for the one status that must win a glance. |
size | 'sm' | 'md' | 'md' | No description in the code yet. |
dot | boolean | false | Leading dot in the tone color. Ignored when an icon is set. |
icon | LucideIcon | none | Leading Lucide icon, for example CircleCheck for success. |
Playground
Change the props and see the real Badge update. Controls are generated from the TypeScript props; nothing here changes the system.
<Badge>Draft</Badge>Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Badge in Storybook).
Embed Storybook stories here (4)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Subtle
Solid
WithDot
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
Pulled components: Badge md gets its padding and min height (a
calc()of tokens is resolved and set, reported as "set, not bound"; acalc()of one token is bound)v1.0.0, Nov 11, 2026
- New
Badge: the sm size gets 8px side padding (space-2) instead of 6px, so small badges no longer feel cramped
v1.0.0, Nov 11, 2026
- New
Data display: Card restyled as a flat plate with an
interactiveoption and padding sizes; Badge gainsappearance(subtle, now the default, or solid), a dot, icons and sizes (existing solid badges must passappearance="solid"to keep their look); new Avatar and AvatarGroup, Table (sortable headers with aria-sort, selectable rows, sticky header, focusable scroll region, useTableSort), Accordion, Tag (removable, toggleable), Divider and Kbdv1.0.0, Nov 11, 2026
- New
Initial foundation: DTCG 2025.10 primitives and light/dark semantic tokens built to CSS variables, plus Button, Input, Badge and Card consuming tokens only
v1.0.0, Nov 11, 2026
- Fix
Figma plugin: updating a component no longer adds its icon swap property again (Badge showed Icon2 and Icon3 after Update all)
v1.0.0, Nov 11, 2026
- Fix
Select: the label and badge row in the trigger now applies to every Select, not only disabled ones
v1.0.0, Nov 11, 2026
- Fix
Add usage guidance files for Button, Input, Badge and Card, plus the list of color pairs to check for contrast
v1.0.0, Nov 11, 2026
- Fix
Adds the generated
component-specs.json(runnpm run specs) for Button, IconButton, Badge, Tag, Input and Card, read by the DS Bridge Figma plugin to pull them as component setsv1.0.0, Nov 11, 2026
- Fix
Demo: the home line, Changes > Waiting on me and the Changes badge now count the same things in the lead's seat (one function,
leadWaitingCount)v1.0.0, Nov 11, 2026