ToneBadge

The only way to show a status color.

Preview

Published

src/examples/tone-badge/example.astro

---
import { ToneBadge } from "@/presentation/components/site/tone-badge";
---

<ToneBadge tone="success" dot>Published</ToneBadge>

Add to your site

npx docs-sitekit add tone-badge

It writes these files, and keeps a file you changed:

src/presentation/components/site/tone-badge.tsx

It requires these entries of the registry, which add restores first:

Props

Built from the TypeScript types and the TSDoc comments of the component, so they cannot drift from the code.

Props of ToneBadge
Key	Type	Default	Allowed values	Description
`tone`	Tone	"neutral"	"neutral", "brand", "success", "warn"	The color of the badge.
`dot`	boolean	false	true, false	Show a dot before the text. The dot is hidden from assistive technology.
`className`	string	-	-	Classes added to the badge.
`children`	string \| number \| bigint \| boolean \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| Iterable<React.ReactNode> \| React.ReactPortal \| Promise<AwaitedReactNode>	required	-	The text of the badge. It always says the status in words, so the color is not the only cue.

Variants and states

Tones

The four tones. A status color is chosen here and nowhere else.

neutralbrandsuccesswarn

src/examples/tone-badge/tones.astro

---
import { ToneBadge } from "@/presentation/components/site/tone-badge";
---

<div class="flex flex-wrap gap-2">
  <ToneBadge>neutral</ToneBadge>
  <ToneBadge tone="brand">brand</ToneBadge>
  <ToneBadge tone="success">success</ToneBadge>
  <ToneBadge tone="warn">warn</ToneBadge>
</div>

With a dot

A dot before the text, hidden from assistive technology.

neutralbrandsuccesswarn

src/examples/tone-badge/dot.astro

---
import { ToneBadge } from "@/presentation/components/site/tone-badge";
---

<div class="flex flex-wrap gap-2">
  <ToneBadge dot>neutral</ToneBadge>
  <ToneBadge tone="brand" dot>brand</ToneBadge>
  <ToneBadge tone="success" dot>success</ToneBadge>
  <ToneBadge tone="warn" dot>warn</ToneBadge>
</div>

About

A small pill with a text and one of four tones. A status color is chosen here and nowhere else, and a test fails when another component names one. Callout is the other place that has a tone of its own, for its edge and label.

Accessibility

The tone is never the only cue: the badge always holds a text that says the status in words.
The dot is decorative, so it is aria-hidden.
The badge is not interactive and takes no focus.
Every tone reaches WCAG AA on the page and on a surface in both themes, checked on the tokens and measured in the browser on every route.

Source

tone-badge.tsx

Edit this page

Last updated 5 November 2026