Site and editorial

Badge

<forma-badge>

Compact labels and metadata; status badges carry meaning in text with a redundant colored edge.

Authoring tag
<forma-badge>
Behavior owner
Site content
Canonical source
patterns/badge.html

Purpose

Badges are small mono-face labels for metadata on public pages: language, version, runtime, release status or topic. A badge is a span (or an a when it links somewhere) inside an unstyled ul.forma-badge-list, which wraps. data-forma-status adds a thicker inline-start edge in a status color; the badge text always states the status, so the edge is a redundant cue. The brand-neutral defaults make every status edge the primary text color; a theme or brand may give statuses distinct hues.

Use when

  • Showing release status and version facts in a product hero.
  • Listing technologies, standards or topics that describe a product or article.
  • Linking a small set of related topics or a changelog from a page.

Avoid when

  • Showing record or workflow state in an application: use Status lozenge.
  • A status needs a message or an action: use Alert or a Callout.
  • The label is a main action: use a Button.

Behavior to know

  • Text is the primary cue; the status edge only repeats it. Status glyphs do not exist yet (GAP-MKT-08).
  • Badges inside a list wrap onto new lines; the list is a native ul, so the count is announced.
  • Linked badges have no underline; a stronger border on hover and the shell's focus ring mark them as interactive.

Basic example

The smallest correct markup: the canonical pattern from patterns/badge.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal badge

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Minimal badge Raw HTML for HTML · Minimal badge
<forma-badge class="forma-component-tag">
<div class="forma-site">
  <ul class="forma-badge-list" aria-label="Product facts">
    <li><span class="forma-badge">F#</span></li>
    <li><span class="forma-badge">Zero runtime</span></li>
    <li><span class="forma-badge" data-forma-status="success">Stable</span></li>
    <li><span class="forma-badge" data-forma-status="warning">Preview</span></li>
    <li><a class="forma-badge" href="#changelog">Changelog</a></li>
  </ul>
</div>
</forma-badge>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Release status in a hero

A product's release facts: a success status plus plain metadata badges, next to the hero actions.

  • Stable
  • Version 1.4.0
  • .NET 8
  • MIT licence
HTML · Release status in a hero Raw HTML for HTML · Release status in a hero
<forma-badge class="forma-component-tag">
  <div class="forma-site">
    <ul class="forma-badge-list" aria-label="Release facts">
      <li><span class="forma-badge" data-forma-status="success">Stable</span></li>
      <li><span class="forma-badge">Version 1.4.0</span></li>
      <li><span class="forma-badge">.NET 8</span></li>
      <li><span class="forma-badge">MIT licence</span></li>
    </ul>
  </div>
</forma-badge>

Click or tap the code once to select all of it, then copy.

Scenario

Lifecycle statuses

All four status values on a component inventory. Each badge's text states the status; the edge color repeats it and depends on the theme.

  • Stable: Site header
  • New: Callout
  • Preview: Media hero
  • Deprecated: Landing layout
HTML · Lifecycle statuses Raw HTML for HTML · Lifecycle statuses
<forma-badge class="forma-component-tag">
  <div class="forma-site">
    <ul class="forma-badge-list" aria-label="Pattern lifecycle">
      <li><span class="forma-badge" data-forma-status="success">Stable: Site header</span></li>
      <li><span class="forma-badge" data-forma-status="info">New: Callout</span></li>
      <li><span class="forma-badge" data-forma-status="warning">Preview: Media hero</span></li>
      <li><span class="forma-badge" data-forma-status="danger">Deprecated: Landing layout</span></li>
    </ul>
  </div>
</forma-badge>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelul.forma-badge-liststring—Names the list ("Release facts", "Topics").
hrefa.forma-badgeURL—Makes a badge a link. Use an a, never a clickable span.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-badgeBlock class—The badge: bordered mono label on the surrounding tone. On an a it gets a 24px minimum height and a stronger border on hover.
[data-forma-status]Attribute hook"danger", "info", "success", "warning"success, warning, danger or info. Thickens the inline-start edge and colors it with --forma-color-status-*. The text must state the same status.
.forma-badge-listBlock class—Unstyled ul that wraps its badges with a small gap and vertical margin.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between linked badges; span badges are not focusable.
EnterFollows a linked badge (native link behavior).

States

Badge states
StateHow it is expressedPresentation
Plainspan.forma-badgeNeutral bordered label.
Statusdata-forma-statusAccent-width inline-start edge in the status color; text states the status.
Link hovera.forma-badge:hoverThe border strengthens to the tone's strong rule.
Focus:focus-visible on a.forma-badgeThe shell's outline and halo.

Accessibility

Forma provides

  • Never relies on the status color: the edge is redundant with the badge text, and defaults are hue-free.
  • Draws a solid system-color border on badges in forced colors.
  • Keeps linked badges at a 24px minimum height with visible focus.

Your application supplies

  • Write the status in the badge text ("Stable", "Deprecated"), not only in data-forma-status.
  • Put badges in a labelled list.
  • Use a for badges that navigate; do not make spans interactive with script.

Responsive behavior

  • The list is a wrapping flex row; badges wrap to new lines as space shrinks.
  • Badges size to their text; there are no breakpoints.

Motion

  • No animation: hover changes the border color of linked badges instantly.

Usage guidance

Do

  • Keep badges to one or two words of metadata.
  • Use status badges sparingly, usually one per product or item.

Avoid

  • Using badges as buttons or primary navigation.
  • Encoding meaning only in the edge color.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.