xertica-ds

A comprehensive Design System with React components and Tailwind CSS - shadcn/ui alternative

Features

✨ 60+ Production-Ready Components - Built with Radix UI and Tailwind CSS
🎨 Multiple Color Themes - Choose from 6 pre-built themes or customize your own
🌓 Dark Mode Support - Built-in dark mode with smooth transitions
📦 Two Usage Modes - Direct imports or CLI-based installation
🔧 TypeScript First - Full type safety and IntelliSense support
🎯 shadcn/ui Compatible - Drop-in replacement for shadcn components
⚡ Tailwind CSS v4 - Latest Tailwind with modern features
🚀 Zero Config - Works out of the box with sensible defaults

Installation

Option 1: Direct Installation (Recommended for new projects)

npm install xertica-ds

Then import components directly:

import { Button, Card, Dialog } from 'xertica-ds';

function App() {
  return (
    <Card>
      <Button>Click me</Button>
    </Card>
  );
}

Option 2: CLI Installation (shadcn-style)

Initialize the design system in your project:

npx xertica-ds init

This will:

• Set up Tailwind CSS v4 configuration
• Copy design tokens and base styles
• Configure your project structure
• Let you choose a color theme
• Optionally install example pages

Then add components as needed:

npx xertica-ds add button card dialog

Quick Start

1. Install the package

npm install xertica-ds

2. Import styles in your main file

// main.tsx or App.tsx
import 'xertica-ds/styles/globals.css';

3. Use components

import { Button, Card, CardHeader, CardTitle, CardContent } from 'xertica-ds';

function App() {
  return (
    <Card className="w-96">
      <CardHeader>
        <CardTitle>Welcome to xertica-ds</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}

Available Components

Layout & Structure

• Card - Flexible container with header, content, and footer
• Separator - Visual divider between content
• Aspect Ratio - Maintain consistent aspect ratios
• Resizable - Resizable panels and layouts
• Sidebar - Application sidebar with collapsible sections

Form Controls

• Button - Primary action buttons with variants
• Input - Text input fields
• Textarea - Multi-line text input
• Select - Dropdown selection
• Checkbox - Boolean input
• Radio Group - Single selection from multiple options
• Switch - Toggle switch
• Slider - Range input
• Calendar - Date picker
• Form - Form wrapper with validation

Feedback & Overlays

• Dialog - Modal dialogs
• Alert Dialog - Confirmation dialogs
• Sheet - Side panel overlay
• Drawer - Bottom drawer
• Popover - Floating content
• Tooltip - Contextual hints
• Toast (Sonner) - Notification toasts
• Alert - Inline alerts and messages
• Progress - Progress indicators
• Skeleton - Loading placeholders

Navigation

• Navigation Menu - Top navigation
• Menubar - Application menu bar
• Dropdown Menu - Contextual menus
• Context Menu - Right-click menus
• Breadcrumb - Navigation breadcrumbs
• Tabs - Tabbed interfaces
• Pagination - Page navigation

Data Display

• Table - Data tables
• Chart - Data visualizations (Recharts)
• Badge - Status badges
• Avatar - User avatars
• Carousel - Image/content carousel
• Accordion - Collapsible content
• Collapsible - Show/hide content
• Hover Card - Hover preview cards
• Scroll Area - Custom scrollbars

Advanced Components

• Command - Command palette (⌘K)
• Xertica Assistant - AI chat interface
• Map Components - Google Maps integration
• Language Selector - Multi-language support
• Theme Toggle - Dark mode switcher

CLI Commands

init

Initialize the design system in your project

npx xertica-ds init

Options:

• Choose installation paths
• Select color theme
• Pick integrations (Sonner, Google Maps, Calendar)
• Add example pages

add

Add components to your project

# Add single component
npx xertica-ds add button

# Add multiple components
npx xertica-ds add button card dialog

# Add integration
npx xertica-ds add integration sonner

update

Update project configuration

npx xertica-ds update

doctor

Check for configuration issues

npx xertica-ds doctor

Themes

xertica-ds comes with 6 pre-built color themes:

• Default - Xertica purple theme
• Blue - Professional blue
• Green - Fresh green
• Orange - Energetic orange
• Red - Bold red
• Slate - Neutral slate

Choose your theme during init or customize the CSS variables in styles/xertica/tokens.css.

Migration from shadcn/ui

xertica-ds is designed as a drop-in replacement for shadcn/ui. Key differences:

1. Package-based: Install via npm instead of copying files
2. Pre-built themes: Choose from multiple themes out of the box
3. Additional components: Includes AI assistant, maps, and more
4. Tailwind v4: Uses the latest Tailwind CSS version

To migrate:

# 1. Install xertica-ds
npm install xertica-ds

# 2. Replace imports
# Before: import { Button } from "@/components/ui/button"
# After:  import { Button } from "xertica-ds"

# 3. Update styles import
# Before: import "@/styles/globals.css"
# After:  import "xertica-ds/styles/globals.css"

See MIGRATION_FROM_SHADCN.md for detailed migration guide.

TypeScript Support

All components are fully typed with TypeScript. You get:

• Full IntelliSense support
• Type-safe props
• Autocomplete for component APIs
• Type definitions for all exports

import { Button, type ButtonProps } from 'xertica-ds';

const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Dark Mode

Dark mode is built-in and works automatically. Add the dark class to your root element:

// Toggle dark mode
document.documentElement.classList.toggle('dark');

Or use the provided ThemeProvider and ThemeToggle components:

import { ThemeProvider, ThemeToggle } from 'xertica-ds';

function App() {
  return (
    <ThemeProvider>
      <ThemeToggle />
      {/* Your app */}
    </ThemeProvider>
  );
}

Customization

Custom Theme Colors

Edit styles/xertica/tokens.css to customize colors:

@theme {
  --color-primary: #your-color;
  --color-background: #your-bg;
  /* ... more variables */
}

Component Styling

All components use Tailwind CSS classes and can be customized via className:

<Button className="bg-blue-500 hover:bg-blue-600">
  Custom Button
</Button>

Requirements

• React 18+
• TypeScript 5+ (recommended)
• Tailwind CSS 4+
• Node.js 18+

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please see our Contributing Guide.

License

MIT © Xertica

Links

• Documentation
• NPM Package
• GitHub Repository
• Issue Tracker

Acknowledgments

Built with:

• Radix UI - Unstyled, accessible components
• Tailwind CSS - Utility-first CSS framework
• Lucide Icons - Beautiful icon set
• Inspired by shadcn/ui

Made with ❤️ by Xertica