@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/ui/.card.md

@@ -1,56 +1,73 @@
-<!-- source-hash: 5558d90751c9222d7ee8a9204399d39b -->
-A comprehensive React component library providing reusable card UI elements with customizable styling and layouts. Built with TypeScript and Tailwind CSS for consistent design system implementation.
+<!-- source-hash: 292b6d5f3843f309d54f8359c29fda08 -->
+A collection of composable card UI components built on `React.forwardRef`, providing a structured layout system for displaying grouped content with optional header, title, description, content, and footer sections. Also exports a specialized `CardHorizontal` component for icon-labeled feature rows.
 
 ## Key Components
 
-- **Card** - Base container with rounded borders, shadow, and theme-aware styling
-- **CardHeader** - Top section with vertical spacing and padding for titles/metadata
-- **CardTitle** - Prominent heading with large font and tight tracking
-- **CardDescription** - Subtitle text with muted styling for secondary information
-- **CardContent** - Main content area with consistent padding
-- **CardFooter** - Bottom section with horizontal item alignment for actions/buttons
-- **CardHorizontal** - Specialized horizontal layout card with icon, title, and description
+| Export | Description |
+|---|---|
+| `Card` | Root container with rounded border, card background, and shadow |
+| `CardHeader` | Flex column wrapper with vertical spacing and padding |
+| `CardTitle` | Styled heading using `text-h2` typography token |
+| `CardDescription` | Muted subtitle using `text-h6` and `text-muted-foreground` |
+| `CardContent` | Main body area with padding (top padding removed) |
+| `CardFooter` | Horizontal flex row for actions, aligned at card bottom |
+| `CardHorizontal` | Standalone horizontal card with icon, title, and description |
+
+All `forwardRef` components accept standard `HTMLDivElement` attributes and merge custom `className` via the `cn` utility.
 
 ## Usage Example
 
 ```typescript
-import { 
-  Card, 
-  CardHeader, 
-  CardTitle, 
-  CardDescription, 
-  CardContent, 
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
   CardFooter,
-  CardHorizontal 
-} from './card'
+} from "@/components/ui/card"
+import { CardHorizontal } from "@/components/ui/card"
+import { ShieldIcon } from "lucide-react"
 
-// Standard vertical card
-function ProfileCard() {
+// Composable vertical card
+function FeatureCard() {
   return (
-    <Card className="w-96">
+    <Card>
       <CardHeader>
-        <CardTitle>User Profile</CardTitle>
-        <CardDescription>Manage your account settings</CardDescription>
+        <CardTitle>Endpoint Management</CardTitle>
+        <CardDescription>Monitor and manage all devices</CardDescription>
       </CardHeader>
       <CardContent>
-        <p>Profile content goes here</p>
+        <p>Real-time device status and alerts.</p>
       </CardContent>
       <CardFooter>
-        <button>Save Changes</button>
+        <button>View Devices</button>
       </CardFooter>
     </Card>
   )
 }
 
-// Horizontal card for category sections
-function CategoryCard() {
+// Horizontal card for feature/category lists
+function CategoryRow() {
   return (
     <CardHorizontal
-      icon={<UserIcon />}
-      title="User Management"
-      description="Handle user accounts and permissions"
+      icon={<ShieldIcon />}
+      title="Security Monitoring"
+      description="Automated threat detection and response"
       borderLeft={true}
     />
   )
 }
-```
+```
+
+## `CardHorizontal` Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `React.ReactNode` | — | Icon rendered at fixed `20×20px` |
+| `title` | `string` | — | Primary label (`text-h6`, primary color) |
+| `description` | `string` | — | Secondary label (`text-h6`, muted color) |
+| `className` | `string` | `''` | Additional Tailwind classes |
+| `borderLeft` | `boolean` | `true` | Toggles left border accent |
+
+**Source:** [`card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/card.tsx)

package/src/components/ui/.checkbox-block.md

@@ -1,46 +1,58 @@
-<!-- source-hash: 01a25a0740d1f4040be1a2e32f829429 -->
-A styled checkbox component that renders as a full-width interactive block with a label, optional description, and error state — built on top of Radix UI's `CheckboxPrimitive`.
+<!-- source-hash: d683834a543ce22b20cc1a05b1b5edc7 -->
+A styled checkbox component that renders as a full-width card/block layout, combining a Radix UI checkbox primitive with a label, optional description, trailing slot, and inline error display.
 
 ## Key Components
 
