# Badge

## Overview

The badge component presents short inline labels, status values, metadata, and rendered token values with a compact rounded visual treatment.

Use `span.badge` for display-only content. Use chips when the user is choosing checkbox or radio values.

## When to use

Use a badge for a short read-only label, status, metadata value, or rendered token value.

## When not to use

Do not use a badge for links, actions, or selectable values; use a link, button, or chip respectively.

## Usage

For a default brand badge, omit `data-variant`:

```html
<span class="badge">Featured</span>
```

For a status or low-emphasis badge, use `data-variant`:

```html
<span class="badge" data-variant="success">Approved</span>
<span class="badge" data-variant="warning">Pending</span>
<span class="badge" data-variant="unavailable">Unavailable</span>
```

Badges can include an optional leading icon through the shared `.icon` pattern:

```html
<span class="badge" data-variant="success">
  <span class="icon" aria-hidden="true">check_circle</span>
  <span>Approved</span>
</span>
```

Use badges when the interface needs a short read-only label, status, metadata token, or rendered token value.

Use chips when a checkbox or radio group should scan like compact chips while keeping native form behavior.

Use a future token input pattern, not a standalone badge, when the user needs to enter, parse, remove, validate, or submit a comma-, tab-, newline-, or space-separated set of tokens.

Do not use `a.badge` or `button.badge`; link badges and button badges are not part of this component's public API.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- BDG-001: The default badge and `data-variant="brand"` use a filled brand treatment.
- BDG-002: `info`, `success`, `warning`, `error`, and `unavailable` variants use a subtle background with strong-color text and border.
- BDG-003: Individual badges stay on one line; use `.cluster` to wrap groups of badges.
- BDG-004: Badges use a fixed pill radius by default and can override it with `--badge-border-radius`.
## Accessibility

- Use `span.badge` only for display content.
- Keep badge text short and descriptive.
- Mark decorative icons with `aria-hidden="true"`.
- Do not rely on color alone when a status value needs to communicate critical information; include clear text.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--badge-background` | `<color>` | Sets the badge fill color for the default and status variants; change it to tune the visual weight of the badge surface. |
| `--badge-border-color` | `<color>` | Sets the badge outline color; change it when the border needs to separate the badge from nearby surfaces or match a status color. |
| `--badge-border-radius` | `<length>` | Sets the badge corner shape; change it to move badges from pill-shaped labels toward a squarer product style. |
| `--badge-border-width` | `<length>` | Sets the badge surface border width; change it when badges need a stronger or subtler edge. |
| `--badge-color` | `<color>` | Sets the badge text and icon color; change it when the fill or border color requires a different contrast pairing. |
| `--badge-control-gap` | `<length>` | Sets --badge-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-control-padding-inline` | `<length>` | Sets --badge-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-family-sans` | `Any` | Sets --badge-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-size` | `<length>` | Sets --badge-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-size-caption` | `<length>` | Sets --badge-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-icon-size` | `<length>` | Sets the size passed to icons inside badges; change it when icons should read larger or smaller than the label text. |
| `--badge-line-height` | `<number>` | Sets --badge-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-error-strong`
- `--color-error-subtle`
- `--color-info-strong`
- `--color-info-subtle`
- `--color-primary`
- `--color-success-strong`
- `--color-success-subtle`
- `--color-text-inverse`
- `--color-unavailable-strong`
- `--color-unavailable-subtle`
- `--color-warning-strong`
- `--color-warning-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-gap`
- `--layout-control-padding-inline`
- `--layout-surface-border-width`