> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Badge Component: Status and Risk Level Indicators

> The Clementine DS Badge renders inline status and risk level labels with semantic color coding across 8 intent variants including 4 risk tiers.

Badge renders non-interactive inline labels that communicate status, severity, or count. It ships 8 background intent variants — four semantic feedback intents (`neutral`, `success`, `error`, `warning`) and four risk tiers (`critical`, `high`, `medium`, `low`) — plus a dedicated `risk` prop that resolves Mantine color and variant automatically.

> [!NOTE]
>
> **Status: Draft** — Badge ships in production and the token contract is defined. Full spec verification is still in progress. Avoid adding new intents or changing token bindings until the component reaches AI-Ready status.

## When to use

* Status indicator in a data table row (e.g. "Active", "Revoked", "Pending")
* Severity tier on a security finding (e.g. "Critical", "High")
* Count next to a navigation item
* Tag or label on a content item

## When not to use

* **Tappable or clickable labels.** Use Button.
* **Selectable tags.** Use a chip pattern (not yet specced in Clementine DS).

## Usage

```tsx theme={null}
import { Badge, type RiskLevel } from '@clementine-ds/ui';

// Semantic intent — pass Mantine color and variant directly
<Badge color="green" variant="light">Active</Badge>
<Badge color="red" variant="light">Error</Badge>
<Badge color="orange" variant="light">Warning</Badge>

// Neutral (default)
<Badge variant="light">Draft</Badge>

// Risk tier — use the risk prop; color and variant resolve automatically
<Badge risk="critical">Critical</Badge>
<Badge risk="high">High</Badge>
<Badge risk="medium">Medium</Badge>
<Badge risk="low">Low</Badge>

// Typed risk level from a data model
const level: RiskLevel = finding.severity;
<Badge risk={level}>{level}</Badge>
```

## Props

Badge extends `MantineBadgeProps` and adds one Clementine-specific prop. The package also exports `BadgeProps` and `RiskLevel` as named TypeScript types.

| Prop | Type | Default | Description |
| - | - | - | - |
| `risk` | `RiskLevel` (`'critical' \| 'high' \| 'medium' \| 'low'`) | — | Shorthand for risk-tier badges. When set, overrides `color` and `variant` using the built-in risk color map. |
| `color` | `string` | — | Mantine color key. Use when `risk` is not set. |
| `variant` | `string` | — | Mantine badge variant (`light`, `filled`, `outline`, etc.). |
| `children` | `ReactNode` | — | The label text content. |
| `...MantineBadgeProps` | — | — | All other Mantine Badge props are passed through. |

Import the types alongside the component:

```tsx theme={null}
import { Badge, type BadgeProps, type RiskLevel } from '@clementine-ds/ui';
```

The `risk` prop resolves internally as follows:

| Risk level | Resolved `color` | Resolved `variant` |
| - | - | - |
| `critical` | `red` | `filled` |
| `high` | `orange` | `light` |
| `medium` | `orange` | `light` |
| `low` | `green` | `light` |

## Intents and variants

Badge covers eight intent categories across two groups.

**Semantic feedback intents:**

| Intent | Suggested use |
| - | - |
| `neutral` | Default state, draft, unknown |
| `success` | Active, complete, healthy, passed |
| `error` | Failed, invalid, blocked |
| `warning` | Degraded, expiring, at risk |

**Risk tier intents:**

| Intent | Suggested use |
| - | - |
| `critical` | Immediately exploitable, requires urgent action |
| `high` | Significant exposure, escalate |
| `medium` | Moderate exposure, schedule remediation |
| `low` | Minimal exposure, track and review |

Use the `risk` prop for all four risk tiers — it ensures the correct color/variant pairing without you needing to manage them manually.

## Token contract

10 component-tier tokens. Tokens follow the 3-tier cascade: component → semantic → primitive.

> [!NOTE]
>
> Badge carries **Draft** status. The token bindings listed here are current and used in production, but full verification has not been completed. Dark-mode behavior and per-intent foreground tokens may be revised in a future update.

| Token | Resolves through | Light value |
| - | - | - |
| `badge.bg.neutral` | `surface.subtle` | `#f3f3f0` |
| `badge.bg.success` | `feedback.success-subtle` | `#f0fdf4` |
| `badge.bg.error` | `feedback.error-subtle` | `#fef2f2` |
| `badge.bg.warning` | `feedback.warning-subtle` | `#fff7ed` |
| `badge.bg.risk-critical` | `risk.critical-subtle` | `#fef2f2` |
| `badge.bg.risk-high` | `risk.high-subtle` | `#fff7ed` |
| `badge.bg.risk-medium` | `risk.medium-subtle` | `#ffedd5` |
| `badge.bg.risk-low` | `risk.low-subtle` | `#f0fdf4` |
| `badge.fg.default` | `text.primary` | `#1a1a18` |
| `badge.radius` | `radius.sm` | `4px` |

All background tokens resolve to subtle surface-level tints, keeping the badge visually lightweight. The foreground token (`badge.fg.default`) uses `text.primary` for all intents — a per-intent foreground token may be introduced once the reconciliation is complete.

## Accessibility

Badge is a presentational component. It carries no required ARIA attributes of its own.

| Concern | Guidance |
| - | - |
| Presentational role | Badge renders as a `<span>`. Screen readers announce its text content inline with the surrounding context. |
| Conveying critical status | If a Badge communicates state that is critical to the user's task (e.g., a "Critical" severity label on a vulnerability row), the **parent element** is responsible for surfacing that information to assistive technology — for example, via `aria-label` or `aria-describedby` on the row. |
| Color alone | Badge currently relies on background color to differentiate intents. Ensure the surrounding context (the label text itself, or the parent's accessible name) communicates intent without requiring color perception. |

> [!NOTE]
>
> The ARIA approach for badges that convey context-critical state is still under review. The `aria_correct` gate passes today because Badge is presentational, but additional guidance for parent-level ARIA announcements will be added when the spec advances to AI-Ready.

## Anatomy

| Part | Element | Purpose |
| - | - | - |
| `root` | `<span>` | Outer container. Owns padding, border-radius (`badge.radius`), and background fill (`badge.bg.*`). |
| `label` | Text node | The visible text content. Inherits foreground color from `badge.fg.default`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.