-- **`CheckboxBlock`** — A `forwardRef` component wrapping `@radix-ui/react-checkbox` with a card-style block layout
-- **`CheckboxBlockProps`** — Interface extending standard checkbox behavior with `label`, `description`, `error`, and `className`
+### `CheckboxBlock`
+A `forwardRef` component wrapping `@radix-ui/react-checkbox` that renders a tappable card row containing:
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `label` | `string` | Required primary text displayed next to the checkbox |
-| `description` | `React.ReactNode` | Optional secondary text below the label |
-| `error` | `string` | Error message shown below the block; also triggers a red border |
+|---|---|---|
+| `label` | `React.ReactNode` | Primary label (supports rich text/links) |
+| `description` | `React.ReactNode` | Optional secondary line below label |
+| `trailing` | `React.ReactNode` | Optional trailing slot (e.g. action button); must call `preventDefault` to avoid toggling |
+| `truncateLabel` | `boolean` | Ellipsize label overflow instead of wrapping |
+| `error` | `string` | Error message shown below the block; triggers red border |
+| `disabled` | `boolean` | Dims and disables interaction |
 | `checked` / `defaultChecked` | `boolean` | Controlled/uncontrolled checked state |
 | `onCheckedChange` | `(checked: boolean) => void` | Change handler |
-| `disabled` | `boolean` | Disables interaction and reduces opacity |
 
 ## Usage Example
 
 ```typescript
 import { CheckboxBlock } from "./checkbox-block"
 
-// Basic usage
+// Uncontrolled with description
 <CheckboxBlock
   id="terms"
-  label="Accept Terms & Conditions"
-  description="By checking this, you agree to our terms of service."
+  label="Accept Terms of Service"
+  description="You agree to our privacy policy and terms."
+  defaultChecked={false}
   onCheckedChange={(checked) => console.log(checked)}
 />
 
-// With error state
+// Controlled with error and trailing action
 <CheckboxBlock
-  id="required-field"
-  label="Required option"
-  error="This field is required"
-  checked={false}
-  onCheckedChange={handleChange}
+  id="notify"
+  checked={isChecked}
+  onCheckedChange={setIsChecked}
+  label="Enable notifications"
+  trailing={<button onClick={(e) => { e.preventDefault(); openSettings() }}>Configure</button>}
+  error={!isChecked ? "This field is required" : undefined}
 />
 
-// Disabled
+// Truncated label, disabled
 <CheckboxBlock
-  id="disabled-option"
-  label="Unavailable option"
+  id="long"
+  label="A very long label that should not wrap to a second line"
+  truncateLabel
   disabled
 />
-```
+```
+
+## Notes
+
+- On mobile, `trailing` content stacks full-width below the text; on `md+` it aligns inline.
+- Minimum touch target height is `44px` (mobile) / `48px` (desktop), increasing to `60px`/`64px` when a description is present.
+- Error text is absolutely positioned below the block to avoid layout shift.
+- Source: [`checkbox-block.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/checkbox-block.tsx)

package/src/components/ui/.checkbox-with-description.md

@@ -1,41 +1,39 @@
-<!-- source-hash: c1a54005af93850cd2ca67c81ddf2ca7 -->
-A compound checkbox component that pairs a Radix UI checkbox with a title and description, styled with ODS (OpenFrame Design System) tokens.
+<!-- source-hash: 59a0ae55416cf1e4d81e6e2acf777fff -->
+A compound checkbox component that renders a labeled checkbox alongside a title and descriptive text, built on Radix UI's `CheckboxPrimitive` with ODS design tokens.
 
 ## Key Components
 
-- **`CheckboxWithDescription`** — A `forwardRef` component combining a controlled checkbox, label, and descriptive text in a card-style container
-- **`CheckboxWithDescriptionProps`** — Interface defining the component's controlled state and content props
-
-### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `id` | `string` | ✅ | Links the label `htmlFor` to the checkbox input |
-| `checked` | `boolean` | ✅ | Controlled checked state |
-| `onCheckedChange` | `(checked: boolean) => void` | ✅ | Change handler |
-| `title` | `string` | ✅ | Primary label text |
-| `description` | `string` | ✅ | Secondary descriptive text |
-| `disabled` | `boolean` | ❌ | Disables interaction and dims the container |
-| `className` | `string` | ❌ | Additional classes for the outer wrapper |
+- **`CheckboxWithDescription`** — A `forwardRef` wrapper component combining a Radix UI checkbox, a `Label`, and a secondary description span into a card-style container
+- **`CheckboxWithDescriptionProps`** — Interface defining required and optional props:
+  - `id` — Links the label to the checkbox input
+  - `checked` / `onCheckedChange` — Controlled state
+  - `title` — Primary label text
+  - `description` — Secondary helper text rendered in `ods-text-secondary`
+  - `disabled` / `className` — Optional modifiers
 
 ## Usage Example
 
 ```typescript
 import { CheckboxWithDescription } from "@/components/ui/checkbox-with-description"
 
-function SettingsForm() {
+function NotificationSettings() {
   const [enabled, setEnabled] = React.useState(false)
 
   return (
     <CheckboxWithDescription
-      id="notifications"
+      id="email-notifications"
       checked={enabled}
       onCheckedChange={setEnabled}
       title="Email Notifications"
-      description="Receive alerts when a ticket is updated or assigned to you."
+      description="Receive alerts and updates directly to your inbox."
     />
   )
 }
 ```
 
