TAI Design System

A comprehensive React component library built with TypeScript, Tailwind CSS, and shadcn/ui patterns. This design system provides a unified set of highly customizable, accessible components for building modern web applications with consistent design and excellent developer experience.

✨ Features

• 🎨 Modern Design: Built with Tailwind CSS and shadcn/ui patterns
• 🎯 TypeScript First: Full TypeScript support with comprehensive type definitions
• 📱 Responsive: Mobile-first design with responsive utilities
• ♿ Accessible: WCAG compliant components with proper ARIA attributes
• 🎨 Highly Customizable: Extensive prop options for every component
• 📚 Storybook: Interactive component documentation and playground
• 🧪 Well Tested: Comprehensive test suite with Jest and React Testing Library
• 📦 Tree Shakeable: Optimized bundle size with ES modules support
• 🔧 Developer Experience: ESLint, Prettier, and TypeScript for code quality
• 🚀 Production Ready: Battle-tested components ready for real-world use

📦 Installation

npm install tai-design-system
# or
yarn add tai-design-system
# or
pnpm add tai-design-system

Peer Dependencies

⚡ Bundle Size Optimization: We've reduced the bundle size by 95% (from 10.5MB to ~250KB) by externalizing heavy dependencies. See BUNDLE_OPTIMIZATION_GUIDE.md for migration details.

Make sure you have the required peer dependencies installed:

npm install react react-dom

# Additional peer dependencies (required for v1.0.0+)
npm install @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-radio-group @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip class-variance-authority clsx lucide-react recharts tailwind-merge

🚀 Quick Start

1. Import Styles

Import the CSS file in your application's entry point:

// In your main App.tsx or index.tsx
import 'tai-design-system/dist/styles.css';

2. Configure Tailwind (Optional)

If you're using Tailwind CSS in your project, extend your config:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/tai-design-system/dist/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
};

3. Start Using Components

import React from 'react';
import { Button, Alert, Badge, Avatar } from 'tai-design-system';

function App() {
  return (
    <div className="space-y-4 p-4">
      <Alert
        variant="success"
        title="Welcome!"
        description="Your setup is complete."
        dismissible
        autoClose={5000}
      />

      <div className="flex items-center gap-4">
        <Avatar src="/avatar.jpg" name="John Doe" status="online" size="lg" />

        <Badge variant="primary" icon={<CheckIcon />} removable>
          Active User
        </Badge>
      </div>

      <Button variant="solid" size="lg" colorScheme="primary">
        Get Started
      </Button>
    </div>
  );
}

📚 Component Documentation

Core Components

Alert

A versatile alert component with animations, auto-dismiss, and progress indicators.

import { Alert } from 'tai-design-system';

// Basic usage
<Alert
  variant="success"
  title="Success!"
  description="Your changes have been saved."
/>

// With auto-close and progress bar
<Alert
  variant="warning"
  title="Warning"
  description="This action cannot be undone."
  autoClose={5000}
  showProgress
  animation="slide"
  position="top"
/>

// Custom styling
<Alert
  variant="info"
  title="New Feature"
  showIcon={false}
  bordered
  size="large"
  styles={{
    container: { backgroundColor: '#f0f9ff' },
    title: { fontWeight: 'bold' }
  }}
/>

Props:

• variant: 'success' | 'info' | 'error' | 'warning' | 'default'
• size: 'default' | 'compact' | 'large'
• animation: 'none' | 'fade' | 'slide' | 'bounce'
• autoClose: number (milliseconds)
• showProgress: boolean
• dismissible: boolean
• bordered: boolean
• Full TypeScript autocomplete for all props

Avatar

Flexible avatar component with status indicators, badges, and fallbacks.

import { Avatar } from 'tai-design-system';

// Basic avatar with image
<Avatar
  src="/user-photo.jpg"
  name="Jane Smith"
  size="xl"
/>

// With status indicator
<Avatar
  name="John Doe"
  status="online"
  statusPosition="bottom-right"
  shape="circle"
/>

// With badge and custom colors
<Avatar
  name="Admin User"
  badge={5}
  badgePosition="top-right"
  backgroundColor="#e3f2fd"
  textColor="#1976d2"
/>

// Loading state
<Avatar
  src="/loading-image.jpg"
  loading
  loadingComponent={<CustomSpinner />}
/>

Props:

• size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'
• shape: 'circle' | 'square' | 'rounded'
• status: 'online' | 'offline' | 'busy' | 'away'
• badge: React.ReactNode
• loading: boolean
• clickable: boolean
• bordered: boolean
• Full TypeScript autocomplete for all props

Badge

Feature-rich badge component with counts, status indicators, and animations.

import { Badge } from 'tai-design-system';

