@codeswayam/ui 1.2.1 → 1.3.0

package/README.md

@@ -1,323 +1,877 @@
 # @codeswayam/ui
 
-**Version:** 1.2.0
+[![npm version](https://img.shields.io/npm/v/@codeswayam/ui?style=flat-square&color=6366f1)](https://www.npmjs.com/package/@codeswayam/ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18%2B%20%7C%2019-61DAFB?style=flat-square&logo=react)](https://react.dev/)
+[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.x-38BDF8?style=flat-square&logo=tailwindcss)](https://tailwindcss.com/)
+[![Radix UI](https://img.shields.io/badge/Radix%20UI-primitives-blueviolet?style=flat-square)](https://www.radix-ui.com/)
 
-Shared React UI component library for all CodeSwayam SaaS applications. Built on Radix UI primitives with Tailwind CSS. Includes base components, SaaS-specific components, layout components, and design tokens.
+> Shared component library for all CodeSwayam applications — built on Radix UI primitives, styled with Tailwind CSS, and patterned after shadcn/ui conventions.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Peer Dependencies](#peer-dependencies)
+- [Setup](#setup)
+- [Component Reference](#component-reference)
+  - [Base Components](#base-components)
+  - [Data Components](#data-components)
+  - [Display Components](#display-components)
+  - [Feedback Components](#feedback-components)
+  - [Layout Components](#layout-components)
+  - [Brand Mesh Components](#brand-mesh-components)
+  - [SaaS Components](#saas-components)
+- [Utilities](#utilities)
+- [Design Tokens](#design-tokens)
+- [Code Examples](#code-examples)
+- [Compatibility Matrix](#compatibility-matrix)
+
+---
+
+## Overview
+
+`@codeswayam/ui` is the single source of truth for UI across all CodeSwayam products. It provides:
+
+- **Base primitives** — Button, Card, Badge, Input, Label, Avatar, Modal, Dropdown
+- **Data display** — Full-featured DataTable powered by TanStack Table v8
+- **Display components** — KPI StatCards, PageHeader, CopyButton
+- **Feedback** — Skeleton loaders, ConfirmDialog, ErrorState
+- **Layout** — Platform-wide GlobalNavbar and GlobalFooter
+- **SaaS-specific** — StatusBadge, UserMenu
+
+Every component is fully typed, supports dark mode, and uses `class-variance-authority` (CVA) for variant management.
 
 ---
 
 ## Installation
 
 ```bash
+# npm
 npm install @codeswayam/ui
+
+# yarn
+yarn add @codeswayam/ui
+
+# pnpm
+pnpm add @codeswayam/ui
 ```
 
-**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `next >= 13`
+---
+
+## Peer Dependencies
+
+| Dependency | Version | Purpose |
+|---|---|---|
+| `react` | `^18.0.0 \|\| ^19.0.0` | React runtime |
+| `react-dom` | `^18.0.0 \|\| ^19.0.0` | DOM bindings |
+| `tailwindcss` | `^3.4.0` | Utility-first CSS framework |
+| `@radix-ui/react-dialog` | `^1.0.0` | Modal/Dialog primitives |
+| `@radix-ui/react-dropdown-menu` | `^2.0.0` | Dropdown menu primitives |
+| `@radix-ui/react-avatar` | `^1.0.0` | Avatar primitives |
+| `@radix-ui/react-label` | `^2.0.0` | Label primitive |
+| `@tanstack/react-table` | `^8.0.0` | Headless table for DataTable |
+| `class-variance-authority` | `^0.7.0` | Variant class management |
+| `clsx` | `^2.0.0` | Conditional class joining |
+| `tailwind-merge` | `^2.0.0` | Tailwind class deduplication |
+| `lucide-react` | `^0.400.0` | Icon set |
+
+Install all peer dependencies:
+
+```bash
+npm install react react-dom tailwindcss \
+  @radix-ui/react-dialog @radix-ui/react-dropdown-menu \
+  @radix-ui/react-avatar @radix-ui/react-label \
+  @tanstack/react-table class-variance-authority \
+  clsx tailwind-merge lucide-react
+```
 
 ---
 
 ## Setup
 
-Include the package source in your app's Tailwind config so styles are picked up:
+### 1. Import global CSS tokens
+
+Add the design token stylesheet to your app's entry point (e.g., `app/layout.tsx` in Next.js):
+
+```tsx
+// app/layout.tsx
+import '@codeswayam/ui/globals.css';
+```
+
+### 2. Configure Tailwind
+
+Add the package to your `tailwind.config.ts` content paths so Tailwind can detect and include its classes:
 
-```js
-// tailwind.config.js
-module.exports = {
+```ts
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
   content: [
-    "./src/**/*.{ts,tsx}",
-    "./node_modules/@codeswayam/ui/dist/**/*.{js,mjs}",
+    './app/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    // Include the UI package
+    './node_modules/@codeswayam/ui/src/**/*.{ts,tsx}',
   ],
+  darkMode: 'class',
+  theme: {
+    extend: {},
+  },
+  plugins: [],
 };
+
+export default config;
 ```
 
-Import the global CSS tokens in your root layout:
+### 3. Import and use components
 
 ```tsx
-// app/layout.tsx
-import "@codeswayam/ui/dist/globals.css"; // design tokens + base styles
+import { Button, Card, CardContent } from '@codeswayam/ui';
 ```
 
 ---
 
-## Utility
+## Component Reference
 
-### `cn(...inputs)`
+### Base Components
 
-Merges Tailwind classes with conflict resolution via `clsx` + `tailwind-merge`.
+#### Button
 
-```typescript
-import { cn } from "@codeswayam/ui";
+```tsx
+import { Button } from '@codeswayam/ui';
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | Visual style variant |
+| `size` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'default'` | Button size |
+| `asChild` | `boolean` | `false` | Render as a child element (Radix Slot) |
+| `disabled` | `boolean` | `false` | Disables the button |
+| ...`ButtonHTMLAttributes` | | | All native button props |
 
-cn("px-4 py-2", isActive && "bg-primary", "px-6");
-// → "py-2 bg-primary px-6"
+---
+
+#### Card
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@codeswayam/ui';
 ```
 
+| Component | Description |
+|---|---|
+| `Card` | Outer container with border, shadow, and rounded corners |
+| `CardHeader` | Top section — typically holds title and description |
+| `CardTitle` | Heading text inside the header |
+| `CardDescription` | Subtitle / muted description inside the header |
+| `CardContent` | Main content area with padding |
+| `CardFooter` | Bottom section — typically holds actions |
+
 ---
 
-## Base Components
+#### Badge
 
-### `<Button>`
+```tsx
+import { Badge } from '@codeswayam/ui';
+```
 
-Built with `class-variance-authority` and Radix `Slot` for polymorphic rendering.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | Color and style variant |
+| ...`HTMLAttributes<HTMLDivElement>` | | | All native div props |
+
+---
+
+#### Input
 
 ```tsx
-import { Button } from "@codeswayam/ui";
+import { Input } from '@codeswayam/ui';
+```
+
+Accepts all standard `InputHTMLAttributes<HTMLInputElement>` props. Renders a styled text input consistent with the design system.
+
+---
 
-<Button variant="default" size="default">Click me</Button>
-<Button variant="outline" size="sm">Cancel</Button>
-<Button variant="destructive">Delete</Button>
-<Button variant="ghost" size="icon"><TrashIcon /></Button>
+#### Label
 
-// Render as a link using asChild
-<Button asChild variant="default">
-  <a href="/dashboard">Go to Dashboard</a>
-</Button>
+```tsx
+import { Label } from '@codeswayam/ui';
 ```
 
-**Variants:** `default`, `destructive`, `outline`, `secondary`, `ghost`, `link`
-**Sizes:** `default`, `sm`, `lg`, `icon`
+Wraps Radix `@radix-ui/react-label`. Accepts all native `LabelHTMLAttributes` and a `htmlFor` prop.
 
 ---
 
-### `<Card>` family
+#### Avatar
 
 ```tsx
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@codeswayam/ui";
+import { Avatar, AvatarImage, AvatarFallback } from '@codeswayam/ui';
+```
 
-<Card>
-  <CardHeader>
-    <CardTitle>Plan Overview</CardTitle>
-    <CardDescription>Your current subscription details</CardDescription>
-  </CardHeader>
-  <CardContent>
-    <p>Pro Plan — ₹499/month</p>
-  </CardContent>
-  <CardFooter>
-    <Button>Manage Plan</Button>
-  </CardFooter>
-</Card>
+| Component | Description |
+|---|---|
+| `Avatar` | Container with size constraints and rounded styling |
+| `AvatarImage` | Renders the user image with `onError` fallback behaviour |
+| `AvatarFallback` | Shown when the image fails to load (e.g., initials) |
+
+---
+
+#### Modal
+
+```tsx
+import { Modal } from '@codeswayam/ui';
 ```
 
+| Prop | Type | Description |
+|---|---|---|
+| `open` | `boolean` | Controls open/close state |
+| `onOpenChange` | `(open: boolean) => void` | Called when state changes |
+| `title` | `string` | Modal heading |
+| `description` | `string` | Optional subtitle |
+| `children` | `ReactNode` | Modal body content |
+| `trigger` | `ReactNode` | Optional trigger element |
+
 ---
 
-### `<Badge>`
+#### DropdownMenu
 
 ```tsx
-import { Badge } from "@codeswayam/ui";
+import { DropdownMenu } from '@codeswayam/ui';
+```
+
+Re-exports Radix `@radix-ui/react-dropdown-menu` primitives with consistent styling. Supports all Radix sub-components: `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSeparator`, etc.
+
+---
+
+### Data Components
 
-<Badge variant="default">Active</Badge>
-<Badge variant="secondary">Beta</Badge>
-<Badge variant="destructive">Expired</Badge>
-<Badge variant="outline">Free</Badge>
-<Badge variant="success">Paid</Badge>
-<Badge variant="warning">Pending</Badge>
-<Badge variant="info">Info</Badge>
-<Badge variant="purple">AI</Badge>
+#### DataTable
+
+Full TanStack Table v8 implementation with sorting, global filtering, column visibility, and pagination.
+
+```tsx
+import { DataTable } from '@codeswayam/ui';
 ```
 
-**Variants:** `default`, `secondary`, `destructive`, `outline`, `success`, `warning`, `info`, `purple`
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `columns` | `ColumnDef<TData>[]` | ✅ | TanStack Table column definitions |
+| `data` | `TData[]` | ✅ | Array of row data |
+| `searchKey` | `string` | ❌ | Column key to use for global search |
+| `pagination` | `boolean` | ❌ | Enable pagination controls |
+| `actions` | `ReactNode` | ❌ | Additional action elements in the toolbar |
 
 ---
 
-### `<Input>`
+#### TableToolbar
+
+Internal toolbar used by `DataTable`, also exportable for custom table implementations.
+
+| Prop | Type | Description |
+|---|---|---|
+| `table` | `Table<TData>` | TanStack Table instance |
+| `searchKey` | `string` | Column accessor key for search |
+| `actions` | `ReactNode` | Additional toolbar actions |
+
+---
+
+#### EmptyState
 
 ```tsx
-import { Input } from "@codeswayam/ui";
+import { EmptyState } from '@codeswayam/ui';
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `icon` | `ReactNode` | Icon element (e.g., from lucide-react) |
+| `title` | `string` | Primary empty state message |
+| `description` | `string` | Secondary supporting text |
+| `action` | `ReactNode` | Optional call-to-action button |
+
+---
+
+### Display Components
 
-<Input type="email" placeholder="Enter your email" />
-<Input type="password" disabled />
+#### StatCard
+
+KPI metric card with optional trend indicator.
+
+```tsx
+import { StatCard } from '@codeswayam/ui';
 ```
 
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | ✅ | Metric label |
+| `value` | `string \| number` | ✅ | Current metric value |
+| `trend` | `'up' \| 'down' \| 'neutral'` | ❌ | Trend direction |
+| `trendValue` | `string` | ❌ | Trend change text (e.g., `"+12%"`) |
+| `icon` | `ReactNode` | ❌ | Icon element |
+| `description` | `string` | ❌ | Supporting text below the value |
+
 ---
 
-### `<Label>`
+#### PageHeader
 
 ```tsx
-import { Label } from "@codeswayam/ui";
+import { PageHeader } from '@codeswayam/ui';
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `title` | `string` | Page title |
+| `description` | `string` | Optional subtitle |
+| `actions` | `ReactNode` | Right-side action buttons |
 
-<Label htmlFor="email">Email Address</Label>
-<Input id="email" type="email" />
+---
+
+#### CopyButton
+
+```tsx
+import { CopyButton } from '@codeswayam/ui';
 ```
 
+| Prop | Type | Description |
+|---|---|---|
+| `value` | `string` | Text to copy to clipboard |
+| `className` | `string` | Additional CSS classes |
+
+Shows a checkmark icon on successful copy, then reverts after 2 seconds.
+
 ---
 
-### `<Avatar>`, `<AvatarImage>`, `<AvatarFallback>`
+### Feedback Components
 
-Built on Radix Avatar with automatic fallback to initials.
+#### Skeleton
 
 ```tsx
-import { Avatar, AvatarImage, AvatarFallback } from "@codeswayam/ui";
+import { Skeleton } from '@codeswayam/ui';
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `className` | `string` | Width, height, and shape via Tailwind classes |
 
-<Avatar className="h-10 w-10 rounded-lg">
-  <AvatarImage src={user.image} alt={user.name} />
-  <AvatarFallback className="bg-primary/10 text-primary font-bold">
-    {initials}
-  </AvatarFallback>
-</Avatar>
+Use as a drop-in loading placeholder:
+
+```tsx
+<Skeleton className="h-4 w-[250px]" />
+<Skeleton className="h-12 w-12 rounded-full" />
 ```
 
 ---
 
-### `<DropdownMenu>` and sub-components
+#### ConfirmDialog
 
-Full Radix DropdownMenu with all primitives exported.
+```tsx
+import { ConfirmDialog } from '@codeswayam/ui';
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `open` | `boolean` | ✅ | Controls open/close state |
+| `onOpenChange` | `(open: boolean) => void` | ✅ | State change handler |
+| `onConfirm` | `() => void` | ✅ | Called on confirmation |
+| `title` | `string` | ✅ | Dialog heading |
+| `description` | `string` | ✅ | Warning message |
+| `confirmLabel` | `string` | ❌ | Confirm button text (default: `"Confirm"`) |
+| `cancelLabel` | `string` | ❌ | Cancel button text (default: `"Cancel"`) |
+| `variant` | `'default' \| 'destructive'` | ❌ | Confirm button style |
+
+---
+
+#### ErrorState
 
 ```tsx
-import {
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuGroup,
-  DropdownMenuShortcut,
-} from "@codeswayam/ui";
+import { ErrorState } from '@codeswayam/ui';
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `title` | `string` | Error heading |
+| `description` | `string` | Error details |
+| `retry` | `() => void` | Optional retry callback — shows a "Try again" button |
 
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <Button variant="ghost">Options</Button>
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align="end">
-    <DropdownMenuLabel>My Account</DropdownMenuLabel>
-    <DropdownMenuSeparator />
-    <DropdownMenuItem onClick={handleProfile}>Profile</DropdownMenuItem>
-    <DropdownMenuItem onClick={handleLogout} className="text-destructive">
-      Sign Out
-    </DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
+---
+
+### Layout Components
+
+#### GlobalNavbar
+
+Platform-wide top navigation bar used across all CodeSwayam apps.
+
+```tsx
+import { GlobalNavbar } from '@codeswayam/ui';
 ```
 
+| Prop | Type | Description |
+|---|---|---|
+| `links` | `NavLink[]` | Array of `{ href, label, active? }` navigation links |
+| `user` | `NavUser` | `{ name, email, avatarUrl? }` for user display |
+| `notifications` | `Notification[]` | Array of notification items |
+| `credits` | `number` | Current AI credit balance to display |
+
 ---
 
-## SaaS Components
+#### GlobalFooter
+
+```tsx
+import { GlobalFooter } from '@codeswayam/ui';
+```
+
+Platform-wide footer with links and branding. Accepts no required props — configuration is embedded from the package.
+
+---
 
-### `<UserMenu>`
+### Brand Mesh Components
 
-High-end user profile dropdown for SaaS navigation bars. Shows avatar, name, email, and action items (Profile Settings, Security, Sign Out).
+#### BrandNav & BrandAppSwitcher
+
+Federated ecosystem navigation and 9-dot app launcher connecting all CodeSwayam products (Code Swayam, PixelForge, PDFCraft, Neural AI, AuraFlow).
 
 ```tsx
-import { UserMenu } from "@codeswayam/ui";
+import { BrandNav, BrandAppSwitcher } from '@codeswayam/ui';
+
+// Standalone Nav Bar
+<BrandNav
+  currentProduct="pixelforge"
+  theme="dark" // "dark" | "light"
+  ctaText="Explore CodeSwayam"
+  ctaHref="https://codeswayam.com"
+/>
 
-<UserMenu
-  user={{ name: "Niteesh", email: "niteesh@example.com", image: "/avatar.jpg" }}
-  onLogout={handleLogout}
-  onProfileClick={() => router.push("/settings")}
-  onSecurityClick={() => router.push("/settings/security")}
+// Or embed the 9-dot App Switcher inside your custom navbar:
+<BrandAppSwitcher
+  currentProduct="pdfcraft"
+  theme="light"
 />
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `user` | `{ name?, email, image? } \| null` | User to display. Renders nothing if null |
-| `onLogout` | `() => void` | Called when "Sign Out" is clicked |
-| `onProfileClick` | `() => void` | Called when "Profile Settings" is clicked |
-| `onSecurityClick` | `() => void` | Called when "Security" is clicked |
-| `className` | `string` | Additional CSS classes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `currentProduct` | `'codeswayam' \| 'pixelforge' \| 'pdfcraft' \| 'neural' \| 'auraflow'` | `undefined` | Highlights active application with "Current" badge |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Visual styling theme for backgrounds and text |
+| `ctaText` | `string` | `'Explore Suite'` | Call-to-action button label |
+| `ctaHref` | `string` | `'https://codeswayam.com'` | Destination URL for the CTA button |
 
 ---
 
-### `<AppLogo>`
+#### BrandFooterSection
 
-Standard CodeSwayam app logo for consistency across platforms.
+Cross-domain internal linking block with built-in Schema.org Knowledge Graph `Organization` entity JSON-LD to pass Domain Authority and topical trust across subdomains.
 
 ```tsx
-import { AppLogo } from "@codeswayam/ui";
+import { BrandFooterSection } from '@codeswayam/ui';
 
-<AppLogo />                    // Icon + "CodeSwayam" text
-<AppLogo showText={false} />   // Icon only
-<AppLogo className="scale-90" />
+<BrandFooterSection
+  currentApp="pixelforge"
+  theme="dark" // "dark" | "light"
+/>
 ```
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `showText` | `boolean` | `true` | Whether to show the "CodeSwayam" text |
-| `className` | `string` | — | Additional CSS classes |
+|---|---|---|---|
+| `currentApp` | `'codeswayam' \| 'pixelforge' \| 'pdfcraft' \| 'neural' \| 'auraflow'` | `undefined` | Highlights active application in the ecosystem grid |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Color scheme for footer text, borders, and backgrounds |
 
 ---
 
-### `<StatusBadge>`
+### SaaS Components
 
-Smart subscription status badge with automatic color coding.
+#### StatusBadge
 
-```tsx
-import { StatusBadge } from "@codeswayam/ui";
+Specialized badge for subscription and plan statuses.
 
-<StatusBadge status="active" />               // Green — "Active"
-<StatusBadge status="pending_cancellation" /> // Amber — "Pending Cancel"
-<StatusBadge status="canceled" />             // Red — "Canceled"
-<StatusBadge status="past_due" />             // Red — "Past Due"
+```tsx
+import { StatusBadge } from '@codeswayam/ui';
 ```
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `status` | `"active" \| "past_due" \| "canceled" \| "pending_cancellation" \| string` | Subscription status |
+|---|---|---|
+| `status` | `'active' \| 'cancelled' \| 'trial' \| 'expired'` | Subscription status |
 | `className` | `string` | Additional CSS classes |
 
+Color mapping:
+
+| Status | Color |
+|---|---|
+| `active` | Green |
+| `trial` | Blue / Indigo |
+| `cancelled` | Gray |
+| `expired` | Red |
+
+---
+
+#### UserMenu
+
+User avatar dropdown with profile, settings, and logout actions.
+
+```tsx
+import { UserMenu } from '@codeswayam/ui';
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `user` | `{ name: string; email: string; avatarUrl?: string }` | ✅ | User info for display |
+| `onSignOut` | `() => void` | ✅ | Callback for sign-out action |
+
+---
+
+## Utilities
+
+### `cn()` — className utility
+
+```tsx
+import { cn } from '@codeswayam/ui';
+```
+
+Combines `clsx` and `tailwind-merge` to safely join conditional class names without Tailwind conflicts:
+
+```tsx
+// Merges classes, resolving Tailwind conflicts intelligently
+cn('px-4 py-2', isActive && 'bg-blue-600', 'px-6')
+// → 'py-2 bg-blue-600 px-6'  (px-4 is overridden by px-6)
+```
+
 ---
 
-## Layout Components
+## Design Tokens
 
-### `<GlobalNavbar>`
+Import the global stylesheet for CSS custom properties:
 
-Responsive marketing navbar for public-facing pages. Auto-hides on app routes (`/app/*`, `/dashboard/*`). Includes scroll-aware blur effect, desktop nav links, and mobile slide-in menu.
+```tsx
+import '@codeswayam/ui/globals.css';
+```
+
+This provides CSS variables following the shadcn/ui convention:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 47.4% 11.2%;
+  --primary: 262.1 83.3% 57.8%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --border: 214.3 31.8% 91.4%;
+  --radius: 0.5rem;
+  /* ... */
+}
+
+.dark {
+  --background: 224 71% 4%;
+  --foreground: 213 31% 91%;
+  /* ... dark mode overrides ... */
+}
+```
+
+To enable dark mode, apply the `dark` class to your `<html>` element.
+
+---
+
+## Code Examples
+
+### 1. Installation and Setup
 
 ```tsx
-import { GlobalNavbar } from "@codeswayam/ui";
+// app/layout.tsx (Next.js App Router)
+import '@codeswayam/ui/globals.css';
+import type { ReactNode } from 'react';
 
-// In your root layout — renders only on public pages
-export default function RootLayout({ children }) {
+export default function RootLayout({ children }: { children: ReactNode }) {
   return (
-    <>
-      <GlobalNavbar />
-      {children}
-    </>
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+---
+
+### 2. Button Variants
+
+```tsx
+import { Button } from '@codeswayam/ui';
+
+export function ButtonShowcase() {
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button variant="default">Save Changes</Button>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="destructive">Delete Account</Button>
+      <Button variant="ghost">View Details</Button>
+      <Button variant="link">Learn more →</Button>
+      <Button size="sm">Small</Button>
+      <Button size="lg">Large</Button>
+      <Button disabled>Disabled</Button>
+    </div>
+  );
+}
+```
+
+---
+
+### 3. DataTable with Column Definitions
+
+```tsx
+import { DataTable } from '@codeswayam/ui';
+import type { ColumnDef } from '@tanstack/react-table';
+
+type User = {
+  id: string;
+  name: string;
+  email: string;
+  status: 'active' | 'inactive';
+  joinedAt: string;
+};
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => (
+      <StatusBadge status={row.getValue('status')} />
+    ),
+  },
+  {
+    accessorKey: 'joinedAt',
+    header: 'Joined',
+    cell: ({ row }) => new Date(row.getValue('joinedAt')).toLocaleDateString(),
+  },
+];
+
+export function UsersTable({ users }: { users: User[] }) {
+  return (
+    <DataTable
+      columns={columns}
+      data={users}
+      searchKey="name"
+      pagination
+    />
   );
 }
 ```
 
-- Transparent on load, blurred dark background on scroll
-- Auth links route to `NEXT_PUBLIC_AUTH_URL` or `localhost:3003` in dev
-- Full-screen mobile menu with slide animation
-- Hidden automatically on `/app` and `/dashboard` routes
+---
+
+### 4. StatCard for KPI Dashboard
+
+```tsx
+import { StatCard } from '@codeswayam/ui';
+import { Users, TrendingUp, DollarSign, Zap } from 'lucide-react';
+
+export function DashboardStats() {
+  return (
+    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+      <StatCard
+        title="Total Users"
+        value="12,481"
+        trend="up"
+        trendValue="+8.2%"
+        icon={<Users className="h-5 w-5 text-blue-500" />}
+        description="vs. last month"
+      />
+      <StatCard
+        title="Monthly Revenue"
+        value="$48,290"
+        trend="up"
+        trendValue="+14.5%"
+        icon={<DollarSign className="h-5 w-5 text-green-500" />}
+        description="vs. last month"
+      />
+      <StatCard
+        title="Churn Rate"
+        value="2.4%"
+        trend="down"
+        trendValue="-0.8%"
+        icon={<TrendingUp className="h-5 w-5 text-red-500" />}
+        description="vs. last month"
+      />
+      <StatCard
+        title="AI Credits Used"
+        value="1.2M"
+        trend="up"
+        trendValue="+23%"
+        icon={<Zap className="h-5 w-5 text-yellow-500" />}
+        description="this billing cycle"
+      />
+    </div>
+  );
+}
+```
 
 ---
 
-### `<GlobalFooter>`
+### 5. GlobalNavbar Integration
 
-Standard marketing footer for public pages.
+```tsx
+import { GlobalNavbar } from '@codeswayam/ui';
+import { usePathname } from 'next/navigation';
+
+const NAV_LINKS = [
+  { href: '/dashboard', label: 'Dashboard' },
+  { href: '/agents', label: 'Agents' },
+  { href: '/workflows', label: 'Workflows' },
+  { href: '/analytics', label: 'Analytics' },
+];
+
+export function AppNavbar({ user, credits, notifications }) {
+  const pathname = usePathname();
+
+  return (
+    <GlobalNavbar
+      links={NAV_LINKS.map((link) => ({
+        ...link,
+        active: pathname.startsWith(link.href),
+      }))}
+      user={user}
+      notifications={notifications}
+      credits={credits}
+    />
+  );
+}
+```
+
+---
+
+### 6. StatusBadge for Subscription Status
 
 ```tsx
-import { GlobalFooter } from "@codeswayam/ui";
+import { StatusBadge, Card, CardContent } from '@codeswayam/ui';
 
-<GlobalFooter />
+type Subscription = {
+  planName: string;
+  status: 'active' | 'trial' | 'cancelled' | 'expired';
+  renewsAt: string;
+};
+
+export function SubscriptionCard({ sub }: { sub: Subscription }) {
+  return (
+    <Card>
+      <CardContent className="pt-6 flex items-center justify-between">
+        <div>
+          <p className="font-semibold">{sub.planName}</p>
+          <p className="text-sm text-muted-foreground">
+            Renews {new Date(sub.renewsAt).toLocaleDateString()}
+          </p>
+        </div>
+        <StatusBadge status={sub.status} />
+      </CardContent>
+    </Card>
+  );
+}
 ```
 
 ---
 
-## Full Export List
+### 7. ConfirmDialog for Destructive Actions
 
-```typescript
-// Base
-Button, buttonVariants
-Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
-Badge, badgeVariants
-Input
-Label
-Avatar, AvatarImage, AvatarFallback
-DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
-DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel,
-DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup,
-DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent,
-DropdownMenuSubTrigger, DropdownMenuRadioGroup
+```tsx
+import { useState } from 'react';
+import { Button, ConfirmDialog } from '@codeswayam/ui';
 
-// SaaS
-UserMenu, AppLogo, StatusBadge
+export function DeleteAgentButton({ agentId, onDelete }) {
+  const [open, setOpen] = useState(false);
 
-// Layout
-GlobalNavbar, GlobalFooter
+  const handleConfirm = async () => {
+    await onDelete(agentId);
+    setOpen(false);
+  };
 
-// Utils
-cn
+  return (
+    <>
+      <Button variant="destructive" size="sm" onClick={() => setOpen(true)}>
+        Delete Agent
+      </Button>
+      <ConfirmDialog
+        open={open}
+        onOpenChange={setOpen}
+        onConfirm={handleConfirm}
+        title="Delete Agent"
+        description="This will permanently delete the agent and all associated conversation history. This action cannot be undone."
+        confirmLabel="Delete"
+        cancelLabel="Keep Agent"
+        variant="destructive"
+      />
+    </>
+  );
+}
 ```
+
+---
+
+### 8. Skeleton Loading States
+
+```tsx
+import { Skeleton, Card, CardContent, CardHeader } from '@codeswayam/ui';
+
+export function AgentCardSkeleton() {
+  return (
+    <Card>
+      <CardHeader className="space-y-2">
+        <Skeleton className="h-5 w-1/3" />
+        <Skeleton className="h-4 w-2/3" />
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-5/6" />
+        <Skeleton className="h-4 w-4/6" />
+      </CardContent>
+    </Card>
+  );
+}
+
+export function DashboardSkeleton() {
+  return (
+    <div className="space-y-6">
+      {/* Stats row */}
+      <div className="grid grid-cols-4 gap-4">
+        {Array.from({ length: 4 }).map((_, i) => (
+          <Skeleton key={i} className="h-28 rounded-xl" />
+        ))}
+      </div>
+      {/* Table */}
+      <Skeleton className="h-64 rounded-xl" />
+    </div>
+  );
+}
+```
+
+---
+
+## Compatibility Matrix
+
+| Environment | Supported | Notes |
+|---|---|---|
+| React 18.x | ✅ | Full support |
+| React 19.x | ✅ | Full support |
+| Next.js 14 (App Router) | ✅ | Import CSS in root layout |
+| Next.js 14 (Pages Router) | ✅ | Import CSS in `_app.tsx` |
+| Next.js 15 | ✅ | Full support |
+| Vite (React) | ✅ | Standard setup |
+| Remix | ✅ | Import CSS in root route |
+| Tailwind CSS 3.x | ✅ | Required — add package to content paths |
+| TypeScript 4.x | ✅ | Minimum supported |
+| TypeScript 5.x | ✅ | Recommended |
+| Dark mode | ✅ | CSS class strategy (`dark` on `<html>`) |
+| SSR | ✅ | All components are SSR-safe |
+| Tree-shaking | ✅ | Named imports are tree-shakeable |
+
+---
+
+## License
+
+MIT © CodeSwayam