-> The outer container becomes visually dimmed (`opacity-50`) and non-interactive (`cursor-not-allowed`) when `disabled` is set, applying consistently to both the checkbox and its label.
+## Notes
+
+- Applies `opacity-50 cursor-not-allowed` to the entire container when `disabled` is set, not just the native input
+- Uses ODS design tokens (`ods-accent`, `ods-border`, `ods-card`) for consistent theming
+- Checkbox indicator renders `CheckboxCheckmarkIcon` at 10px when `data-[state=checked]` is active
+- `displayName` is set for React DevTools clarity

package/src/components/ui/.chevron-button.md

@@ -1,43 +1,43 @@
-<!-- source-hash: cdf56d600d330b114e8fb5c69c27907c -->
-A customizable chevron button component built with React and Lucide icons that supports dynamic direction, expandable states, and multiple sizing options with optional custom styling.
+<!-- source-hash: 5df1a18bd1179672bf26c9b99fc30f83 -->
+A client-side React button component that renders a chevron icon (up or down) with configurable size, direction, and expand/collapse state.
 
 ## Key Components
 
-- **`ChevronButton`** - Main React component that renders a button with chevron icons from Lucide React
-- **`ChevronButtonProps`** - TypeScript interface extending button HTML attributes with chevron-specific props
-- **Size variants** - Three predefined sizes (sm, md, lg) with corresponding icon dimensions
-- **Direction control** - Supports 'up' and 'down' chevron orientations with expandable state logic
+### `ChevronButton`
+
+A `forwardRef` button component built on native `<button>` with the following props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `'up' \| 'down'` | `'down'` | Static chevron direction |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Icon size (`h-4`, `h-5`, `h-6`) |
+| `isExpanded` | `boolean` | — | When provided, overrides `direction` — `true` → up, `false` → down |
+| `backgroundColor` | `string` | — | Inline background color |
+| `borderColor` | `string` | — | Inline border color |
+| `className` | `string` | — | Additional Tailwind classes via `cn()` |
+
+> **Note:** `isExpanded` takes priority over `direction` when determining the rendered icon.
 
 ## Usage Example
 
 ```typescript
-import { ChevronButton } from './chevron-button'
+import { ChevronButton } from "@/components/ui/chevron-button"
 
-// Basic usage with default down chevron
-<ChevronButton onClick={() => console.log('clicked')} />
-
-// Expandable dropdown with state control
-<ChevronButton 
-  isExpanded={isOpen}
-  onClick={() => setIsOpen(!isOpen)}
-  size="lg"
-/>
+// Static direction
+<ChevronButton direction="up" size="sm" onClick={handleClick} />
 
-// Custom styled chevron button
-<ChevronButton
-  direction="up"
-  size="sm"
-  backgroundColor="#f3f4f6"
-  borderColor="#d1d5db"
-  className="hover:bg-gray-200"
-/>
+// Controlled expand/collapse toggle
+const [open, setOpen] = React.useState(false)
 
-// Form integration
 <ChevronButton
-  type="submit"
-  disabled={isLoading}
-  isExpanded={showDetails}
+  isExpanded={open}
+  size="lg"
+  backgroundColor="#f4f4f5"
+  borderColor="#e4e4e7"
+  onClick={() => setOpen(prev => !prev)}
 />
 ```
 