// Basic badges
<Badge variant="primary">New</Badge>
<Badge variant="success" icon={<CheckIcon />}>Completed</Badge>

// With remove button
<Badge
  variant="secondary"
  removable
  onRemove={() => console.log('Removed')}
>
  Tag
</Badge>

// Count badge
<Badge
  variant="destructive"
  count={99}
  maxCount={99}
  showZero
/>

// Status badge with pulse
<Badge
  status="processing"
  pulse
  dot
>
  Processing
</Badge>

// Custom styling
<Badge
  variant="outline"
  maxWidth={100}
  truncate
  styles={{
    container: { borderRadius: '4px' }
  }}
>
  Long text that will be truncated
</Badge>

Props:

• variant: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'outline' | 'neutral'
• size: 'xs' | 'sm' | 'md' | 'lg'
• shape: 'rounded' | 'square' | 'pill'
• removable: boolean
• count: number
• status: 'default' | 'processing' | 'success' | 'error' | 'warning'
• pulse: boolean
• dot: boolean
• Full TypeScript autocomplete for all props

Button

Comprehensive button component with loading states, icons, and variants.

import { Button } from 'tai-design-system';

// Basic button
<Button variant="solid" colorScheme="primary">
  Click Me
</Button>

// With loading state
<Button
  isLoading
  loadingText="Saving..."
  colorScheme="success"
>
  Save Changes
</Button>

// With icons
<Button
  leftIcon={<SearchIcon />}
  rightIcon={<ArrowRightIcon />}
  variant="outline"
>
  Search
</Button>

// Icon button
<Button variant="ghost" size="icon">
  <SettingsIcon />
</Button>

// Full width button
<Button fullWidth size="lg" colorScheme="error">
  Delete Account
</Button>

Props:

• variant: 'solid' | 'outline' | 'ghost' | 'link'
• colorScheme: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
• size: 'xs' | 'sm' | 'default' | 'lg' | 'xl' | 'icon'
• isLoading: boolean
• isDisabled: boolean
• fullWidth: boolean
• leftIcon: React.ReactElement
• rightIcon: React.ReactElement

Form Components

Input

Enhanced input component with validation states and icons.

import { Input, Label } from 'tai-design-system';

<div className="space-y-2">
  <Label htmlFor="email" required>
    Email Address
  </Label>
  <Input
    id="email"
    type="email"
    placeholder="[email protected]"
    leftIcon={<MailIcon />}
    error="Please enter a valid email"
  />
</div>;

Select

Searchable select component with groups and custom rendering.

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from 'tai-design-system';

<Select defaultValue="option1">
  <SelectTrigger className="w-[200px]">
    <SelectValue placeholder="Choose an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Fruits</SelectLabel>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
    </SelectGroup>
    <SelectGroup>
      <SelectLabel>Vegetables</SelectLabel>
      <SelectItem value="carrot">Carrot</SelectItem>
      <SelectItem value="potato">Potato</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>;

Checkbox & Switch

Form controls with custom styling and states.

import { Checkbox, Switch, Label } from 'tai-design-system';

// Checkbox
<div className="flex items-center space-x-2">
  <Checkbox
    id="terms"
    defaultChecked
    onCheckedChange={(checked) => console.log(checked)}
  />
  <Label htmlFor="terms">
    I agree to the terms and conditions
  </Label>
</div>

// Switch
<div className="flex items-center justify-between">
  <Label htmlFor="notifications">Enable notifications</Label>
  <Switch
    id="notifications"
    defaultChecked
    onCheckedChange={(checked) => console.log(checked)}
  />
</div>

Layout Components

Card

Flexible card component with sections.

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from 'tai-design-system';

<Card className="w-[380px]">
  <CardHeader>
    <CardTitle>Account Settings</CardTitle>
    <CardDescription>Manage your account preferences</CardDescription>
  </CardHeader>
  <CardContent>{/* Form fields */}</CardContent>
  <CardFooter className="flex justify-between">
    <Button variant="outline">Cancel</Button>
    <Button>Save Changes</Button>
  </CardFooter>
</Card>;

Dialog

Accessible modal dialog component.

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from 'tai-design-system';

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent className="sm:max-w-[425px]">
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>
        Make changes to your profile here. Click save when you're done.
      </DialogDescription>
    </DialogHeader>
    <div className="grid gap-4 py-4">{/* Form content */}</div>
    <DialogFooter>
      <Button type="submit">Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>;

Navigation Components

Breadcrumb

Accessible breadcrumb navigation.

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from 'tai-design-system';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/products">Products</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Product Details</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>;

Tabs

Tab navigation component.

import { Tabs, TabsContent, TabsList, TabsTrigger } from 'tai-design-system';

