# Badge

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/badge
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=240-2

```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeDefault = () => <Badge label="Filed" tone="success" />;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/badge`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required; conveys meaning independently of color |
| `tone` | `BadgeTone` | optional | neutral |
| `size` | `"sm" \| "md"` | optional | sm: 20 high; md: 24 high |
| `indicatorConfig` | `{ type: "dot"; } \| { type: "status"; status: StatusKind; }` | optional | Optional; dot and status icon are mutually exclusive |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### indicatorConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"dot"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"status"` | Yes |  |
| `status` | `"failed" \| "completed" \| "to-do" \| "scheduled" \| "in-progress" \| "in-review" \| "canceled" \| "blocking" \| "blocked-by" \| "needs-attention"` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported.

## Usage rules [#usage-rules]

Badges never remove a value, navigate, or trigger actions. Use Tag for user-chosen values and Button/link for interactions. Static badges do not create live regions.

The application maps domain statuses to label, tone, and optional existing lifecycle icon. Pathfinder does not infer status from English text or depend on filing enums. Keep labels to one or two words in sentence case. Small badges use a 12px status icon, medium uses the existing 16px artwork scaled to its authored 14px slot. Text wraps for unexpected long translations without clipping the meaning.

## Examples [#examples]

### Tones [#tones]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeTones = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
    <Badge label="Draft" />
    <Badge label="In review" tone="info" />
    <Badge label="Filed" tone="success" />
    <Badge label="Due soon" tone="warning" />
    <Badge label="Overdue" tone="error" />
  </div>
);
```


### Sizes [#sizes]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeSizes = () => (
  <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
    <Badge label="Filed" tone="success" size="sm" />
    <Badge label="Filed" tone="success" size="md" />
  </div>
);
```


### Indicators [#indicators]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeIndicators = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
    <Badge label="Due soon" tone="warning" indicatorConfig={{ type: 'dot' }} />
    <Badge
      label="Filed"
      tone="success"
      indicatorConfig={{ type: 'status', status: 'completed' }}
    />
    <Badge
      label="In progress"
      tone="info"
      size="md"
      indicatorConfig={{ type: 'status', status: 'in-progress' }}
    />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Badge [#badge]

Source: [240:123](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=240-123), anatomy 242:311, guidance 242:344.

- `BADGE-01` — Source: system-reported status, read-only. User-picked values belong to Tag; actions belong to Button/link. No removal, click, loading, disabled, or automatic live-region behavior.
- `BADGE-02` — Source: label conveys meaning without color; neutral/info/success/warning/error; optional 6px dot or lifecycle icon, never both. sm 20/radius4/padding6/Label12 Strong/icon12; md 24/radius6/padding8/Label13 Strong/icon14; gap6, no border. Scale existing 16 artwork for the 14 slot, not a duplicate SVG download.
- `BADGE-03` — Source/Pathfinder: one domain mapping owned by the application. One or two words, sentence case. Neutral pearl-200/900; semantic 100 fills and 800/900 copy. Unexpected long labels wrap without clipping meaning.