Shadcn Design System

A modern, comprehensive React component library that extends Shadcn UI with powerful features and enhancements.

🌟 Features

• 🎨 40+ High-quality Components - Production-ready React components
• 🪝 Custom React Hooks - Utility hooks for common patterns
• ✨ Beautiful Animations - Pre-built animation components and utilities
• 🎭 Tailwind CSS - Utility-first styling with full customization
• 📦 Tree-shakeable - Import only what you need
• 🌙 Dark Mode Support - Built-in theme switching
• 📱 Responsive - Mobile-first design approach
• ♿ Accessible - ARIA compliant components
• 🔧 TypeScript - Full type safety
• 📖 Well-documented - Comprehensive examples and API docs

📚 Documentation

• 📖 Storybook - Interactive component documentation
• 📦 NPM Package - Latest package on npm

🤖 AI Skills

Add this design system skill to your AI Agent so it can automatically recognize components, props, and usage patterns:

npx skills add https://github.com/sonth87/design-system/tree/main/skills/shadcn-design-system --skill shadcn-design-system

Once added, the AI Agent can:

• Know exactly how to import and use each component
• Generate code with correct props, types, and examples
• Understand design tokens, hooks, and utilities in this design system

See full reference at docs/SKILL.md

---

🚀 Installation

Using npm

npm install @sth87/shadcn-design-system

Using pnpm

pnpm add @sth87/shadcn-design-system

Using yarn

yarn add @sth87/shadcn-design-system

⚙️ Setup

1. Install Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom tailwindcss

2. Import Styles

Import the CSS in your main application file (e.g., main.tsx or App.tsx):

import "@sth87/shadcn-design-system/index.css";

// animation
import "@sth87/shadcn-design-system/animation.css";

💻 Usage

Basic Example

import { Button, Input } from "@sth87/shadcn-design-system";

function App() {
  return (
    <div className="p-6 max-w-md">
      <h1 className="text-2xl font-bold mb-4">Welcome</h1>
      <Input placeholder="Enter your email" className="mb-4" />
      <Button variant="default" className="w-full">
        Get Started
      </Button>
    </div>
  );
}

Using Hooks

import { useDebounce } from "@sth87/shadcn-design-system";
import { useState, useEffect } from "react";

function SearchComponent() {
  const [search, setSearch] = useState("");
  const debouncedSearch = useDebounce(search, 500);

  useEffect(() => {
    // API call with debounced value
    if (debouncedSearch) {
      console.log("Searching for:", debouncedSearch);
    }
  }, [debouncedSearch]);

  return <Input value={search} onChange={(e) => setSearch(e.target.value)} />;
}

📦 What's Included

Components

Layout & Structure

• Card
• Separator
• ScrollArea
• Resizable
• Glass
• Sidebar

Form Controls

• Input
• Textarea
• Checkbox
• Radio
• Switch
• Select
• DatePicker
• TimePicker
• RangePicker
• Upload
• InputOTP

Navigation

• Breadcrumb
• Tabs
• Pagination
• Stepper
• Command

Feedback & Overlays

• Toast
• Dialog
• Sheet
• Popover
• Tooltip
• Alert

Data Display

• Table
• Badge
• Avatar
• Carousel
• ImageViewer
• QrCode
• Rate
• Skeleton

Animations

• Marquee
• TextAnimations
• Interactive Components

Advanced Components

• TreeSelect
• Tour
• Cropper
• ContextMenu
• DropdownMenu
• Masonry

Custom Hooks

• useDebounce / useDebouncedCallback - Debounce values and callbacks
• useIntersectionObserver - Detect element visibility
• useMediaQuery - Responsive breakpoint detection
• useMousePosition - Track mouse coordinates
• useOnClickOutside - Detect clicks outside element
• useScrollLock - Lock/unlock body scroll
• useEventListener - Simplified event handling
• useCallbackRef - Stable callback references
• And more...

🎨 Customization

All components support the className prop for custom styling with Tailwind CSS:

<Button
  variant="outline"
  size="lg"
  className="bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600"
>
  Custom Gradient Button
</Button>

Theme Customization

Override CSS variables for global theming:

:root {
  --background: #ffffff;
  --foreground: #2e3a5b;
  --muted-foreground: #58617c;
  --subtle-foreground: #777f94;
  --card: #ffffff;
  --card-foreground: #0a0a0a;
  --popover: #ffffff;
  --popover-foreground: #0a0a0a;
  --primary: #f37320;
  --primary-foreground: #fafafa;
  --secondary: #213f99;
  --secondary-foreground: #fafafa;
  --muted: #f5f5f5;
  /* --muted-foreground: #737373; */
  --accent: #f5f5f5;
  --accent-foreground: #171717;
  --destructive: #e7000b;
  --destructive-foreground: #fafafa;
  /* state color */
  --success: #39cc7e;
  --success-foreground: #ffffff;
  --error: #ff6262;
  --error-foreground: #ffffff;
  --warning: #ff9d57;
  --warning-foreground: #ffffff;
  /* end state color */
  --border: #e5e5e5;
  --input: #e5e5e5;
  --ring: #a1a1a1;
  --chart-1: #f54a00;
  --chart-2: #009689;
  --chart-3: #104e64;
  --chart-4: #ffba00;
  --chart-5: #fd9a00;
  --radius: 0.625rem;
  --sidebar: #f1f5f9;
  --sidebar-foreground: #2e3a5b;
  --sidebar-primary: #171717;
  --sidebar-primary-foreground: #fafafa;
  --sidebar-accent: #f5f5f5;
  --sidebar-accent-foreground: #171717;
  --sidebar-border: #e5e5e5;
  --sidebar-ring: #a1a1a1;
}

.dark {
  --background: #303841;
  --foreground: #94a0ad;
  --muted-foreground: #eaebef;
  --subtle-foreground: #f5f5f7;
  --card: #36404a;
  --card-foreground: #94a0ad;
  --popover: #0a0a0a;
  --popover-foreground: #fafafa;
  --primary: #f37320;
  --primary-foreground: #fafafa;
  --secondary: #213f99;
  --secondary-foreground: #fafafa;
  --muted: #36404a;
  /* --muted-foreground: #a1a1a1; */
  --accent: #262626;
  --accent-foreground: #fafafa;
  --destructive: #82181a;
  --destructive-foreground: #fb2c36;
  /* state color */
  --success: #39cc7e;
  --success-foreground: #ffffff;
  --error: #ff6262;
  --error-foreground: #ffffff;
  --warning: #ff9d57;
  --warning-foreground: #ffffff;
  /* end state color */
  --border: #262626;
  --input: #262626;
  --ring: #737373;
  --chart-1: #1447e6;
  --chart-2: #00bc7d;
  --chart-3: #fd9a00;
  --chart-4: #ad46ff;
  --chart-5: #ff2056;
  --sidebar: #37424c;
  --sidebar-foreground: #94a0ad;
  --sidebar-primary: #1447e6;
  --sidebar-primary-foreground: #fafafa;
  --sidebar-accent: #262626;
  --sidebar-accent-foreground: #fafafa;
  --sidebar-border: #262626;
  --sidebar-ring: #525252;
}

🛠️ Development

This is a monorepo managed with pnpm workspaces and Turborepo.

Prerequisites

• Node.js 18+
• pnpm 8+

Install Dependencies

pnpm install

Development Server

pnpm dev

Build

pnpm build

Storybook

pnpm storybook

🤝 Contributing

Contributions are welcome! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project is built on top of:

• Shadcn UI - Original component library
• Radix UI - Headless UI components
• Tailwind CSS - Utility-first CSS framework
• React - UI library

---

Sonth87