Agentela Design System

A dark-mode first React component library with plug-and-play preset components for rapid dashboard development.

🚀 Features

• 🌙 Dark-mode first: Default dark theme with light mode as .light class variant
• ⚛️ Modern React: Built with React 19.1.1 and TypeScript 5.9.2
• 📚 Component Documentation: Comprehensive Storybook 8.6.14 with 25+ interactive stories
• 🏗️ Production Ready: Rollup build system with CJS/ESM dual format output
• ♿ Accessibility: Built on Radix UI primitives for solid a11y foundation
• 🎨 Modern Styling: Tailwind CSS 3.4.17 with HSL custom properties
• 🔒 Type Safe: Full TypeScript support with exported interfaces
• 🚀 Plug-and-Play: Complete preset components for instant dashboard creation
• 📊 Chart Integration: Built-in Recharts components for data visualization

📦 Installation

npm install agentela-design-system

🚀 Quick Start (Plug-and-Play)

Create a complete dashboard in just a few lines:

import { SimpleDashboard, ThemeProvider } from 'agentela-design-system'
import { Home, Users, TrendingUp, Settings } from 'lucide-react'

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <SimpleDashboard
        title="Analytics Dashboard" 
        subtitle="Welcome back, John!"
        sidebar={{
          navigation: [
            { label: 'Dashboard', icon: Home, isActive: true },
            { label: 'Users', icon: Users },
            { label: 'Analytics', icon: TrendingUp },
            { label: 'Settings', icon: Settings }
          ],
          user: {
            name: 'John Doe',
            email: '[email protected]',
            role: 'Admin',
            initials: 'JD'
          }
        }}
        metrics={[
          {
            title: 'Total Users',
            value: '12,345',
            icon: Users,
            iconColor: 'purple',
            trend: { value: '+12%', isPositive: true }
          },
          {
            title: 'Revenue',
            value: '$45,678',
            icon: TrendingUp,
            iconColor: 'green',
            trend: { value: '+8.2%', isPositive: true }
          }
        ]}
        quickActions={[
          { label: 'Add User', icon: Users },
          { label: 'Export Data', icon: TrendingUp }
        ]}
      />
    </ThemeProvider>
  )
}

Using Individual Preset Components

import { 
  MetricCard, 
  PerformanceChart, 
  StatusBadge,
  UserProfile,
  QuickActions 
} from 'agentela-design-system'

function Dashboard() {
  return (
    <div className="grid gap-6">
      {/* Metrics Row */}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        <MetricCard
          title="Active Users"
          value="2,847"
          icon={Users}
          iconColor="blue"
          trend={{ value: '+12%', isPositive: true }}
          badge={{ text: 'Live', variant: 'success' }}
        />
        {/* More metrics... */}
      </div>

      {/* Chart Section */}
      <PerformanceChart
        title="Performance Overview"
        data={chartData}
        type="area"
        metrics={[
          { key: 'users', name: 'Users', color: '#8884d8' },
          { key: 'revenue', name: 'Revenue', color: '#82ca9d' }
        ]}
      />

      {/* Status Badges */}
      <div className="flex gap-2">
        <StatusBadge status="active" label="System Online" />
        <StatusBadge status="pending" label="2 Updates Available" />
      </div>
    </div>
  )
}

🎨 Components

🚀 Preset Components (Plug-and-Play)

Ready-to-use dashboard components that work out of the box:

• SimpleDashboard - Complete dashboard layout with sidebar, metrics, and content area
• MetricCard - Beautiful metric displays with icons, trends, and color-coded badges
• PerformanceChart - Interactive charts (line, area, bar) with multiple data series
• QuickSidebar - Configurable sidebar with navigation sections and user profile
• QuickActions - Action button groups for common dashboard tasks
• StatusBadge - Semantic status indicators (active, error, pending, success, etc.)
• UserProfile - User avatar with profile information and dropdown actions

🧱 Base UI Components

Core building blocks for custom interfaces:

Form Components

• Input - Text input with variants (default, file) and validation states
• Textarea - Multi-line text input with resize control
• Label - Accessible form labels with proper associations
• Checkbox - Styled checkbox with indeterminate state support
• Radio Group - Grouped radio button selections
• Switch - Toggle switch for binary choices
• Select - Dropdown selection with search and grouping
• Input OTP - One-time password input with automatic focus management
• Form - React Hook Form integration with validation and error handling

Navigation & Layout

