📦 Installation

# Using npm
npm install black-ui

# Using yarn
yarn add black-ui

# Using pnpm
pnpm add black-ui

🔧 Requirements

• React 18+
• Tailwind CSS 3.3+
• TypeScript 4.9+ (for TypeScript users)

🚀 Quick Start

import React from 'react';
import { Button, Card } from 'black-ui';

export default function App() {
  return (
    <Card className="p-6 shadow-lg">
      <h2 className="text-2xl font-bold mb-4">Welcome to Black UI</h2>
      <p className="text-muted-foreground mb-4">
        Start building beautiful interfaces with our professional components.
      </p>
      <Button>Get Started</Button>
    </Card>
  );
}

✨ Features

• 🎨 Beautiful Design System — Sleek, professional aesthetics with carefully crafted components
• ♿ Accessible Components — WCAG 2.1 compliant with full keyboard navigation and screen reader support
• 🌙 Dark Mode Built-in — Seamless light and dark mode transitions with consistent theming
• 📱 Fully Responsive — Components designed to work flawlessly across all device sizes
• ⚡ Performance Optimized — Efficient rendering with minimal bundle size impact
• 🧩 Highly Customizable — Flexible theming system that adapts to your brand
• 🔄 Interactive Effects — Smooth animations and transitions enhance user experience
• 📊 Advanced UI Patterns — Sophisticated components for complex data visualization and user interactions

🧩 Component Library

Black UI includes a comprehensive set of components:

Layout & Structure

• Accordion — Collapsible content panels
• AspectRatio — Maintain proportional dimensions
• Card — Versatile content containers
• Resizable — User-adjustable panels
• ScrollArea — Custom scrollable containers
• Separator — Visual dividers with various styles
• Table — Data-rich displays with sorting and filtering

Inputs & Forms

• Button — Multiple variants and sizes
• Checkbox — Customizable selection controls
• Input — Text entry with validations
• InputOTP — One-time password inputs
• Label — Accessible form labels
• RadioGroup — Option selection controls
• Slider — Range selection with visual feedback
• Switch — Toggle controls with animated states
• Textarea — Multi-line text input

Navigation

• Breadcrumb — Hierarchical page navigation
• DynamicNavigation — Context-aware navigation systems
• Pagination — Multi-page content navigation
• Sidebar — Collapsible application navigation
• Tabs — Content organization and switching

Feedback & Status

• Alert — Contextual messages with various severities
• Progress — Visual indicators for processes
• Skeleton — Loading state placeholders
• Toast — Temporary notifications with auto-dismiss

Overlay & Popups

• AlertDialog — Confirmation dialogues
• Dialog — Modal content containers
• Drawer — Side-emerging panels
• Popover — Contextual floating content
• Tooltip — Information on hover

Advanced Components

• AnimatedBlobBackground — Engaging visual effects
• Avatar — User representations with fallbacks
• BorderBeam — Animated border highlights
• Carousel — Scrollable content showcase
• Dock — macOS-style application launchers
• InteractiveGradient — Responsive color effects
• SeasonalHoverCards — Context-sensitive information cards
• SmokyCursor — Engaging cursor trails and effects

🎭 Advanced Animations

Black UI incorporates sophisticated animation systems:

import { InteractiveGradient } from 'black-ui';

function GradientDemo() {
  return (
    <InteractiveGradient 
      className="min-h-[400px] rounded-lg flex items-center justify-center"
      colors={["#ff0080", "#7928ca", "#0070f3"]}
    >
      <div className="text-center text-white p-8">
        <h2 className="text-3xl font-bold mb-4">Interactive Experience</h2>
        <p>Move your cursor to interact with this gradient background</p>
      </div>
    </InteractiveGradient>
  );
}

🔍 Customization

Black UI components can be customized using Tailwind CSS classes:

<Card 
  className="bg-gradient-to-tr from-zinc-900 to-zinc-800 text-white border-none"
  hoverable 
  bordered={false}
>
  <CardHeader>
    <CardTitle size="lg">Custom Card</CardTitle>
    <CardDescription>With gradient background</CardDescription>
  </CardHeader>
  <CardContent>
    This card uses a custom gradient background.
  </CardContent>
  <CardFooter align="end">
    <Button variant="secondary">Cancel</Button>
    <Button>Submit</Button>
  </CardFooter>
</Card>

🌈 Theming System

Black UI uses CSS variables for theming, making it easy to customize:

:root {
  --primary: 240 5% 10%;
  --primary-foreground: 0 0% 98%;
  
  /* Add your custom theme colors */
  --brand-purple: 267 100% 58%;
  --brand-blue: 214 100% 60%;
}

.dark {
  --primary: 0 0% 98%;
  --primary-foreground: 240 5% 10%;
}

📊 Component Showcase

📖 Documentation

For comprehensive documentation including all components, props, and examples:

View Documentation

🛣️ Roadmap

• Q3 2025 — Template marketplace launch
• Q4 2025 — Advanced data visualization components
• Q1 2026 — Headless component options for ultimate flexibility
• Q2 2026 — Enterprise-focused features and plugins

🤝 Contributing

We welcome contributions to Black UI! Here's how you can help:

1. Fork the repository
2. Create a 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

Please read our Contributing Guidelines for more details.

📋 Changelog

Version 1.0.0 (June 2025)

• 🎉 Initial stable release with 40+ production-ready components
• 🌙 Dark mode support finalized
• ♿ WCAG 2.1 AA compliance across all components
• 📱 Responsive design for all screen sizes
• 🔧 Theme customization system
• ⚡ Performance optimizations

📄 License

Black UI is licensed under the MIT License.