Badge
Badges are small status indicators used to communicate state, category, or quantity. They are always pill-shaped, always soft-colored, and never use hard/saturated backgrounds.
Overview
Badges appear inline next to text, in table cells, and in card headers. The design language uses soft tinted backgrounds (10–15% opacity of the semantic color) paired with a dark-tinted text color from the same hue family. Never use a full-saturation background like #0E9F6E directly — always use the -bg token pair.
.badge-dot) adds a colored dot via CSS pseudo-element — no emoji needed.When to Use
- Indicating the status of a record (Active, Pending, Inactive)
- Categorizing by role, type, or classification
- Labeling items in tables, lists, and cards
- An action is needed — use a Button instead
- Displaying long text (>3 words) — use a callout
- Navigation or filtering — use tabs or a select
Anatomy
<span> element. display:inline-flex, align-items:center. Pill shape via border-radius:999px. Never a div or button..badge-dot class. CSS ::before pseudo-element. width/height:6px, border-radius:50%, background:currentColor.Variants
Sizes
Token Reference
| Class | Background | Text Color | Use For |
|---|---|---|---|
| .badge-success | #DEF7EC | #03543F | Active, approved, completed |
| .badge-warning | #FEF3C7 | #92400E | Pending, review, in progress |
| .badge-danger | #FDE2E2 | #9B1C1C | Inactive, rejected, error |
| .badge-info | #E1EFFE | #1E429F | Role: Admin, informational |
| .badge-purple | #F5F3FF | #5521B5 | Role: Director |
| .badge-neutral | #F1F5F9 | #64748B | Archived, no status |
| .badge-hot | #fef2f2 | #dc2626 | Lead: Hot prospect |
| .badge-warm | #fff7ed | #ea580c | Lead: Warm prospect |
| .badge-cold | #f0f9ff | #0284c7 | Lead: Cold prospect |
| .badge-deal | #f0fdf4 | #16a34a | Lead: Closed deal |
| .badge-lost | #f9fafb | #6b7280 | Lead: Lost deal |
States
Badges are static display elements — they have no interactive states. They do not respond to hover, focus, or click. If interaction is needed, use a Button component instead.
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| variant | string | required | — | Color theme. 'success'|'warning'|'danger'|'info'|'purple'|'amber'|'neutral'|'hot'|'warm'|'cold'|'deal'|'lost' |
| dot | boolean | optional | false | Adds colored dot via CSS ::before. Use for status badges. |
| size | string | optional | 'default' | 'sm' | 'default' | 'lg' |
| children | string | required | — | Label text. Plain text only. Max 3 words. |
Accessibility
| Requirement | Implementation |
|---|---|
| Screen reader | Badge text is read inline as part of its parent context. No additional ARIA needed for static badges. |
| Color alone | Never rely on color alone. Always include a text label. Dot indicators supplement but never replace the label. |
| Contrast | All badge color pairs meet WCAG AA minimum 4.5:1 contrast ratio. |
Composition
Best Practices
Content Rules
AI Implementation Guide
<span> elements, always inline-flex. Base class is .badge + one variant class. The dot is added via .badge-dot CSS ::before — never a DOM element. Do NOT use emoji. Never make badges interactive. Always use the soft bg+text paired token system.Related Components
Design Decisions
Changelog
- 13 variants across status, role, and lead temperature categories
- Dot indicator via CSS ::before pseudo-element
- 3 sizes: sm, default, lg
Behavior
Badges are purely presentational — no hover, focus, click, or animation states. Their value updates reactively when the underlying data changes. The UI re-renders with the new variant and label instantly. No entrance or exit animation is applied to badge changes. If a badge needs to be interactive (e.g. a removable tag), that is a separate component with button semantics.