Badge · Operant docs

Badge renders a compact status pill (.ods-badge). Per AGENTS.md #4 — "a colored state MUST also carry text or an icon" — a badge's color is never the only signal; the label text does the actual communicating, the color reinforces it.

Installation

HTML — already included if you loaded the 3 stylesheets. See the Installation guide.

React

npm install @operant/ui

@operant/ui is currently a monorepo workspace package, not yet published to the public npm registry.

Usage

HTML

<span class="ods-badge">Escalated</span>

React

import { Badge } from "@operant/ui";

export default function Example() {
  return <Badge>Escalated</Badge>;
}

Examples

Neutral (default)

<span class="ods-badge">Escalated</span>

<Badge>Escalated</Badge>

Outcome variants

success, warning, danger, and info map to the status token families in AGENTS.md #4 — use them for outcomes, not decoration.

<span class="ods-badge -success">Resolved</span>
<span class="ods-badge -warning">Needs review</span>
<span class="ods-badge -danger">Failed</span>
<span class="ods-badge -info">v2.3</span>

<Badge variant="success">Resolved</Badge>
<Badge variant="warning">Needs review</Badge>
<Badge variant="danger">Failed</Badge>
<Badge variant="info">v2.3</Badge>

Agent variant

agent uses --color-agent-active — reserve it for AI-identity/activity labels (AGENTS.md #4: "AI identity & activity"), not for generic info.

<span class="ods-badge -agent">AI generated</span>

<Badge variant="agent">AI generated</Badge>

Solid

solid drops the hairline border (border: 0) for a bolder pill — combine with any variant.

<span class="ods-badge -danger -solid">Blocked</span>

<Badge variant="danger" solid>
  Blocked
</Badge>

API Reference

`<Badge>`

Renders a <span class="ods-badge">.

Prop	Type	Default	Description
`variant`	`"neutral" \| "success" \| "warning" \| "danger" \| "info" \| "agent"`	`"neutral"`	Selects the color family. `neutral` adds no modifier class.
`solid`	`boolean`	`false`	Adds `-solid`, removing the hairline border.
`className`	`string`	—	Additional classes merged onto the badge.
`children`	`ReactNode`	—	Label content.

All other native <span> attributes (id, title, aria-*, data-*, etc.) are forwarded to the element.

HTML-side modifiers: .ods-badge (base) + one of -success / -warning / -danger / -info / -agent, optionally combined with -solid.

Accessibility

A badge is a <span>, not an interactive element — it carries no implicit role and is not part of the tab order. Don't use it as a button or link substitute.
Color is never the only signal: every variant is defined by a text label, and the badge's background/text/border colors all derive from the same semantic token pair (e.g. --color-danger + --color-danger-subtle + --color-danger-border), so contrast holds in both themes.
If a badge communicates an urgent or changing status (e.g. a live run's outcome flipping to -danger), wrap it in a region with aria-live/role="status" at the call site — the badge itself doesn't announce changes.