Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): Badge records its shipped contract as current (#8263)

Cindy Zhang1eb6cce41955
diff --git a/packages/core/src/Badge/Badge.spec.md b/packages/core/src/Badge/Badge.spec.md
new file mode 100644
index 0000000000..99a8198a11
--- /dev/null
+++ b/packages/core/src/Badge/Badge.spec.md
@@ -0,0 +1,207 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Badge
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-24
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Badge/Badge.test.tsx,
+ packages/core/src/serverSafeComponents.test.ts,
+ packages/core/src/theme/themingTargets.test.ts,
+ packages/core/src/theme/extensibleAxes.test.ts,
+ apps/storybook/stories/Badge.stories.tsx,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# Badge component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A read-only, one-line label with a required `label`, an optional leading `icon`, and a theme-extensible `variant` (default `neutral`). |
+| Behavior | The badge never wraps; a label wider than the available space is cut with an ellipsis inside the badge, and a string or number label is also carried in the root's `title`. |
+| End-user impact | Readers see a compact status or category label that stays inside its container; assistive technology reads the full label text. |
+| Builder impact | None; the record describes shipped behavior. |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
+| Review checks | Reject a badge that wraps or escapes its container, a `title` derived from a rich label, a badge that adds its own role, tab stop, or live region, or a variant that is not reflected on `badge`. |
+| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV2,INV6,INV14`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Badge marks one status or category with a short, non-interactive label. It owns
+the label's one-line geometry, its overflow treatment, and the closed set of
+built-in tones that a theme can extend.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+ or styling output changes
+- Controlled/uncontrolled behavior: not applicable; Badge holds no state
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Clipped label tail is pointer-only (AR4).** Keyboard and touch users cannot
+ reveal the clipped tail of a long label; only a pointer hover on the native
+ `title` shows it. Assistive technology still receives the full text from the
+ DOM.
+
+## Ownership boundary
+
+**Owns**
+
+- The badge root, its optional leading Icon slot, and the Label container.
+- One-line geometry, inline padding, radius, typography, and the ellipsis
+ overflow treatment.
+- The built-in `variant` tones and the reflection of `variant` on the `badge`
+ theming target.
+- Deriving the root `title` from a string or number label.
+
+**Does not own / non-goals**
+
+- Which status or category a product shows, its wording, and whether a badge is
+ appropriate — owned by the product callsite and consumer guidance in
+ `Badge.doc.mjs`.
+- The supplied icon's artwork, size, and accessibility exposure — owned by the
+ supplied node (`component:Icon` when an Icon is passed).
+- Tag-like and dot-only status presentations — owned by
+ `component:Token` and `component:StatusDot`.
+- Contrast of the color tokens each tone uses — owned by the active theme.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Tone (`variant`) | Semantic: `neutral`, `info`, `success`, `warning`, `error`; color: `blue`, `cyan`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow`; theme additions | Selects the badge fill and text color. | All badges | `neutral` | `component:Badge` | Stable | A theme-added value is reflected on `badge` and receives no component fill or color (FR6); TypeScript rejects unregistered values. |
+| Label | string, number, or rich node | The visible badge content. | Always rendered; required | Required | `component:Badge` | Stable | An empty string renders an empty label and no `title`. |
+| Icon | present; absent | Optional caller-supplied node shown before the label. | All badges | absent | `component:Badge` | Stable | Absent renders no icon and no placeholder. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1 | Badge renders one inline-flex `span` root, centered on both axes, with block size `--spacing-5`, no block padding, inline padding `--spacing-2`, `--radius-full` corners, inherited font family, `--text-supporting-size` and `--text-supporting-leading` type, and `--font-weight-medium` weight. | Current source |
+| FR2 | When `icon` is supplied it renders directly inside the root, before the Label container, separated by `--spacing-1`; the label always renders inside its own Label container. | Current source and tests |
+| FR3 | The badge is one line and never wraps. The root is capped at the inline size of its container and may shrink below its content size; a label that does not fit is clipped with a trailing ellipsis inside the Label container and does not escape the badge. | Current source and consumer docs |
+| FR4 | A non-empty string label or any number label sets the root `title` to the label text, whether or not the label is clipped. A rich-node or empty-string label sets no `title`. | Current source and tests |
+| FR5 | `variant` defaults to `neutral`. `neutral` paints `--color-neutral` with primary text; `info`, `success`, `warning`, and `error` paint the solid accent, success, warning, and error colors with their matching on-color text; each color variant paints its tinted background with its matching colored text. | Current source and consumer docs |
+| FR6 | The `badge` target carries the resolved `variant` for every value, including a value a theme adds through `BadgeVariantMap`. A theme-added value receives no component fill or text color, so it renders the FR1 geometry over a transparent background in the inherited text color until a theme paints it. | Current source and extensible-axis test |
+| FR7 | `ref` reaches the root `span`. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge in that order after the component styles. | Current source and tests |
+| FR8 | Badge uses no hooks, measurement, or client-only API, so it renders identically on the server and the client. | Current source and server-safety test |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change any visual property of `badge`,
+ including per-`variant` fill, text color, height, and radius, without changing
+ anatomy, the one-line rule, or the `title` rule.
+- **AV2 — Label content.** Label length and content may vary; clipping position
+ depends on the available inline size.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------- | ------------------------------------------------------------------------- | -------------------------------- |
+| Default | Neutral tone, one line, `title` equal to the string label. | Label text. |
+| With icon | Icon renders before the Label container on the inline-start side. | Icon artwork and size. |
+| Count | A number label renders as text and sets `title` to its string form. | Tone. |
+| Long label, narrow | The badge stays within its container and the label ends in an ellipsis. | Clip position. |
+| Rich label | The node renders inside the Label container and no `title` is set. | Node content. |
+| Theme-added variant | `data-variant` names the added value; no component fill or color applies. | Theme paint for the added value. |
+
+### Transformation and precedence order
+
+- **ORD1 — Root attributes.** Component class and `data-variant` → component
+ styles → `xstyle` → `className` → `style` → derived `title` → remaining
+ caller props.
+- **ORD2 — Content order.** Icon, then Label container, in logical inline
+ order.
+
+### Performance and resources
+
+- **PR1 — Static render.** Badge registers no listener, observer, timer, or
+ effect and performs no layout measurement.
+
+## Accessibility contract
+
+- **AR1 — Static text.** Badge adds no role, tab stop, or live region of its
+ own and exposes its label as ordinary text in reading order, so a changed
+ label is not announced. A caller `role` or `tabIndex` passes through (FR7).
+- **AR2 — Meaning in text.** Badge renders `label` as text, and tone color
+ supplements that text. An empty label renders a color-only badge with nothing
+ in the accessibility tree; supplying a meaningful label is the callsite's
+ responsibility.
+- **AR3 — Icon exposure is delegated.** Badge adds no name, role, or
+ `aria-hidden` to the supplied icon; its exposure is the supplied node's own
+ (an Icon without a label is decorative under `component:Icon`).
+- **AR4 — Full text stays in the DOM.** Clipping is visual only: the complete
+ label remains in the accessibility tree, and the FR4 `title` exposes it to
+ pointer hover. Implementation gap: keyboard and touch users have no way to
+ reveal a clipped tail.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Badge root | A compact one-line pill whose tone signals status or category. | Current source | Supporting | FR1, FR3, FR5, FR6 |
+| Icon | An optional leading glyph that helps identify the badge type. | Current source and docs | Supporting | FR2, AR3 |
+| Label | The text or number that carries the badge's meaning. | Current source and docs | Prominent | FR3, FR4, AR2, AR4 |
+
+Theming: the root is the single `badge` target and reflects `variant`. The Label
+container and the Icon slot add no targets: the label inherits `badge`, and a
+supplied icon keeps its own styling and inherits the badge text color.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+ rules; FR7 applies them to the root `span`.
+- `architecture:component-theming-surface` owns target qualification, state
+ reflection, and extensible-axis rules; FR6 records Badge's extensible
+ `variant` axis and its unthemed fallback.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR2, FR7 | `Badge.test.tsx` | Icon, ref, passthrough | Dropping the icon, the ref, or a passthrough prop fails DOM assertions. Gap: the icon-before-label order is untested. | `audit:Badge/behavior` |
+| AR1–AR3 | Source review | Default, with icon | Gap: no automated check fails if Badge adds its own role, tab stop, live region, or icon semantics. | `audit:Badge/a11y` |
+| FR5 | `Badge.test.tsx` `data-variant` assertions; `Badge.stories.tsx` variant fixtures in a browser | `success` and `purple` reflection; every tone rendered | A lost `data-variant` for those tones fails. Gap: no automated check covers the `neutral` default's reflection or any tone's paint; a paint change is visible only in the rendered fixtures. | `audit:Badge/theming` |
+| FR4, AR4 | `Badge.test.tsx` full-label suite | String, number, rich, and empty labels | Setting `title` from a rich or empty label, or dropping it for a string or number, fails. Gap: no check asserts that a clipped label stays whole in the accessibility tree. | `audit:Badge/a11y` |
+| FR1, FR3 | `Badge.stories.tsx` long-label fixture in a browser | Long labels in tight space | A label that wraps or escapes the badge is visible in the rendered fixture. | `audit:Badge/layout` |
+| FR6 | `extensibleAxes.test.ts`, `themingTargets.test.ts` | `BadgeVariantMap`, `badge` target | Removing `variant` from the target reflection or the doc's `visualProps` fails the structural checks. Gap: no test renders a theme-added value, so the unthemed fallback is verified by source review only. | `audit:Badge/theming` |
+| FR8, PR1 | `serverSafeComponents.test.ts` | Import graph | Adding a hook or a client-only import to Badge fails the server-safety invariant. | `audit:Badge/behavior` |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+- **OQ1 — How should the full text of a clipped label reach keyboard and touch
+ users?** (`human-design`) Options include a measured tooltip shown only when
+ the label is clipped, which makes Badge a client component and focusable
+ while clipped, or leaving recovery to the callsite.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.