# Darwin UI

> Darwin UI is a macOS-inspired React component library featuring glass-morphism aesthetics, dark theme (with light mode support), and Tailwind CSS integration. It provides 36+ production-ready components with Framer Motion animations and full accessibility support.

## Overview

Darwin UI brings the refined aesthetics of macOS to React applications. Key features include:

- **macOS-inspired design**: Glass-morphism effects, traffic light buttons, window chrome
- **Dark & Light themes**: Optimized for dark mode by default with full light mode support
- **Framer Motion animations**: Smooth spring physics and micro-interactions with prefers-reduced-motion support
- **Tailwind CSS**: Full integration with Tailwind for easy customization
- **Accessible**: WAI-ARIA compliant with keyboard navigation support
- **TypeScript**: Full type definitions included
- **Animation Configuration**: Global animation settings via configureAnimations()

### Installation

```bash
npm install @pikoloo/darwin-ui
```

Import the styles in your app entry point:

```javascript
import '@pikoloo/darwin-ui/styles.css';
```

The stylesheet is precompiled in v2.1 and later; no Tailwind `@source` directive is required.

## Agentic Coding

Darwin UI is indexed on Context7 for AI assistant integration. AI agents can fetch up-to-date documentation:

- **Context7**: https://context7.com/surajmandalcell/darwin-ui
- **Documentation**: https://darwin-ui.mandalsuraj.com

When working with Darwin UI in AI assistants (Claude, Cursor, etc.), reference Context7 for the latest API documentation.

## Getting Started

