Status badges: text and colour, never colour alone

Short answer: a status badge always carries a written label and uses colour as confirmation. Map every state to a Badge variant and a fixed label, then check contrast at 4.5:1, because the text is small.

Four variants, five states

The map lives in a typed object, not in a chain of if blocks. A new state then fails to compile until it has its label, and the text cannot fall behind the colour.

import { Badge } from "@/components/ui/badge";

const tones = {
  active: { variant: "default", label: "Attivo" },
  pending: { variant: "secondary", label: "In attesa" },
  failed: { variant: "destructive", label: "Fallito" },
  draft: { variant: "outline", label: "Bozza" },
} as const;

export type State = keyof typeof tones;

export function StatusBadge({ state }: { state: State }) {
  const tone = tones[state];
  return {tone.label};
}

The colour of a fifth state

A yellow warning is not a Badge variant: it is a new token. It arrives through the three theme steps, light value, dark value and mapping in @theme inline, then a local variant in the component file. The procedure is in how to theme shadcn.

Shape, size and announcements

• Dot plus text for compact lists: the dot is decorative, so mark it aria-hidden.
• No icon-only badge: a green circle does not say “active” to someone who cannot see green.
• For a status that changes by itself, put role="status" on the container, not on the badge, and do not announce on every render.

Source: WCAG 2.2 criterion 1.4.1 forbids carrying information in colour alone, and criterion 1.4.3 asks for 4.5:1 on normal-size text, which is the size of a badge; the shadcn/ui badge.tsx component ships under the MIT licence.

A named limitation

The destructive variant is meant for actions, not states: on a single “Failed” badge it works, but across a table of ten failed rows it becomes noise and loses the signal. A second limit: a badge is not a live region, so a state that changes after a fetch is never announced by a screen reader until you add role="status" to the right container.

Where to continue

In the catalogue you find the shadcn library, a badge block with preview and the dashboard category blocks. The method for measuring colour pairs is in UI palettes and measured contrast, the tokens in how to theme shadcn; the comparison of ready-made themes is free versus premium shadcn themes. For a badge inside a long table read the best React table libraries; for status in words rather than colour, an accordion for FAQs.