-The component intelligently selects the chevron direction based on either the `isExpanded` prop (taking precedence) or the `direction` prop, making it ideal for collapsible sections, dropdowns, and accordion interfaces.
+## Source
+
+[`chevron-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/ui/chevron-button.tsx)

package/src/components/ui/.circular-progress.md

@@ -1,66 +1,55 @@
-<!-- source-hash: b3367d6791779cace17c9e0ea0b291bc -->
-A React SVG-based circular progress ring component with configurable variants, sizes, and overflow behavior for displaying percentage values.
+<!-- source-hash: b3bf4bccce844da265f752f1cb27c87b -->
+A React SVG-based circular progress ring component with support for multiple semantic variants, configurable sizing, and overflow handling for values exceeding 100%.
 
 ## Key Components
 
 ### Types
 
-| Type | Values | Description |
-|------|--------|-------------|
-| `CircularProgressVariant` | `success` \| `warning` \| `error` \| `info` \| `accent` | Color theme for the progress ring |
-| `CircularProgressOverflow` | `clamp` \| `wrap` | How to handle percentages exceeding 100 |
+- **`CircularProgressVariant`** — `'success' | 'warning' | 'error' | 'info' | 'accent'`
+- **`CircularProgressOverflow`** — `'clamp'` (default, caps ring at 100%) or `'wrap'` (ring wraps per 100 units, label shows raw value)
 
-### Props (`CircularProgressProps`)
+### `CircularProgress` Component
 
-| Prop | Default | Description |
-|------|---------|-------------|
-| `percentage` | — | Progress value (0–100 in clamp; unbounded in wrap) |
-| `variant` | `'success'` | Color variant using ODS design tokens |
-| `size` | `56` | Diameter in pixels |
-| `strokeWidth` | `10` | Ring stroke thickness in pixels |
-| `showLabel` | `true` | Renders percentage text in the center |
-| `labelFormat` | `'percent'` | `'percent'` → `"70%"`, `'value'` → `"70"` |
-| `overflow` | `'clamp'` | Overflow handling strategy |
-
-### `CircularProgress` (exported component)
-
-Renders a two-circle SVG (track + progress arc) rotated -90° so progress starts at the top. The progress arc is animated via `strokeDashoffset`.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `percentage` | `number` | — | Progress value (0–100 in clamp mode; can exceed 100 in wrap mode) |
+| `variant` | `CircularProgressVariant` | `'success'` | Controls ring and track colors via ODS tokens |
+| `size` | `number` | `56` | Width/height in pixels |
+| `strokeWidth` | `number` | `10` | Ring stroke thickness in pixels |
+| `showLabel` | `boolean` | `true` | Renders centered text label |
+| `labelFormat` | `'percent' \| 'value'` | `'percent'` | `'percent'` → `"70%"`, `'value'` → `"70"` |
+| `overflow` | `CircularProgressOverflow` | `'clamp'` | How values > 100 are handled |
+| `className` | `string` | — | Additional CSS classes on the wrapper |
 
 ## Usage Example
 
 ```typescript
-// Basic usage
-<CircularProgress percentage={72} />
+// Default success ring at 75%
+<CircularProgress percentage={75} />
 
-// Overage warning with wrap mode
+// Warning ring with wrap overflow — ring shows 30%, label shows "130%"
 <CircularProgress
   percentage={130}
   variant="warning"
   overflow="wrap"
 />
-// Ring shows 30%, label shows 130%
 
-// Custom size, no label, accent variant
+// Compact error ring, value-only label, no label
 <CircularProgress
-  percentage={45}
-  variant="accent"
-  size={80}
-  strokeWidth={8}
-  showLabel={false}
+  percentage={42}
+  variant="error"
+  size={40}
+  strokeWidth={6}
+  labelFormat="value"
 />
 
-// Raw value label (no % suffix)
+// Accent ring, large, no label
 <CircularProgress
-  percentage={88}
-  labelFormat="value"
-  variant="info"
+  percentage={60}
+  variant="accent"
+  size={80}
+  showLabel={false}
 />
 ```
 
-## Overflow Behavior
-
-```text
-clamp mode:  percentage=130 → ring=100%, label="100%"
-wrap mode:   percentage=130 → ring=30%,  label="130%"
-wrap mode:   percentage=200 → ring=100%, label="200%"  (exact lap = full ring)
-```
+**Source:** [`circular-progress.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/circular-progress.tsx)

