---
type: "TechArticle"
softwareVersion: "1.0.0"
url: "https://registry.docsloth.dev/components/badge.html"
markdown: "https://registry.docsloth.dev/docs/badge.md"
component: "badge"
section: "pure"
trust_class: "pure"
implementation_status: "implemented_native"
renderer: "native block"
install: "docsloth component add @docsloth/badge@1.0.0"
spec: "packages/contracts/component-specs/badge.md"
props_schema: "packages/contracts/component-props/badge.schema.json"
---

> Index: [Agent index](https://registry.docsloth.dev/llms.txt)

# badge

Compact status label

| Field | Value |
| --- | --- |
| Trust class | pure |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | text |
| Key prop (protocol fixture) | no protocol fixture published |
| Tools | none |
| Package version | 1.0.0 |
| Package digest | sha256:861bab9e5ab9cd4fcd541c879097947bc594509657e038e1129ae02381954717 |

## Install

```sh
docsloth component add @docsloth/badge@1.0.0
```

Live package: sha256:861bab9e5ab9cd4fcd541c879097947bc594509657e038e1129ae02381954717 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

## Props

The prop schema is normative in `packages/contracts/component-props/badge.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `text` | string \| number | no |  |
| `label` | string \| number | no | Alias for text. |
| `tone` | "info" \| "success" \| "warning" \| "danger" \| "neutral" | no |  |
| `prefix` | string | no | maxLength: 40 |

Example props generated from this schema:

```json
{
  "text": "Stable",
  "label": "Stable",
  "tone": "info",
  "prefix": "status"
}
```

This schema requires no props beyond the component envelope.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "badge",
  "props": {
    "text": "Stable",
    "tone": "success",
    "prefix": "status"
  }
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<span class="ds-badge" data-component="badge" data-tone="success">
<span class="ds-badge-prefix">status:</span> Stable</span>
```

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

## Specification

Generated from `packages/contracts/component-specs/badge.md`.

### Contract

Packaged: this block ships as `@docsloth/badge@1.0.0` — an installable component package (kind `block`, capability `render.html`, Apache-2.0) whose production props schema is `packages/contracts/component-props/badge.schema.json` and whose catalog entry is in `packages/contracts/component-catalog.json`. No protocol manifest fixture is published (`manifest_fixture: null`): the fixture models a packaged protocol runtime this block does not have.

### Intended behavior

Inline status pill: a `<span class="ds-badge">` carrying a tone and an optional textual prefix. Markdown renders the same message as inline code with the prefix inside it (`` `status: Stable` ``), so state survives copy/paste, diffs and agent extraction instead of relying on color alone. JSON keeps the raw props for machine consumers.

### Failure and fallback

Missing/empty `text` (or a non-string, non-finite-number value) degrades to the labelled fallback block. An unknown `tone` degrades to `info` without losing the message, and a non-string `prefix` falls back to the default `status` prefix. No prop shape throws.

### Required acceptance cases

Assert the tone whitelist (`info`, `success`, `warning`, `danger`, `neutral`), that prefix and text appear in both HTML and Markdown, that no live-region/`role="status"` semantics are claimed, and that HTML/Markdown visible text matches. Also test missing text, an unknown tone, unknown extra props, mobile 360px, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

### Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

### Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

### Native renderer block

Block type: `badge`. Renderer: `packages/renderer/src/index.ts` (native, no permission surface).

#### Native block props

| prop | type | required | behaviour |
| --- | --- | --- | --- |
| `text` | string \| number | yes | Badge message; `label` is accepted as an alias. |
| `tone` | `info` \| `success` \| `warning` \| `danger` \| `neutral` | no | Visual tone (default `info`); unknown values degrade to `info`. |
| `prefix` | string | no | Textual prefix before the message (default `status`); an empty string omits it. |

#### Example

```json
{ "type": "badge", "props": { "text": "Stable", "tone": "success", "prefix": "status" } }
```

Markdown: `` `status: Stable` ``.

## Package manifest

No protocol fixture is published for this renderer-native block.

| Field | Value |
| --- | --- |
| Fixture | none published |

## Sources

| Source | Path |
| --- | --- |
| Component page | https://registry.docsloth.dev/components/badge.html |
| Markdown twin | https://registry.docsloth.dev/docs/badge.md |
| LLM index | https://registry.docsloth.dev/llms.txt |
| Specification | packages/contracts/component-specs/badge.md |
| Prop schema | packages/contracts/component-props/badge.schema.json |
| Catalog | packages/contracts/component-catalog.json |