# @shavin/ui — Comprehensive LLM Context & Technical Specification

> **Target Audience**: AI Agents, LLMs, and Engineers generating, auditing, or refactoring code using `@shavin/ui`.
> **Official Docs Hub**: https://docs.shavin.cc
> **Marketing Site**: https://www.shavin.cc

---

## TABLE OF CONTENTS
1. Core Mental Model & Two-Tier Architecture
2. Installation, Tailwind Setup & Wiring
3. ThemeProvider Configuration & Props Reference
4. Complete Design Token Reference Dictionary
5. Typography System & Guidelines
6. Comprehensive Component Reference (All 139 Primitives & Exports)
7. Strict Architectural Do's, Don'ts & Anti-Patterns
8. Model Context Protocol (MCP) Server & AI Integration
9. Pre-Built Blocks & Production Templates

---

## 1. CORE MENTAL MODEL & TWO-TIER ARCHITECTURE

`@shavin/ui` is an enterprise-grade React design system delivering a strict two-tier token architecture, WCAG 2.1 AAA accessible primitives, a live theme configurator, and an integrated Model Context Protocol (MCP) server for zero-hallucination AI-assisted UI development.

### The Two Tiers
1. **Foundation Tokens**: Raw neutral gray palette scale (`--n-0` through `--n-1000`) defined in `src/styles/global.css`. **Never reference `--n-*` outside `global.css`.**
2. **Semantic Tokens**: Role-based variables (`--bg-canvas`, `--bg-surface`, `--fg`, `--accent`, `--hairline`), remapped per theme (`:root` = light, `.dark` = dark).
3. **The Invariant Law**: Every component and template MUST use ONLY semantic Tailwind utility classes (`bg-surface`, `text-fg`, `border-hairline`).
   - **ZERO hex codes** (`#123456` is forbidden).
   - **ZERO `rgb()` or `hsl()` literals** in layout or component markup.
   - **ZERO `--n-*` foundation variables** in JSX.

### Directory Layout & Import Rule
- **Standard**: Monorepo with `packages/ui`, `packages/mcp-server`, `packages/cli`, `apps/docs`, `apps/studio`, and `apps/website`.
- **IMPORT RULE**: ALWAYS import from `@shavin/ui` root.
  ```tsx
  // ✅ CORRECT:
  import { Button, Card, TextField, Heading, Text, ThemeProvider } from "@shavin/ui";

  // ❌ FORBIDDEN:
  import { Button } from "@shavin/ui/primitives/Button";
  import { Card } from "@shavin/ui/src/primitives/Card";
  ```

---

## 2. INSTALLATION, TAILWIND SETUP & WIRING

### Method A: Automated 1-Command Setup (Recommended)
Run the automated CLI initializer in your project root:
```bash
npx @shavin/cli init
```
This single command automatically:
1. **Framework Detection**: Inspects whether you are using Next.js (App or Pages Router), Vite, or Remix.
2. **Dependency Installation**: Installs `@shavin/ui` and necessary peer dependencies.
3. **Tailwind Configuration**: Adds `presets: [require("@shavin/ui/tailwind-preset")]` to `tailwind.config.ts`.
4. **CSS Stylesheet Injection**: Injects `@import "@shavin/ui/styles.css";` into your root stylesheet (`globals.css`).
5. **Next.js Transpilation**: Adds `transpilePackages: ["@shavin/ui"]` into `next.config.mjs` (when on Next.js).
6. **Root Provider Scaffolding**: Detects your root layout (`app/layout.tsx`, `pages/_app.tsx`, or `src/App.tsx`) and wraps your application in `<ThemeProvider>`.

---

### Method B: Manual Step-by-Step Installation

#### Step 1: Install Package
```bash
npm install @shavin/ui
# or
pnpm add @shavin/ui
# or
yarn add @shavin/ui
```

#### Step 2: Configure Tailwind CSS Preset
Add `@shavin/ui/tailwind-preset` to your `tailwind.config.ts`:
```ts
import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@shavin/ui/dist/**/*.{js,mjs}",
  ],
  presets: [require("@shavin/ui/tailwind-preset")],
};

export default config;
```

#### Step 3: Import Stylesheet
In your root CSS file (`src/app/globals.css` or `src/styles/global.css`):
```css
@import "@shavin/ui/styles.css";
```

#### Step 4: Transpile Packages (Next.js App or Pages Router)
In `next.config.mjs`:
```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ["@shavin/ui"],
};

export default nextConfig;
```

#### Step 5: Wrap Root Layout in ThemeProvider
In your root layout (`app/layout.tsx`):
```tsx
import "@shavin/ui/styles.css";
import "./globals.css";
import { ThemeProvider } from "@shavin/ui";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className="min-h-screen bg-canvas text-fg antialiased">
        <ThemeProvider
          accentColor="grass"
          grayColor="gray"
          radius="large"
          scaling="100%"
          panelBackground="solid"
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

---

## 3. THEMEPROVIDER CONFIGURATION & PROPS REFERENCE

`ThemeProvider` is the top-level configuration engine for `@shavin/ui`. It applies CSS custom properties dynamically to `:root` and mounts `ShavinDevInspector` in development mode.

### ThemeProvider Props Reference

| Prop | Type | Default | Description |
|---|---|---|---|
| `accentColor` | `string` | `"monochrome"` | One of the 24 curated accent colors. Controls primary buttons, active tabs, focus rings, and selection indicators. |
| `grayColor` | `string` | `"neutral"` | Neutral gray scale family (Zinc, Slate, Gray, Neutral, Stone). Maps `--n-0` through `--n-1000`. |
| `radius` | `"none" | "small" | "medium" | "large" | "full"` | `"medium"` | Base radius scale preset. Controls `--radius-lg` (controls) and `--radius-panel` (containers). |
| `scaling` | `"90%" | "95%" | "100%" | "105%" | "110%"` | `"100%"` | Global typographic and spatial scaling factor. High-density dashboards use `95%`. |
| `panelBackground` | `"solid" | "translucent"` | `"solid"` | Determines whether dialogs, popovers, and menus use opaque fills or frosted translucent backdrop blur. |
| `displayFont` | `string` | `"Inter"` | Display headline font family loaded dynamically from Google Fonts. |
| `bodyFont` | `string` | `"Inter"` | Body prose font family loaded dynamically from Google Fonts. |

### Available Accent Palettes (24 Curated Presets)
- **Monochrome** (`#000000`)
- **Tomato** (`#e54d2e`)
- **Red** (`#e5484d`)
- **Ruby** (`#e54666`)
- **Crimson** (`#e93d82`)
- **Pink** (`#d6409f`)
- **Plum** (`#ab4aba`)
- **Purple** (`#8e4ec6`)
- **Violet** (`#6e56cf`)
- **Iris** (`#5b5bd6`)
- **Indigo** (`#3e63dd`)
- **Blue** (`#0090ff`)
- **Cyan** (`#00a2c7`)
- **Teal** (`#12a594`)
- **Jade** (`#29a383`)
- **Green** (`#30a46c`)
- **Grass** (`#46a758`)
- **Lime** (`#bdee63`)
- **Mint** (`#86ead4`)
- **Sky** (`#7ce2fe`)
- **Amber** (`#ffc53d`)
- **Gold** (`#978365`)
- **Bronze** (`#a18072`)
- **Brown** (`#ad7f58`)

### Available Gray Scales (5 Neutral Families)
- **Zinc** (`#71717a`): Cool, balanced modern tech neutral.
- **Slate** (`#64748b`): Crisp oceanic slate with blue undertones.
- **Gray** (`#6b7280`): True neutral balanced gray.
- **Neutral** (`#737373`): Unbiased pure neutral gray.
- **Stone** (`#78716c`): Warm architectural earth-tone gray.

### Radius Presets & Geometry Map
| Preset | Control Radius (`--radius-lg`) | Panel Radius (`--radius-panel`) | Visual Character |
|---|---|---|---|
| `none` | `0px` | `0px` | Sharp industrial/brutalist geometry. |
| `small` | `0.25rem` (4px) | `0.5rem` (8px) | Tight compact data density. |
| `medium` | `0.5rem` (8px) | `1.0rem` (16px) | Standard balanced enterprise desktop. |
| `large` | `0.75rem` (12px) | `1.5rem` (24px) | Friendly modern consumer software. |
| `full` | `9999px` (Pill) | `1.5rem` (24px) | Pill-shaped controls while containers remain safely capped at 24px curve. |

### Preventing Flash of Unstyled Content (SSR)
Render `<ThemeScript />` inside your `<head>` to instantly read `localStorage` before React hydration:
```tsx
import { ThemeScript } from "@shavin/ui";

export default function Document() {
  return (
    <html lang="en">
      <head>
        <ThemeScript />
      </head>
      <body>...</body>
    </html>
  );
}
```

---

## 4. COMPLETE DESIGN TOKEN REFERENCE DICTIONARY

### Semantic Color Tokens

| Semantic Token | Tailwind Class | Semantic Purpose / Role |
|---|---|---|
| `--bg-canvas` | `bg-canvas` | Furthest-back background surface behind all layouts. |
| `--bg-surface` | `bg-surface` | Default content surface (cards, inputs, panels) sitting on canvas. |
| `--bg-surface-hover` | `bg-surface-hover` | Hover / active fill for interactive surface rows and cards. |
| `--bg-surface-raised` | `bg-surface-raised` | Elevated cards or panels needing one level of step-up. |
| `--bg-elevated` | `bg-elevated` | Floating surface fill (Dialog, Menu, Popover, Select dropdown). |
| `--hairline` | `border-hairline` | Default 1px subtle divider and border line. |
| `--hairline-strong` | `border-hairline-strong` | Higher contrast border for active states, card headers, or hover. |
| `--fg` | `text-fg` | Primary text and high-contrast glyphs. |
| `--fg-subtle` | `text-fg-subtle` | Paired descriptions, field helper texts, sub-headers. |
| `--fg-muted` | `text-fg-muted` | Standalone meta, timestamps, badge labels. |
| `--accent` | `bg-accent` / `text-accent` | Active brand/theme accent color. |
| `--accent-hover` | `bg-accent-hover` | Hover variant for accent-filled elements. |
| `--accent-fg` | `text-accent-fg` | Contrast-safe foreground on top of solid accent fill. |
| `--accent-subtle` | `bg-accent-subtle` | 10% tinted accent background fill for soft buttons and tags. |
| `--accent-contrast` | `text-accent-contrast` | Contrast-safe accent text on light/soft surfaces. |
| `--success` | `bg-success` / `text-success` | Positive status indicator, success badges, checkmarks. |
| `--warning` | `bg-warning` / `text-warning` | Caution, attention, pending review indicators. |
| `--danger` | `bg-danger` / `text-danger` | Destructive actions, delete buttons, error validation. |
| `--link` | `text-link` | Hyperlink color with underline affordance. |

### Concentric Radius System
1. **Controls** (`rounded-[var(--radius-lg)]`): Single-line inputs, buttons, badges, chips, switches. Go pill-shaped at "Full" preset.
2. **Panels & Containers** (`rounded-[var(--radius-panel)]`): Cards, dialogs, popovers, menus, accordions, callouts. Intentionally capped at finite curve — **NEVER** use `--radius-lg` on containers or accordions.
3. **Concentric Nesting Formula**:
   $$\mathbf{R_{\text{inner}} = \max(0, R_{\text{outer}} - \text{Padding})}$$
4. **Tailwind Concentric Utilities**:
   - `rounded-panel-p3`: Use when outer container has `p-3` padding ($R_{inner} = R_{panel} - 12px$).
   - `rounded-panel-p5`: Use when outer container has `p-5` padding ($R_{inner} = R_{panel} - 20px$).
   - `rounded-panel-inner`: Nested element inside standard container.

### Elevation Shadows
- `shadow-panel`: Default elevation shadow for cards, popovers, and dropdown menus.
- `shadow-modal`: Deep backdrop elevation shadow for modal Dialog and AlertDialog surfaces.

### Physics & Easing
- Out Easing: `cubic-bezier(0.23, 1, 0.32, 1)` (spring-like deceleration for all opening and entering choreography).
- Standard Duration: `< 250ms` for responsive interactions; `< 150ms` for micro-interactions.

---

## 5. TYPOGRAPHY SYSTEM & GUIDELINES

### Typography Primitives Table

| Tag | Component | Semantics | Key Props |
|---|---|---|---|
| `<Heading>` | Heading | `<h1>`–`<h6>` | `as="h1"|"h2"|"h3"|"h4"|"h5"|"h6"`, `size="xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl"`, `weight`, `align`, `color` |
| `<Text>` | Text | `<p>` / `<span>` | `as="p"|"span"|"div"|"label"`, `size="xs"|"sm"|"base"|"md"|"lg"|"xl"`, `weight`, `color="default"|"subtle"|"muted"|"accent"` |
| `<Em>` | Em | `<em>` | Inline italic emphasis. |
| `<Strong>` | Strong | `<strong>` | Inline bold text. |
| `<Quote>` | Quote | `<q>` | Inline curly quotes. |
| `<Blockquote>` | Blockquote | `<blockquote>` | Pull quote block with left accent hairline. |
| `<Code>` | Code | `<code>` | Inline monospace code snippet badge. |
| `<Kbd>` | Kbd | `<kbd>` | Keyboard shortcut key indicator (⌘K, Ctrl+P). |
| `<Link>` | Link | `<a>` | Hyperlink anchor with token styles and hover underline. |

### Strict Typographic Contrast & Layout Rules
1. **The Contrast Law**:
   - Primary Title / Header: `text-fg` (or `<Heading>` default).
   - Paired Description / Subtitle: MUST use `text-fg-subtle` (or `<Text color="subtle">`).
   - Meta / Timestamp / Secondary Label: MUST use `text-fg-muted` (or `<Text color="muted">`).
   - **Violation**: Never pair `text-fg` directly with `text-fg-muted` — the contrast gap is too steep and illegible.
2. **Text Balance**: All display and section headings MUST include `text-balance` to eliminate typographic orphans.
3. **Text Pretty**: All body text paragraphs MUST include `text-pretty` for optimal multi-line word wrapping.
4. **Measure Limit**: Limit prose measure to `max-w-2xl` (680px). Never allow body paragraphs to span full viewport width.
5. **Tabular Numerals**: All numbers, metrics, financial values, and data counters MUST use `tabular-nums font-mono` to avoid layout jitter during updates.

---

## 6. COMPREHENSIVE COMPONENT REFERENCE (ALL 139 PRIMITIVES & EXPORTS)

Each entry contains the component tag, import statement, variants, props, concrete copy-paste TSX declaration, and documentation link.

### Layout & Shell (21 components)

#### `<AppFrame>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Props**: `sidebar` (required): `ReactNode`, `children` (required): `ReactNode`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<NavRail collapsible><NavItem active icon={<Home />}>Dashboard</NavItem></NavRail>}><div>Main Dashboard Content</div></AppFrame>
```

#### `<AspectRatio>`
- **Documentation**: [https://docs.shavin.cc/foundations/aspect-ratio](https://docs.shavin.cc/foundations/aspect-ratio)
- **Description**: Ratio layout wrapper primitive built on Radix AspectRatio for reserving media element proportions.
- **Import**: `import { AspectRatio } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use AspectRatio around images, video embeds, and map containers.
  - ❌ DON'T: Do not leave media elements without aspect ratio preservation — use AspectRatio to prevent layout shifts.
- **Sample Declaration**:
```tsx
<AspectRatio ratio={16 / 9}><Image src="cover.jpg" alt="Video thumbnail" fit="cover" /></AspectRatio>
```

