Badge — Design System

Examples

Semantic states

Readable words carry the meaning alongside semantic color roles.

DraftReviewOperationalNeeds reviewFailedQueued

Badge examples for neutral and semantic states

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

export function Example() {
  return <Badge variant="success">Operational</Badge>;
}

Color palettes

Use a supported hue for neutral Badge treatments without reaching for raw color values.

RedOrangeAmberYellowLimeGreenTealCyanBlueIndigoVioletPink

Badge color palette comparison

import { Badge } from "@phuctech/ui/components/badge";
import {
  colorPaletteLabels,
  colorPalettes,
  type ColorPalette,
} from "@phuctech/ui/color-palette";

const palettes = colorPalettes.filter((palette): palette is Exclude<ColorPalette, "neutral"> => palette !== "neutral");

export function Example() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      {palettes.map((palette) => (
        <Badge key={palette} colorPalette={palette}>
          {colorPaletteLabels[palette]}
        </Badge>
      ))}
    </div>
  );
}

Density

Small, default, and large labels align with nearby content.

SmallDefaultLarge

Badge size comparison

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

export function Example() {
  return <Badge variant="success">Operational</Badge>;
}

Status with a clear label

Never use a color-only dot when a state affects understanding.

Operational

Badge status with readable text

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

export function Example() {
  return <Badge variant="success">Operational</Badge>;
}

In a list or Card

Badge adds metadata without turning the surrounding surface into a control; use the playground to compare hue and treatment.

Atlas onboardingActive

A status label in a compact list row.

Badge inside a list row

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

export function Example() {
  return <Badge variant="default" colorPalette="violet">Active</Badge>;
}

When to use

Use Badge for a short label such as a lifecycle state, role, or queue. Use body text or an Alert when people need an explanation, next step, or announcement.

Usage

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

export function Example() {
  return <Badge variant="success">Operational</Badge>;
}

Variants

Badge variants and intended meaning
Variant	Use for
`default`	Primary classification or neutral emphasis.
`secondary`	Quiet metadata on a secondary surface.
`outline`	Low-emphasis labels where a boundary is useful.
`success`, `warning`, `danger`, `info`	Semantic states; always pair color with a readable word.
`colorPalette`	Explicit hue for `default`, `secondary`, and `outline` treatments. Semantic states keep their fixed meaning.

API

Component API
Prop	Type	Default	Description	Constraints
`variant`	`"default" \| "secondary" \| "outline" \| "success" \| "warning" \| "danger" \| "info"`	`"default"`	Visual and semantic emphasis.	Do not rely on color as the only state signal.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Badge height and text density.	Keep labels short enough to scan.
`colorPalette`	`"neutral" \| "red" \| "orange" \| "amber" \| "yellow" \| "lime" \| "green" \| "teal" \| "cyan" \| "blue" \| "indigo" \| "violet" \| "pink"`	`—`	Hue for default, secondary, and outline treatments.	Semantic variants retain their success, warning, danger, or info role.
`children`	`ReactNode`	`required`	The readable label.	Use a concise word or phrase; do not leave it empty.

Tokens

Component tokens
Token	Role	Effective value	Usage
`--color--bg / --color--text`	Semantic state	`success / warning / danger / info`	Background and text roles keep status readable in both themes.
`--radius-*`	Pill geometry	`full radius`	The label reads as metadata rather than a control.
`--size-control-*`	Label height	`sm / md / lg`	Keeps inline labels aligned with nearby controls.

Accessibility

Write the state in the label: “Operational” is better than a green dot alone.
Use sufficient contrast for the label and boundary in both themes.
Do not make Badge interactive; use Button or a link when it needs activation.

Do and don’t

Keep the label short, readable, and redundant with the color meaning.

Don’t

Put paragraphs, controls, or the only error explanation inside a Badge.

Card provides the surface where a status label often belongs.
Colors documents semantic status roles and contrast checks.