• Button - Multiple variants (default, destructive, outline, secondary, ghost, link)
• Badge - Status indicators and labels with semantic colors
• Breadcrumb - Navigation trail with separators and active states
• Pagination - Page navigation with previous/next and numbered pages
• Tabs - Tabbed interface with keyboard navigation
• Toggle - Pressable toggle buttons with variants
• Toggle Group - Grouped toggle selections (single/multiple)

Display Components

• Card - Container with header, content, footer composition
• Avatar - User profile images with fallback initials
• Alert - Contextual messages (default, destructive, warning, info, success)
• Progress - Progress bars with customizable appearance
• Separator - Visual dividers (horizontal/vertical)
• Skeleton - Loading placeholders for content
• Empty State - Placeholder for empty data sets

Interactive Components

• Dialog - Modal dialogs with overlay and focus management
• Alert Dialog - Confirmation dialogs with action buttons
• Sheet - Slide-out panels from any direction
• Drawer - Mobile-friendly bottom drawer
• Popover - Floating content attached to triggers
• Tooltip - Contextual help text on hover/focus
• Hover Card - Rich content on hover with delay
• Dropdown Menu - Action menus with icons, shortcuts, and separators
• Context Menu - Right-click contextual menus
• Command - Command palette with search and keyboard navigation

Advanced Components

• Calendar - Date picker with month/year navigation
• Accordion - Collapsible content sections
• Collapsible - Simple show/hide content wrapper
• Scroll Area - Custom scrollbars with smooth scrolling
• Resizable - Draggable panel resize handles
• Slider - Range input with single/dual handles
• Table - Data tables with header, body, footer structure
• Toast - Notification system with queue management
• Toaster - Toast notification container and management
• System Alert Banner - System-wide alert notifications

Chart Components

• Chart Container - Responsive chart wrapper with theming
• Chart Tooltip - Interactive chart data tooltips
• Chart Legend - Chart legend with customizable styling
• Area Chart - Area charts for trend visualization
• Bar Chart - Bar charts for comparative data
• Line Chart - Line charts for time series data
• Pie Chart - Pie charts for proportional data

🏗️ Layout Components

Complete layout solutions for dashboard applications:

• Sidebar - Collapsible navigation with header, content, and footer sections
  • SidebarHeader - Sidebar header area for branding/title
  • SidebarContent - Main navigation content area
  • SidebarFooter - Footer area for user info/actions
  • SidebarGroup - Grouped navigation sections
  • SidebarMenu - Navigation menu container
  • SidebarMenuItem - Individual navigation items
• Header - Application header with title and action areas
  • HeaderContent - Main header content container
  • HeaderTitle - Header title/branding area
  • HeaderActions - Header action buttons area
• Dashboard Layout - Complete responsive dashboard layout
  • DashboardContent - Main content area
  • DashboardHeader - Dashboard-specific header

🎭 Theme System

• ThemeProvider - Theme context provider with persistence
• useTheme - Theme control hook for switching themes

🌙 Theme System

The design system uses CSS custom properties for theming:

:root {
  --background: 240 10% 3.9%;     /* Dark by default */
  --foreground: 0 0% 98%;
  --primary: 142 76% 36%;
  /* ... */
}

.light {
  --background: 0 0% 100%;        /* Light mode override */
  --foreground: 240 10% 3.9%;
  /* ... */
}

🔧 Usage

Basic Component Usage

import { 
  Button, 
  Card, 
  CardHeader, 
  CardTitle, 
  CardContent,
  Input,
  Label,
  Checkbox,
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem
} from 'agentela-design-system';

function ContactForm() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Contact Information</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="space-y-2">
          <Label htmlFor="name">Name</Label>
          <Input id="name" placeholder="Enter your name" />
        </div>
        
        <div className="space-y-2">
          <Label htmlFor="role">Role</Label>
          <Select>
            <SelectTrigger>
              <SelectValue placeholder="Select role" />
            </SelectTrigger>
            <SelectContent>
              <SelectItem value="admin">Admin</SelectItem>
              <SelectItem value="user">User</SelectItem>
              <SelectItem value="guest">Guest</SelectItem>
            </SelectContent>
          </Select>
        </div>

        <div className="flex items-center space-x-2">
          <Checkbox id="terms" />
          <Label htmlFor="terms">Accept terms and conditions</Label>
        </div>
        
        <Button className="w-full">Submit</Button>
      </CardContent>
    </Card>
  );
}

