# Badge Variants

## Purpose

`badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four rungs (`default` / `secondary` / `destructive` / `outline`) that each pair a background colour with a matching foreground text colour, plus a transparent border for the three filled variants and a foreground-coloured border for the outline variant.

The variants module is intentionally separate (`badge.variants.ts`) so an ejected source copy under `npx shadcn@latest add @suaveplan/badge` keeps the cva config in a dedicated file, mirroring the upstream shadcn convention.

## Features

- Single `variant` axis with four rungs (`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 as a focusable target when wrapped in an anchor or button.
- Hover state for filled variants (`hover:bg-{variant}/80`) — outline variant has no hover treatment because it is decorative.

## Usage: Basic Example

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

const primary = badgeVariants();
const secondary = badgeVariants({ variant: "secondary" });
const danger = badgeVariants({ variant: "destructive" });
const outlined = badgeVariants({ variant: "outline" });
```

## Usage: Advanced Example

```tsx
import { cva } from "class-variance-authority";
import { badgeVariants } from "@suaveplan/react-ui";

const auditBadge = cva(
    [badgeVariants({ variant: "outline" }), "uppercase tracking-wider"].join(" ")
);
```

## API Reference

### `badgeVariants(opts?)`

| Option | Type | Default | Description |
|---|---|---|---|
| `variant` | `"default" \| "secondary" \| "destructive" \| "outline"` | `"default"` | Colour treatment — primary fill, secondary fill, destructive fill, or transparent outline. |

Returns the merged class string.

## Implementation Notes

- The default `variant` is `default` (primary fill) — overriding the default at the `defineVariants` level keeps the API consistent with every other chassis component.
- The chassis intentionally does NOT expose a `size` axis because badges are typographic markers — they should match the size of the surrounding text. Larger / more emphatic markers should use `<StatusBadge>` (icon + colour combo) or compose a `<Badge>` inside a sized container.
- `inline-flex items-center` is applied so badges can contain an icon + label without manual flex setup at the consumer level.
- `rounded-full` produces the pill shape that distinguishes badges from buttons or chips.
- The outline variant has `text-foreground` with a default `border` (no `border-{colour}`) so it picks up the active theme's border colour automatically.