Badge usage
Agent reference
Start here · match your intent, then apply the rules belowsuccess, warning,
error, info. In tables/lists add appearance="dot".secondary,
or outline on busy / colored surfaces.primary for the single most important label —
at most one per view.beta for beta / preview / early-access only —
never as an accent.blue / teal / purple / neutral.
One color per category, reused everywhere.appearance="dot"
colors: collapse to error / warning / neutral /
success buckets.green/red/orange to mean
success/error/warning · rely on color with no text · put a sentence in a badge ·
use destructive (deprecated → error).How badge color works
Two color families — decide which one you are in firstSemantic family — color is the message
Answers “what state is this?”. These ride the traffic-light axis, which people read pre-consciously: red = stop/bad, amber = caution, green = go/good, blue = neutral info. Pick by meaning.
Categorical family — color is just identity
Answers “which kind is this?”. Drawn from the cool / neutral side of the wheel on purpose, so a label never masquerades as an alarm. Choose for mutual contrast, not connotation.
The tension: red, green and orange live in
both families. Rule of thumb — if a good/bad reading is possible, the semantic
variant wins; only use the raw palette hue when the set is purely nominal
(no ordering, no good or bad). Unify by keeping one color mapped to one meaning,
using the fewest hues that still communicate the structure, and always backing
color with text.
Rules
13 rules · ✓ do · ✕ avoid1.Choose by meaning, not by color
Badge color is a signal. Pick the variant whose meaning matches the state,
not the hue you happen to want. Semantic variants carry meaning; palette colors
do not — success says “this is good”, green says nothing.
2.Protect the traffic-light hues
Red, amber and green are pre-loaded with meaning. Spend them only on status. For categories with no good/bad reading, draw from the cool palette — blue, teal, purple, neutral — so an ordinary label never looks like an alarm.
3.A state always maps to the same variant
This is about consistency, not sameness: different states should of course look
different. But a single state must resolve to one variant and stay there. If
"Failed" is error on the overview, it has to be error in the
table too, not a solid red somewhere else. Splitting one meaning across two
styles (a "second red") makes the same status read as two different things.
4.A real status must carry a status color
If a value is genuinely good, bad, or in progress, give it a semantic variant.
Rendering a status with a meaning-free variant (primary, outline,
secondary) strips the signal, so the badge reads as decoration and the state
is invisible at a glance. "Verified" is success, "Pending" is
warning, a failure is error (not warning — don't
under-signal a real failure).
5.Meaning-free labels stay neutral
Metadata like "New", counts, or tags describe, they don't signal status. Use
secondary or outline. Never borrow a status color for decoration,
or a healthy-looking "New" quietly competes with real success states.
6.Use the variant, don't hand-roll the color
Reach for a variant. Don't rebuild a badge with className color overrides,
raw palette values (bg-green-100, #f6821f), a hand-drawn dot
<span>, or a legacy label component. Hand-rolled colors skip Kumo's
tokens, so they drift from the component and break in dark mode.
7.beta is a lifecycle marker, not a hype label
Use the dashed beta variant only for real lifecycle stages — beta, preview, or
early access. Two ways it goes wrong. First, don't paint Beta with an alarm color
(error red or orange); that reads as a failure or warning, not
"experimental". Second, don't reuse the beta styling for marketing labels like "Popular" or
"New" — inventing a lookalike status fabricates a signal that means nothing and dilutes the
one cue users trust to gauge stability.
8.In tables and lists, prefer dot over filled
Stacked filled badges create a “wall of color” that fights for attention and slows
scanning. The dot appearance is a quiet outlined chip with a small status
dot — the color still reads, but the row stays calm.
| api-gateway | Healthy |
| edge-cache | Degraded |
| auth | Down |
| api-gateway | Healthy |
| edge-cache | Degraded |
| auth | Down |
9.Collapse a wide taxonomy into a few dot buckets
When you categorize across many options, group them by theme and give each group one dot color. The eye parses a few hues far faster than many. Here six email dispositions collapse into four severity buckets — the column becomes instantly scannable instead of a rainbow.
| Invoice routing changed | Malicious |
| New device sign-in | Spoof |
| Quarterly review packet | Suspicious |
| Limited-time offer | Spam |
| Weekly usage digest | Bulk |
| Board prep agenda | Clean |
| Invoice routing changed | Malicious |
| New device sign-in | Spoof |
| Quarterly review packet | Suspicious |
| Limited-time offer | Spam |
| Weekly usage digest | Bulk |
| Board prep agenda | Clean |
10.Badges show status or a label, never an action
A badge is a non-interactive display element. Use it freely in tables and lists to show
status or categorization, and next to descriptive text or in a heading to tag what
something is. Never wire a badge to an action (click, remove, toggle) or style it to look
tappable; that is a Button, Chip, or link, not a badge.
| api-gateway | Healthy |
| auth | Down |
11.Never rely on color alone
Roughly 1 in 12 men can’t reliably separate red from green, and screen readers don’t
announce color (the dot is aria-hidden). The label text must carry the
meaning; color and the dot are redundant reinforcement, not the message.
12.Keep badges to one or two words
Badges don’t wrap (white-space: nowrap). Long strings blow out layouts,
especially in table cells. Summarize the state and move any detail to a tooltip or
adjacent text.
13.Show rank with an icon, not a new color
Severity and risk are ranked scales, but rank is a separate axis from meaning. Keep the
hue tied to meaning and let an icon carry the rank. "Critical" and "High" are both bad, so
both stay error red and a small alert icon marks the apex. Don't split them into
a tinted red and a solid red; that mixes the semantic and categorical families
and reads as two different meanings. When a scale isn't good or bad (a confidence or strength
level), keep it in the cool family and rank by emphasis, never with the traffic-light hues or
the alarm icon.