Dandy UI

A modern, TypeScript-first UI component library built with TailwindCSS v4, featuring semantic design tokens, dark mode support, and Next.js compatibility.

Features

• 🎨 TailwindCSS v4 - Latest Tailwind with @theme directive and @import syntax
• 🌙 Dark Mode - Built-in dark mode support with semantic tokens
• 📱 Responsive - Mobile-first responsive design
• 🔧 TypeScript - Full TypeScript support with strict type checking
• 🚀 Next.js Ready - Compatible with Next.js 13+ App Router, 14, and 15
• 🌳 Tree Shakable - Only import what you need
• 🎯 Semantic Tokens - CSS custom properties for consistent theming
• ⚡ Vite Powered - Fast development and optimized builds
• 📦 Separate Theme - Theme CSS ships separately for flexible integration

Installation

npm install dandy-ui
# or
yarn add dandy-ui
# or
pnpm add dandy-ui

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom tailwindcss @radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-select

Quick Start

1. Import CSS Files

Import the required CSS files in your app entry point (e.g., app.tsx, main.tsx, or _app.tsx):

// Import base styles (required - includes utilities & animations)
import "dandy-ui/base.css";

// Import theme variables (required - includes color tokens & design system)
import "dandy-ui/theme.css";

2. Configure TailwindCSS v4

With TailwindCSS v4, you no longer need a tailwind.config.js file. Instead, add the library content to your main CSS file where you import TailwindCSS:

/* In your main CSS file (e.g., globals.css or app.css) */
@import "tailwindcss";
@import "dandy-ui/theme.css";

@config "./path/to/your/app/**/*.{js,ts,jsx,tsx}";
@config "./node_modules/dandy-ui/dist/**/*.{js,ts,jsx,tsx}";

Or if you prefer to keep the theme separate, just ensure TailwindCSS can find the component files:

@import "tailwindcss";
@config "./src/**/*.{js,ts,jsx,tsx}";
@config "./node_modules/dandy-ui/dist/**/*.{js,ts,jsx,tsx}";

3. Use Components

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Text,
} from "dandy-ui";

function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome to Dandy UI</CardTitle>
      </CardHeader>
      <CardContent>
        <Text className="mb-4">
          A beautiful component library built with TailwindCSS.
        </Text>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}

Development

Prerequisites

• Node.js 18+
• npm/yarn/pnpm

Setup

1. Clone the repository

2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

4. Build the library:

   npm run build

Available Scripts

• npm run dev - Start development server with example components
• npm run build - Build the library for production
• npm run build:watch - Build in watch mode
• npm run typecheck - Run TypeScript type checking
• npm run preview - Preview the built library

Components

Layout

• Container - Responsive container with max-width options
• Card - Flexible card component with variants

Typography

• Text - Styled text component with size and variant options
• Heading - Semantic heading component (h1-h6)

Forms

• Button - Button component with variants and states
• Input - Form input with error states and variants

Design System

Semantic Tokens

The library uses CSS custom properties for consistent theming:

:root {
  --color-primary: 221.2 83.2% 53.3%;
  --color-background: 0 0% 100%;
  --color-foreground: 222.2 84% 4.9%;
  /* ... more tokens */
}

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

Dark Mode

Toggle dark mode by adding the dark class to your root element:

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

Browser Support

• Chrome 91+
• Firefox 90+
• Safari 14+
• Edge 91+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Nidhal Bettaibi