Advanced Component Usage

import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
  Toast,
  useToast
} from 'agentela-design-system'

function AdvancedExample() {
  const { toast } = useToast()

  return (
    <div className="flex gap-4">
      {/* Modal Dialog */}
      <Dialog>
        <DialogTrigger asChild>
          <Button>Open Settings</Button>
        </DialogTrigger>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Settings</DialogTitle>
          </DialogHeader>
          <div className="py-4">
            <p>Configure your preferences here.</p>
          </div>
        </DialogContent>
      </Dialog>

      {/* Confirmation Dialog */}
      <AlertDialog>
        <AlertDialogTrigger asChild>
          <Button variant="destructive">Delete Account</Button>
        </AlertDialogTrigger>
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Are you sure?</AlertDialogTitle>
            <AlertDialogDescription>
              This action cannot be undone.
            </AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>Cancel</AlertDialogCancel>
            <AlertDialogAction>Continue</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>

      {/* Toast Notification */}
      <Button
        onClick={() => {
          toast({
            title: "Success!",
            description: "Your changes have been saved.",
          })
        }}
      >
        Show Toast
      </Button>
    </div>
  )
}

Complete Layout Usage

import { 
  DashboardLayout, 
  Sidebar, 
  SidebarHeader, 
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton,
  Header,
  HeaderContent,
  HeaderTitle,
  HeaderActions,
  Button,
  Avatar,
  AvatarImage,
  AvatarFallback
} from 'agentela-design-system';

function Dashboard() {
  return (
    <DashboardLayout
      sidebar={
        <Sidebar>
          <SidebarHeader>
            <h2 className="text-lg font-semibold">My App</h2>
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Navigation</SidebarGroupLabel>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton isActive>
                    <Home className="h-4 w-4" />
                    <span>Dashboard</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton>
                    <Users className="h-4 w-4" />
                    <span>Users</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
          <SidebarFooter>
            <div className="flex items-center gap-2 p-2">
              <Avatar className="h-8 w-8">
                <AvatarImage src="/user.jpg" />
                <AvatarFallback>JD</AvatarFallback>
              </Avatar>
              <div className="flex-1 text-sm">
                <div className="font-medium">John Doe</div>
                <div className="text-muted-foreground">Admin</div>
              </div>
            </div>
          </SidebarFooter>
        </Sidebar>
      }
      header={
        <Header>
          <HeaderContent>
            <HeaderTitle>Dashboard Overview</HeaderTitle>
            <HeaderActions>
              <Button variant="outline" size="sm">
                Settings
              </Button>
              <Button size="sm">
                Add New
              </Button>
            </HeaderActions>
          </HeaderContent>
        </Header>
      }
    >
      <div className="flex-1 space-y-6 p-6">
        <h1 className="text-3xl font-bold">Welcome to your dashboard</h1>
        {/* Your main content here */}
      </div>
    </DashboardLayout>
  );
}

Chart Usage

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
  AreaChart,
  Area,
  XAxis,
  YAxis,
  CartesianGrid,
  ResponsiveContainer
} from 'agentela-design-system'

const chartData = [
  { month: 'Jan', users: 400, revenue: 2400 },
  { month: 'Feb', users: 300, revenue: 1398 },
  { month: 'Mar', users: 200, revenue: 9800 },
  { month: 'Apr', users: 278, revenue: 3908 },
  { month: 'May', users: 189, revenue: 4800 },
]

function AnalyticsChart() {
  return (
    <ChartContainer
      config={{
        users: {
          label: "Users",
          color: "hsl(var(--chart-1))",
        },
        revenue: {
          label: "Revenue", 
          color: "hsl(var(--chart-2))",
        },
      }}
      className="h-[400px]"
    >
      <AreaChart data={chartData}>
        <CartesianGrid strokeDasharray="3 3" />
        <XAxis dataKey="month" />
        <YAxis />
        <ChartTooltip content={<ChartTooltipContent />} />
        <Area
          type="monotone"
          dataKey="users"
          stackId="1"
          stroke="var(--color-users)"
          fill="var(--color-users)"
        />
        <Area
          type="monotone"
          dataKey="revenue"
          stackId="1"
          stroke="var(--color-revenue)"
          fill="var(--color-revenue)"
        />
      </AreaChart>
    </ChartContainer>
  )
}

Theme Provider

import { ThemeProvider } from 'agentela-design-system';