- [Introduction](https://darwin-ui.mandalsuraj.com/docs/getting-started/introduction): Overview of Darwin UI and its macOS-inspired design philosophy
- [Agentic Coding](https://darwin-ui.mandalsuraj.com/docs/getting-started/agentic-coding): How to use Darwin UI with AI coding assistants
- [Installation](https://darwin-ui.mandalsuraj.com/docs/getting-started/installation): How to install and set up Darwin UI in your project
- [Quick Start](https://darwin-ui.mandalsuraj.com/docs/getting-started/quick-start): Get up and running with your first Darwin UI components

## Components

### Layout & Navigation
- [Accordion](https://darwin-ui.mandalsuraj.com/docs/components/accordion): Collapsible content sections with smooth Framer Motion animations
- [Card](https://darwin-ui.mandalsuraj.com/docs/components/card): Glass-morphism container with header, content, and footer sections
- [Sidebar](https://darwin-ui.mandalsuraj.com/docs/components/sidebar): Navigation sidebar with collapsible mode, tooltips, and active state indicators
- [Tabs](https://darwin-ui.mandalsuraj.com/docs/components/tabs): Tabbed navigation with animated indicator and keyboard support
- [Window](https://darwin-ui.mandalsuraj.com/docs/components/window): macOS-style window chrome with traffic light buttons (close, minimize, maximize)

### Forms & Inputs
- [Button](https://darwin-ui.mandalsuraj.com/docs/components/button): Versatile button with 10 variants (primary, secondary, ghost, etc.) and 3 sizes
- [Checkbox](https://darwin-ui.mandalsuraj.com/docs/components/checkbox): Checkbox with indeterminate state support and spring animations
- [Input](https://darwin-ui.mandalsuraj.com/docs/components/input): Text input with validation states (error, success), icons, and clear button
- [SearchInput](https://darwin-ui.mandalsuraj.com/docs/components/search-input): Search input with magnifying glass icon and clear functionality
- [Select](https://darwin-ui.mandalsuraj.com/docs/components/select): Dropdown select with custom styling and keyboard navigation
- [MultiSelect](https://darwin-ui.mandalsuraj.com/docs/components/multi-select): Multi-selection dropdown with tag display and search filtering
- [Slider](https://darwin-ui.mandalsuraj.com/docs/components/slider): Range slider with customizable track, thumb, and step values
- [Switch](https://darwin-ui.mandalsuraj.com/docs/components/switch): Toggle switch with spring physics animation
- [Textarea](https://darwin-ui.mandalsuraj.com/docs/components/textarea): Multi-line text input with auto-resize and character count
- [DateSelect](https://darwin-ui.mandalsuraj.com/docs/components/date-select): Date picker with calendar interface and range selection support
- [Upload](https://darwin-ui.mandalsuraj.com/docs/components/upload): File upload with drag-and-drop support and file type validation
- [ContactForm](https://darwin-ui.mandalsuraj.com/docs/components/contact-form): Pre-built contact form with name, email, message fields and validation

### Feedback & Overlays
- [Alert](https://darwin-ui.mandalsuraj.com/docs#alert): Inline alerts and modal-style alert dialogs with semantic variants
- [Badge](https://darwin-ui.mandalsuraj.com/docs/components/badge): Status badges with semantic colors and optional dot indicator
- [Dialog](https://darwin-ui.mandalsuraj.com/docs/components/dialog): Modal dialog with focus trap, portal rendering, and backdrop click dismiss
- [DropdownMenu](https://darwin-ui.mandalsuraj.com/docs/components/dropdown-menu): Full-featured dropdown menu with keyboard navigation, submenus, and separators
- [Modal](https://darwin-ui.mandalsuraj.com/docs/components/modal): Modal dialog with glass-morphism backdrop and smooth animations
- [Popover](https://darwin-ui.mandalsuraj.com/docs/components/popover): Flexible popover with portal support and multiple placement options
- [Toast](https://darwin-ui.mandalsuraj.com/docs#toast): Toast notification system with auto-dismiss and action buttons
- [Tooltip](https://darwin-ui.mandalsuraj.com/docs/components/tooltip): Accessible tooltip with multiple positions and delay options
- [ContextMenu](https://darwin-ui.mandalsuraj.com/docs/components/context-menu): Right-click context menu with keyboard support

### Data Display
- [Avatar](https://darwin-ui.mandalsuraj.com/docs/components/avatar): User avatar with image fallback to initials and group stacking
- [Charts](https://darwin-ui.mandalsuraj.com/docs/components/charts): SVG-based charts: Line, Bar, Area, Pie, Donut, and Stacked Bar with animations
- [Image](https://darwin-ui.mandalsuraj.com/docs/components/image): Image component with lazy loading and click-to-enlarge lightbox
- [Progress](https://darwin-ui.mandalsuraj.com/docs/components/progress): Linear and circular progress indicators with animated fill
- [Skeleton](https://darwin-ui.mandalsuraj.com/docs/components/skeleton): Loading placeholder with shimmer animation effect
- [Table](https://darwin-ui.mandalsuraj.com/docs/components/table): Data table with sorting, selection, and loading states

### Utilities
- [CloseButton](https://darwin-ui.mandalsuraj.com/docs/components/close-button): Red close button matching macOS traffic light style
- [MdEditor](https://darwin-ui.mandalsuraj.com/docs/components/md-editor): Markdown editor with live preview and toolbar
- [Reveal](https://darwin-ui.mandalsuraj.com/docs/components/reveal): Scroll-triggered reveal animations with multiple effects

## Animation Configuration

Darwin UI provides a global animation configuration system:

```typescript
import { configureAnimations, ANIMATION_CONFIG } from '@pikoloo/darwin-ui';

// Disable all animations
configureAnimations({ enabled: false });

// Customize durations
configureAnimations({
  durations: { fast: 0.05, normal: 0.1, slow: 0.15 }
});

// Disable specific animation types
configureAnimations({
  disable: { hover: true, scale: true }
});
```

The library automatically respects `prefers-reduced-motion` system preference.

## Theming

- [Colors](https://darwin-ui.mandalsuraj.com/docs/theming/colors): HSL-based color system with CSS custom properties for easy theming
- [Dark Mode](https://darwin-ui.mandalsuraj.com/docs/theming/dark-mode): Dark theme optimized by default with light mode support via class toggle
- [Customization](https://darwin-ui.mandalsuraj.com/docs/theming/customization): Customize via CSS variables or Tailwind config extension

## Hooks

- **useMediaQuery**: Responsive design hook that returns true when media query matches
- **useIsMobile**: Returns true when viewport is below 768px (mobile breakpoint)
- **useEscapeKey**: Calls callback when Escape key is pressed, useful for modal dismissal
- **useContactForm**: Form handling hook with built-in validation for contact forms

## Utilities

- **cn**: Tailwind class merging utility using clsx and tailwind-merge
- **prefersReducedMotion**: Check if user prefers reduced motion
- **getDuration**: Get animation duration respecting reduced motion preference
- **getSpring**: Get spring animation config (snappy, smooth, gentle)
- **configureAnimations**: Configure global animation settings (disable, customize durations)

## Resources

- [GitHub Repository](https://github.com/surajmandalcell/darwin-ui): Source code and issue tracking
- [NPM Package](https://www.npmjs.com/package/@pikoloo/darwin-ui): Package details and version history
- [Changelog](https://darwin-ui.mandalsuraj.com/changelog): Release notes and version history
- [Context7 Docs](https://context7.com/surajmandalcell/darwin-ui): AI-optimized documentation