package/src/components/ui/.color-preset-select.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 8c7a0dd97bd59ac0d3df5150557e0d01 -->
+Client-side color selection components providing both a preset-based dropdown selector and a full-featured color picker with HEX/RGB/HSL input support.
+
+## Key Components
+
+### Exports & Constants
+
+| Name | Type | Description |
+|---|---|---|
+| `ColorPreset` | Interface | Shape for a color preset entry (`key`, `label`, `color`) |
+| `TICKET_STATUS_COLOR_PRESETS` | `readonly ColorPreset[]` | 12-color palette for ticket status use |
+| `CUSTOM_PRESET_KEY` | `string` | Sentinel key `'custom'` for user-defined colors |
+| `DEFAULT_CUSTOM_STATUS_COLOR` | `string` | Fallback hex `#888888` for custom presets |
+| `ColorPresetSelect` | Component | Dropdown to pick from named presets or switch to custom |
+| `ColorPickerInput` | Component | Popover with a saturation/hue canvas and HEX/RGB/HSL text inputs |
+
+### Internal Helpers
+
+- **`HexInputs`** — controlled text input with draft state; validates against `HEX_PATTERN` on blur/Enter
+- **`ChannelInput`** — numeric-only input clamped to `[min, max]`; used by RGB and HSL rows
+- **`RgbInputs`** / **`HslInputs`** — three-channel rows converting to/from hex via `ods-color-utils`
+
+## Usage Example
+
+```typescript
+import {
+  ColorPresetSelect,
+  ColorPickerInput,
+  TICKET_STATUS_COLOR_PRESETS,
+} from './color-preset-select'
+
+// Preset selector (e.g. ticket status badge color)
+<ColorPresetSelect
+  value={color}
+  presetKey={presetKey}
+  presets={TICKET_STATUS_COLOR_PRESETS}
+  onChange={({ color, preset }) => {
+    setColor(color)
+    setPresetKey(preset)
+  }}
+/>
+
+// Free-form color picker (always works in hex)
+<ColorPickerInput
+  value={color}          // "#5ea62e"
+  onChange={setColor}    // receives hex string
+/>
+```
+
+> **Note:** Both components use `value`/`onChange` in hex (`#rrggbb`). Color space conversions (RGB ↔ HSL ↔ hex) are handled internally via `utils/ods-color-utils`.
+
+## Source
+
+[`color-preset-select.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/color-preset-select.tsx)

package/src/components/ui/.color-swatch.md

@@ -0,0 +1,37 @@
+<!-- source-hash: 2ae93287b79efdeb7690ec2709feb96f -->
+A small presentational component that renders a square color preview swatch, used as a shared building block across color and status selector UIs.
+
+## Key Components
+
+**`ColorSwatch`** — Default export function component.
+
+**`ColorSwatchProps`** — Interface defining the component's props:
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `color` | `string` | ✅ | Any valid CSS color value applied as `backgroundColor` |
+| `className` | `string` | ❌ | Optional additional Tailwind/CSS classes |
+
+## Usage Example
+
+```typescript
+import { ColorSwatch } from './color-swatch'
+
+// Basic usage
+<ColorSwatch color="#3B82F6" />
+
+// With custom sizing override
+<ColorSwatch color="rgb(239, 68, 68)" className="size-6" />
+
+// Composed inside a status selector
+<div className="flex items-center gap-2">
+  <ColorSwatch color={selectedStatus.color} />
+  <span>{selectedStatus.label}</span>
+</div>
+```
+
+## Notes
+
+- Renders as an `aria-hidden` `<span>` — purely decorative; excluded from the accessibility tree.
+- Default styles: `inline-block`, `16×16px` (`size-4`), `shrink-0`, `rounded-sm`.
+- Uses the shared [`cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/cn.ts) utility for class merging, so `className` overrides compose cleanly with Tailwind.

package/src/components/ui/.content-loader.md

@@ -1,43 +1,50 @@
-<!-- source-hash: f80d7f61d9427dcf715215adf596f271 -->
-A unified skeleton loading component that replaces duplicate loading patterns across the UI, using ODS design tokens for consistent theming.
+<!-- source-hash: 40cfee9a50603599ef7a29bb3b0234f7 -->
+A unified skeleton loading component that renders animated placeholder UI for different content layouts using ODS design tokens, replacing duplicate loading patterns across the application.
 
 ## Key Components
 
-**`ContentLoader`** — Main export. Renders an animated pulse skeleton based on the selected `variant`.
+### `ContentLoader`
+The primary export. Accepts a `variant` prop to switch between four skeleton layouts, with configurable item count and optional title placeholder.
 
-**`ContentLoaderProps`**
+**Props (`ContentLoaderProps`):**
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|---|---|---|---|
 | `variant` | `'card' \| 'form' \| 'detail' \| 'list'` | `'card'` | Skeleton layout type |
 | `items` | `number` | `4` | Number of repeated skeleton items |
