Badge

A short label for a status, category or count, next to what it describes.

In Accessible first

See it live

Start Storybook to see it live: npm run storybook

Live from StorybookOpen Badge in StorybookSee it in dark

When to use it

In Accessible first: A status label with an icon and a word, in a clear rectangle. Not color alone, and not a pill.

• Use it when: A state people scan for in a list or table, or a small category label.
• Not when: A message people must read (alert or toast), or an action (a button).

Instead:

• Alert: A message, not a label.
• Button: Something to press.

Variants

What each variant is for in any design system, then what Accessible first decided and why. Each sample is the live story with that variant set.

neutraltoneUsed in Accessible first

Start Storybook to see it live

What it is for

A label with no status meaning: a category, a count, a waiting state.

✓Nothing is wrong and nothing needs doing.

✕The state needs attention.

In Accessible first

A waiting state, such as an application saved to resume later, with an icon and a word.

Because

How many signals carry each meaning?Three: color, icon and word · accessibility.countHow long is one visit?One sitting · scenarios.q2

infotoneNot used in Accessible first

Start Storybook to see it live

What it is for

News: worth knowing, nothing to act on.

✓Something is happening or coming.

✕Something is wrong or nearly wrong.

In Accessible first

Neutral covers news with nothing to do: one clear way to do each thing.

Because

When does a component get another look?Only when the meaning changes · components.values

successtoneUsed in Accessible first

Start Storybook to see it live

What it is for

Done, healthy or paid.

✓The outcome people wanted.

✕A state that is only waiting.

In Accessible first

A finished task, with a filled icon and a word.

Because

How many signals carry each meaning?Three: color, icon and word · accessibility.countWhich outcome matters most?Completion without errors · outcomes.q1

warningtoneUsed in Accessible first

Start Storybook to see it live

What it is for

Needs attention soon; nothing has failed yet.

✓A risk people can still act on.

✕Something already failed.

In Accessible first

A risk people can still fix before they finish, with an icon and a word.

Because

How many signals carry each meaning?Three: color, icon and word · accessibility.countWhat is a costly mistake?A task that fails · outcomes.q2

dangertoneUsed in Accessible first

Start Storybook to see it live

What it is for

Failed, blocked or lost; act now.

✓A real failure or loss.

✕Anything that is only unusual.

In Accessible first

A failure that blocks the task, with a filled icon and a word; an alert says how to fix it.

Because

How many signals carry each meaning?Three: color, icon and word · accessibility.countWhat is a costly mistake?A task that fails · outcomes.q2

How Accessible first uses it

A status

Use Badge with an icon and a word

Not Color alone

Status must survive no color and a screen reader.

Shape of a status badge

Use radius.badge (rectangle)

Not A pill

Clear shapes with a word inside.

Why it works this way

Badge looks the way it does because of 5 answers about this product. Each card is one answer, in three steps: the answer, what it decided for Badge, and what would move if it changed.

How many signals carry each meaning?accessibility.count

1The answer

Three: color, icon and word

Never color alone.

2So Badge

• ✓uses neutral: A waiting state, such as an application saved to resume later, with an icon and a word.
• ✓uses success: A finished task, with a filled icon and a word.
• ✓uses warning: A risk people can still fix before they finish, with an icon and a word.
• ✓uses danger: A failure that blocks the task, with a filled icon and a word; an alert says how to fix it.

It also shapes Alert: destructive Item: muted

3If it changed

4

Badge decisions would reopen

and 1 answer that follow from it: Status and messages.

How long is one visit?scenarios.q2

1The answer

One sitting

An application is finished in one sitting, or saved and resumed.

2So Badge

• ✓uses neutral: A waiting state, such as an application saved to resume later, with an icon and a word.

3If it changed

1

Badge decision would reopen

No other answer follows from it.

When does a component get another look?components.values

1The answer

Only when the meaning changes

One clear way to do each thing.

2So Badge

• –does not use info: Neutral covers news with nothing to do: one clear way to do each thing.

3If it changed

1

Badge decision would reopen

No other answer follows from it.

Which outcome matters most?outcomes.q1

1The answer

Completion without errors

Completion without errors is the measure.

2So Badge

• ✓uses success: A finished task, with a filled icon and a word.

It also shapes Alert: default

3If it changed

