# `variants` — chassis cva variants entry point

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Single canonical entry point for `class-variance-authority` (cva) used
by every chassis component. The chassis re-exports the bare `cva` /
`VariantProps` here (one of the rare exceptions to "never re-export
external deps for convenience" per CLAUDE.md §4 — justified by the
typing trade-off, see `useThemedVariants`). The `defineVariants` helper
wraps `cva` with a debug-friendly component-name tag so chassis
DevTools surfaces and the registry generator can attribute resolver
output to its source component.

## Features

- Re-exports `cva` and `VariantProps` from
  `class-variance-authority`
- `defineVariants(name, base, config)` returns the same cva resolver
  with a non-enumerable `componentName` property attached
- `name` arg accepts either a registered `ThemableVariantNames` key
  (with autocomplete) or an arbitrary string literal so component
  packs can declare new component names without first updating the
  chassis `ThemableVariants` interface

## Usage: Basic example

```ts
import { defineVariants } from "@suaveplan/react-ui/variants";

export const buttonVariants = defineVariants("Button", "inline-flex h-9", {
    variants: {
        variant: { default: "bg-primary", ghost: "bg-transparent" },
        size: { sm: "px-3", md: "px-4", lg: "px-6" },
    },
    defaultVariants: { variant: "default", size: "md" },
});
```

## Usage: Advanced example

```ts
import { defineVariants, type VariantProps } from "@suaveplan/react-ui/variants";

export const cardVariants = defineVariants("Card", "rounded border", {
    variants: {
        padding: { none: "", sm: "p-2", md: "p-4", lg: "p-6" },
    },
    defaultVariants: { padding: "md" },
});

export type CardVariants = VariantProps<typeof cardVariants>;

declare module "@suaveplan/react-ui/theme" {
    interface ThemableVariants {
        readonly Card: typeof cardVariants;
    }
}
```

## API Reference

- `cva` — re-exported from `class-variance-authority`
- `VariantProps` — re-exported `VariantProps`
- `defineVariants(name, base, config)` — wraps `cva` and tags the
  resolver with `componentName`

## Implementation notes

The `componentName` property is non-enumerable so it does NOT appear in
JSON serialisation, `Object.keys`, or `for...in` iteration — keeping
the cva resolver's surface area unchanged for consumers that pass the
function around. The tag is used by the registry generator
(`scripts/build-registry.ts` in Wave 3) to map ejected component source
to its resolver's named identity. The chassis's `useThemedVariants`
hook does NOT consult the tag — it keys cache entries on the
`(themeName, componentName)` tuple supplied by the call site, which
keeps the cache lookup O(1) and dependency-free.