--- 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.