Actions & feedback

Badge

A compact, non-interactive label for status, category, or short metadata.

BadgeBadgePropsBadgeVariant

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Ready

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { Badge } from '@ai-created/ui';

export function Example() {
  return (
    <Badge>
      {"Ready"}
    </Badge>
  );
}

Import

tsx

import { Badge } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Container

Required

Inline pill that carries the semantic tone.

span

Label

Required

Short status or category text.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Feedback/Badge

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish as a component set with semantic tone variants and one text property.

Auto layout

Direction: horizontal
Gap: 0px
Padding: 2px 8px
Alignment: Center in both axes
Wrap: No wrap

Resizing

Width: hug
Height: hug
Minimum width: Content width
Maximum width: Recommended 160px
Minimum height: 18px
Maximum height: One line
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Tone	variant	default	variant	default, muted, success, warning, error, info
LabelRequired	text	Ready	children	No additional constraint

Nested assets and slots

Label

slot / required

Status or classification text.

children

Content limits

Label

One to three words, maximum 24 characters

Overflow: Do not truncate; replace with shorter vocabulary.

A badge is compact metadata, not explanatory content.

Localization and RTL

Translatable: Label

Text follows the document direction; pill geometry is symmetric.
Test status terminology in the longest supported locale.
Verify color-independent meaning after translation.

Responsive behavior

Always intrinsic.

No internal breakpoint

Do not force fill width.
Allow the parent row to wrap the whole badge as a unit.

Authoring limits

Do not add interactive variants to the design asset.
Badge remains a span and must not receive click behavior.

Accountable owner

Design systems feedback owner

Canonical source: src/components/Badge.tsx

Semantic tone names may change only with the shared status taxonomy.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Text size

11px

Horizontal padding

8px

Vertical padding

2px

Radius

9999px

Border

1px

Rules

Keep labels brief and non-wrapping.
Choose a tone that matches the status meaning, not decoration.

Token dependencies

--color-surface / --color-surface2

Neutral fills.

--color-border

Neutral border.

--color-success / warning / info / error

Semantic text.

--color-*-surface / --color-*-border

Semantic fill and border pairs.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

default

Trigger: Default variant.
Visual response: Surface2 fill with standard border and primary text.
Behavior: Static metadata.

muted

Trigger: Muted variant.
Visual response: Quieter surface and secondary text.
Behavior: Static metadata.

success

Trigger: Positive status.
Visual response: Success surface, border, and text.
Behavior: Static metadata.

warning

Trigger: Cautionary status.
Visual response: Warning surface, border, and text.
Behavior: Static metadata.

error

Trigger: Failure status.
Visual response: Error surface, border, and text.
Behavior: Static metadata.

info

Trigger: Informational status.
Visual response: Info surface, border, and text.
Behavior: Static metadata.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Plain inline <span> with no implicit role.
Accessible name: Text content is read in surrounding context.

Write a meaningful label rather than encoding meaning only by color.
Do not add interaction to Badge; pair it with a real control when needed.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Badge } from '@ai-created/ui';

Server Component compatible

Forwards a span ref and accepts native span attributes.
Use variant for semantic tone and className only for contextual layout.

tsx

<Badge variant="success">Ready</Badge>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
variant	BadgeVariant	default	default, muted, success, warning, error, or info.
className	string	undefined	Additional classes.
...props	HTMLAttributes<HTMLSpanElement>	undefined	Native span attributes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use one to three words.
Place close to the object or value being classified.

Do not

Do not use as a button or filter chip.
Do not put sentences or essential instructions in a badge.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Renders a span and maps all six variants.
Forwards ref and native attributes.

Interaction

No interaction is expected.

Accessibility

Text remains meaningful without color.

Visual

Capture every tone in dark and light modes.

Related specifications

notice surface