Contents

Components

Badge

A small chip in the label voice that says what state something is in, with a tone from the fixed tone vocabulary.

host
Props
tone
import { Badge } from "@sideby/ui/badge";

<Badge mark>host</Badge>

When to use it

A badge labels the state of one thing: a member, a link, a caption track. It is not a button and it does not respond to a click. When a badge describes a member’s sync status, use Member status instead, which maps the seven statuses to their tones for you.

The text in the badge is what it means. The tone colours it, and the optional mark adds a second shape cue, but someone who cannot see the colour reads the same thing from the words.

Every tone

Tones, words only
host now playing loaded waiting on Leo no captions no subtitles found link failed
import { Badge } from "@sideby/ui/badge";

<Badge>host</Badge>
<Badge tone="active">now playing</Badge>
<Badge tone="complete">loaded</Badge>
<Badge tone="in-flight">waiting on Leo</Badge>
<Badge tone="quiet">no captions</Badge>
<Badge tone="missing">no subtitles found</Badge>
<Badge tone="destructive">link failed</Badge>

Tones with the mark
host now playing loaded waiting on Leo no captions no subtitles found link failed
import { Badge } from "@sideby/ui/badge";

<Badge mark>host</Badge>
<Badge tone="in-flight" mark>waiting on Leo</Badge>
<Badge tone="quiet" mark>no captions</Badge>

The mark is a small square before the words. The in-flight mark pulses (only when the reader allows motion), the quiet mark is hollow and dashed, and the active and complete mark uses the in-sync colour, which holds 3:1 against the page in both themes.

Picking a tone

The tones are a fixed set. Never invent a new hue for a status.

ToneMeansExample
neutralA plain fact with no statehost
activeThe current or selected thingnow playing
completeFinished or matched; looks the same as activeloaded
in-flightIn progress, or waiting on a personwaiting on Leo
quietAn absence. Nothing is wrongno captions
missingExpected but not there: a gap, not damageno subtitles found
destructiveA real failurelink failed
  • An absence is quiet, never destructive. A video without captions is not an error.
  • A gap is missing. Something we looked for and did not find.
  • Waiting on a person is in-flight. Someone has to tap, load or come back.
  • Destructive means a real failure that someone needs to act on. Keep it rare, so it still means something.

With an icon

An icon sits before the words, sized to the label text with the sideby 2.25 stroke. It is decorative: mark it aria-hidden and let the words carry the meaning.

Icon
host no captions link failed
import { Badge } from "@sideby/ui/badge";
import Crown from "@lucide/svelte/icons/crown";

<Badge><Crown aria-hidden="true" />host</Badge>

Accessibility

  • The words are always rendered. Colour, the dashed outline and the pulse are extra cues, never the only one (WCAG 1.4.1).
  • The source text stays lowercase and CSS uppercases it, so a screen reader says “link failed”, not letters.
  • The mark is aria-hidden. It adds nothing a screen reader needs.
  • A badge is not a live region. If its text changes while someone is on the page and they need to know, announce the change separately, as Member status does.
  • The pulse stops under reduced motion. The mark stays, still.

Copy

Two or three lowercase words that name the state: loaded, no captions, waiting on Leo. Name what is happening, not how it should feel. Skip punctuation and status codes.