@codeswayam/ui

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
• Installation
• Peer Dependencies
• Setup
• Component Reference
  • Base Components
  • Data Components
  • Display Components
  • Feedback Components
  • Layout Components
  • Brand Mesh Components
  • SaaS Components
• Utilities
• Design Tokens
• Code Examples
• 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

# npm
npm install @codeswayam/ui

# yarn
yarn add @codeswayam/ui

# pnpm
pnpm add @codeswayam/ui

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:

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

1. Import global CSS tokens

Add the design token stylesheet to your app's entry point (e.g., app/layout.tsx in Next.js):

// 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:

// tailwind.config.ts
import type { Config } from 'tailwindcss';

const config: Config = {
  content: [
    './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;

3. Import and use components

import { Button, Card, CardContent } from '@codeswayam/ui';

Component Reference

Base Components

Button

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 |

Card

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 |

Badge

import { Badge } from '@codeswayam/ui';

| Prop | Type | Default | Description | |---|---|---|---| | variant | 'default' \| 'secondary' \| 'destructive' \| 'outline' | 'default' | Color and style variant | | ...HTMLAttributes<HTMLDivElement> | | | All native div props |

Input

import { Input } from '@codeswayam/ui';

Accepts all standard InputHTMLAttributes<HTMLInputElement> props. Renders a styled text input consistent with the design system.

Label

import { Label } from '@codeswayam/ui';

Wraps Radix @radix-ui/react-label. Accepts all native LabelHTMLAttributes and a htmlFor prop.

Avatar

import { Avatar, AvatarImage, AvatarFallback } from '@codeswayam/ui';

| 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

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 |

DropdownMenu

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

DataTable

Full TanStack Table v8 implementation with sorting, global filtering, column visibility, and pagination.

import { DataTable } from '@codeswayam/ui';

| 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 |

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

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

StatCard

KPI metric card with optional trend indicator.

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 |

PageHeader

import { PageHeader } from '@codeswayam/ui';

| Prop | Type | Description | |---|---|---| | title | string | Page title | | description | string | Optional subtitle | | actions | ReactNode | Right-side action buttons |

CopyButton

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.

Feedback Components

Skeleton

import { Skeleton } from '@codeswayam/ui';

| Prop | Type | Description | |---|---|---| | className | string | Width, height, and shape via Tailwind classes |

Use as a drop-in loading placeholder:

<Skeleton className="h-4 w-[250px]" />
<Skeleton className="h-12 w-12 rounded-full" />

ConfirmDialog

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

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 |

Layout Components

GlobalNavbar

Platform-wide top navigation bar used across all CodeSwayam apps.

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 |

GlobalFooter

import { GlobalFooter } from '@codeswayam/ui';

Platform-wide footer with links and branding. Accepts no required props — configuration is embedded from the package.

Brand Mesh Components

BrandNav & BrandAppSwitcher

Federated ecosystem navigation and 9-dot app launcher connecting all CodeSwayam products (Code Swayam, PixelForge, PDFCraft, Neural AI, AuraFlow).

import { BrandNav, BrandAppSwitcher } from '@codeswayam/ui';

// Standalone Nav Bar
<BrandNav
  currentProduct="pixelforge"
  theme="dark" // "dark" | "light"
  ctaText="Explore CodeSwayam"
  ctaHref="https://codeswayam.com"
/>

// Or embed the 9-dot App Switcher inside your custom navbar:
<BrandAppSwitcher
  currentProduct="pdfcraft"
  theme="light"
/>

| 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 |

BrandFooterSection

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.

import { BrandFooterSection } from '@codeswayam/ui';

<BrandFooterSection
  currentApp="pixelforge"
  theme="dark" // "dark" | "light"
/>

| Prop | Type | Default | Description | |---|---|---|---| | 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 |

SaaS Components

StatusBadge

Specialized badge for subscription and plan statuses.

import { StatusBadge } from '@codeswayam/ui';

| Prop | Type | Description | |---|---|---| | 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.

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

import { cn } from '@codeswayam/ui';

Combines clsx and tailwind-merge to safely join conditional class names without Tailwind conflicts:

// 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)

Design Tokens

Import the global stylesheet for CSS custom properties:

import '@codeswayam/ui/globals.css';

This provides CSS variables following the shadcn/ui convention:

: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

// app/layout.tsx (Next.js App Router)
import '@codeswayam/ui/globals.css';
import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

2. Button Variants

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

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
    />
  );
}

4. StatCard for KPI Dashboard

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>
  );
}

5. GlobalNavbar Integration

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

import { StatusBadge, Card, CardContent } from '@codeswayam/ui';

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>
  );
}

7. ConfirmDialog for Destructive Actions

import { useState } from 'react';
import { Button, ConfirmDialog } from '@codeswayam/ui';

export function DeleteAgentButton({ agentId, onDelete }) {
  const [open, setOpen] = useState(false);

  const handleConfirm = async () => {
    await onDelete(agentId);
    setOpen(false);
  };

  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

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 |

Changelog

v1.3.2

• Enhanced component styles and tokens compatibility with Next.js 16 and React 19.

License

MIT © CodeSwayam