first commit

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

@@ -0,0 +1,85 @@
+# Breadcrumb Variants (cva config)
+
+## Purpose
+
+`breadcrumbVariants`, `breadcrumbListVariants`, `breadcrumbItemVariants`, `breadcrumbLinkVariants`, `breadcrumbPageVariants`, `breadcrumbSeparatorVariants`, and `breadcrumbEllipsisVariants` are the cva (class-variance-authority) configurations powering every `<Breadcrumb>` slot. They are split from `breadcrumb.tsx` into their own module so an ejected source copy under `npx shadcn@latest add @suaveplan/breadcrumb` keeps the cva configurations in a dedicated file. Theme overrides flow through `useThemedVariants("Breadcrumb<Slot>")`.
+
+The wrapper cva is intentionally empty — breadcrumbs sit in many layout contexts (page header, sticky bar, embedded card) and adding margin / padding here would conflict with the host layout. The list, item, link, page, separator, and ellipsis cvas carry only the classes intrinsic to the breadcrumb itself.
+
+## Features
+
+- List: flex row with `gap-1.5 sm:gap-2.5`, wraps on narrow viewports, muted foreground.
+- Item: inline-flex row with `gap-1.5` between an interactive crumb and a separator.
+- Link: hover lift to foreground colour, focus-visible ring, smooth-easing colour transition with `motion-reduce:transition-none`.
+- Page: foreground colour, normal weight (so it does not visually outweigh the page heading).
+- Separator: sized to `[&>svg]:size-3.5` so the chevron matches the surrounding text.
+- Ellipsis: `flex h-9 w-9` square so the dots have a clear hit-area.
+
+## Usage: Basic Example
+
+```ts
+import {
+    breadcrumbLinkVariants,
+    breadcrumbPageVariants,
+} from "@suaveplan/react-ui";
+
+const linkClassName = breadcrumbLinkVariants();
+const pageClassName = breadcrumbPageVariants();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { breadcrumbListVariants, cn } from "@suaveplan/react-ui";
+
+export function BoldBreadcrumbList({
+    children,
+    className,
+}: {
+    children: React.ReactNode;
+    className?: string;
+}) {
+    return (
+        <ol className={cn(breadcrumbListVariants(), "font-bold", className)}>
+            {children}
+        </ol>
+    );
+}
+```
+
+## API Reference
+
+### `breadcrumbVariants(): string`
+
+Returns the wrapper class string (currently empty by design; reserved for theme overrides).
+
+### `breadcrumbListVariants(): string`
+
+Returns the `<ol>` class string. No arguments.
+
+### `breadcrumbItemVariants(): string`
+
+Returns the `<li>` class string. No arguments.
+
+### `breadcrumbLinkVariants(): string`
+
+Returns the `<a>` class string. No arguments.
+
+### `breadcrumbPageVariants(): string`
+
+Returns the current-page `<span>` class string. No arguments.
+
+### `breadcrumbSeparatorVariants(): string`
+
+Returns the separator `<li>` class string. No arguments.
+
+### `breadcrumbEllipsisVariants(): string`
+
+Returns the ellipsis `<span>` class string. No arguments.
+
+## Implementation Notes
+
+- All variants take no axes. Breadcrumb is intentionally simple — variants would multiply test surface area for marginal customisation gain.
+- The list cva uses `flex-wrap` so long breadcrumb trails wrap gracefully on narrow viewports rather than overflowing.
+- The link cva uses `focus-visible` (not `focus`) so the ring only appears for keyboard users, not on every mouse click.
+- `motion-reduce:transition-none` collapses the colour transition for users with `prefers-reduced-motion: reduce`.