---
name: badge-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Badge for
compact status, category, discount, or metadata labels without duplicating
token-backed color and spacing classes in JSX.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/atoms/badge.tsx libs/ui/src/tokens/components/atoms/_badge.css libs/ui/stories/atoms/badge.stories.tsx libs/ui/src/atoms/badge.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Badge Usage
Use Badge for short non-interactive labels. It is not a button, link, alert, or
long message container.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Badge`.
**Use it when**
- Short, non-interactive labels of state or category: `Draft`, `Paid`, `New`, `−20 %`.
- Counts next to navigation items or tabs (unread, pending).
- Product flags on cards (discount, new, out of stock).
**Use something else when**
| Need | Use instead |
| --- | --- |
| A sentence explaining something | StatusText |
| Something the user can click or remove | Button / ActionIcon (removable filter chips live in the filter UI) |
| A page-level alert | inline StatusText section at the top of the content |
| Confirming an action | Toast |
**Do**
- Use one word, two at most; map each state to one variant app-wide (see the status table in ux-guidelines/ux-writing). Exception: names from that shared status vocabulary may be longer (`Out of stock`).
- Pair colour with the word — the text carries the meaning, colour only supports it.
- Place status badges next to the title they describe (page header meta, first table column or a Status column).
- Use `discount` only for price reductions, `danger` only for failed/blocked states.
**Don't**
- Mix synonyms (`Live`, `Active`, `Enabled`) for one state.
- Use a badge as a button or link.
- Stack more than two badges on one item — prioritise.
- Show a `0` count badge; hide it until there is something to count.
**Copy and states**
- Sentence case, no punctuation; counts formatted with `Intl.NumberFormat` (`1,204`), capped (`99+`) in navigation.
- Give count badges context for screen readers (`3 unread messages`).
**Behaviour (from the UX spec)**
- When the data changes, update the text and the `severity` together; show a result badge (`Approved`) only after the data confirms it.
- Never let colour alone imply a discount, approval or permission; `discount` needs a documented price comparison.
- A compact `Out of stock` card flag is a `danger` Badge; availability with detail or a delivery estimate is `AvailabilityStatus`.
**Figma → code**
| Figma | Code |
| --- | --- |
| `severity=primary…neutral`, `size=sm…xl` | `severity`, `size`; code also has `appearance="outline"` (a severity-coloured border), which Figma does not draw yet |
| — | `severity="custom"` + `bgColor` / `fgColor` / `borderColor` (code only) |
| `Label` text layer | `children` (string) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Badge → UX guidelines*.
## Setup
```tsx
import { Badge } from "@techsio/ui-kit/atoms/badge"
Published
```
Supported props from `src/atoms/badge.tsx`:
```text
severity: primary | secondary | tertiary | discount | info | success | warning | danger | neutral | custom
appearance: solid | outline
size: sm | md | lg | xl
children: string
dynamic: requires bgColor, fgColor, and borderColor
```
## Core Patterns
### Match the UX role to variant
```text
success -> completed, published, available
warning -> needs attention, low stock, pending risk
danger -> failed, destructive status, critical problem
info -> neutral informational state
discount -> price/promotion label
neutral (renders the outline look) -> low-emphasis label
appearance="outline" -> any severity as a colored border instead of a fill
```
Do not use `danger` only because the design has red text. If the visual should
change globally, use `app-token-overrides`.
### Keep Badge text short
```tsx
Pending
```
If the content needs a sentence or action, use `StatusText`, `Toast`, `Alert`
when available, or another molecule/organism usage skill.
### Treat dynamic as an explicit escape hatch
```tsx
Custom
```
Use `dynamic` only for values that cannot be represented by the standard
semantic/component token chain, such as runtime swatches. Prefer semantic
variants first.
## Common Mistakes
### HIGH Native span badge
Wrong:
```tsx
Active
```
Correct:
```tsx
Active
```
Source: libs/ui/src/atoms/badge.tsx
### HIGH Inline color duplicate
Wrong:
```tsx
Failed
```
Correct:
```tsx
Failed
```
The badge token classes already provide background, foreground, border,
padding, radius, and text sizing.
Source: libs/ui/src/tokens/components/atoms/_badge.css
### MEDIUM Dynamic variant without required colors
Wrong:
```tsx
Brand
```
Correct:
```tsx
Brand
```
`dynamic` requires explicit color props in the component source.
Source: libs/ui/src/atoms/badge.tsx
### MEDIUM Long actionable content
Wrong:
```tsx
Your profile needs attention, click here
```
Correct:
```tsx
Your profile needs attention.
```
Badge is for compact labels, not messages or actions.
## Validation Commands
```sh
rg -n "]*className=.*(badge|rounded|bg-|text-)" apps
rg -n "]*variant=|severity=\"(ghost|error)\"" apps
rg -n "]*severity=\"custom\"" apps
rg -n "]*className=.*(bg-|text-|border-|px-|py-|rounded-)" apps
```
## Display-size compatibility
The canonical comparison is sm/md/lg, default md. The existing xl size remains
available for display-only composition; it is not a fourth form-control size.
Badges are not interaction targets and therefore do not use field heights.
Custom dynamic colours must retain readable text and a useful status label.
## React 19 refs
Both ordinary and dynamic Badge accept an object or callback `ref` to their
rendered `HTMLSpanElement`, for measurement and anchored composition.