Badge

Visual Hierarchy

Use variant="default" for primary emphasis (active states, highlights), variant="secondary" for neutral tags and categories, variant="outline" for subtle labels, and variant="destructive" for errors, warnings, and critical counts. Avoid mixing too many badge variants in a single row.

Spacing & Layout

When grouping badges, use gap-2 for tight layouts (inline tags) or gap-4 for standard spacing. Badges are inline-flex and shrink-0 by default, so they will not wrap text or collapse in flex containers. Use flex-wrap on the parent to allow wrapping.

Responsive Behavior

Badges have a fixed text-xs size and compact padding, making them suitable for all screen sizes. On mobile, ensure badge groups use flex-wrap to prevent horizontal overflow. Counter badges use min-w-5 for consistent circular sizing even with single digits.

Color & Contrast

All badge variants meet WCAG 2.1 AA contrast requirements. The default variant uses bg-primary with text-primary-foreground for maximum contrast. When using custom colors via className, verify contrast ratios manually. The outline variant relies on text-foreground on a transparent background for a subtle appearance.

Keyboard Navigation

• Static badges (span elements) are not focusable by default, which is correct for decorative labels
• When using asChild with links, Tab moves focus to the badge link
• Enter activates link badges (standard anchor behavior)
• Focus ring uses focus-visible:ring-[3px] for clear visibility

Screen Reader Support

• Badges render as <span> elements and are read inline with surrounding text
• Icon-only badges require aria-label for screen reader users
• For counter badges that update dynamically, add role="status" and aria-live="polite"
• Link badges announce their text content and role automatically via the anchor element

Focus Management

Visible focus ring with 3px width using focus-visible:ring-[3px]. Focus states use focus-visible:border-ring and focus-visible:ring-ring/50 for consistent ring styling. Destructive badges use a red ring via focus-visible:ring-destructive/20.

Color Independence

Do not rely solely on color to convey meaning. Pair badge colors with descriptive text or icons (e.g., a check icon with "Complete" rather than a green badge alone). This ensures users with color vision deficiencies can interpret badge meaning.

ARIA Attributes

{/* Standard badge */}
<Badge>Active</Badge>

{/* Icon-only badge - requires aria-label */}
<Badge aria-label="3 notifications">
  <BellIcon className="size-3" />
</Badge>

{/* Status badge with role for dynamic updates */}
<Badge role="status" aria-live="polite">
  {unreadCount} new messages
</Badge>

{/* Badge used as a link */}
<Badge asChild>
  <a href="/notifications" aria-label="View all notifications">
    Notifications
  </a>
</Badge>