badge

Compact status label

Install

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.

Example props generated from this schema:

{
  "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):

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

Renderer HTML (entities decoded and wrapped for display):

<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

Example

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

Markdown: ` status: Stable `.

Package manifest

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

Sources