#### `<Box>`
- **Documentation**: [https://docs.shavin.cc/components/box](https://docs.shavin.cc/components/box)
- **Description**: Generic div-based container primitive with translucent panel support and background media props. Useful for media-backed panels and callout boxes.
- **Import**: `import { Box } from "@shavin/ui";`
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`, `as`: `ElementType`, `translucent`: `boolean`, `surface`: `Surface`
- **Best Practices**:
  - ✅ DO: Use Box as a generic container when Flex or Grid structure is not needed.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media panels with bottom-aligned text.
  - ❌ DON'T: Do not nest <video> children manually — use bgVideo prop for automatic media layer rendering.
- **Sample Declaration**:
```tsx
<Box className="p-4 border border-hairline rounded-[var(--radius-panel)] bg-surface">Content</Box>
```

#### `<Container>`
- **Documentation**: [https://docs.shavin.cc/components/container](https://docs.shavin.cc/components/container)
- **Description**: Width-constrained content container with size presets (xs to full) and background media props. Useful for centered hero content with full-bleed media backdrops.
- **Import**: `import { Container } from "@shavin/ui";`
- **Variants**: `size` ("xs" | "sm" | "md" | "lg" | "xl" | "full")
- **Default Variants**: {"size":"md"}
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`, `as`: `ElementType`, `translucent`: `boolean`, `surface`: `Surface`
- **Best Practices**:
  - ✅ DO: Use Container inside Section to constrain content width within full-bleed sections.
  - ✅ DO: Use bgImage with dark-50 overlay + surface=dark for centered hero content over media.
  - ❌ DON'T: Do not wrap media in nested divs — pass bgVideo/bgImage directly to Container.
- **Sample Declaration**:
```tsx
<Container size="md"><Heading size="xl">Title</Heading><Text>Content here.</Text></Container>
```

#### `<Flex>`
- **Documentation**: [https://docs.shavin.cc/components/flex](https://docs.shavin.cc/components/flex)
- **Description**: Flexbox container primitive supporting token gap scale, direction, alignment, justification, polymorphic tag rendering, and background media props (bgVideo, bgImage, bgOverlays, bgSize, bgVideoPaused).
- **Import**: `import { Flex } from "@shavin/ui";`
- **Variants**: `direction` ("row" | "column" | "col" | "row-reverse" | "column-reverse" | "col-reverse"); `align` ("start" | "center" | "end" | "stretch" | "baseline"); `justify` ("start" | "center" | "end" | "between" | "around"); `wrap` ("nowrap" | "wrap")
- **Default Variants**: {"direction":"row","align":"stretch","justify":"start","wrap":"nowrap","gap":"3"}
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`, `as`: `ElementType`, `translucent`: `boolean`, `surface`: `Surface`
- **Best Practices**:
  - ✅ DO: Use Flex for 1-dimensional row or column item alignment with token-spaced gaps.
  - ❌ DON'T: Do not write arbitrary inline flex utility strings when Flex primitive provides structured token props.
  - ✅ DO: Use bgVideo / bgImage props for media backgrounds instead of hand-crafting <video> or <img> children with absolute positioning.
- **Sample Declaration**:
```tsx
<Flex align="center" justify="between" gap="4"><div>Title</div><Button size="sm">Action</Button></Flex>
```

#### `<Grid>`
- **Documentation**: [https://docs.shavin.cc/components/grid](https://docs.shavin.cc/components/grid)
- **Description**: CSS Grid container primitive supporting column/row counts, token gap scale, cross-axis alignment, and background media props (bgVideo, bgImage, bgOverlays, bgSize, bgVideoPaused).
- **Import**: `import { Grid } from "@shavin/ui";`
- **Variants**: `columns` ("1" | "2" | "3" | "4" | "5" | "6"); `rows` ("1" | "2" | "3" | "4" | "5" | "6"); `align` ("start" | "center" | "end" | "stretch"); `gap` ("0" | "1" | "2" | "3" | "4" | "5" | "6" | "7")
- **Default Variants**: {"columns":"2","align":"stretch","gap":"4"}
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`, `as`: `ElementType`, `translucent`: `boolean`, `surface`: `Surface`
- **Best Practices**:
  - ✅ DO: Use Grid for 2-dimensional layouts with equal-width columns and token gap spacing.
  - ❌ DON'T: Do not mix arbitrary grid-cols-* utilities when Grid primitive provides structured column props.
  - ✅ DO: Use bgVideo / bgImage for shared media backdrops across grid items — the primitive renders the media layer behind all children.
- **Sample Declaration**:
```tsx
<Grid columns="3" gap="4"><Card padding="md">Item 1</Card><Card padding="md">Item 2</Card><Card padding="md">Item 3</Card></Grid>
```

#### `<Inset>`
- **Documentation**: [https://docs.shavin.cc/components/inset](https://docs.shavin.cc/components/inset)
- **Description**: Card layout helper component that bleeds content to container edges using negative margin scale math.
- **Import**: `import { Inset } from "@shavin/ui";`
- **Variants**: `p` ("sm" | "md"); `side` ("all" | "top" | "bottom" | "x")
- **Default Variants**: {"p":"sm","side":"all"}
- **Props**: `clip`: `boolean`
- **Best Practices**:
  - ✅ DO: Use Inset inside Card for edge-to-edge header images, full-bleed code blocks, or maps.
  - ❌ DON'T: Do not manually write hardcoded negative margins like -mx-5 -mt-5 — use Inset p='md' side='top' instead.
- **Sample Declaration**:
```tsx
<Card p="sm"><Inset side="top" p="sm" clip><Image src="cover.jpg" ratio="16/9" /></Inset><div>Card Body Content</div></Card>
```

#### `<Layout>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<Sidebar>...</Sidebar>}><main className="p-6">Content</main></AppFrame>
```

#### `<NavItem>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Props**: `active`: `boolean`, `icon`: `ReactNode`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<NavRail collapsible><NavItem active icon={<Home />}>Dashboard</NavItem></NavRail>}><div>Main Dashboard Content</div></AppFrame>
```

#### `<NavRail>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`, `collapsible`: `boolean`, `collapsed`: `boolean`, `defaultCollapsed`: `boolean`, `onCollapsedChange`: `(collapsed: boolean) => void`, `togglePosition`: `"top" | "bottom"`, `toggleLabel`: `string`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<NavRail collapsible><NavItem active icon={<Home />}>Dashboard</NavItem></NavRail>}><div>Main Dashboard Content</div></AppFrame>
```

#### `<NavSectionLabel>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<NavRail collapsible><NavItem active icon={<Home />}>Dashboard</NavItem></NavRail>}><div>Main Dashboard Content</div></AppFrame>
```

#### `<ProfileTrigger>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Application layout shell frame components providing collapsible sidebar navigation rail, section headings, and profile triggers.
- **Import**: `import { AppFrame, NavItem, NavRail, NavSectionLabel, ProfileTrigger } from "@shavin/ui";`
- **Props**: `name` (required): `string`, `avatarUrl`: `string | null`
- **Best Practices**:
  - ✅ DO: Use AppFrame and NavRail for application dashboards, admin consoles, and SaaS app shells.
  - ❌ DON'T: Do not use NavRail for simple single-page marketing websites.
- **Sample Declaration**:
```tsx
<AppFrame sidebar={<NavRail collapsible><NavItem active icon={<Home />}>Dashboard</NavItem></NavRail>}><div>Main Dashboard Content</div></AppFrame>
```

#### `<Section>`
- **Documentation**: [https://docs.shavin.cc/components/section](https://docs.shavin.cc/components/section)
- **Description**: Vertical-rhythm section primitive with padding presets (1-4) and background media props. Ideal for full-bleed hero bands with bgVideo or bgImage.
- **Import**: `import { Section } from "@shavin/ui";`
- **Variants**: `size` ("1" | "2" | "3" | "4")
- **Default Variants**: {"size":"2"}
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`, `as`: `ElementType`, `translucent`: `boolean`, `surface`: `Surface`
- **Best Practices**:
  - ✅ DO: Use Section for page-level vertical rhythm bands — combine with Container inside for content width constraint.
  - ✅ DO: Use bgVideo + bgOverlays=\"dark-50\" + surface=\"dark\" for full-bleed hero sections with readable white text.
  - ❌ DON'T: Do not manually position <video> elements with absolute utilities — use the bgVideo prop instead.
- **Sample Declaration**:
```tsx
<Section size="2"><Container size="md"><Heading size="xl">Section Title</Heading><Text>Content goes here.</Text></Container></Section>
```

#### `<Sidebar>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Props**: `side`: `"left" | "right"`, `variant`: `"fixed" | "collapsible" | "floating" | "inset"`, `collapsibleMode`: `"icon" | "offcanvas" | "none"`, `collapsed`: `boolean`, `onCollapsedChange`: `(collapsed: boolean) => void`, `defaultCollapsed`: `boolean`, `width`: `string`, `resizable`: `boolean`, `minWidth`: `number`, `maxWidth`: `number`, `children`: `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarBody>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarFooter>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarHeader>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarNavItem>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Props**: `icon`: `ReactNode`, `label` (required): `string`, `active`: `boolean`, `badge`: `ReactNode`, `href`: `string`, `onClick`: `() => void`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarSection>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Props**: `title`: `string`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<SidebarTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/sidebar](https://docs.shavin.cc/components/sidebar)
- **Description**: Comprehensive sidebar layout primitive supporting left/right docking, collapsible modes, resizability, and compound sub-components.
- **Import**: `import { Sidebar, SidebarBody, SidebarFooter, SidebarHeader, SidebarNavItem, SidebarSection, SidebarTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Sidebar for left navigation rails, right inspector panels, and dashboard control drawers.
  - ❌ DON'T: Do not create ad-hoc sidebar panels using raw divs — use Sidebar with SidebarHeader, SidebarBody, and SidebarFooter for consistent layout rhythm.
- **Sample Declaration**:
```tsx
<Sidebar variant="collapsible"><SidebarHeader><SidebarTrigger /></SidebarHeader><SidebarBody><SidebarSection title="App"><SidebarNavItem label="Overview" active /></SidebarSection></SidebarBody></Sidebar>
```

#### `<TopBar>`
- **Documentation**: [https://docs.shavin.cc/foundations/app-shell](https://docs.shavin.cc/foundations/app-shell)
- **Description**: Header bar chrome component for page headers, breadcrumbs, search bars, and action toolbars.
- **Import**: `import { TopBar } from "@shavin/ui";`
- **Props**: `children`: `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use TopBar at the top of main content columns to host breadcrumbs, page titles, and action buttons.
  - ❌ DON'T: Do not put primary application navigation inside TopBar — reach for NavRail or Sidebar instead.
- **Sample Declaration**:
```tsx
<TopBar><Breadcrumbs items={[{ label: "Dashboard", href: "/" }, { label: "Analytics" }]} /><Button variant="soft" size="sm">Export</Button></TopBar>
```


### Typography (10 components)

#### `<Blockquote>`
- **Documentation**: [https://docs.shavin.cc/components/typography/quotes](https://docs.shavin.cc/components/typography/quotes)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`, `cite`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Code>`
- **Documentation**: [https://docs.shavin.cc/components/typography/code-kbd](https://docs.shavin.cc/components/typography/code-kbd)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Em>`
- **Documentation**: [https://docs.shavin.cc/components/typography/em-strong](https://docs.shavin.cc/components/typography/em-strong)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Heading>`
- **Documentation**: [https://docs.shavin.cc/components/typography/headings](https://docs.shavin.cc/components/typography/headings)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `as`: `ElementType`, `truncate`: `boolean`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Kbd>`
- **Documentation**: [https://docs.shavin.cc/components/typography/code-kbd](https://docs.shavin.cc/components/typography/code-kbd)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Link>`
- **Documentation**: [https://docs.shavin.cc/components/typography/links](https://docs.shavin.cc/components/typography/links)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `size`: `"xs" | "sm" | "md" | "lg"`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Quote>`
- **Documentation**: [https://docs.shavin.cc/components/typography/em-strong](https://docs.shavin.cc/components/typography/em-strong)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Strong>`
- **Documentation**: [https://docs.shavin.cc/components/typography/em-strong](https://docs.shavin.cc/components/typography/em-strong)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Text>`
- **Documentation**: [https://docs.shavin.cc/components/typography/body](https://docs.shavin.cc/components/typography/body)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Props**: `as`: `ElementType`, `truncate`: `boolean`
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<div><Heading size="2xl" as="h1">Dashboard Overview</Heading><Text size="sm" color="muted">View system performance and active project metrics.</Text></div>
```

#### `<Typography>`
- **Documentation**: [https://docs.shavin.cc/foundations/typography/overview](https://docs.shavin.cc/foundations/typography/overview)
- **Description**: Core typography primitives (Heading, Text, Em, Strong, Quote, Blockquote, Code, Kbd, Link) for system prose styling.
- **Import**: `import { Blockquote, Code, Em, Heading, Kbd, Link, Quote, Strong, Text } from "@shavin/ui";`
- **Variants**: `size` ("inherit" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4" | "5" | "6" | "7" | "8" | "9" | "xs" | "overline" | "1" | "2" | "3"); `weight` ("inherit" | "normal" | "medium" | "semibold" | "bold"); `truncate` ("true" | "false"); `color` ("inherit" | "default" | "fg" | "muted" | "subtle" | "danger" | "link" | "accent"); `underline` ("always" | "hover" | "none")
- **Default Variants**: {"size":"inherit","weight":"inherit","truncate":"false","color":"default","underline":"hover"}
- **Best Practices**:
  - ✅ DO: Use Heading and Text with semantic tokens for consistent font hierarchy across application views.
  - ❌ DON'T: Do not use literal Tailwind font size classes like text-2xl or text-sm directly in components — reach for Heading or Text primitives.
- **Sample Declaration**:
```tsx
<Heading size="2xl">Welcome</Heading>
<Text color="subtle">Enterprise React design system.</Text>
```


### Buttons & Actions (4 components)

#### `<ActionBar>`
- **Documentation**: [https://docs.shavin.cc/components/action-bar](https://docs.shavin.cc/components/action-bar)
- **Description**: Floating action bar pill for canvas tools, block insertion, and rich editor controls with searchable popovers.
- **Import**: `import { ActionBar } from "@shavin/ui";`
- **Props**: `groups` (required): `ActionBarGroup[]`, `onAction`: `(groupKey: string, value: string) => void`, `onInsert`: `(groupKey: string, value: string) => void`, `className`: `string`, `ariaLabel`: `string`
- **Best Practices**:
  - ✅ DO: Use ActionBar for canvas editing tools (e.g. Add Component, Theme Switcher, Zoom Controls).
  - ❌ DON'T: Do not use ActionBar for primary page navigation — reach for TopBar or Tabs instead.
- **Sample Declaration**:
```tsx
<ActionBar groups={[{ key: "actions", label: "Actions", items: [{ value: "edit", label: "Edit" }, { value: "delete", label: "Delete" }] }]} onSelect={(val) => console.log(val)} />
```

#### `<Button>`
- **Documentation**: [https://docs.shavin.cc/components/button](https://docs.shavin.cc/components/button)
- **Description**: General-purpose trigger for in-page actions (toolbars, forms, cards, action bars).
- **Import**: `import { Button } from "@shavin/ui";`
- **Variants**: `variant` ("solid" | "soft" | "outline" | "ghost"); `tone` ("accent" | "danger"); `size` ("sm" | "md" | "lg")
- **Default Variants**: {"variant":"solid","tone":"accent","size":"md"}
- **Props**: `asChild`: `boolean`, `truncate`: `boolean`, `iconLeft`: `ReactNode`, `iconRight`: `ReactNode`
- **Best Practices**:
  - ✅ DO: Use variant='solid' tone='accent' for primary action in a container or form.
  - ✅ DO: Use variant='ghost' or variant='soft' for secondary/toolbar actions to preserve visual hierarchy.
  - ❌ DON'T: Do not place two solid accent buttons adjacent to each other in the same action bar.
- **Sample Declaration**:
```tsx
<Button variant="solid" tone="accent">Save Changes</Button>
```

#### `<CloseButton>`
- **Documentation**: [https://docs.shavin.cc/components/dialog](https://docs.shavin.cc/components/dialog)
- **Description**: Accessible modal dialog built on Radix Dialog primitive with focus trapping, ESC key dismiss, and entry/exit transitions.
- **Import**: `import { CloseButton, Dialog } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg")
- **Default Variants**: {"size":"sm"}
- **Best Practices**:
  - ✅ DO: Always provide a clear, actionable title and primary footer button.
  - ❌ DON'T: Do not use Dialog for quick non-blocking notifications — reach for Toast instead.
- **Sample Declaration**:
```tsx
<CloseButton onClick={handleClose} size="md" aria-label="Close dialog" />
```

#### `<IconButton>`
- **Documentation**: [https://docs.shavin.cc/components/icon-button](https://docs.shavin.cc/components/icon-button)
- **Description**: Square icon-only action button primitive enforcing mandatory aria-label prop and control radius (--radius-lg).
- **Import**: `import { IconButton } from "@shavin/ui";`
- **Variants**: `variant` ("solid" | "soft" | "outline" | "ghost"); `tone` ("accent" | "danger"); `size` ("sm" | "md" | "lg")
- **Default Variants**: {"variant":"solid","tone":"accent","size":"md"}
- **Props**: `children` (required): `ReactNode`
- **Best Practices**:
  - ✅ DO: Always pass a descriptive aria-label (e.g. aria-label='Close dialog').
  - ❌ DON'T: Do not pass visible text children — reach for Button instead.
- **Sample Declaration**:
```tsx
<IconButton aria-label="Open settings" variant="ghost"><Settings className="h-5 w-5" /></IconButton>
```


### Form Controls (17 components)

#### `<Checkbox>`
- **Documentation**: [https://docs.shavin.cc/components/checkbox](https://docs.shavin.cc/components/checkbox)
- **Description**: Boolean selection control built on Radix Checkbox primitive with control radius (--radius-lg) and custom checkmark indicator.
- **Import**: `import { Checkbox } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md")
- **Default Variants**: {"size":"md"}
- **Props**: `label`: `string`
- **Best Practices**:
  - ✅ DO: Use Checkbox for binary independent choices or terms acceptance.
  - ❌ DON'T: Do not use Checkbox for mutually exclusive single choice selections — reach for RadioGroup or Switch instead.
- **Sample Declaration**:
```tsx
<Checkbox label="Accept Terms and Conditions" defaultChecked />
```

#### `<CheckboxCards>`
- **Documentation**: [https://docs.shavin.cc/components/checkbox](https://docs.shavin.cc/components/checkbox)
- **Description**: Multi-select option cards grid combining custom card containers with built-in Radix Checkbox controls.
- **Import**: `import { CheckboxCards, CheckboxCardsItem } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use CheckboxCards when selecting multiple options that need rich visual titles, icons, or pricing details.
  - ❌ DON'T: Do not use CheckboxCards for single-choice selection — reach for RadioGroup with variant='cards' instead.
- **Sample Declaration**:
```tsx
<CheckboxCards><CheckboxCardsItem checked={true} onCheckedChange={() => {}}>Advanced Analytics</CheckboxCardsItem></CheckboxCards>
```

#### `<CheckboxCardsItem>`
- **Documentation**: [https://docs.shavin.cc/components/checkbox](https://docs.shavin.cc/components/checkbox)
- **Description**: Multi-select option cards grid combining custom card containers with built-in Radix Checkbox controls.
- **Import**: `import { CheckboxCards, CheckboxCardsItem } from "@shavin/ui";`
- **Props**: `checked` (required): `boolean`, `onCheckedChange` (required): `(checked: boolean) => void`, `children` (required): `ReactNode`, `disabled`: `boolean`, `style`: `CSSProperties`
- **Best Practices**:
  - ✅ DO: Use CheckboxCards when selecting multiple options that need rich visual titles, icons, or pricing details.
  - ❌ DON'T: Do not use CheckboxCards for single-choice selection — reach for RadioGroup with variant='cards' instead.
- **Sample Declaration**:
```tsx
<CheckboxCards><CheckboxCardsItem checked={true} onCheckedChange={() => {}}>Advanced Analytics</CheckboxCardsItem></CheckboxCards>
```

#### `<CheckboxGroup>`
- **Documentation**: [https://docs.shavin.cc/components/checkbox](https://docs.shavin.cc/components/checkbox)
- **Description**: Vertical multi-select list wrapper built with semantic role='group' accessibility container.
- **Import**: `import { CheckboxGroup, CheckboxGroupItem } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use CheckboxGroup for vertical lists of multi-select form fields.
  - ❌ DON'T: Do not use CheckboxGroup for mutually exclusive options — reach for RadioGroup instead.
- **Sample Declaration**:
```tsx
<CheckboxGroup><CheckboxGroupItem label="Email Alerts" checked={true} onCheckedChange={() => {}} /><CheckboxGroupItem label="SMS Notifications" checked={false} onCheckedChange={() => {}} /></CheckboxGroup>
```

#### `<CheckboxGroupItem>`
- **Documentation**: [https://docs.shavin.cc/components/checkbox](https://docs.shavin.cc/components/checkbox)
- **Description**: Vertical multi-select list wrapper built with semantic role='group' accessibility container.
- **Import**: `import { CheckboxGroup, CheckboxGroupItem } from "@shavin/ui";`
- **Props**: `checked` (required): `boolean`, `onCheckedChange` (required): `(checked: boolean) => void`, `label` (required): `string`, `disabled`: `boolean`
- **Best Practices**:
  - ✅ DO: Use CheckboxGroup for vertical lists of multi-select form fields.
  - ❌ DON'T: Do not use CheckboxGroup for mutually exclusive options — reach for RadioGroup instead.
- **Sample Declaration**:
```tsx
<CheckboxGroup><CheckboxGroupItem label="Email Alerts" checked={true} onCheckedChange={() => {}} /><CheckboxGroupItem label="SMS Notifications" checked={false} onCheckedChange={() => {}} /></CheckboxGroup>
```

#### `<Combobox>`
- **Documentation**: [https://docs.shavin.cc/components/combobox](https://docs.shavin.cc/components/combobox)
- **Description**: Searchable autocomplete dropdown control combining text input typing with filtered Radix Popover item selection.
- **Import**: `import { Combobox } from "@shavin/ui";`
- **Props**: `value` (required): `string`, `onChange` (required): `(value: string) => void`, `options` (required): `string[]`, `prettyOptionLabel`: `(val: string) => string`, `size`: `"sm" | "md"`
- **Best Practices**:
  - ✅ DO: Use Combobox when selecting from large datasets (>10 items) where typing to filter enhances speed.
  - ❌ DON'T: Do not use Combobox for small static option lists (<= 5 items) — reach for Select or RadioGroup instead.
- **Sample Declaration**:
```tsx
<Combobox value="United States" options={["Canada", "Mexico", "United Kingdom", "United States"]} onChange={() => {}} />
```

#### `<Dropdown>`
- **Documentation**: [https://docs.shavin.cc/components/dropdown](https://docs.shavin.cc/components/dropdown)
- **Description**: Simple select dropdown supporting both custom styled popup panel and native HTML <select> mobile rendering.
- **Import**: `import { Dropdown } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md"); `appearance` ("default" | "ghost")
- **Default Variants**: {"size":"md","appearance":"default"}
- **Props**: `value` (required): `string`, `onChange` (required): `(v: string) => void`, `options` (required): `DropdownOption[]`, `disabled`: `boolean`, `variant`: `"native" | "default"`, `ariaLabel`: `string`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use appearance='ghost' for inline toolbar filters.
  - ❌ DON'T: Do not use Dropdown for complex multi-select or searchable items — use Combobox instead.
- **Sample Declaration**:
```tsx
<Dropdown value={value} onChange={(e) => setValue(e.target.value)} options={[{ value: "all", label: "All Items" }, { value: "active", label: "Active" }, { value: "archived", label: "Archived" }]} />
```

#### `<Radio>`
- **Documentation**: [https://docs.shavin.cc/components/radio-group](https://docs.shavin.cc/components/radio-group)
- **Description**: Single-choice radio selection group built on Radix RadioGroup primitive supporting radio buttons and selectable card grid layouts.
- **Import**: `import { Radio, RadioGroup } from "@shavin/ui";`
- **Variants**: `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"radius":"inherit"}
- **Props**: `value` (required): `string`, `label`: `string`, `description`: `string`, `disabled`: `boolean`, `radius`: `RadiusPreset`, `variant`: `"default" | "cards"`, `className`: `string`, `children`: `ReactNode`
- **Best Practices**:
  - ✅ DO: Use RadioGroup for mutually exclusive choices when all options should be visible at once.
  - ❌ DON'T: Do not use RadioGroup if options exceed 6 — reach for Select instead.
- **Sample Declaration**:
```tsx
<RadioGroup defaultValue="monthly"><Radio value="monthly" label="Monthly Billing" /><Radio value="annual" label="Annual Billing" /></RadioGroup>
```

#### `<RadioGroup>`
- **Documentation**: [https://docs.shavin.cc/components/radio-group](https://docs.shavin.cc/components/radio-group)
- **Description**: Single-choice radio selection group built on Radix RadioGroup primitive supporting radio buttons and selectable card grid layouts.
- **Import**: `import { Radio, RadioGroup } from "@shavin/ui";`
- **Variants**: `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"radius":"inherit"}
- **Props**: `variant`: `"default" | "cards"`, `radius`: `RadiusPreset`
- **Best Practices**:
  - ✅ DO: Use RadioGroup for mutually exclusive choices when all options should be visible at once.
  - ❌ DON'T: Do not use RadioGroup if options exceed 6 — reach for Select instead.
- **Sample Declaration**:
```tsx
<RadioGroup defaultValue="monthly"><Radio value="monthly" label="Monthly Billing" /><Radio value="annual" label="Annual Billing" /></RadioGroup>
```

#### `<SegmentedControl>`
- **Documentation**: [https://docs.shavin.cc/components/segmented-control](https://docs.shavin.cc/components/segmented-control)
- **Description**: Exclusive single-select toggle group built on Radix ToggleGroup primitive supporting default, pill, expand, and icon variants.
- **Import**: `import { SegmentedControl, SegmentedControlItem } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "pill" | "expand" | "icon"); `size` ("sm" | "md")
- **Default Variants**: {"variant":"default","size":"md"}
- **Props**: `size`: `Size`, `variant`: `Variant`, `iconOnly`: `boolean`
- **Best Practices**:
  - ✅ DO: Use SegmentedControl for compact inline view switchers (e.g. List vs Grid).
  - ❌ DON'T: Do not use SegmentedControl for long multi-page tab routing — reach for Tabs instead.
- **Sample Declaration**:
```tsx
<SegmentedControl value="list" onValueChange={() => {}}><SegmentedControlItem value="list">List</SegmentedControlItem><SegmentedControlItem value="grid">Grid</SegmentedControlItem></SegmentedControl>
```

#### `<SegmentedControlItem>`
- **Documentation**: [https://docs.shavin.cc/components/segmented-control](https://docs.shavin.cc/components/segmented-control)
- **Description**: Exclusive single-select toggle group built on Radix ToggleGroup primitive supporting default, pill, expand, and icon variants.
- **Import**: `import { SegmentedControl, SegmentedControlItem } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "pill" | "expand" | "icon"); `size` ("sm" | "md")
- **Default Variants**: {"variant":"default","size":"md"}
- **Props**: `value` (required): `string`, `children`: `ReactNode`, `icon`: `ReactNode`, `label`: `ReactNode`, `disabled`: `boolean`
- **Best Practices**:
  - ✅ DO: Use SegmentedControl for compact inline view switchers (e.g. List vs Grid).
  - ❌ DON'T: Do not use SegmentedControl for long multi-page tab routing — reach for Tabs instead.
- **Sample Declaration**:
```tsx
<SegmentedControl value="list" onValueChange={() => {}}><SegmentedControlItem value="list">List</SegmentedControlItem><SegmentedControlItem value="grid">Grid</SegmentedControlItem></SegmentedControl>
```

#### `<Select>`
- **Documentation**: [https://docs.shavin.cc/components/select](https://docs.shavin.cc/components/select)
- **Description**: Accessible dropdown select control built on Radix Select primitive with option grouping and viewport collision positioning.
- **Import**: `import { Select } from "@shavin/ui";`
- **Props**: `value` (required): `string`, `options` (required): `(Option | OptionGroup)[]`, `onChange` (required): `(v: string) => void`, `onItemHighlight`: `(v: string | null) => void`, `ariaLabel`: `string`, `placeholder`: `string`, `className`: `string`, `contentClassName`: `string`, `contentStyle`: `React.CSSProperties`, `size`: `"sm" | "md"`
- **Best Practices**:
  - ✅ DO: Use Select for single-choice option picker with 5+ options.
  - ❌ DON'T: Do not pass value='' inside option arrays — empty string sentinel is forbidden in Radix Select.
- **Sample Declaration**:
```tsx
<Select value={selected} onValueChange={setSelected} options={[{ value: "grass", label: "Grass" }, { value: "indigo", label: "Indigo" }, { value: "ruby", label: "Ruby" }]} placeholder="Select a color" />
```

#### `<Slider>`
- **Documentation**: [https://docs.shavin.cc/components/slider](https://docs.shavin.cc/components/slider)
- **Description**: Range slider input primitive built on Radix Slider supporting single or dual thumb values, track marks, and radius customization.
- **Import**: `import { Slider } from "@shavin/ui";`
- **Variants**: `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"radius":"inherit"}
- **Props**: `marks`: `number[]`
- **Best Practices**:
  - ✅ DO: Use Slider for numeric range selection such as volume, price filters, or opacity settings.
  - ❌ DON'T: Do not use Slider for small discrete selection sets (<= 4 options) — reach for SegmentedControl instead.
- **Sample Declaration**:
```tsx
<Slider defaultValue={[45]} min={0} max={100} step={1} />
```

#### `<Stepper>`
- **Documentation**: [https://docs.shavin.cc/components/stepper](https://docs.shavin.cc/components/stepper)
- **Description**: Data-driven multi-step progress stepper component for checkout wizards, onboarding flows, dialog sequences, and status trackers.
- **Import**: `import { Stepper } from "@shavin/ui";`
- **Props**: `steps` (required): `Step[]`, `current` (required): `number`, `orientation`: `"horizontal" | "vertical"`, `variant`: `"default" | "cards" | "pills"`, `size`: `"sm" | "md"`, `onStepClick`: `(stepIndex: number) => void`, `clickable`: `boolean | "completed" | "all"`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use variant='cards' for multi-step modal headers and onboarding wizards where each step needs clear context.
  - ✅ DO: Pass onStepClick to allow users to navigate back to completed steps.
  - ❌ DON'T: Do not use Stepper for non-sequential, random-access tabs — reach for Tabs instead.
- **Sample Declaration**:
```tsx
<Stepper activeStep={1} steps={[{ title: "Guidelines", description: "Review standards" }, { title: "Account", description: "Personal details" }, { title: "Confirm", description: "Verification" }]} />
```

#### `<Switch>`
- **Documentation**: [https://docs.shavin.cc/components/switch](https://docs.shavin.cc/components/switch)
- **Description**: Toggle switch control built on Radix Switch primitive with pill rounded-full track and animated sliding thumb handle.
- **Import**: `import { Switch } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md")
- **Default Variants**: {"size":"md"}
- **Best Practices**:
  - ✅ DO: Use Switch for instant system setting toggles (e.g. Dark Mode, Notifications).
  - ❌ DON'T: Do not use Switch for form items requiring a manual Submit button — reach for Checkbox instead.
- **Sample Declaration**:
```tsx
<Switch defaultChecked size="md" />
```

#### `<TextArea>`
- **Documentation**: [https://docs.shavin.cc/components/text-area](https://docs.shavin.cc/components/text-area)
- **Description**: Multi-line text input control with control radius (--radius-lg) and custom error state styling.
- **Import**: `import { TextArea } from "@shavin/ui";`
- **Variants**: `invalid` ("true" | "false")
- **Default Variants**: {"invalid":"false"}
- **Best Practices**:
  - ✅ DO: Use TextArea for multi-line inputs such as feedback forms, bio descriptions, and comment fields.
  - ❌ DON'T: Do not use TextArea for single-line inputs — reach for TextField instead.
- **Sample Declaration**:
```tsx
<TextArea rows={4} placeholder="Describe your experience..." />
```

#### `<TextField>`
- **Documentation**: [https://docs.shavin.cc/components/text-field](https://docs.shavin.cc/components/text-field)
- **Description**: Single-line text input control with control radius (--radius-lg), leading/trailing icon slots, and optional label/hint wrapper.
- **Import**: `import { TextField } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg"); `invalid` ("true" | "false")
- **Default Variants**: {"size":"md","invalid":"false"}
- **Props**: `leadingIcon`: `ReactNode`, `trailingIcon`: `ReactNode`, `label`: `string`, `hint`: `string`, `length`: `number | string`, `mask`: `boolean`, `separator`: `ReactNode`, `separatorIndex`: `number`, `onComplete`: `(code: string) => void`, `slotClassName`: `string`, `showHidePassword`: `boolean`, `errorMessage`: `string`
- **Best Practices**:
  - ✅ DO: Use TextField for single-line text inputs (names, emails, search queries).
  - ❌ DON'T: Do not use TextField for multi-line text input — reach for TextArea instead.
- **Sample Declaration**:
```tsx
<TextField label="Email Address" placeholder="alex@company.com" hint="We will never share your email." />
```


### Pickers & Selection (6 components)

#### `<ColorPicker>`
- **Documentation**: [https://docs.shavin.cc/components/color-picker](https://docs.shavin.cc/components/color-picker)
- **Description**: Color picker control supporting preset swatches, native HTML5 eyedropper pipette, and direct hex or RGB string input.
- **Import**: `import { ColorPicker } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg" | "full")
- **Default Variants**: {"size":"md"}
- **Props**: `value` (required): `string`, `onChange` (required): `(hex: string) => void`, `variant`: `"default" | "field" | "canvas"`, `opacity`: `number`, `onOpacityChange`: `(opacity: number) => void`, `presets`: `ColorPickerSwatch[]`, `swatchLayout`: `"grid" | "scroll"`, `maxSwatches`: `number`, `colorMode`: `"hex" | "rgb"`, `customLabel`: `React.ReactNode`, `customLabelClassName`: `string`, `allowCustom`: `boolean`
- **Best Practices**:
  - ✅ DO: Use ColorPicker in design system configurators, theme customizers, or canvas drawing tools.
  - ❌ DON'T: Do not use ColorPicker when selecting from a tiny closed set (<= 3 choices) — reach for RadioGroup or Select instead.
- **Sample Declaration**:
```tsx
<ColorPicker value="#46a758" onChange={() => {}} variant="default" swatchLayout="grid" />
```

#### `<DatePicker>`
- **Documentation**: [https://docs.shavin.cc/components/date-picker](https://docs.shavin.cc/components/date-picker)
- **Description**: Standalone themeable date and time picker with portal popup calendar, editable text draft input, and customizable token styling.
- **Import**: `import { DatePicker } from "@shavin/ui";`
- **Props**: `value` (required): `Date`, `onChange` (required): `(d: Date) => void`, `dateOnly`: `boolean`, `tokens`: `Partial<DatePickerTokens>`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use DatePicker for form date selection (e.g. Birthdays, Scheduling, Event dates).
  - ❌ DON'T: Do not use DatePicker for static inline event calendar displays — reach for Calendar primitive instead.
- **Sample Declaration**:
```tsx
<DatePicker value={new Date()} onChange={() => {}} dateOnly={false} />
```

#### `<IconPicker>`
- **Documentation**: [https://docs.shavin.cc/components/icon-picker](https://docs.shavin.cc/components/icon-picker)
- **Description**: Searchable icon selection popover grid supporting Lucide icons for builder, form customizers, and toolbar triggers.
- **Import**: `import { ICON_REGISTRY, IconPicker } from "@shavin/ui";`
- **Props**: `value` (required): `string`, `onChange` (required): `(v: string) => void`, `children`: `React.ReactNode`, `variant`: `"default" | "icon"`, `size`: `"sm" | "md" | "lg"`, `allowNone`: `boolean`, `libraries`: `string[]`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use variant='icon' inside toolbars, action bars, or compact property panels.
  - ✅ DO: Use IconPicker in page builder tools or customization settings forms.
  - ❌ DON'T: Do not use IconPicker for simple static navigation links — use Button or MenuItem instead.
- **Sample Declaration**:
```tsx
<IconPicker value="sparkles" onChange={(v) => console.log(v)} allowNone />
```

#### `<TimePicker>`
- **Documentation**: [https://docs.shavin.cc/components/time-picker](https://docs.shavin.cc/components/time-picker)
- **Description**: Time selection primitive supporting interval dropdown (TimePicker), segmented inputs (TimePickerInput), and analog clock face popover (TimePickerClock).
- **Import**: `import { TimePicker, TimePickerClock, TimePickerInput } from "@shavin/ui";`
- **Props**: `value` (required): `Date`, `onChange` (required): `(d: Date) => void`, `ariaLabel`: `string`, `intervalMinutes`: `number`
- **Best Practices**:
  - ✅ DO: Use TimePicker for appointment scheduling, meeting times, and reminders.
  - ❌ DON'T: Do not use TimePicker for duration inputs (e.g. 2 hours 15 minutes) — reach for TextField or Select instead.
- **Sample Declaration**:
```tsx
<TimePicker value={new Date()} onChange={() => {}} intervalMinutes={15} />
```

#### `<TimePickerClock>`
- **Documentation**: [https://docs.shavin.cc/components/time-picker](https://docs.shavin.cc/components/time-picker)
- **Description**: Time selection primitive supporting interval dropdown (TimePicker), segmented inputs (TimePickerInput), and analog clock face popover (TimePickerClock).
- **Import**: `import { TimePicker, TimePickerClock, TimePickerInput } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use TimePicker for appointment scheduling, meeting times, and reminders.
  - ❌ DON'T: Do not use TimePicker for duration inputs (e.g. 2 hours 15 minutes) — reach for TextField or Select instead.
- **Sample Declaration**:
```tsx
<TimePicker value={new Date()} onChange={() => {}} intervalMinutes={15} />
```

#### `<TimePickerInput>`
- **Documentation**: [https://docs.shavin.cc/components/time-picker](https://docs.shavin.cc/components/time-picker)
- **Description**: Time selection primitive supporting interval dropdown (TimePicker), segmented inputs (TimePickerInput), and analog clock face popover (TimePickerClock).
- **Import**: `import { TimePicker, TimePickerClock, TimePickerInput } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use TimePicker for appointment scheduling, meeting times, and reminders.
  - ❌ DON'T: Do not use TimePicker for duration inputs (e.g. 2 hours 15 minutes) — reach for TextField or Select instead.
- **Sample Declaration**:
```tsx
<TimePicker value={new Date()} onChange={() => {}} intervalMinutes={15} />
```


### Data Display (34 components)

#### `<Avatar>`
- **Documentation**: [https://docs.shavin.cc/components/avatar](https://docs.shavin.cc/components/avatar)
- **Description**: User avatar image with automatic initial-letter fallback built on Radix Avatar primitive.
- **Import**: `import { Avatar } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg" | "xl"); `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"size":"md","radius":"full"}
- **Props**: `src`: `string`, `alt`: `string`, `fallback`: `React.ReactNode`, `fallbackIcon`: `React.ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Always pass initials (e.g. fallback='JD') or an alt label for screen readers.
  - ❌ DON'T: Do not force radius='none' globally on avatars unless rendering a square badge or logo tile.
- **Sample Declaration**:
```tsx
<Avatar src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=100" fallback="JD" size="md" />
```

#### `<Badge>`
- **Documentation**: [https://docs.shavin.cc/components/badge](https://docs.shavin.cc/components/badge)
- **Description**: Status indicator pill component supporting semantic color schemes and control radius (--radius-lg).
- **Import**: `import { Badge } from "@shavin/ui";`
- **Variants**: `variant` ("surface" | "outline" | "soft" | "solid"); `tone` ("neutral" | "accent" | "success" | "warning" | "danger"); `size` ("sm" | "md" | "lg"); `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"variant":"surface","tone":"neutral","size":"md","radius":"inherit"}
- **Props**: `color`: `"neutral" | "accent" | "success" | "warning" | "danger"`, `icon`: `React.ReactNode`
- **Best Practices**:
  - ✅ DO: Use Badge for status tags, metadata counts, and status indicators.
  - ❌ DON'T: Do not use Badge as a clickable primary action button — reach for Button instead.
- **Sample Declaration**:
```tsx
<Badge color="success">Active</Badge>
```

#### `<Calendar>`
- **Documentation**: [https://docs.shavin.cc/components/calendar](https://docs.shavin.cc/components/calendar)
- **Description**: Full-featured schedule and event calendar primitive supporting full month grid and 1-day, 2-day, or 3-day time columns.
- **Import**: `import { Calendar, CalendarEventChip, CalendarView } from "@shavin/ui";`
- **Props**: `date`: `Date`, `defaultDate`: `Date`, `onDateChange`: `(date: Date) => void`, `view`: `CalendarViewMode`, `defaultView`: `CalendarViewMode`, `onViewChange`: `(view: CalendarViewMode) => void`, `allowedViews`: `CalendarViewMode[]`, `allowViewChange`: `boolean`, `startHour`: `number`, `endHour`: `number`, `events`: `CalendarEvent[]`, `onSelectDate`: `(date: Date) => void`, `onEventClick`: `(event: CalendarEvent) => void`, `fitContainer`: `boolean`, `className`: `string`, `style`: `CSSProperties`
- **Best Practices**:
  - ✅ DO: Use Calendar for dashboard scheduling views, event planners, and booking applications.
  - ❌ DON'T: Do not use Calendar inside a compact dropdown field — reach for DatePicker instead.
- **Sample Declaration**:
```tsx
<Calendar view="month" events={[{ id: "1", title: "Team Sync", date: "2026-09-18", time: "10:00 AM", tone: "info" }]} />
```

#### `<CalendarEventChip>`
- **Documentation**: [https://docs.shavin.cc/components/calendar](https://docs.shavin.cc/components/calendar)
- **Description**: Full-featured schedule and event calendar primitive supporting full month grid and 1-day, 2-day, or 3-day time columns.
- **Import**: `import { Calendar, CalendarEventChip, CalendarView } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Calendar for dashboard scheduling views, event planners, and booking applications.
  - ❌ DON'T: Do not use Calendar inside a compact dropdown field — reach for DatePicker instead.
- **Sample Declaration**:
```tsx
<CalendarEventChip event={{ id: "1", title: "Sprint Demo", date: "2026-09-18", time: "2:00 PM", tone: "accent" }} />
```

#### `<CalendarView>`
- **Documentation**: [https://docs.shavin.cc/components/calendar](https://docs.shavin.cc/components/calendar)
- **Description**: Full-featured schedule and event calendar primitive supporting full month grid and 1-day, 2-day, or 3-day time columns.
- **Import**: `import { Calendar, CalendarEventChip, CalendarView } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Calendar for dashboard scheduling views, event planners, and booking applications.
  - ❌ DON'T: Do not use Calendar inside a compact dropdown field — reach for DatePicker instead.
- **Sample Declaration**:
```tsx
<CalendarView view="month" currentDate={new Date()} />
```

#### `<Callout>`
- **Documentation**: [https://docs.shavin.cc/components/callout](https://docs.shavin.cc/components/callout)
- **Description**: High-visibility information container panel built with panel radius (--radius-panel) and semantic colors.
- **Import**: `import { Callout } from "@shavin/ui";`
- **Variants**: `color` ("neutral" | "accent" | "success" | "warning" | "danger")
- **Default Variants**: {"color":"neutral"}
- **Props**: `title`: `string`, `icon`: `React.ReactNode`
- **Best Practices**:
  - ✅ DO: Use Callout for important tips, warnings, or inline status updates.
  - ❌ DON'T: Do not use Callout for temporary floating notifications — reach for Toast instead.
- **Sample Declaration**:
```tsx
<Callout color="warning" title="Action Required">Please verify your email address before continuing.</Callout>
```

#### `<Card>`
- **Documentation**: [https://docs.shavin.cc/components/card](https://docs.shavin.cc/components/card)
- **Description**: Surface card primitive with padding presets (none to 3xl), interactive hover state, and background media props. Ideal for media-rich product cards and feature tiles.
- **Import**: `import { Card, CardList, CardListItem, CardRow, StatCard } from "@shavin/ui";`
- **Variants**: `padding` ("none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `interactive` ("true" | "false")
- **Default Variants**: {"padding":"sm","interactive":"false"}
- **Props**: `bgVideo`: `string`, `bgImage`: `string`, `bgSize`: `"cover" | "contain"`, `bgOverlays`: `string`, `bgVideoPaused`: `boolean`
- **Best Practices**:
  - ✅ DO: Use Card for grouped content blocks with consistent surface treatment and elevation.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media cards with bottom-aligned text.
  - ❌ DON'T: Do not embed <video> elements as children — pass bgVideo prop and the card handles media layer rendering.
- **Sample Declaration**:
```tsx
<Card padding="md">Card content</Card>
```

#### `<CardList>`
- **Documentation**: [https://docs.shavin.cc/components/card](https://docs.shavin.cc/components/card)
- **Description**: Surface card primitive with padding presets (none to 3xl), interactive hover state, and background media props. Ideal for media-rich product cards and feature tiles.
- **Import**: `import { Card, CardList, CardListItem, CardRow, StatCard } from "@shavin/ui";`
- **Variants**: `padding` ("none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `interactive` ("true" | "false")
- **Default Variants**: {"padding":"sm","interactive":"false"}
- **Best Practices**:
  - ✅ DO: Use Card for grouped content blocks with consistent surface treatment and elevation.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media cards with bottom-aligned text.
  - ❌ DON'T: Do not embed <video> elements as children — pass bgVideo prop and the card handles media layer rendering.
- **Sample Declaration**:
```tsx
<Card padding="md">Card content</Card>
```

#### `<CardListItem>`
- **Documentation**: [https://docs.shavin.cc/components/card](https://docs.shavin.cc/components/card)
- **Description**: Surface card primitive with padding presets (none to 3xl), interactive hover state, and background media props. Ideal for media-rich product cards and feature tiles.
- **Import**: `import { Card, CardList, CardListItem, CardRow, StatCard } from "@shavin/ui";`
- **Variants**: `padding` ("none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `interactive` ("true" | "false")
- **Default Variants**: {"padding":"sm","interactive":"false"}
- **Best Practices**:
  - ✅ DO: Use Card for grouped content blocks with consistent surface treatment and elevation.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media cards with bottom-aligned text.
  - ❌ DON'T: Do not embed <video> elements as children — pass bgVideo prop and the card handles media layer rendering.
- **Sample Declaration**:
```tsx
<Card padding="md">Card content</Card>
```

#### `<CardRow>`
- **Documentation**: [https://docs.shavin.cc/components/card](https://docs.shavin.cc/components/card)
- **Description**: Surface card primitive with padding presets (none to 3xl), interactive hover state, and background media props. Ideal for media-rich product cards and feature tiles.
- **Import**: `import { Card, CardList, CardListItem, CardRow, StatCard } from "@shavin/ui";`
- **Variants**: `padding` ("none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `interactive` ("true" | "false")
- **Default Variants**: {"padding":"sm","interactive":"false"}
- **Best Practices**:
  - ✅ DO: Use Card for grouped content blocks with consistent surface treatment and elevation.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media cards with bottom-aligned text.
  - ❌ DON'T: Do not embed <video> elements as children — pass bgVideo prop and the card handles media layer rendering.
- **Sample Declaration**:
```tsx
<Card padding="md">Card content</Card>
```

#### `<Chart>`
- **Documentation**: [https://docs.shavin.cc/components/chart](https://docs.shavin.cc/components/chart)
- **Description**: SVG-based data visualization component supporting bar, line, area, step, donut, and radar chart types.
- **Import**: `import { Chart } from "@shavin/ui";`
- **Props**: `data` (required): `ChartDataItem[]`, `type`: `| "bar"`, `series`: `ChartSeriesConfig[]`
- **Best Practices**:
  - ✅ DO: Use Chart for analytics dashboards, metric trends, and performance reports.
  - ❌ DON'T: Do not pass unformatted raw numbers if values represent currency or percentages — format labels beforehand.
- **Sample Declaration**:
```tsx
<Chart type="bar" data={[{ label: "Jan", value: 400 }, { label: "Feb", value: 650 }, { label: "Mar", value: 800 }]} />
```

#### `<ChatBubble>`
- **Documentation**: [https://docs.shavin.cc/components/chat-bubble](https://docs.shavin.cc/components/chat-bubble)
- **Description**: Messaging and AI chat transcript bubble component supporting incoming, outgoing, and system message variants.
- **Import**: `import { ChatBubble } from "@shavin/ui";`
- **Variants**: `variant` ("incoming" | "outgoing" | "system")
- **Default Variants**: {"variant":"incoming"}
- **Props**: `children` (required): `React.ReactNode`, `author`: `string`, `timestamp`: `string`, `avatarSrc`: `string`, `avatarFallback`: `string`, `hideAvatar`: `boolean`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use ChatBubble for building AI chat interfaces, customer support chats, and team messaging transcripts.
  - ❌ DON'T: Do not use ChatBubble for long editorial blog articles — reach for Section or Container instead.
- **Sample Declaration**:
```tsx
<ChatBubble variant="incoming" author="Shavin AI" avatarFallback="AI" timestamp="Just now">How can I assist you with your design system today?</ChatBubble>
```

#### `<CodeBlock>`
- **Documentation**: [https://docs.shavin.cc/components/code-block](https://docs.shavin.cc/components/code-block)
- **Description**: Syntax-highlighted code block component with integrated copy button and standalone or attached card variants.
- **Import**: `import { CodeBlock } from "@shavin/ui";`
- **Props**: `code` (required): `string`, `language`: `SupportedLanguage`, `appearance`: `"dark" | "light" | "auto"`, `theme`: `"dark" | "light" | "auto"`, `variant`: `"standalone" | "attached" | "collapsible" | "split"`, `collapsible`: `boolean`, `split`: `"vertical" | "horizontal"`, `previewPosition`: `"left" | "right" | "top" | "bottom"`, `children`: `ReactNode`, `wrap`: `boolean`, `copyable`: `boolean`, `state`: `"open" | "close"`, `defaultOpen`: `boolean`, `onStateChange`: `(state: "open" | "close") => void`, `description`: `string`, `title`: `string`
- **Best Practices**:
  - ✅ DO: Use CodeBlock for documentation code snippets, API responses, and CLI commands.
  - ❌ DON'T: Do not import massive heavy client-side syntax highlighter libraries — CodeBlock provides fast zero-dep highlighting.
- **Sample Declaration**:
```tsx
<CodeBlock code={`import { Button } from "@shavin/ui";\\n\\nexport default function App() {\\n  return <Button>Click me</Button>;\\n}`} />
```

#### `<CodeEditor>`
- **Documentation**: [https://docs.shavin.cc/components/code-editor](https://docs.shavin.cc/components/code-editor)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { CodeEditor } from "@shavin/ui";`
- **Props**: `value` (required): `string`, `onChange`: `(value: string) => void`, `filename`: `string`, `language`: `string`, `showLanguage`: `boolean`, `hideHeader`: `boolean`, `showHeader`: `boolean`, `theme`: `"dark" | "light" | "auto"`, `allowThemeToggle`: `boolean`, `readOnly`: `boolean`, `placeholder`: `string`, `minHeight`: `number | string`, `copyable`: `boolean`, `headerLeft`: `ReactNode`, `headerRight`: `ReactNode`, `footer`: `ReactNode`, `className`: `string`
- **Sample Declaration**:
```tsx
<CodeEditor value={code} onChange={setCode} language="typescript" />
```

#### `<DataList>`
- **Documentation**: [https://docs.shavin.cc/components/data-list](https://docs.shavin.cc/components/data-list)
- **Description**: Semantic key-value definition list primitive built on HTML <dl>, <dt>, and <dd> elements.
- **Import**: `import { DataList, DataListItem } from "@shavin/ui";`
- **Variants**: `orientation` ("vertical" | "horizontal")
- **Default Variants**: {"orientation":"vertical"}
- **Best Practices**:
  - ✅ DO: Use DataList for key-value property summaries in drawer inspectors, detail sidebars, or modal viewports.
  - ❌ DON'T: Do not use plain <div> or <span> pairs when displaying key-value properties — reach for DataList.
- **Sample Declaration**:
```tsx
<DataList orientation="vertical"><DataListItem label="Status">Active</DataListItem><DataListItem label="Role">Administrator</DataListItem></DataList>
```

#### `<DataListItem>`
- **Documentation**: [https://docs.shavin.cc/components/data-list](https://docs.shavin.cc/components/data-list)
- **Description**: Semantic key-value definition list primitive built on HTML <dl>, <dt>, and <dd> elements.
- **Import**: `import { DataList, DataListItem } from "@shavin/ui";`
- **Variants**: `orientation` ("vertical" | "horizontal")
- **Default Variants**: {"orientation":"vertical"}
- **Props**: `label` (required): `string`, `className`: `string`, `children` (required): `ReactNode`
- **Best Practices**:
  - ✅ DO: Use DataList for key-value property summaries in drawer inspectors, detail sidebars, or modal viewports.
  - ❌ DON'T: Do not use plain <div> or <span> pairs when displaying key-value properties — reach for DataList.
- **Sample Declaration**:
```tsx
<DataList orientation="vertical"><DataListItem label="Status">Active</DataListItem><DataListItem label="Role">Administrator</DataListItem></DataList>
```

#### `<Icon>`
- **Documentation**: [https://docs.shavin.cc/components/icon](https://docs.shavin.cc/components/icon)
- **Description**: Universal vector icon renderer with strict size tokens (xs to 3xl), numeric pixel scaling, semantic color tokens, and open SVG component wrapping.
- **Import**: `import { Icon } from "@shavin/ui";`
- **Variants**: `size` ("xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `color` ("default" | "subtle" | "muted" | "accent" | "contrast" | "success" | "warning" | "danger" | "inherit")
- **Default Variants**: {"size":"md","color":"default"}
- **Props**: `name`: `string`, `icon`: `LucideIcon | React.ElementType | React.ReactNode`, `size`: `IconSizeToken | number | string`, `color`: `IconColorToken | (string & {})`, `strokeWidth`: `number`, `absoluteStrokeWidth`: `boolean`, `customSize`: `number | string`, `title`: `string`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use size tokens (xs through 3xl) or multiples of 16 for sharp pixel-grid alignment.
  - ✅ DO: Pass semantic color tokens (e.g. color='accent' or color='muted') to ensure dark mode parity.
  - ❌ DON'T: Do not hardcode raw hex colors when a semantic color token exists.
- **Sample Declaration**:
```tsx
<Icon name="Sparkles" size="lg" color="accent" />
```

#### `<ICON_REGISTRY>`
- **Documentation**: [https://docs.shavin.cc/components/icon-picker](https://docs.shavin.cc/components/icon-picker)
- **Description**: Searchable icon selection popover grid supporting Lucide icons for builder, form customizers, and toolbar triggers.
- **Import**: `import { ICON_REGISTRY, IconPicker } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use variant='icon' inside toolbars, action bars, or compact property panels.
  - ✅ DO: Use IconPicker in page builder tools or customization settings forms.
  - ❌ DON'T: Do not use IconPicker for simple static navigation links — use Button or MenuItem instead.
- **Sample Declaration**:
```tsx
import { ICON_REGISTRY } from "@shavin/ui";
const IconComponent = ICON_REGISTRY["ArrowRight"];
```

#### `<Image>`
- **Documentation**: [https://docs.shavin.cc/components/image](https://docs.shavin.cc/components/image)
- **Description**: Image primitive with automatic broken-link placeholder fallback, aspect-ratio preservation, and object-fit scaling.
- **Import**: `import { Image } from "@shavin/ui";`
- **Variants**: `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"radius":"inherit"}
- **Props**: `src`: `string`, `alt`: `string`, `ratio`: `string`, `fit`: `"cover" | "contain" | "fill" | "none"`, `placeholder`: `React.ReactNode`
- **Best Practices**:
  - ✅ DO: Always pass ratio='16/9' or explicit dimensions to reserve space and prevent layout shifts.
  - ❌ DON'T: Do not use raw un-styled <img> tags — reach for Image primitive to handle load failures gracefully.
- **Sample Declaration**:
```tsx
<Image src="https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800" alt="Abstract shapes" ratio="16/9" fit="cover" />
```

#### `<List>`
- **Documentation**: [https://docs.shavin.cc/components/typography/list](https://docs.shavin.cc/components/typography/list)
- **Description**: Semantic typography prose list component supporting bulleted, numbered, alpha, and roman numeral markers.
- **Import**: `import { List, ListItem } from "@shavin/ui";`
- **Variants**: `marker` ("bullet" | "number" | "lower-roman" | "upper-roman" | "lower-alpha" | "upper-alpha" | "none")
- **Default Variants**: {"marker":"bullet"}
- **Props**: `as`: `"ul" | "ol"`
- **Best Practices**:
  - ✅ DO: Use List for prose bullet points, feature lists, and sequential steps.
  - ❌ DON'T: Do not use List for clickable interactive item rows — reach for Card or DataList instead.
- **Sample Declaration**:
```tsx
<List marker="bullet"><ListItem>First key feature point</ListItem><ListItem>Second key feature point</ListItem></List>
```

#### `<ListItem>`
- **Documentation**: [https://docs.shavin.cc/components/typography/list](https://docs.shavin.cc/components/typography/list)
- **Description**: Semantic typography prose list component supporting bulleted, numbered, alpha, and roman numeral markers.
- **Import**: `import { List, ListItem } from "@shavin/ui";`
- **Variants**: `marker` ("bullet" | "number" | "lower-roman" | "upper-roman" | "lower-alpha" | "upper-alpha" | "none")
- **Default Variants**: {"marker":"bullet"}
- **Best Practices**:
  - ✅ DO: Use List for prose bullet points, feature lists, and sequential steps.
  - ❌ DON'T: Do not use List for clickable interactive item rows — reach for Card or DataList instead.
- **Sample Declaration**:
```tsx
<List marker="bullet"><ListItem>First key feature point</ListItem><ListItem>Second key feature point</ListItem></List>
```

#### `<Progress>`
- **Documentation**: [https://docs.shavin.cc/components/progress](https://docs.shavin.cc/components/progress)
- **Description**: Loading and task progress bar built on Radix Progress primitive supporting determinate percentages and indeterminate loading states.
- **Import**: `import { Progress } from "@shavin/ui";`
- **Variants**: `variant` ("bar" | "top-bar"); `size` ("sm" | "md")
- **Default Variants**: {"variant":"bar","size":"md"}
- **Props**: `value`: `number | null`, `indeterminate`: `boolean`, `showValue`: `boolean`, `valueFormat`: `(value: number) => string`, `label`: `string`, `labelPosition`: `"top" | "right"`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Progress for file upload progress, step wizard completion, or page loading bars.
  - ❌ DON'T: Do not use Progress for interactive slider input controls — reach for Slider instead.
- **Sample Declaration**:
```tsx
<Progress value={65} showValue label="Uploading document..." labelPosition="top" />
```

#### `<Row>`
- **Documentation**: [https://docs.shavin.cc/components/row](https://docs.shavin.cc/components/row)
- **Description**: Flexible interactive row primitive with leading slot, middle title, trailing actions, active state, and drag handle icon.
- **Import**: `import { Row, RowDragHandle } from "@shavin/ui";`
- **Variants**: `active` ("true" | "false")
- **Default Variants**: {"active":"false"}
- **Props**: `as`: `ElementType`, `leading`: `ReactNode`, `trailing`: `ReactNode`, `children`: `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Row for sidebar navigation items, list rows, setting items, and sortable cards.
  - ❌ DON'T: Do not render interactive nested <button> elements inside a Row with as='button' — pass as='div' instead.
- **Sample Declaration**:
```tsx
<Row leading={<Folder />} trailing={<Badge>12</Badge>} active>Projects</Row>
```

#### `<RowDragHandle>`
- **Documentation**: [https://docs.shavin.cc/components/row](https://docs.shavin.cc/components/row)
- **Description**: Flexible interactive row primitive with leading slot, middle title, trailing actions, active state, and drag handle icon.
- **Import**: `import { Row, RowDragHandle } from "@shavin/ui";`
- **Variants**: `active` ("true" | "false")
- **Default Variants**: {"active":"false"}
- **Props**: `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Row for sidebar navigation items, list rows, setting items, and sortable cards.
  - ❌ DON'T: Do not render interactive nested <button> elements inside a Row with as='button' — pass as='div' instead.
- **Sample Declaration**:
```tsx
<Row leading={<Folder />} trailing={<Badge>12</Badge>} active>Projects</Row>
```

#### `<Skeleton>`
- **Documentation**: [https://docs.shavin.cc/components/skeleton](https://docs.shavin.cc/components/skeleton)
- **Description**: Pulsing content placeholder block and SkeletonMimic structural wrapper for zero-layout-shift loading states.
- **Import**: `import { Skeleton, SkeletonMimic } from "@shavin/ui";`
- **Props**: `className`: `string`
- **Best Practices**:
  - ✅ DO: Use SkeletonMimic around card or table layouts to auto-generate loading skeletons directly from real JSX markup.
  - ❌ DON'T: Do not hardcode pixel dimensions for every skeleton line if SkeletonMimic can mirror the exact component tree.
- **Sample Declaration**:
```tsx
<div className="flex items-center gap-3"><Skeleton className="h-10 w-10 rounded-full" /><div className="space-y-2"><Skeleton className="h-4 w-32" /><Skeleton className="h-3 w-20" /></div></div>
```

#### `<SkeletonMimic>`
- **Documentation**: [https://docs.shavin.cc/components/skeleton](https://docs.shavin.cc/components/skeleton)
- **Description**: Pulsing content placeholder block and SkeletonMimic structural wrapper for zero-layout-shift loading states.
- **Import**: `import { Skeleton, SkeletonMimic } from "@shavin/ui";`
- **Props**: `loading`: `boolean`, `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use SkeletonMimic around card or table layouts to auto-generate loading skeletons directly from real JSX markup.
  - ❌ DON'T: Do not hardcode pixel dimensions for every skeleton line if SkeletonMimic can mirror the exact component tree.
- **Sample Declaration**:
```tsx
<div className="flex items-center gap-3"><Skeleton className="h-10 w-10 rounded-full" /><div className="space-y-2"><Skeleton className="h-4 w-32" /><Skeleton className="h-3 w-20" /></div></div>
```

#### `<Spinner>`
- **Documentation**: [https://docs.shavin.cc/components/spinner](https://docs.shavin.cc/components/spinner)
- **Description**: Loading indicator supporting circular spin, pulsing wave dots, Claude-style cycling glyphs, and animated typing ellipsis.
- **Import**: `import { Spinner } from "@shavin/ui";`
- **Variants**: `variant` ("spin" | "dots" | "glyph" | "ellipsis"); `size` ("sm" | "md" | "lg")
- **Default Variants**: {"variant":"spin","size":"md"}
- **Props**: `glyphs`: `string[]`, `intervalMs`: `number`
- **Best Practices**:
  - ✅ DO: Use Spinner inside Button loading states or section loading overlays.
  - ❌ DON'T: Do not render full-page spinners without descriptive text explaining what is loading.
- **Sample Declaration**:
```tsx
<Button disabled><Spinner size="sm" /> Loading...</Button>
```

#### `<StatCard>`
- **Documentation**: [https://docs.shavin.cc/components/card](https://docs.shavin.cc/components/card)
- **Description**: Surface card primitive with padding presets (none to 3xl), interactive hover state, and background media props. Ideal for media-rich product cards and feature tiles.
- **Import**: `import { Card, CardList, CardListItem, CardRow, StatCard } from "@shavin/ui";`
- **Variants**: `padding` ("none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"); `interactive` ("true" | "false")
- **Default Variants**: {"padding":"sm","interactive":"false"}
- **Best Practices**:
  - ✅ DO: Use Card for grouped content blocks with consistent surface treatment and elevation.
  - ✅ DO: Use bgImage with gradient-bottom overlay for media cards with bottom-aligned text.
  - ❌ DON'T: Do not embed <video> elements as children — pass bgVideo prop and the card handles media layer rendering.
- **Sample Declaration**:
```tsx
<Card padding="md">Card content</Card>
```

#### `<Table>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```

#### `<TableBody>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```

#### `<TableCell>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```

#### `<TableColumnHeaderCell>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```

#### `<TableHeader>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```

#### `<TableRow>`
- **Documentation**: [https://docs.shavin.cc/components/table](https://docs.shavin.cc/components/table)
- **Description**: Data grid table primitives matching design system divider and hairline border visual token specifications.
- **Import**: `import { Table, TableBody, TableCell, TableColumnHeaderCell, TableHeader, TableRow } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use Table for structured tabular data, invoices, user directories, and audit logs.
  - ❌ DON'T: Do not use Table for page layout columns — reach for Grid or Flex instead.
- **Sample Declaration**:
```tsx
<Table><TableHeader><TableRow><TableColumnHeaderCell>Name</TableColumnHeaderCell><TableColumnHeaderCell>Role</TableColumnHeaderCell></TableRow></TableHeader><TableBody><TableRow><TableCell>Elena Rostova</TableCell><TableCell>Staff Engineer</TableCell></TableRow></TableBody></Table>
```


### Overlays & Modals (26 components)

#### `<Accordion>`
- **Documentation**: [https://docs.shavin.cc/components/accordion](https://docs.shavin.cc/components/accordion)
- **Description**: Collapsible disclosure panels built on Radix Accordion primitive with ChevronDown 180-degree rotation convention.
- **Import**: `import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "outline" | "ghost")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Accordion for grouping secondary FAQs, settings sections, or dense collapsible details.
  - ❌ DON'T: Do not use ChevronRight for accordion triggers — use ChevronDown with 180deg rotation per section 4 convention.
- **Sample Declaration**:
```tsx
<Accordion type="single" collapsible><AccordionItem value="1"><AccordionTrigger>What is @shavin/ui?</AccordionTrigger><AccordionContent>Enterprise React design system engine.</AccordionContent></AccordionItem></Accordion>
```

#### `<AccordionContent>`
- **Documentation**: [https://docs.shavin.cc/components/accordion](https://docs.shavin.cc/components/accordion)
- **Description**: Collapsible disclosure panels built on Radix Accordion primitive with ChevronDown 180-degree rotation convention.
- **Import**: `import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "outline" | "ghost")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Accordion for grouping secondary FAQs, settings sections, or dense collapsible details.
  - ❌ DON'T: Do not use ChevronRight for accordion triggers — use ChevronDown with 180deg rotation per section 4 convention.
- **Sample Declaration**:
```tsx
<Accordion type="single" collapsible><AccordionItem value="1"><AccordionTrigger>What is @shavin/ui?</AccordionTrigger><AccordionContent>Enterprise React design system engine.</AccordionContent></AccordionItem></Accordion>
```

#### `<AccordionItem>`
- **Documentation**: [https://docs.shavin.cc/components/accordion](https://docs.shavin.cc/components/accordion)
- **Description**: Collapsible disclosure panels built on Radix Accordion primitive with ChevronDown 180-degree rotation convention.
- **Import**: `import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "outline" | "ghost")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Accordion for grouping secondary FAQs, settings sections, or dense collapsible details.
  - ❌ DON'T: Do not use ChevronRight for accordion triggers — use ChevronDown with 180deg rotation per section 4 convention.
- **Sample Declaration**:
```tsx
<Accordion type="single" collapsible><AccordionItem value="1"><AccordionTrigger>What is @shavin/ui?</AccordionTrigger><AccordionContent>Enterprise React design system engine.</AccordionContent></AccordionItem></Accordion>
```

#### `<AccordionTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/accordion](https://docs.shavin.cc/components/accordion)
- **Description**: Collapsible disclosure panels built on Radix Accordion primitive with ChevronDown 180-degree rotation convention.
- **Import**: `import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "outline" | "ghost")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Accordion for grouping secondary FAQs, settings sections, or dense collapsible details.
  - ❌ DON'T: Do not use ChevronRight for accordion triggers — use ChevronDown with 180deg rotation per section 4 convention.
- **Sample Declaration**:
```tsx
<Accordion type="single" collapsible><AccordionItem value="1"><AccordionTrigger>What is @shavin/ui?</AccordionTrigger><AccordionContent>Enterprise React design system engine.</AccordionContent></AccordionItem></Accordion>
```

#### `<AlertDialog>`
- **Documentation**: [https://docs.shavin.cc/components/alert-dialog](https://docs.shavin.cc/components/alert-dialog)
- **Description**: Explicit destructive confirmation dialog requiring intentional user action. Built on Radix AlertDialog primitive without outside-click dismissal.
- **Import**: `import { AlertDialog } from "@shavin/ui";`
- **Props**: `open` (required): `boolean`, `onOpenChange` (required): `(open: boolean) => void`, `title` (required): `string`, `description`: `ReactNode`, `confirmLabel`: `string`, `cancelLabel`: `string`, `onConfirm` (required): `() => void`, `danger`: `boolean`, `intent`: `"info" | "warning" | "success" | "danger" | "default"`, `layout`: `"default" | "centered"`, `badgeText`: `string`, `icon`: `ReactNode`, `children`: `ReactNode`
- **Best Practices**:
  - ✅ DO: Use AlertDialog for irreversible destructive actions like deleting accounts or dropping database records.
  - ❌ DON'T: Do not use AlertDialog for casual dismissible dialogs — use standard Dialog instead.
- **Sample Declaration**:
```tsx
<AlertDialog open={isOpen} onOpenChange={setIsOpen} title="Delete Project?" description="This action cannot be undone." intent="danger" confirmLabel="Delete" onConfirm={handleDelete} />
```

#### `<ContextMenu>`
- **Documentation**: [https://docs.shavin.cc/components/context-menu](https://docs.shavin.cc/components/context-menu)
- **Description**: Right-click context action menu built on Radix ContextMenu primitive with data-panel surface styling.
- **Import**: `import { ContextMenu, ContextMenuItem } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Props**: `trigger` (required): `ReactNode`, `children` (required): `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use ContextMenu for desktop right-click power-user shortcuts (e.g. file row actions).
  - ❌ DON'T: Do not hide critical primary functionality exclusively behind right-click context menus.
- **Sample Declaration**:
```tsx
<ContextMenu trigger={<div>Right click me</div>}><ContextMenuItem>Copy Link</ContextMenuItem><ContextMenuItem variant="danger">Delete</ContextMenuItem></ContextMenu>
```

#### `<ContextMenuItem>`
- **Documentation**: [https://docs.shavin.cc/components/context-menu](https://docs.shavin.cc/components/context-menu)
- **Description**: Right-click context action menu built on Radix ContextMenu primitive with data-panel surface styling.
- **Import**: `import { ContextMenu, ContextMenuItem } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use ContextMenu for desktop right-click power-user shortcuts (e.g. file row actions).
  - ❌ DON'T: Do not hide critical primary functionality exclusively behind right-click context menus.
- **Sample Declaration**:
```tsx
<ContextMenu trigger={<div>Right click me</div>}><ContextMenuItem>Copy Link</ContextMenuItem><ContextMenuItem variant="danger">Delete</ContextMenuItem></ContextMenu>
```

#### `<Dialog>`
- **Documentation**: [https://docs.shavin.cc/components/dialog](https://docs.shavin.cc/components/dialog)
- **Description**: Accessible modal dialog built on Radix Dialog primitive with focus trapping, ESC key dismiss, and entry/exit transitions.
- **Import**: `import { CloseButton, Dialog } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg")
- **Default Variants**: {"size":"sm"}
- **Props**: `title` (required): `string`, `subtitle`: `string`, `onClose` (required): `() => void`, `children`: `ReactNode`, `footer`: `ReactNode`, `dismissible`: `boolean`
- **Best Practices**:
  - ✅ DO: Always provide a clear, actionable title and primary footer button.
  - ❌ DON'T: Do not use Dialog for quick non-blocking notifications — reach for Toast instead.
- **Sample Declaration**:
```tsx
<Dialog title="Confirm Export" subtitle="Export data as CSV?" onClose={() => {}} footer={<Button>Export</Button>} />
```

#### `<HoverCard>`
- **Documentation**: [https://docs.shavin.cc/components/hover-card](https://docs.shavin.cc/components/hover-card)
- **Description**: Hover-triggered preview card panel built on Radix HoverCard primitive with open/close intent delays and collision detection.
- **Import**: `import { HoverCard, HoverCardContent, HoverCardTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use HoverCard for user profile popover previews when hovering @mentions or links.
  - ❌ DON'T: Do not put essential user actions inside HoverCard — reach for Popover or Dialog instead.
- **Sample Declaration**:
```tsx
<HoverCard><HoverCardTrigger asChild><a href="#">@alex</a></HoverCardTrigger><HoverCardContent><div>Alex Morgan</div></HoverCardContent></HoverCard>
```

#### `<HoverCardContent>`
- **Documentation**: [https://docs.shavin.cc/components/hover-card](https://docs.shavin.cc/components/hover-card)
- **Description**: Hover-triggered preview card panel built on Radix HoverCard primitive with open/close intent delays and collision detection.
- **Import**: `import { HoverCard, HoverCardContent, HoverCardTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use HoverCard for user profile popover previews when hovering @mentions or links.
  - ❌ DON'T: Do not put essential user actions inside HoverCard — reach for Popover or Dialog instead.
- **Sample Declaration**:
```tsx
<HoverCard><HoverCardTrigger asChild><a href="#">@alex</a></HoverCardTrigger><HoverCardContent><div>Alex Morgan</div></HoverCardContent></HoverCard>
```

#### `<HoverCardTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/hover-card](https://docs.shavin.cc/components/hover-card)
- **Description**: Hover-triggered preview card panel built on Radix HoverCard primitive with open/close intent delays and collision detection.
- **Import**: `import { HoverCard, HoverCardContent, HoverCardTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use HoverCard for user profile popover previews when hovering @mentions or links.
  - ❌ DON'T: Do not put essential user actions inside HoverCard — reach for Popover or Dialog instead.
- **Sample Declaration**:
```tsx
<HoverCard><HoverCardTrigger asChild><a href="#">@alex</a></HoverCardTrigger><HoverCardContent><div>Alex Morgan</div></HoverCardContent></HoverCard>
```

#### `<Menu>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Props**: `trigger` (required): `ReactNode`, `children` (required): `ReactNode`, `align`: `"start" | "end"`
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<MenuItem>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<MenuSub>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<MenuSubContent>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<MenuSubTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<MenuTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/menu](https://docs.shavin.cc/components/menu)
- **Description**: Floating action dropdown menu built on Radix DropdownMenu primitive with full keyboard navigation and nested sub-menu support.
- **Import**: `import { Menu, MenuItem, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger } from "@shavin/ui";`
- **Variants**: `variant` ("default" | "danger")
- **Default Variants**: {"variant":"default"}
- **Best Practices**:
  - ✅ DO: Use Menu for contextual action lists (e.g. ⋯ overflow triggers).
  - ❌ DON'T: Do not use Menu as a form select control — reach for Select instead.
- **Sample Declaration**:
```tsx
<Menu trigger={<MenuTrigger />}><MenuItem>Edit</MenuItem><MenuItem variant="danger">Delete</MenuItem></Menu>
```

#### `<Popover>`
- **Documentation**: [https://docs.shavin.cc/components/popover](https://docs.shavin.cc/components/popover)
- **Description**: Click-triggered floating panel built on Radix Popover primitive with collision detection and focus trapping.
- **Import**: `import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Set align='start' and collisionPadding=8 for standard floating popovers.
  - ❌ DON'T: Do not use Popover for simple hover labels — reach for Tooltip instead.
- **Sample Declaration**:
```tsx
<Popover><PopoverTrigger asChild><Button>Open Popover</Button></PopoverTrigger><PopoverContent><Text>Popover Content</Text></PopoverContent></Popover>
```

#### `<PopoverAnchor>`
- **Documentation**: [https://docs.shavin.cc/components/popover](https://docs.shavin.cc/components/popover)
- **Description**: Click-triggered floating panel built on Radix Popover primitive with collision detection and focus trapping.
- **Import**: `import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Set align='start' and collisionPadding=8 for standard floating popovers.
  - ❌ DON'T: Do not use Popover for simple hover labels — reach for Tooltip instead.
- **Sample Declaration**:
```tsx
<Popover><PopoverTrigger asChild><Button>Open Popover</Button></PopoverTrigger><PopoverContent><Text>Popover Content</Text></PopoverContent></Popover>
```

#### `<PopoverContent>`
- **Documentation**: [https://docs.shavin.cc/components/popover](https://docs.shavin.cc/components/popover)
- **Description**: Click-triggered floating panel built on Radix Popover primitive with collision detection and focus trapping.
- **Import**: `import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Set align='start' and collisionPadding=8 for standard floating popovers.
  - ❌ DON'T: Do not use Popover for simple hover labels — reach for Tooltip instead.
- **Sample Declaration**:
```tsx
<Popover><PopoverTrigger asChild><Button>Open Popover</Button></PopoverTrigger><PopoverContent><Text>Popover Content</Text></PopoverContent></Popover>
```

#### `<PopoverTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/popover](https://docs.shavin.cc/components/popover)
- **Description**: Click-triggered floating panel built on Radix Popover primitive with collision detection and focus trapping.
- **Import**: `import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Set align='start' and collisionPadding=8 for standard floating popovers.
  - ❌ DON'T: Do not use Popover for simple hover labels — reach for Tooltip instead.
- **Sample Declaration**:
```tsx
<Popover><PopoverTrigger asChild><Button>Open Popover</Button></PopoverTrigger><PopoverContent><Text>Popover Content</Text></PopoverContent></Popover>
```

#### `<ProfileModal>`
- **Documentation**: [https://docs.shavin.cc/blocks/profile-modal](https://docs.shavin.cc/blocks/profile-modal)
- **Description**: Tabbed user account settings modal dialog built on Radix Dialog primitive with two-column side avatar layout.
- **Import**: `import { ProfileModal } from "@shavin/ui";`
- **Props**: `title` (required): `string`, `onClose` (required): `() => void`, `tabs`: `readonly ProfileModalTab<T>[]`, `activeTab`: `T`, `onTabChange`: `(key: T) => void`, `avatar`: `ReactNode`, `children` (required): `ReactNode`, `dismissible`: `boolean`
- **Best Practices**:
  - ✅ DO: Use ProfileModal for multi-tab account preferences, user profile settings, or organization billing dialogs.
  - ❌ DON'T: Do not use ProfileModal for simple single-button alerts — reach for AlertDialog instead.
- **Sample Declaration**:
```tsx
<ProfileModal open={isOpen} onOpenChange={setIsOpen} user={{ name: "Jane Doe", email: "jane@example.com" }} />
```

#### `<Spotlight>`
- **Documentation**: [https://docs.shavin.cc/components/spotlight](https://docs.shavin.cc/components/spotlight)
- **Description**: Command palette modal overlay component featuring auto-focused search input, keyboard navigation shortcuts, and result list slot.
- **Import**: `import { Spotlight } from "@shavin/ui";`
- **Props**: `open` (required): `boolean`, `onOpenChange` (required): `(open: boolean) => void`, `query` (required): `string`, `onQueryChange` (required): `(query: string) => void`, `onKeyDown`: `(e: React.KeyboardEvent<HTMLInputElement>) => void`, `placeholder`: `string`, `children`: `ReactNode`, `footer`: `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Spotlight for global search command palettes (Cmd+K) and quick navigation search dialogs.
  - ❌ DON'T: Do not use Spotlight for simple single-field form inputs — reach for TextField instead.
- **Sample Declaration**:
```tsx
<Spotlight open={true} onOpenChange={() => {}} query="" onQueryChange={() => {}}><div>Search Results List</div></Spotlight>
```

#### `<Toast>`
- **Documentation**: [https://docs.shavin.cc/components/toast](https://docs.shavin.cc/components/toast)
- **Description**: Non-blocking floating notification system with swipe-to-dismiss, hover expansion, and promise lifecycle helpers.
- **Import**: `import { ToastProvider } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Wrap application root with <ToastProvider position='bottom-right'> and consume via useToast().
  - ❌ DON'T: Do not use Toast for critical modal confirmations — reach for AlertDialog instead.
- **Sample Declaration**:
```tsx
const { success } = useToast(); success("Changes saved successfully");
```

#### `<ToastProvider>`
- **Documentation**: [https://docs.shavin.cc/components/toast](https://docs.shavin.cc/components/toast)
- **Description**: Non-blocking floating notification system with swipe-to-dismiss, hover expansion, and promise lifecycle helpers.
- **Import**: `import { ToastProvider } from "@shavin/ui";`
- **Props**: `children` (required): `React.ReactNode`, `position`: `ToastPosition`, `duration`: `number`
- **Best Practices**:
  - ✅ DO: Wrap application root with <ToastProvider position='bottom-right'> and consume via useToast().
  - ❌ DON'T: Do not use Toast for critical modal confirmations — reach for AlertDialog instead.
- **Sample Declaration**:
```tsx
const { success } = useToast(); success("Changes saved successfully");
```

#### `<Tooltip>`
- **Documentation**: [https://docs.shavin.cc/components/tooltip](https://docs.shavin.cc/components/tooltip)
- **Description**: Hover or focus label hint built on Radix Tooltip primitive with automatic positioning, arrow indicator, and theme tone overrides.
- **Import**: `import { Tooltip } from "@shavin/ui";`
- **Props**: `content` (required): `ReactNode`, `children` (required): `ReactElement`, `side`: `"top" | "right" | "bottom" | "left"`, `delayDuration`: `number`, `tone`: `"auto" | "dark" | "light"`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Tooltip for short, non-interactive icon descriptions or action hints.
  - ❌ DON'T: Do not place interactive buttons or links inside Tooltip content — use Popover instead.
- **Sample Declaration**:
```tsx
<Tooltip content="Save item to library"><Button iconLeft={<PlusIcon />}>Save</Button></Tooltip>
```


### Navigation & Utilities (23 components)

#### `<BlockPreview>`
- **Documentation**: [https://docs.shavin.cc/blocks/overview](https://docs.shavin.cc/blocks/overview)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { BlockPreview, DeviceContext, MiniBlockPreview, MiniPreviewFrame, SafeMiniPreview } from "@shavin/ui";`
- **Props**: `title` (required): `string`, `code` (required): `string`, `command` (required): `string`, `layout`: `"fullscreen" | "sidebar" | "sidebar-right" | "header" | "centered" | "plain" | "app-shell"`, `builderKey`: `string`, `builderUrl`: `string`, `children` (required): `ReactNode`
- **Sample Declaration**:
```tsx
<BlockPreview blockId="auth-card" title="Authentication Block" />
```

#### `<BottomNav>`
- **Documentation**: [https://docs.shavin.cc/components/bottom-nav](https://docs.shavin.cc/components/bottom-nav)
- **Description**: Fixed full-width mobile navigation bar for primary viewport routing with active indicators and notification badges.
- **Import**: `import { BottomNav } from "@shavin/ui";`
- **Props**: `items` (required): `BottomNavItem[]`, `onSelect`: `(href: string) => void`, `ariaLabel`: `string`
- **Best Practices**:
  - ✅ DO: Use BottomNav for primary mobile application view navigation (3-5 top destinations).
  - ❌ DON'T: Do not use BottomNav on desktop viewports — hide on sm/md breakpoints via CSS.
- **Sample Declaration**:
```tsx
<BottomNav items={[{ href: "/", label: "Home", active: true }, { href: "/search", label: "Search" }, { href: "/settings", label: "Settings" }]} />
```

#### `<Breadcrumbs>`
- **Documentation**: [https://docs.shavin.cc/components/breadcrumbs](https://docs.shavin.cc/components/breadcrumbs)
- **Description**: Hierarchical navigation tree bar with ChevronRight separators and automatic label truncation.
- **Import**: `import { Breadcrumbs } from "@shavin/ui";`
- **Props**: `items` (required): `BreadcrumbItem[]`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Breadcrumbs at the top of detail pages to allow users to navigate up the page hierarchy.
  - ❌ DON'T: Do not use Breadcrumbs on top-level root pages.
- **Sample Declaration**:
```tsx
<Breadcrumbs items={[{ label: "Home", href: "/" }, { label: "Settings", href: "/settings" }, { label: "Profile", href: "/settings/profile" }]} />
```

#### `<DeviceContext>`
- **Documentation**: [https://docs.shavin.cc/blocks/overview](https://docs.shavin.cc/blocks/overview)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { BlockPreview, DeviceContext, MiniBlockPreview, MiniPreviewFrame, SafeMiniPreview } from "@shavin/ui";`
- **Sample Declaration**:
```tsx
<DeviceContext.Provider value={{ device: "desktop" }}>{children}</DeviceContext.Provider>
```

#### `<Drawer>`
- **Documentation**: [https://docs.shavin.cc/components/overview](https://docs.shavin.cc/components/overview)
- **Description**: Edge-mounted overlay panel that slides in from left or right. Built on Radix Dialog with focus trapping, scroll lock, backdrop dismiss, and directional slide-in/slide-out animations. Use for temporary contextual panels — unlike Sidebar (in-flow layout), Drawer overlays content and dismisses on outside click.
- **Import**: `import { Drawer } from "@shavin/ui";`
- **Variants**: `side` ("left" | "right"); `variant` ("fixed" | "floating"); `size` ("sm" | "md" | "lg" | "xl")
- **Default Variants**: {"side":"right","variant":"floating","size":"md"}
- **Props**: `open` (required): `boolean`, `onClose` (required): `() => void`, `title` (required): `ReactNode`, `subtitle`: `string`, `side`: `"left" | "right"`, `variant`: `"fixed" | "floating"`, `size`: `"sm" | "md" | "lg" | "xl"`, `dismissible`: `boolean`, `overlayOpacity`: `number`, `children`: `ReactNode`, `footer`: `ReactNode`, `className`: `string`, `headerClassName`: `string`, `modal`: `boolean`
- **Best Practices**:
  - ✅ DO: Use Drawer for temporary contextual panels like filters, inspectors, quick settings, or mobile navigation that should overlay content and dismiss on outside interaction.
  - ❌ DON'T: Do not use Drawer for persistent navigation or always-visible panels — use Sidebar (in-flow layout) instead. Drawer is for temporary, dismissible surfaces.
- **Sample Declaration**:
```tsx
<Drawer />
```

#### `<MiniBlockPreview>`
- **Documentation**: [https://docs.shavin.cc/blocks/overview](https://docs.shavin.cc/blocks/overview)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { BlockPreview, DeviceContext, MiniBlockPreview, MiniPreviewFrame, SafeMiniPreview } from "@shavin/ui";`
- **Props**: `children`: `ReactNode`, `scale`: `number`, `fallback`: `ReactNode`, `className`: `string`, `playVideo`: `boolean`
- **Sample Declaration**:
```tsx
<MiniBlockPreview blockId="dashboard-kpi" />
```

#### `<MiniPreviewFrame>`
- **Documentation**: [https://docs.shavin.cc/blocks/overview](https://docs.shavin.cc/blocks/overview)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { BlockPreview, DeviceContext, MiniBlockPreview, MiniPreviewFrame, SafeMiniPreview } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`, `showDotGrid`: `boolean`
- **Sample Declaration**:
```tsx
<MiniPreviewFrame>{children}</MiniPreviewFrame>
```

#### `<Pagination>`
- **Documentation**: [https://docs.shavin.cc/components/pagination](https://docs.shavin.cc/components/pagination)
- **Description**: Page navigation control across data tables, lists, and editorial documentation supporting numeric pages, simple compact status, and article card variants.
- **Import**: `import { Pagination } from "@shavin/ui";`
- **Variants**: `variant` ("numeric" | "simple" | "cards"); `size` ("sm" | "md" | "lg")
- **Default Variants**: {"variant":"numeric","size":"md"}
- **Props**: `page`: `number`, `totalPages`: `number`, `onPageChange`: `(page: number) => void`, `prevLabel`: `string`, `nextLabel`: `string`, `prevTitle`: `string`, `nextTitle`: `string`, `prevHref`: `string`, `nextHref`: `string`
- **Best Practices**:
  - ✅ DO: Use variant='numeric' for data tables and search results; use variant='cards' for documentation portals.
  - ❌ DON'T: Do not display pagination controls if totalPages === 1.
- **Sample Declaration**:
```tsx
<Pagination page={1} totalPages={10} onPageChange={() => {}} />
```

#### `<SafeMiniPreview>`
- **Documentation**: [https://docs.shavin.cc/blocks/overview](https://docs.shavin.cc/blocks/overview)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { BlockPreview, DeviceContext, MiniBlockPreview, MiniPreviewFrame, SafeMiniPreview } from "@shavin/ui";`
- **Sample Declaration**:
```tsx
<SafeMiniPreview blockId="hero-section" />
```

#### `<ScrollArea>`
- **Documentation**: [https://docs.shavin.cc/components/scroll-area](https://docs.shavin.cc/components/scroll-area)
- **Description**: Custom styled scrollbar viewport primitive built on Radix ScrollArea supporting vertical and horizontal scrolling.
- **Import**: `import { ScrollArea } from "@shavin/ui";`
- **Props**: `children` (required): `ReactNode`, `className`: `string`, `style`: `CSSProperties`
- **Best Practices**:
  - ✅ DO: Use ScrollArea inside fixed-height dialogs, dropdowns, and sidebars.
  - ❌ DON'T: Do not forget to set an explicit height (e.g. h-64 or max-h-80) on ScrollArea container.
- **Sample Declaration**:
```tsx
<ScrollArea className="h-48 border border-hairline p-3"><div className="space-y-4"><div>Item 1</div><div>Item 2</div><div>Item 3</div><div>Item 4</div></div></ScrollArea>
```

#### `<Separator>`
- **Documentation**: [https://docs.shavin.cc/components/separator](https://docs.shavin.cc/components/separator)
- **Description**: Visual horizontal or vertical divider primitive built on Radix Separator using semantic hairline token styling.
- **Import**: `import { Separator } from "@shavin/ui";`
- **Variants**: `orientation` ("horizontal" | "vertical"); `size` ("1" | "2" | "3" | "4" | "full"); `color` ("hairline" | "hairline-strong" | "subtle" | "muted" | "default" | "accent" | "contrast" | "danger" | "inherit")
- **Default Variants**: {"orientation":"horizontal","size":"1","color":"hairline"}
- **Props**: `color`: `SeparatorColorToken | (string & {})`, `size`: `SeparatorSizeToken`, `orientation`: `"horizontal" | "vertical"`
- **Best Practices**:
  - ✅ DO: Use Separator to separate distinct content sections or toolbar button groups.
  - ❌ DON'T: Do not use literal <hr> elements — reach for Separator for accessible token-driven dividers.
- **Sample Declaration**:
```tsx
<div className="space-y-4"><div>Top Content</div><Separator /><div >Bottom Content</div></div>
```

#### `<ShavinDevInspector>`
- **Documentation**: [https://docs.shavin.cc/get-started/dev-inspector](https://docs.shavin.cc/get-started/dev-inspector)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { ShavinDevInspector, ShavinDevTools } from "@shavin/ui";`
- **Sample Declaration**:
```tsx
<ShavinDevInspector position="bottom-right" />
```

#### `<ShavinDevTools>`
- **Documentation**: [https://docs.shavin.cc/get-started/dev-inspector](https://docs.shavin.cc/get-started/dev-inspector)
- **Description**: Shavin Design System UI primitive.
- **Import**: `import { ShavinDevInspector, ShavinDevTools } from "@shavin/ui";`
- **Props**: `className`: `string`, `position`: `"bottom-left" | "bottom-right" | "top-left" | "top-right"`, `forceShow`: `boolean`
- **Sample Declaration**:
```tsx
<ShavinDevTools enabled={process.env.NODE_ENV === "development"} />
```

#### `<Sortable>`
- **Documentation**: [https://docs.shavin.cc/components/sortable](https://docs.shavin.cc/components/sortable)
- **Description**: Zero-dependency HTML5 drag-and-drop list re-ordering primitive with render-prop item formatting and grip handle.
- **Import**: `import { Sortable, SortableHandle } from "@shavin/ui";`
- **Props**: `items` (required): `T[]`, `onReorder` (required): `(next: T[]) => void`, `getKey` (required): `(item: T, index: number) => string | number`, `children` (required): `(item: T, index: number) => ReactNode`, `orientation`: `"vertical" | "horizontal" | "grid"`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Sortable for kanban card columns, dashboard widget re-ordering, and navigation list prioritization.
  - ❌ DON'T: Do not use heavy third-party drag-and-drop packages when native HTML5 Sortable provides zero-bundle drag reordering.
- **Sample Declaration**:
```tsx
<Sortable items={["Task A", "Task B"]} getKey={(item) => item} onReorder={() => {}}>{(item) => <div className="p-2 border border-hairline"><SortableHandle /> {item}</div>}</Sortable>
```

#### `<SortableHandle>`
- **Documentation**: [https://docs.shavin.cc/components/sortable](https://docs.shavin.cc/components/sortable)
- **Description**: Zero-dependency HTML5 drag-and-drop list re-ordering primitive with render-prop item formatting and grip handle.
- **Import**: `import { Sortable, SortableHandle } from "@shavin/ui";`
- **Props**: `className`: `string`
- **Best Practices**:
  - ✅ DO: Use Sortable for kanban card columns, dashboard widget re-ordering, and navigation list prioritization.
  - ❌ DON'T: Do not use heavy third-party drag-and-drop packages when native HTML5 Sortable provides zero-bundle drag reordering.
- **Sample Declaration**:
```tsx
<Sortable items={["Task A", "Task B"]} getKey={(item) => item} onReorder={() => {}}>{(item) => <div className="p-2 border border-hairline"><SortableHandle /> {item}</div>}</Sortable>
```

#### `<Tabs>`
- **Documentation**: [https://docs.shavin.cc/components/tabs-full](https://docs.shavin.cc/components/tabs-full)
- **Description**: Tabbed navigation and in-page state container built on Radix Tabs primitive supporting line, segmented, pills, and button variants.
- **Import**: `import { Tabs, TabsContent, TabsList, TabsTrigger } from "@shavin/ui";`
- **Props**: `as`: `"states" | "navigation"`, `variant`: `TabVariant`, `orientation`: `"horizontal" | "vertical"`, `size`: `"sm" | "md"`, `value`: `string`, `defaultValue`: `string`, `onValueChange`: `(value: string) => void`, `items`: `readonly TabItem[]`, `tabs`: `readonly TabItem[]`, `linkComponent`: `ElementType`, `children`: `ReactNode`, `className`: `string`
- **Best Practices**:
  - ✅ DO: Use variant='line' for main page/section tabs and variant='segmented' for compact inline filters.
  - ❌ DON'T: Do not mix as='states' and as='navigation' modes in the same tab strip.
- **Sample Declaration**:
```tsx
<Tabs defaultValue="account"><TabsList><TabsTrigger value="account">Account</TabsTrigger><TabsTrigger value="billing">Billing</TabsTrigger></TabsList><TabsContent value="account"><Text>Account settings</Text></TabsContent><TabsContent value="billing"><Text>Billing details</Text></TabsContent></Tabs>
```

#### `<TabsContent>`
- **Documentation**: [https://docs.shavin.cc/components/tabs-full](https://docs.shavin.cc/components/tabs-full)
- **Description**: Tabbed navigation and in-page state container built on Radix Tabs primitive supporting line, segmented, pills, and button variants.
- **Import**: `import { Tabs, TabsContent, TabsList, TabsTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use variant='line' for main page/section tabs and variant='segmented' for compact inline filters.
  - ❌ DON'T: Do not mix as='states' and as='navigation' modes in the same tab strip.
- **Sample Declaration**:
```tsx
<TabsContent value="overview"><Text>Overview panel content</Text></TabsContent>
```

#### `<TabsList>`
- **Documentation**: [https://docs.shavin.cc/components/tabs-full](https://docs.shavin.cc/components/tabs-full)
- **Description**: Tabbed navigation and in-page state container built on Radix Tabs primitive supporting line, segmented, pills, and button variants.
- **Import**: `import { Tabs, TabsContent, TabsList, TabsTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use variant='line' for main page/section tabs and variant='segmented' for compact inline filters.
  - ❌ DON'T: Do not mix as='states' and as='navigation' modes in the same tab strip.
- **Sample Declaration**:
```tsx
<TabsList><TabsTrigger value="overview">Overview</TabsTrigger><TabsTrigger value="analytics">Analytics</TabsTrigger></TabsList>
```

#### `<TabsTrigger>`
- **Documentation**: [https://docs.shavin.cc/components/tabs-full](https://docs.shavin.cc/components/tabs-full)
- **Description**: Tabbed navigation and in-page state container built on Radix Tabs primitive supporting line, segmented, pills, and button variants.
- **Import**: `import { Tabs, TabsContent, TabsList, TabsTrigger } from "@shavin/ui";`
- **Best Practices**:
  - ✅ DO: Use variant='line' for main page/section tabs and variant='segmented' for compact inline filters.
  - ❌ DON'T: Do not mix as='states' and as='navigation' modes in the same tab strip.
- **Sample Declaration**:
```tsx
<TabsTrigger value="overview">Overview</TabsTrigger>
```

#### `<ThemeProvider>`
- **Documentation**: [https://docs.shavin.cc/foundations/theming](https://docs.shavin.cc/foundations/theming)
- **Description**: Global runtime design system theme provider mutating CSS variables on document root for brand accents, radius, and scaling.
- **Import**: `import { ThemeProvider } from "@shavin/ui";`
- **Props**: `theme`: `string`, `defaultTheme`: `"light" | "dark" | "system"`, `accentColor`: `string`, `grayColor`: `string`, `radius`: `"none" | "small" | "medium" | "large" | "full"`, `scaling`: `90 | 95 | 100 | 105 | 110`, `panelBackground`: `"solid" | "translucent"`, `displayFont`: `string`, `bodyFont`: `string`, `preloadFonts`: `boolean`, `devTools`: `boolean`, `children`: `ReactNode`
- **Best Practices**:
  - ✅ DO: Mount ThemeProvider once near application root to apply active theme presets.
  - ❌ DON'T: Do not wrap individual small components in multiple nested ThemeProviders — tokens are global on document root.
- **Sample Declaration**:
```tsx
<ThemeProvider accentColor="Grass" grayColor="Zinc" radius="large" scaling={95} panelBackground="solid" />
```

#### `<ThemeScript>`
- **Documentation**: [https://docs.shavin.cc/foundations/theming](https://docs.shavin.cc/foundations/theming)
- **Description**: Appearance mode controller providing zero-layout-shift switching between light, dark, and system color schemes, complete with a FOUC-prevention hydration script and useTheme hook.
- **Import**: `import { ThemeScript, ThemeSwitcher } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg")
- **Default Variants**: {"size":"md"}
- **Props**: `storageKey`: `string`, `defaultTheme`: `ThemeMode`
- **Best Practices**:
  - ✅ DO: Place <ThemeScript /> in your root layout <head> to eliminate any white/dark flash during initial page load.
  - ❌ DON'T: Do not use ThemeSwitcher to configure accent colors — use ThemeProvider or Configurator for branding palette customizations.
- **Sample Declaration**:
```tsx
<ThemeSwitcher variant="icon-button" />
```

#### `<ThemeSwitcher>`
- **Documentation**: [https://docs.shavin.cc/foundations/theming](https://docs.shavin.cc/foundations/theming)
- **Description**: Appearance mode controller providing zero-layout-shift switching between light, dark, and system color schemes, complete with a FOUC-prevention hydration script and useTheme hook.
- **Import**: `import { ThemeScript, ThemeSwitcher } from "@shavin/ui";`
- **Variants**: `size` ("sm" | "md" | "lg")
- **Default Variants**: {"size":"md"}
- **Props**: `variant`: `"icon-button" | "segmented" | "menu" | "switch"`, `storageKey`: `string`, `defaultTheme`: `ThemeMode`, `showLabels`: `boolean`, `labels`: `{`, `light`: `string`, `dark`: `string`, `system`: `string`
- **Best Practices**:
  - ✅ DO: Place <ThemeScript /> in your root layout <head> to eliminate any white/dark flash during initial page load.
  - ❌ DON'T: Do not use ThemeSwitcher to configure accent colors — use ThemeProvider or Configurator for branding palette customizations.
- **Sample Declaration**:
```tsx
<ThemeSwitcher variant="icon-button" />
```

#### `<Video>`
- **Documentation**: [https://docs.shavin.cc/components/overview](https://docs.shavin.cc/components/overview)
- **Description**: Video primitive with poster image support, aspect-ratio preservation, object-fit scaling, and graceful placeholder fallback when src is missing.
- **Import**: `import { Video } from "@shavin/ui";`
- **Variants**: `radius` ("none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric")
- **Default Variants**: {"radius":"inherit"}
- **Props**: `src`: `string`, `poster`: `string`, `fit`: `"cover" | "contain" | "fill" | "none"`, `ratio`: `string`, `autoPlay`: `boolean`, `loop`: `boolean`, `muted`: `boolean`, `controls`: `boolean`, `placeholder`: `React.ReactNode`
- **Best Practices**:
  - ✅ DO: Always pass ratio='16/9' or explicit dimensions to reserve space and prevent layout shifts.
  - ✅ DO: Provide a poster image for a professional pre-load frame before the video data arrives.
  - ❌ DON'T: Do not use raw un-styled <video> tags — reach for Video primitive to handle placeholders and radius consistently.
- **Sample Declaration**:
```tsx
<Video src="/hero.mp4" poster="/hero-poster.jpg" ratio="16/9" fit="cover" autoPlay loop muted />
```

---

## 7. STRICT ARCHITECTURAL DO'S, DON'TS & ANTI-PATTERNS

Adhere strictly to these architectural quality gates. AI code generators frequently fail on subtle nuances:

### 1. Zero Hex / RGB Rule
- ❌ **DON'T**: `className="bg-[#1e1e20] text-white border-[rgba(255,255,255,0.1)]"`
- ✅ **DO**: `className="bg-surface text-fg border-hairline"`

### 2. Control vs Container Radius
- ❌ **DON'T**: Apply `rounded-[var(--radius-lg)]` to cards, dialogs, popovers, or accordions.
- ❌ **DON'T**: Use `rounded-xl` or `rounded-2xl` literals.
- ✅ **DO**: Apply `rounded-[var(--radius-panel)]` to cards, containers, dialogs, and accordions.
- ✅ **DO**: Apply `rounded-[var(--radius-lg)]` strictly to buttons, text fields, chips, and switches.

### 3. Concentric Padding Trap
- ❌ **DON'T**: Confuse `p-5` with 5px. `p-5` in Tailwind is 20px (1.25rem).
- ❌ **DON'T**: Write inline calculations like `calc(var(--radius-panel) - 5px)` for `p-5`.
- ✅ **DO**: Use pre-calculated concentric utilities: `rounded-panel-p5` for `p-5` containers, `rounded-panel-p3` for `p-3` containers.

### 4. Typography Contrast Pairing
- ❌ **DON'T**: Pair title `text-fg` directly with `text-fg-muted`.
- ✅ **DO**: Pair title `text-fg` with paired description `text-fg-subtle`. Reserve `text-fg-muted` for standalone metadata or timestamps.

### 5. Radix Select Sentinel Gotcha
- ❌ **DON'T**: Set `<Select value="" />` or `<SelectItem value="" />`. Empty string `""` is a reserved Radix sentinel that crashes rendering.
- ✅ **DO**: Use a named sentinel like `value="all"` or omit the `value` prop when empty.

### 6. Radix Overlay Data-Panel Attribute
- ❌ **DON'T**: Render custom floating overlays without `data-panel`.
- ✅ **DO**: Ensure any floating overlay (popover, dropdown, dialog) has `data-panel` attribute for translucent panel backdrop support.

### 7. Chevron Rotation Convention
- **Accordions**: Use `<ChevronDown />` rotated 180° up when expanded (`transition-transform duration-200 group-data-[state=open]:rotate-180`).
- **Nav Trees / Trees**: Use `<ChevronRight />` rotated 90° down when expanded (`transition-transform duration-200 group-data-[state=open]:rotate-90`).

### 8. AI-Slop Named Anti-Patterns (AP-01 to AP-11)
- **AP-01: Badge Soup**: Do NOT place badges above every single section title or feature card. Use clean typography hierarchy instead. Reserve badges for stateful status (e.g. "Active", "Paid", "Draft").
- **AP-02: Paragraph Walls**: Break large blocks of prose into scannable lists, data summaries, or visual callouts.
- **AP-03: Metric Clutter**: Limit dashboards to 3–4 primary KPI stat cards. Don't drown the canvas in redundant metrics.
- **AP-04: Glow Balls / 3D Balls**: Avoid arbitrary decorative gradient spheres or 3D balls that convey zero product value.
- **AP-05: Stock Photos**: Prefer authentic product UI mockups, interactive previews, and real application previews over stock photos.
- **AP-06: Over-Containment**: Don't wrap every individual element in a separate border card. Rely on whitespace proximity before reaching for container borders.
- **AP-07: Status-Chip Soup**: Avoid plastering multiple colorful chips together in tables.
- **AP-08: Kitchen-Sink Bento**: Don't force random unrelated widgets into an asymmetric bento grid.
- **AP-09: Defensive Minimalism**: Avoid empty, barren layouts that provide no utility or depth.
- **AP-10: Vacuous Copywriting**: Avoid generic marketing slogans ("Supercharge your workflow with AI"). Use concrete outcome formulas ("Deploy React apps with zero configuration").
- **AP-11: Lazy Placeholders**: Never use placeholder text like "Lorem ipsum" or broken image URLs.

---

## 8. MODEL CONTEXT PROTOCOL (MCP) SERVER & AI INTEGRATION

The `@shavin/mcp` server provides 20 specialized tools for AI coding assistants (Cursor, Claude Desktop, Antigravity) to query tokens, fetch component signatures, validate code, and verify live DOM compliance.

### Complete MCP Tools List

| Tool Name | Parameters | Purpose |
|---|---|---|
| `get_tokens` | `{ category?: string, density?: "dense" | "full" }` | Query semantic and foundation tokens directly from `tokens.json`. |
| `get_components` | `{ name?: string, density?: "dense" | "full" }` | Inspect exact component signatures, variants, props, and examples. |
| `get_guidelines` | `{ section?: string }` | Retrieve architectural rules, Radix gotchas, and quality gates from AGENTS.md. |
| `get_setup_instructions` | `{ framework: "nextjs" | "react-vite" | "generic" }` | Get copy-paste installation and configuration guides. |
| `get_builder_schema` | `{ category?: string }` | Retrieve visual builder AST schemas and component metadata. |
| `get_block_template` | `{ id: string }` | Retrieve source code and templates for pre-built blocks (auth, chat, dashboard). |
| `validate_code` | `{ code: string, filePath?: string }` | Run token purity and concentric radius linters on JSX/TSX code. |
| `autofix_code` | `{ code: string }` | Automatically rewrite hex codes, invalid radius classes, and bad imports into compliant Shavin tokens. |
| `inspect_environment` | `{}` | Diagnose project setup, theme settings, package versions, and dependencies. |
| `get_project_context` | `{}` | Read `SHAVIN.md` configuration from active project root. |
| `shavin_steer` | `{ query: string }` | High-level guidance tool recommending appropriate skills and architectural paths. |
| `synthesize_layout` | `{ layoutType: string, blocks: string[] }` | Compose full-page layouts using Shavin design rules. |
| `get_live_audit` | `{ path?: string }` | Check live browser tab DOM compliance and WCAG contrast violations via Bridge daemon (:7428). |
| `trigger_live_rescan`| `{ path?: string }` | Force immediate browser rescan of active page. |
| `wait_for_live_clean`| `{ path?: string, timeoutMs?: number }` | Block until zero audit violations remain in the active browser tab. |
| `list_skills` | `{}` | Enumerate available AI skills and instruction manuals. |
| `get_skill` | `{ name: string, section?: string }` | Fetch targeted instructions from a specific AI skill module. |
| `get_skill_mode` | `{ intent: string }` | Match user intent against the Design Activation Matrix. |
| `list_commands` | `{}` | List all available slash commands (/create-screen, /create-block, /audit-ui). |
| `install_skills` | `{ targetDir?: string }` | Synchronize skill markdown files into consuming workspace. |

---

## 9. PRE-BUILT BLOCKS & PRODUCTION TEMPLATES

`@shavin/ui` includes pre-composed production templates that can be used directly or registered into Shavin Studio:

1. **AI Chat Interface** (`/blocks/chat`): Full conversational view with auto-scrolling message list, `<ChatBubble>`, typing indicators, code snippet rendering, and floating `<TextArea>` input action bar.
2. **Authentication Flow** (`/blocks/auth`): Clean, centered auth cards with tabs for Sign In and Sign Up, social OAuth buttons, email validation, and password recovery.
3. **Settings & Account Panel** (`/blocks/settings-panel`): Multi-tab account management shell with profile avatar upload, notification toggles, API key generation, and billing history table.
4. **Subscription Pricing Plans** (`/blocks/pricing-plans`): High-conversion pricing grid with Monthly/Annual billing frequency `<SegmentedControl>`, feature checkmarks, and highlighted "Popular" tier.
5. **Analytics Dashboard Template** (`/blocks/templates/dashboard`): Full-width `<AppFrame>` layout with collapsible `<Sidebar>`, header `<TopBar>`, 4 KPI `<StatCard>` widgets, SVG `<Chart>`, and paginated `<Table>`.
6. **E-Commerce Storefront** (`/blocks/templates/ecommerce`): Filterable product catalog with `<CheckboxCards>`, price `<Slider>`, product image gallery, and flyout cart drawer.
7. **Marketing Landing Page** (`/blocks/templates/landing`): 12-section vertical reading arc with fluid header navigation, bold typography hero, live product preview canvas, customer testimonials, and conversion CTA.

---
*Generated by @shavin/cli & @shavin/ui documentation engine. For live interactive previews, visit https://docs.shavin.cc.*