<Tabs defaultValue="account" className="w-[400px]">
  <TabsList className="grid w-full grid-cols-2">
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="password">Password</TabsTrigger>
  </TabsList>
  <TabsContent value="account">
    <Card>
      <CardHeader>
        <CardTitle>Account</CardTitle>
        <CardDescription>Make changes to your account here.</CardDescription>
      </CardHeader>
      <CardContent>{/* Account form */}</CardContent>
    </Card>
  </TabsContent>
  <TabsContent value="password">
    <Card>
      <CardHeader>
        <CardTitle>Password</CardTitle>
        <CardDescription>Change your password here.</CardDescription>
      </CardHeader>
      <CardContent>{/* Password form */}</CardContent>
    </Card>
  </TabsContent>
</Tabs>;

Data Display

Table

Feature-rich data table component.

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from 'tai-design-system';

const invoices = [
  { invoice: 'INV001', status: 'Paid', method: 'Credit Card', amount: '$250.00' },
  { invoice: 'INV002', status: 'Pending', method: 'PayPal', amount: '$150.00' },
];

<Table>
  <TableHeader>
    <TableRow>
      <TableHead className="w-[100px]">Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Method</TableHead>
      <TableHead className="text-right">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {invoices.map((invoice) => (
      <TableRow key={invoice.invoice}>
        <TableCell className="font-medium">{invoice.invoice}</TableCell>
        <TableCell>{invoice.status}</TableCell>
        <TableCell>{invoice.method}</TableCell>
        <TableCell className="text-right">{invoice.amount}</TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>;

Pagination

Accessible pagination component.

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from 'tai-design-system';

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#" isActive>
        2
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">3</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>;

Feedback Components

Tooltip

Accessible tooltip component.

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from 'tai-design-system';

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="outline">Hover me</Button>
    </TooltipTrigger>
    <TooltipContent>
      <p>This is a helpful tooltip</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>;

DropdownMenu

Accessible dropdown menu component.

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from 'tai-design-system';

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Open Menu</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-56">
    <DropdownMenuLabel>My Account</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      <User className="mr-2 h-4 w-4" />
      <span>Profile</span>
    </DropdownMenuItem>
    <DropdownMenuItem>
      <Settings className="mr-2 h-4 w-4" />
      <span>Settings</span>
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      <LogOut className="mr-2 h-4 w-4" />
      <span>Log out</span>
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>;

🎨 Theming & Customization

CSS Variables

The design system uses CSS variables for theming. Customize by overriding these variables:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 84% 4.9%;
  --success: 142.1 76.2% 36.3%;
  --success-foreground: 355.7 100% 97.3%;
  --warning: 47.9 95.8% 53.1%;
  --warning-foreground: 26 83.3% 14.1%;
  --error: 0 84.2% 60.2%;
  --error-foreground: 210 40% 98%;
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark mode variables */
}

Component Customization

All components support extensive customization through props:

// Custom styles object
<Alert
  styles={{
    container: { borderRadius: '12px' },
    title: { fontSize: '18px' },
    icon: { color: '#10b981' }
  }}
/>

// Custom class names
<Button className="custom-button-class">
  Click Me
</Button>

// Tailwind utilities
<Badge className="bg-gradient-to-r from-purple-400 to-pink-600">
  Gradient Badge
</Badge>

🔧 TypeScript Support

Full TypeScript support with exported types:

import type {
  AlertProps,
  AvatarProps,
  BadgeProps,
  ButtonProps,
  // ... all component props
} from 'tai-design-system';

// Use types in your components
interface MyComponentProps {
  alert?: AlertProps;
  avatar?: AvatarProps;
}

📋 Examples

Complete Form Example

import React, { useState } from 'react';
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Input,
  Label,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  Checkbox,
  Button,
  Alert,
} from 'tai-design-system';

function RegistrationForm() {
  const [submitted, setSubmitted] = useState(false);

  return (
    <>
      {submitted && (
        <Alert
          variant="success"
          title="Registration successful!"
          description="Welcome to our platform."
          autoClose={5000}
          className="mb-4"
        />
      )}

      <Card className="w-full max-w-lg">
        <CardHeader>
          <CardTitle>Create Account</CardTitle>
          <CardDescription>Fill in your details to get started</CardDescription>
        </CardHeader>
        <CardContent className="space-y-4">
          <div className="grid grid-cols-2 gap-4">
            <div className="space-y-2">
              <Label htmlFor="firstName">First Name</Label>
              <Input id="firstName" placeholder="John" />
            </div>
            <div className="space-y-2">
              <Label htmlFor="lastName">Last Name</Label>
              <Input id="lastName" placeholder="Doe" />
            </div>
          </div>

          <div className="space-y-2">
            <Label htmlFor="email">Email</Label>
            <Input id="email" type="email" placeholder="[email protected]" />
          </div>

          <div className="space-y-2">
            <Label htmlFor="country">Country</Label>
            <Select>
              <SelectTrigger id="country">
                <SelectValue placeholder="Select your country" />
              </SelectTrigger>
              <SelectContent>
                <SelectItem value="us">United States</SelectItem>
                <SelectItem value="uk">United Kingdom</SelectItem>
                <SelectItem value="ca">Canada</SelectItem>
                <SelectItem value="au">Australia</SelectItem>
              </SelectContent>
            </Select>
          </div>

          <div className="flex items-center space-x-2">
            <Checkbox id="terms" />
            <Label htmlFor="terms" className="text-sm">
              I agree to the terms of service and privacy policy
            </Label>
          </div>
        </CardContent>
        <CardFooter>
          <Button className="w-full" onClick={() => setSubmitted(true)}>
            Create Account
          </Button>
        </CardFooter>
      </Card>
    </>
  );
}

Dashboard Example

import React from 'react';
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Badge,
  Avatar,
  Button,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from 'tai-design-system';

function Dashboard() {
  const users = [
    { id: 1, name: 'John Doe', email: '[email protected]', status: 'active' },
    { id: 2, name: 'Jane Smith', email: '[email protected]', status: 'inactive' },
  ];

  return (
    <div className="space-y-6 p-6">
      {/* Stats Cards */}
      <div className="grid grid-cols-1 gap-6 md:grid-cols-3">
        <Card>
          <CardHeader className="flex flex-row items-center justify-between pb-2">
            <CardTitle className="text-sm font-medium">Total Users</CardTitle>
            <Badge variant="secondary">+12%</Badge>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">1,234</div>
            <p className="text-xs text-muted-foreground">+10% from last month</p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader className="flex flex-row items-center justify-between pb-2">
            <CardTitle className="text-sm font-medium">Active Sessions</CardTitle>
            <Badge variant="success" dot>
              Live
            </Badge>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">342</div>
            <p className="text-xs text-muted-foreground">+2% from last hour</p>
          </CardContent>
        </Card>

        <Card>
          <CardHeader className="flex flex-row items-center justify-between pb-2">
            <CardTitle className="text-sm font-medium">Revenue</CardTitle>
            <Badge variant="outline">Monthly</Badge>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">$12,345</div>
            <p className="text-xs text-muted-foreground">+18% from last month</p>
          </CardContent>
        </Card>
      </div>

      {/* Users Table */}
      <Card>
        <CardHeader>
          <CardTitle>Recent Users</CardTitle>
        </CardHeader>
        <CardContent>
          <Table>
            <TableHeader>
              <TableRow>
                <TableHead>User</TableHead>
                <TableHead>Email</TableHead>
                <TableHead>Status</TableHead>
                <TableHead className="text-right">Actions</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              {users.map((user) => (
                <TableRow key={user.id}>
                  <TableCell>
                    <div className="flex items-center gap-2">
                      <Avatar name={user.name} size="sm" />
                      <span className="font-medium">{user.name}</span>
                    </div>
                  </TableCell>
                  <TableCell>{user.email}</TableCell>
                  <TableCell>
                    <Badge variant={user.status === 'active' ? 'success' : 'secondary'} dot>
                      {user.status}
                    </Badge>
                  </TableCell>
                  <TableCell className="text-right">
                    <Button variant="ghost" size="sm">
                      Edit
                    </Button>
                  </TableCell>
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </CardContent>
      </Card>
    </div>
  );
}

🚀 Publishing to npm

Pre-publish Checklist

1. ✅ All components are tested
2. ✅ Documentation is up to date
3. ✅ Version number is updated
4. ✅ CHANGELOG is updated
5. ✅ Build passes without errors

Publishing Steps

# 1. Update version in package.json
npm version patch # or minor/major

# 2. Build the library
npm run build

# 3. Test the package locally
npm pack
# Test in another project: npm install path/to/tai-design-system-1.0.0.tgz

# 4. Login to npm (if not already)
npm login

# 5. Publish to npm
npm publish --access public

# 6. Create git tag
git tag v1.0.0
git push origin --tags

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/theaddresstech/tai-design-system.git
cd tai-design-system

# Install dependencies
npm install

# Start Storybook for development
npm run storybook

# Run tests in watch mode
npm run test:watch

# Build the library
npm run build

📄 License

MIT © TAI - see the LICENSE file for details.

🙏 Acknowledgments

• shadcn/ui for the excellent component patterns
• Radix UI for accessible component primitives
• Tailwind CSS for utility-first CSS
• Storybook for component documentation

Made with ❤️ by TAI Team