first commit

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

@@ -0,0 +1,54 @@
+# Card Variants
+
+## Purpose
+
+`cardVariants` (and its sub-component cva resolvers `cardHeaderVariants`, `cardTitleVariants`, `cardDescriptionVariants`, `cardContentVariants`, `cardFooterVariants`) drive the chassis `<Card>` composition. The root `Card` exposes a `variant` axis with three rungs (`default` / `outline` / `ghost`) that swap the border + shadow combinations. The sub-component cvas are presentation-only with no exposed axes — they encode the conventional spacing (`p-6` for header / content / footer with `pt-0` on content / footer to sit flush against the header) so consumer composition stays consistent across the chassis.
+
+The variants module is intentionally separate (`card.variants.ts`) so an ejected source copy under `npx shadcn@latest add @suaveplan/card` keeps the cva config in a dedicated file.
+
+## Features
+
+- Root `variant` axis with `default` (border + shadow), `outline` (border, no shadow), and `ghost` (no border, no shadow).
+- Sub-component cvas encode conventional spacing — `p-6` on header / content / footer with `pt-0` on the latter two.
+- Title is `text-2xl font-semibold leading-none tracking-tight` — matching shadcn's typographic rhythm.
+- Description is `text-sm text-muted-foreground` — visually distinct from the title.
+
+## Usage: Basic Example
+
+```tsx
+import { cardVariants } from "@suaveplan/react-ui";
+
+const default_ = cardVariants();
+const outlined = cardVariants({ variant: "outline" });
+const ghost = cardVariants({ variant: "ghost" });
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { cva } from "class-variance-authority";
+import { cardVariants } from "@suaveplan/react-ui";
+
+const featuredCard = cva(
+    [cardVariants({ variant: "default" }), "ring-2 ring-primary"].join(" ")
+);
+```
+
+## API Reference
+
+### `cardVariants(opts?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"default" \| "outline" \| "ghost"` | `"default"` | Border + shadow combination. |
+
+### `cardHeaderVariants()`, `cardTitleVariants()`, `cardDescriptionVariants()`, `cardContentVariants()`, `cardFooterVariants()`
+
+No options — single canonical class string per resolver.
+
+## Implementation Notes
+
+- The `ghost` variant is useful when the card sits inside another bordered surface (e.g. a `<Sheet>` or another card) — the absent border avoids the visual "double-border" effect.
+- Padding is `p-6` to match shadcn's conventional rhythm. Consumers needing tighter padding override at the call site via `className="p-4"`.
+- `cardContentVariants` and `cardFooterVariants` apply `pt-0` (no top padding) so the header padding is the only top spacing — pairing with the header's `p-6` keeps the spacing rhythm consistent regardless of which sub-components are present.
+- `<CardTitle>` defaults to `<h3>` so it nests beneath `<h1>` / `<h2>` headings without disrupting the document outline. Consumers wanting a different heading level override at the call site by composing with their own heading element and applying `cardTitleVariants()` manually.