# Badge

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - badge.variants — `badgeVariants` is the cva config……
- [badge.variants](./badge.variants.md) — `badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four ru…
- badge.variants — `badgeVariants` is the cva config……

- [badge.variants](./badge.variants.md) — `badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four ru…

- badge.variants — `badgeVariants` is the cva config……

- [badge.variants](./badge.variants.md) — `badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four ru…

- badge.variants — `badgeVariants` is the cva config…

- [badge.variants](./badge.variants.md) — `badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four ru…
- [badge.variants](./badge.variants.md) — `badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four ru…

## Purpose

`<Badge>` is the chassis typographic marker for `@suaveplan/react-ui`. It renders a small inline-flex `<div>` with rounded ends, semibold tracking, and one of four colour variants (`default` / `secondary` / `destructive` / `outline`). Per the shadcn skill rule, `Badge` should be used in place of custom styled spans for status markers, category labels, count indicators, and any other inline emphasis — hand-rolling `<span className="rounded-full bg-green-100 ...">` produces a styled element with no theme awareness, no focus management, and no consistency with the rest of the surface.

The chassis surface is deliberately minimal: no `size` axis (badges inherit text size from the surrounding context), no internal text (children are consumer-provided), and no icon prop (icons are passed as children alongside a label). For status indicators that pair a semantic colour with iconography, use `<StatusBadge>` instead.

## Features

- Four colour variants via the `variant` axis (`default` / `secondary` / `destructive` / `outline`).
- `transition-colors` + `motion-reduce:transition-none` so reduced-motion users see instant colour changes.
- Focus ring scoped to the badge element so it works when wrapped in an anchor or button.
- Hover state on filled variants — outline variant remains decorative.
- Forwards refs to the underlying `<div>`.
- Theme variant overrides via `useThemedVariants("Badge", badgeVariants)` — a `ThemePlugin` may add brand-new variants (e.g. `variant: "premium"`).

## Usage: Basic Example

```tsx
import { Badge } from "@suaveplan/react-ui";

export function NewLabel() {
    return <Badge variant="secondary">New</Badge>;
}
```

## Usage: Advanced Example

```tsx
import { Badge } from "@suaveplan/react-ui";
import { SparklesIcon } from "lucide-react";

export function FeatureFlag() {
    return (
        <Badge variant="outline" className="gap-1">
            <SparklesIcon className="size-3" />
            Beta
        </Badge>
    );
}
```

## API Reference

### `<Badge>`

`forwardRef<HTMLDivElement, BadgeProps>` — renders a `<div>` with the variant classes + consumer-supplied `className` merged via `cn()`.

#### `BadgeProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `"default" \| "secondary" \| "destructive" \| "outline"` | `"default"` | Colour treatment — primary fill, secondary fill, destructive fill, or transparent outline. |
| _all_ `HTMLAttributes<HTMLDivElement>` | _native_ | _native_ | Forwarded as-is — `aria-label`, `id`, `style`, `data-*`, etc. |

#### `badgeVariants`

The bare cva resolver — exported so external consumers (themes, ejected source) can re-use the variants directly.

#### Errors

The Badge component does NOT call `useTranslation()` so it does not interact with the i18n provider. It is safe to render outside a `<TranslationProvider>` / `<ReactUiProvider>`.

## Implementation Notes

- Badges are typographic markers and inherit text size from their parent. The chassis intentionally does NOT expose a `size` axis — consumers wanting larger markers should compose a `<Badge>` inside a sized container or reach for `<StatusBadge>` (which has its own iconography and semantic colour scale).
- `inline-flex items-center` is set so badges can contain an icon + label child pair without consumer flex setup. A `gap-1` className is the conventional spacing when an icon is present.
- The outline variant intentionally has no `hover:` treatment because it is decorative — applying a hover background would imply interactivity the badge does not have.
- The `rounded-full` rule produces the pill shape; combined with the small `px-2.5 py-0.5` and `text-xs font-semibold`, the badge reads as a marker rather than a button.
- Because the rendered element is a `<div>`, badges nested inside paragraphs may produce invalid HTML in strict-mode renderers — wrap text-flow badges in a `<span>` (e.g. `<p>Hello <span><Badge>New</Badge></span></p>`). The chassis leaves this composition decision to the consumer rather than hardcoding a `<span>` (which loses the focus ring for `tabIndex={0}` use cases).