Badge

Components/Feedback and status

ImplementationHTML/CSS/JSArk/Zag — plannedReact · shadcn/Base UIAngular

Identifies a status, category, or attribute with a short, semantically explicit label.

DesignUsageImplementationAccessibility

Documentation sectionDesignUsageImplementationAccessibility

Design

Functional preview

Running with stable DS HTML and CSS, without a component JavaScript runtime.

Loading functional preview…

Open the HTML/CSS/JS playground

Anatomy

Active 1 2

1 Container (.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

Alert Button

Implementation

Status

Stable

Distribution

npm package

Installation

npm

npm install ds-tis

pnpm

pnpm add ds-tis

yarn

yarn add ds-tis

bun

bun add ds-tis

Imports

import 'ds-tis/css'

Markup

<span class="ds-badge ds-badge--success ds-badge--subtle">
  Aprovado
</span>

No Badge runtime

The component uses a native HTML element. JavaScript remains the application responsibility; the DS provides anatomy, visual treatment, and states.

Web implementation contract

CSS classes

Class	Description
ds-badge	Base badge class
ds-badge--solid	Solid filled style
ds-badge--subtle	Subtle light background style
ds-badge--brand	Brand color variant
ds-badge--success	Success/green color variant
ds-badge--warning	Warning/yellow color variant
ds-badge--error	Error/red color variant
ds-badge--info	Info/blue color variant
ds-badge--neutral	Neutral/gray color variant

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

Preserve native element semantics, accessible names, keyboard behavior, and visible focus.

Validation evidence

Covered by the stable Storybook, public runtime tests when applicable, keyboard scenarios, responsive checks, and Axe.

Open the stable reference