first commit

docs/ui/react/react-ui/src/components/checkbox/checkbox.variants.md

@@ -0,0 +1,53 @@
+# Checkbox Variants (cva config)
+
+## Purpose
+
+`checkboxVariants` is the cva (class-variance-authority) configuration that powers every `<Checkbox>` render. It is split from `checkbox.tsx` into its own module so an ejected source copy under `npx shadcn@latest add @suaveplan/checkbox` keeps the cva configuration in a dedicated file. Theme overrides flow through `useThemedVariants("Checkbox", checkboxVariants)`, so the runtime cva resolver can be replaced or extended by an active `ThemePlugin` without touching the component source.
+
+The module exports a single `checkboxVariants` callable resolver tagged with the component name `"Checkbox"` via `defineVariants`.
+
+## Features
+
+- Three sizes (`sm` → `h-3.5 w-3.5`, `default` → `h-4 w-4`, `lg` → `h-5 w-5`) scaling the box.
+- `border-primary` border + `shadow` so the box reads against muted backgrounds.
+- `data-[state=checked]:bg-primary` + `data-[state=indeterminate]:bg-primary` flip the fill when checked or partial.
+- `disabled:cursor-not-allowed disabled:opacity-50` for the native disabled state.
+- `motion-reduce:transition-none` for users with `prefers-reduced-motion: reduce`.
+- `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` for keyboard-only focus styling.
+
+## Usage: Basic Example
+
+```ts
+import { checkboxVariants } from "@suaveplan/react-ui";
+
+const className = checkboxVariants({ size: "default" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { checkboxVariants, cn } from "@suaveplan/react-ui";
+
+export function InlineCheckbox({ extra }: { extra?: string }) {
+    return (
+        <button
+            type="button"
+            role="checkbox"
+            aria-checked="false"
+            className={cn(checkboxVariants({ size: "sm" }), extra)}
+        />
+    );
+}
+```
+
+## API Reference
+
+### `checkboxVariants(props?: { size?: "sm" | "default" | "lg" }): string`
+
+Returns the cva-merged class string for the supplied size. Omitted props fall back to the cva `defaultVariants` (`size: "default"`).
+
+## Implementation Notes
+
+- The resolver is tagged with `componentName: "Checkbox"` (non-enumerable, non-writable) via `defineVariants`.
+- The cva config exposes only the `size` axis. Theme-specific variants (rounded vs square, filled vs outlined) are layered via `variantOverrides.Checkbox` rather than baked into the chassis.
+- Tokens reference theme-driven CSS custom properties (`border-primary`, `bg-primary`, `text-primary-foreground`) so the colour palette comes from the active `ThemePlugin.cssVariables` payload.