Badge
A React source recipe with a span element and the public TIS Badge classes and tokens.
Design
Functional preview
Running with the React source recipe distributed through shadcn and based on Base UI.
Loading functional preview…
Open the React · shadcn/Base UI playground
Anatomy
Active
1
2
1 Container (
2 Text — label content, 1-2 words.
.ds-badge) — pill-shaped span with background color and border-radius.2 Text — label content, 1-2 words.
Solid Variants
Brand
Success
Warning
Error
Info
Neutral
Subtle Variants
Brand
Success
Warning
Error
Info
Neutral
Token mapping
Tokens shown for the brand variant. Other color variants follow the same pattern with their respective color groups.
| Property | Token | CSS variable |
|---|---|---|
| bg (brand solid) | semantic.brand.background.default | --ds-brand-background-default |
| text (brand solid) | semantic.brand.content-default | --ds-brand-content-default |
| bg (brand subtle) | semantic.toned.background.default | --ds-toned-background-default |
| text (brand subtle) | semantic.toned.content-default | --ds-toned-content-default |
| padding-x | component.badge.padding-x.default | --ds-badge-padding-x-default |
| padding-y | component.badge.padding-y.default | --ds-badge-padding-y-default |
| gap | component.badge.gap.default | --ds-badge-gap-default |
| border-radius | component.badge.radius.default | --ds-badge-radius-default |
| border-width | component.badge.border-width.default | --ds-badge-border-width-default |
| label font-size | component.badge.label.font-size.default | --ds-badge-label-font-size-default |
| label line-height | component.badge.label.line-height.default | --ds-badge-label-line-height-default |
| label font-weight | component.badge.label.font-weight.default | --ds-badge-label-font-weight-default |
Usage
When to use
Use badges when
Labeling, categorizing, or showing status: counts, tags, active/inactive states, severity levels.
Don't use badges when
The content needs a description or action (use Alert), the element should be large and interactive (use Button), or you need a floating count indicator (notification dot — future).
Best practices
Active
Beta
Faça
Keep labels to 1-2 words. "New", "Beta", "Active".
This feature is currently in beta testing
Não faça
Use sentences in badges. They should be short labels, not descriptions.
Approved
Rejected
Faça
Use semantic color matching meaning: success for positive, error for negative.
Approved
Rejected
Não faça
Use color decoratively or in contradiction with the label meaning.
Content guidelines
| Rule | Example |
|---|---|
| 1-2 words, sentence case | "New", "Beta", "Active" |
| Status: consistent vocabulary | "Active" / "Inactive" — not "On" / "Off" |
| Counts: use numbers, not words | "3" — not "Three" |
Related
React composition
import { Badge } from "@/components/ui/badge"
<Badge tone="success" variant="subtle">
Aprovado
</Badge>Implementation
- Status
- Beta
- Distribution
- Source via shadcn
Installation
Configure the namespace once in the React integration guide.
npx shadcn@latest add @tis/badgepnpm dlx shadcn@latest add @tis/badgeyarn dlx shadcn@latest add @tis/badgebunx --bun shadcn@latest add @tis/badgePublic contract
- Registry item
@tis/badge- Provider
- React composition
- Distribution
- Source copied into the application
- Status
- Beta
Accessibility
Keyboard interaction
Not interactive
Badges are static display elements and do not receive keyboard focus or interaction.
Accessibility
| WCAG criterion | Requirement | Status |
|---|---|---|
| 1.4.1 Use of Color (A) | Text conveys meaning, not color alone | ✓ |
| 1.4.3 Contrast (AA) | All color combinations meet 4.5:1 contrast ratio | ✓ |
Accessibility note
Badges are visual indicators. Always ensure the badge text itself conveys the meaning — do not rely on color alone. If a badge communicates important status, make sure it is part of the accessible text content, not just an icon or color indicator.
Output responsibility
Keep the badge non-interactive and ensure its short text conveys meaning without relying on color alone.
Validation evidence
Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.