function App() {
  return (
    <ThemeProvider defaultTheme="dark" storageKey="my-app-theme">
      <YourApp />
    </ThemeProvider>
  );
}

🏗️ Development

Prerequisites

• Node.js 18+
• npm 9+

Getting Started

# Clone the repository
git clone https://github.com/nick-renard/agentela-design-system.git
cd agentela-design-system

# Install dependencies
npm install

# Start Storybook for development
npm run storybook

# Or build the library
npm run build

# Watch mode for development
npm run dev

Project Structure

src/
├── components/
│   ├── ui/                    # Base UI components (40+ components)
│   │   ├── button.tsx         # Button with variants
│   │   ├── card.tsx           # Card layout component
│   │   ├── input.tsx          # Form input component
│   │   ├── dialog.tsx         # Modal dialog
│   │   ├── chart.tsx          # Chart components
│   │   └── ...                # All UI primitives
│   ├── layouts/               # Layout components
│   │   ├── sidebar.tsx        # Sidebar navigation
│   │   ├── header.tsx         # Application header
│   │   └── dashboard-layout.tsx # Complete layout
│   ├── presets/               # Plug-and-play components  
│   │   ├── simple-dashboard.tsx    # Complete dashboard
│   │   ├── metric-card.tsx         # Metric display cards
│   │   ├── performance-chart.tsx   # Chart presets
│   │   ├── quick-sidebar.tsx       # Sidebar presets
│   │   ├── user-profile.tsx        # User profile component
│   │   ├── quick-actions.tsx       # Action button groups
│   │   └── status-badge.tsx        # Status indicators
│   ├── debug/                 # Development utilities
│   └── theme-provider.tsx     # Theme management
├── lib/
│   └── utils.ts              # Utility functions (cn, etc.)
├── styles/
│   └── globals.css           # Theme variables & utilities
└── index.ts                  # Main library export

external_components/           # Reference implementations
.storybook/                   # Storybook configuration

Development Workflow

1. Component Development: Create components in src/components/ui/
2. Story Creation: Add Storybook stories alongside components
3. Export Addition: Update src/components/index.ts exports
4. Testing: Verify in Storybook during development
5. Build Verification: Run npm run build to ensure compilation
6. Documentation: Update README and component documentation

Adding New Components

# 1. Create component file
touch src/components/ui/my-component.tsx

# 2. Create story file  
touch src/components/ui/my-component.stories.tsx

# 3. Add exports to index
# Edit src/components/index.ts

# 4. Test in Storybook
npm run storybook

📚 Storybook

All components are documented with interactive Storybook examples:

npm run storybook

Each component includes:

• Interactive Examples - Live component playground
• Props Documentation - Complete API reference
• Variants & States - All component variations
• Dark/Light Themes - Theme switching in toolbar
• Composition Examples - How components work together
• Accessibility Notes - Screen reader and keyboard navigation info

Available Stories

• UI Components (25+ stories): Button, Card, Input, Dialog, etc.
• Layout Components (3 stories): Sidebar, Header, Dashboard Layout
• Preset Components (7 stories): SimpleDashboard, MetricCard, Charts, etc.
• Icons Library (1 story): All available Lucide React icons

🔨 Build System

The library uses a modern build pipeline optimized for component libraries:

• 🏗️ Rollup: Component library bundling with tree-shaking
• 📝 TypeScript: Type checking and declaration generation
• 🎨 PostCSS: CSS processing with Tailwind compilation
• ⚡ Terser: Code minification and optimization
• 📦 Dual Output: CommonJS (lib/index.js) and ES Module (lib/index.esm.js)
• 🏷️ Type Definitions: Full TypeScript declarations (lib/index.d.ts)
• 🗺️ Source Maps: Development debugging support

Build Commands

# Development build (watch mode)
npm run dev

# Production build
npm run build

# Clean build artifacts
npm run clean

# Full clean rebuild
npm run clean && npm run build

📄 License

MIT

📊 Package Stats

• Bundle Size: ~1.4MB compressed, 5.8MB unpacked
• Components: 40+ UI components + 7 preset components
• Dependencies: Minimal runtime dependencies (React, Radix UI, Lucide)
• TypeScript: 100% TypeScript with full type definitions
• Tree Shaking: ES Module build supports dead code elimination
• Compatibility: React >=18.0.0

📄 License

MIT License - see LICENSE for details.

Built with ❤️ by the Agentela team