-| `showTitle` | `boolean` | `true` | Renders a title placeholder bar |
-| `className` | `string` | — | Inner wrapper CSS classes |
-| `containerClassName` | `string` | — | Outer container CSS classes |
+| `showTitle` | `boolean` | `true` | Render a title placeholder bar |
+| `className` | `string` | — | CSS classes for inner wrapper |
+| `containerClassName` | `string` | — | CSS classes for outer container |
 
-**Convenience exports** — Pre-bound variants for direct use:
-- `CardLoader` — stat/metric card layout
-- `FormLoader` — labeled input fields layout
-- `DetailLoader` — two-column detail/sidebar layout
-- `ListLoader` — icon + text row list layout
+### Variant Shortcuts
+Pre-bound convenience exports with `variant` locked:
+
+- **`CardLoader`** — Grid of stat fields with a footer row
+- **`FormLoader`** — Stacked label + input field rows
+- **`DetailLoader`** — Two-column layout with a large content area and sidebar
+- **`ListLoader`** — Row items with avatar, text lines, and action button
+
+All variants use `bg-ods-skeleton` tokens and `animate-pulse` for consistent theming.
 
 ## Usage Example
 
 ```typescript
-// Generic usage
-import { ContentLoader } from './content-loader';
-
+import {
+  ContentLoader,
+  CardLoader,
+  FormLoader,
+  DetailLoader,
+  ListLoader,
+} from './content-loader';
+
+// Generic usage with variant selection
 <ContentLoader variant="list" items={6} showTitle={false} />
 
-// Convenience variants
-import { FormLoader, DetailLoader, ListLoader } from './content-loader';
-
-// Form skeleton with 3 fields
-<FormLoader items={3} />
-
-// Detail page skeleton
-<DetailLoader containerClassName="max-w-4xl" />
+// Convenience wrappers
+<CardLoader items={4} />
+<FormLoader items={5} containerClassName="max-w-lg" />
+<DetailLoader className="mt-4" />
+<ListLoader items={8} showTitle={false} />
+```
 
-// List with custom container
-<ListLoader items={8} showTitle={false} containerClassName="px-0" />
-```
+> **Note:** This is a `'use client'` component. It must be rendered in a client boundary in Next.js App Router projects.

package/src/components/ui/.crossfade-panels.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 4e1e5ab4feba9a5a8cb821fcb8daa1ba -->
+Animated tab-panel stack that keeps all panels mounted in the DOM and switches between them using an opacity/visibility crossfade, preventing layout shift.
+
+## Key Components
+
+### `CrossfadePanels`
+The main exported component. Renders all panels into a single CSS grid cell (`col-start-1 row-start-1`), stacking them so the container height is always `max(panel heights)`. The active panel fades in at `z-[1]`; inactive panels fade out and receive `inert`, `aria-hidden`, and `pointer-events-none` once settled.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `CrossfadePanel` | `{ id, content }` — a single panel descriptor |
+| `CrossfadePanelsProps` | Component props: `activeId`, `panels`, `durationMs`, `className`, `panelClassName` |
+
+## Key Behaviors
+
+- **Height lock** — CSS grid single-cell stacking prevents CLS on switch
+- **Fade-then-hide** — `visibility` interpolates alongside `opacity` so the outgoing panel stays paintable until the fade completes
+- **Fully dead when hidden** — `inert` + `aria-hidden` eliminates tab stops, screen-reader exposure, and click/hover leaks (WCAG compliant)
+- **Motion respect** — `prefers-reduced-motion` collapses the crossfade to an instant swap via `motion-reduce:transition-none`
+
+## Usage Example
+
+```typescript
+import { CrossfadePanels } from './crossfade-panels'
+
+const panels = [
+  { id: 'overview', content: <OverviewPanel /> },
+  { id: 'metrics',  content: <MetricsPanel /> },
+]
+
+function Dashboard() {
+  const [activeId, setActiveId] = React.useState('overview')
+
+  return (
+    <>
+      <TabNavigation activeId={activeId} onChange={setActiveId} />
+      <CrossfadePanels
+        activeId={activeId}
+        panels={panels}
+        durationMs={250}
+        className="mt-4"
+      />
+    </>
+  )
+}
+```
+
+> **When to prefer this over `<TabContent>`:** Use `CrossfadePanels` when panels are cheap to keep mounted and seamless switching matters (strips, media rails, dashboards). Use `<TabContent>` for heavy admin surfaces that should unmount when hidden.