1

Badge decision would reopen

and 2 answers that follow from it: Links and actions, Form steps and errors.

What is a costly mistake?outcomes.q2

1The answer

A task that fails

A failed form can cost someone a benefit.

2So Badge

• ✓uses warning: A risk people can still fix before they finish, with an icon and a word.
• ✓uses danger: A failure that blocks the task, with a filled icon and a word; an alert says how to fix it.

It also shapes Button: secondary Button: danger Alert: destructive

3If it changed

2

Badge decisions would reopen

No other answer follows from it.

Words

• Use common words. Explain any term you must use.
• One idea per sentence. Put the action first.
• Never blame the person.
• Use: Continue, Change, Start, You. Avoid: Invalid, Utilise, Submit, Error code.

The labels components use, from the voice tokens:

• content.action.commit: Continue
• content.action.cancel: Go back
• content.action.destroy: Delete
• content.action.retry: Try again
• content.action.empty-action: Start a new application

See Voice and tone for the whole voice.

Accessibility and keyboard

Test before you ship:

• The status is a word; color and icon add to it, never replace it. undefined

Use it in code

npx open-ds add badge

The component reads only component keys and semantic tokens, so it follows the brand and mode on <html>.

Tokens it reads

Badge reads 17 tokens of its own, each an alias of a semantic token. Each row is one part: its own token, the semantic it aliases, and the value it ends at. Change a semantic and every component that reads it follows; override one of Badge's tokens to change Badge alone.

Changes with theme

Accessible first decides what changes when you switch theme. Here a switch changes colors only, so the marked rows differ between light and dark; everything else holds steady.

Part	Its token and the semantic it aliases	Value
Badge
Corner	component.badge.radiusradius.badgevar(--badge-radius)	radius.4:0.25rem
Padding, left and right	component.badge.padding-xspace.gap.tightvar(--badge-padding-x)	space.12:0.75rem
Text size	component.badge.font-sizetype.caption.font-sizevar(--badge-font-size)	font.size.16:1rem
Gap	component.badge.gapspace.gap.tightvar(--badge-gap)	space.12:0.75rem
Padding, top and bottom	component.badge.padding-ycomponent-spacing-map.hairlinevar(--badge-padding-y)	space.2:0.125rem
Weight	component.badge.font-weighttype.label.font-weightvar(--badge-font-weight)	font.weight.700:700
Font family	component.badge.font-familytype.caption.font-familyvar(--badge-font-family)	font.family.atkinson-hyperlegible:"Atkinson Hyperlegible", Verdana, sans-serif
Neutral
Fill Changes with theme	component.badge.neutral.backgroundcolor.surface.sunkenvar(--badge-neutral-background)	Lightgray.light.100:#EDEDEDDarkgray.dark.100:#222222
Text Changes with theme	component.badge.neutral.labelcolor.text.secondaryvar(--badge-neutral-label)	Lightgray.light.700:#333333Darkgray.dark.600:#B4B4B4
Success
Fill Changes with theme	component.badge.success.backgroundcolor.status.success.subtlevar(--badge-success-background)	Lightgreen.light.100:#DBF7DFDarkgreen.dark.100:#012E16
Text	component.badge.success.labelcolor.text.success-on-lightvar(--badge-success-label)	green.light.800:#023E17
Warning
Fill Changes with theme	component.badge.warning.backgroundcolor.status.warning.subtlevar(--badge-warning-background)	Lightamber.light.100:#FEE8CFDarkamber.dark.100:#372500
Text	component.badge.warning.labelcolor.text.warning-on-lightvar(--badge-warning-label)	amber.light.800:#462A02
Danger
Fill Changes with theme	component.badge.danger.backgroundcolor.status.danger.subtlevar(--badge-danger-background)	Lightred.light.100:#FFDBD8Darkred.dark.100:#451014
Text	component.badge.danger.labelcolor.text.danger-on-lightvar(--badge-danger-label)	red.light.800:#6D0008
Info
Fill Changes with theme	component.badge.info.backgroundcolor.status.info.subtlevar(--badge-info-background)	Lightteal.light.100:#CDF4F0Darkteal.dark.100:#012F2C
Text	component.badge.info.labelcolor.text.info-on-lightvar(--badge-info-label)	teal.light.800:#022C29