@unicity/design-system/README.md

A comprehensive React component library built on Material-UI with advanced theming capabilities including neumorphism design support

# Unicity Design System

A comprehensive React component library built on top of Material-UI, featuring 39+ production-ready components with advanced theming capabilities including neumorphism design support.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)
![React](https://img.shields.io/badge/React-18+-green.svg)
![Material-UI](https://img.shields.io/badge/MUI-5+-purple.svg)

## ✨ Features

- **39+ Production-Ready Components** - Comprehensive component library covering all common UI patterns
- **Advanced Theming** - 4 built-in theme modes including unique neumorphism variants
- **Full TypeScript Support** - Complete type definitions and excellent developer experience
- **Storybook Documentation** - Interactive component playground and documentation
- **Accessibility First** - WCAG compliant components with proper ARIA attributes
- **Responsive Design** - Mobile-first approach with breakpoint-aware components
- **Tree Shaking** - Optimized bundle size with selective imports

## 🎨 Theme Modes

- **Light Mode** - Clean, modern light theme
- **Dark Mode** - Elegant dark theme with proper contrast ratios
- **Neumorphism Light** - Soft, tactile neumorphic design in light mode
- **Neumorphism Dark** - Sophisticated neumorphic design in dark mode

## 📦 Installation

```bash
npm install @unicity/design-system
# or
yarn add @unicity/design-system
# or
pnpm add @unicity/design-system
```

### Peer Dependencies

Make sure you have the required peer dependencies installed:

```bash
npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
```

## 🚀 Quick Start

```tsx
import React from 'react';
import { ThemeProvider, Button, Card } from '@unicity/design-system';

function App() {
  return (
    <ThemeProvider mode="light">
      <Card padding="large">
        <Button variant="contained" color="primary">
          Welcome to Unicity Design System
        </Button>
      </Card>
    </ThemeProvider>
  );
}

export default App;
```

### With Theme Switching

```tsx
import React, { useState } from 'react';
import { 
  ThemeProvider, 
  ThemeSelector, 
  AppBar, 
  Paper,
  Typography 
} from '@unicity/design-system';
import type { ThemeMode } from '@unicity/design-system';

function App() {
  const [themeMode, setThemeMode] = useState<ThemeMode>('light');

  return (
    <ThemeProvider mode={themeMode}>
      <AppBar
        title="My Application"
        actions={[
          <ThemeSelector 
            currentTheme={themeMode}
            onThemeChange={setThemeMode}
          />
        ]}
      />
      <Paper padding="large">
        <Typography variant="h4">
          Beautiful Design System Components
        </Typography>
      </Paper>
    </ThemeProvider>
  );
}
```

## 📚 Component Catalog

### Layout & Navigation
- **AppBar** - Application header with navigation and actions
- **Drawer** - Sidebar navigation with multiple variants
- **Paper** - Surface component with elevation and styling options
- **Modal** - Overlay dialogs and modals
- **Dialog** - Advanced dialog system with multiple variants

### Data Display
- **DataGrid** - Advanced data table with sorting, filtering, and pagination
- **TreeView** - Hierarchical data visualization
- **Card** - Content containers with media support
- **List** - Flexible list component with various item types
- **Accordion** - Collapsible content sections
- **Odometer** - Animated number display with locale-aware formatting
- **Typography** - Enhanced typography with truncation, gradients, and text shadows

### Input & Controls
- **TextField** - Enhanced text input with validation
- **Select** - Dropdown selection with search and grouping
- **Autocomplete** - Smart search and selection input
- **DatePicker** - Comprehensive date/time selection
- **Checkbox** - Enhanced checkbox with indeterminate state
- **Radio** - Radio button groups with custom styling
- **Switch** - Toggle switches with animations
- **Slider** - Range and value sliders
- **Rating** - Star rating component

### Feedback & Communication
- **Alert** - Contextual alerts and notifications
- **Snackbar** - Toast notifications system
- **Progress** - Progress indicators (linear and circular)
- **Skeleton** - Loading placeholders
- **LoadingButton** - Buttons with integrated loading states

### Navigation & Actions
- **Button** - Enhanced buttons with multiple variants
- **IconButton** - Icon-based action buttons
- **Fab** - Floating Action Buttons
- **SpeedDial** - Quick action menus
- **Tabs** - Tab navigation component
- **Breadcrumbs** - Navigation breadcrumb trails
- **Pagination** - Page navigation controls
- **Menu** - Context menus and dropdowns

### Data Visualization
- **Badge** - Notification badges and indicators
- **Chip** - Compact elements for tags and filters
- **Avatar** - User profile images and placeholders
- **Tooltip** - Contextual help and information

## 🎛️ Theme System

### Using Built-in Themes

```tsx
import { ThemeProvider } from '@unicity/design-system';

// Available modes: 'light' | 'dark' | 'neumorphism-light' | 'neumorphism-dark'
<ThemeProvider mode="neumorphism-light">
  <YourApp />
</ThemeProvider>
```

### Custom Theme Configuration

```tsx
import { ThemeProvider, getTheme } from '@unicity/design-system';

const customTheme = getTheme('light', {
  palette: {
    primary: {
      main: '#your-brand-color',
    },
  },
  typography: {
    fontFamily: 'Your Custom Font',
  },
});

<ThemeProvider theme={customTheme}>
  <YourApp />
</ThemeProvider>
```

### Using Individual Themes

```tsx
import { 
  lightTheme, 
  darkTheme, 
  neumorphismLightTheme, 
  neumorphismDarkTheme 
} from '@unicity/design-system';
import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles';

<MuiThemeProvider theme={neumorphismDarkTheme}>
  <YourApp />
</MuiThemeProvider>
```

## 📖 Component Examples

### Advanced Data Grid

```tsx
import { DataGrid } from '@unicity/design-system';

const columns = [
  { field: 'id', headerName: 'ID', width: 90 },
  { field: 'name', headerName: 'Name', width: 150 },
  { field: 'email', headerName: 'Email', width: 200 },
];

const data = [
  { id: 1, name: 'John Doe', email: 'john@example.com' },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
];

<DataGrid
  columns={columns}
  data={data}
  pagination
  searchable
  selectable
  onRowSelect={(rows) => console.log('Selected:', rows)}
/>
```

### Animated Odometer

```tsx
import { Odometer } from '@unicity/design-system';

// Basic usage
<Odometer value={1234.56} />

// Currency formatting
<Odometer 
  value={1234.56}
  numberFormatOptions={{
    style: 'currency',
    currency: 'USD',
  }}
/>

// Percentage with custom styling
<Odometer 
  value={0.1234}
  numberFormatOptions={{
    style: 'percent',
    minimumFractionDigits: 2,
  }}
  sx={{ fontSize: '2rem', color: 'primary.main' }}
  styles={{
    digit: { fontWeight: 700 },
    literalSegment: { color: 'text.secondary' }
  }}
/>

// German locale with custom formatting
<Odometer 
  value={1234.56}
  locale="de-DE"
  numberFormatOptions={{
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }}
/>

// Interactive odometer with state management
const [value, setValue] = useState(1000);

<Odometer 
  value={value}
  animateOnMount={false}
  sx={{ backgroundColor: '#f0f0f0', padding: 2, borderRadius: 1 }}
/>
```

### Interactive Dialog

```tsx
import { Dialog, Button } from '@unicity/design-system';

const [open, setOpen] = useState(false);

<Dialog
  open={open}
  onClose={() => setOpen(false)}
  title="Confirmation Required"
  variant="confirmation"
  content="Are you sure you want to proceed with this action?"
  actions={[
    { label: 'Cancel', onClick: () => setOpen(false) },
    { 
      label: 'Confirm', 
      variant: 'contained', 
      onClick: () => handleConfirm(),
      autoFocus: true 
    }
  ]}
/>
```

### Enhanced Typography

```tsx
import { Typography } from '@unicity/design-system';

// Basic usage with different variants
<Typography variant="h1">Main Page Title</Typography>
<Typography variant="h2" color="primary">Section Title</Typography>
<Typography variant="body1">Regular paragraph text with good readability.</Typography>

// Truncation examples
<Typography truncate>
  This long text will be truncated with ellipsis when it exceeds the container width
</Typography>

<Typography lines={2}>
  This paragraph will show only 2 lines and truncate with ellipsis. 
  Useful for content previews and summaries.
</Typography>

// Gradient text effects
<Typography variant="h2" gradient>
  Default Gradient Text
</Typography>

<Typography 
  variant="h3" 
  gradient 
  gradientColors={['#ff6b6b', '#4ecdc4']}
>
  Custom Gradient Colors
</Typography>

// Text shadow effects
<Typography variant="h2" textShadow color="white">
  Text with Shadow Effect
</Typography>

// Combined effects
<Typography 
  variant="h2" 
  gradient 
  gradientColors={['#667eea', '#764ba2']}
  textShadow
  shadowColor="#333"
>
  Gradient + Shadow Effect
</Typography>
```

### Form with Validation

```tsx
import { TextField, DatePicker, Select, Button } from '@unicity/design-system';

<form>
  <TextField
    label="Full Name"
    required
    validate={(value) => !value ? 'Name is required' : null}
  />
  
  <DatePicker
    type="date"
    label="Birth Date"
    required
  />
  
  <Select
    label="Country"
    options={countries}
    searchable
    required
  />
  
  <Button type="submit" variant="contained">
    Submit Form
  </Button>
</form>
```

## 🛠️ Development

### Prerequisites

- Node.js 16+ 
- npm/yarn/pnpm

### Setup

```bash
# Clone the repository
git clone https://github.com/your-org/unicity-design-system.git

# Install dependencies
npm install

# Start Storybook development server
npm run storybook

# Build the library
npm run build

# Run tests
npm test
```

### Development Scripts

```bash
npm run dev          # Start development environment
npm run build        # Build production bundle
npm run storybook    # Start Storybook server
npm run test         # Run test suite
npm run lint         # Lint code
npm run type-check   # TypeScript type checking
```

### Project Structure

```
src/
├── components/          # All components
│   ├── Button/
│   │   ├── Button.tsx
│   │   └── Button.stories.tsx
│   └── ...
├── theme/              # Theme system
│   ├── theme.ts
│   └── ThemeProvider.tsx
└── index.ts           # Main exports

dist/                  # Built library
docs/                  # Documentation
storybook-static/      # Built Storybook
```

## 📝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Component Development Guidelines

1. **TypeScript First** - All components must be written in TypeScript
2. **Storybook Documentation** - Every component needs comprehensive stories
3. **Accessibility** - Follow WCAG guidelines and test with screen readers
4. **Testing** - Include unit tests for component logic
5. **Theme Integration** - Support all theme modes
6. **Responsive Design** - Mobile-first approach

### Adding New Components

```bash
# Create component structure
mkdir src/components/NewComponent
touch src/components/NewComponent/NewComponent.tsx
touch src/components/NewComponent/NewComponent.stories.tsx

# Add to main exports
# Update src/index.ts
```

## 🔧 Advanced Usage

### Tree Shaking

Import only what you need for optimal bundle size:

```tsx
// ✅ Good - tree shaking friendly
import { Button } from '@unicity/design-system';

// ❌ Avoid - imports entire library
import * as DesignSystem from '@unicity/design-system';
```

### Custom Components

Extend existing components with your own styling:

```tsx
import { Button } from '@unicity/design-system';
import { styled } from '@mui/material/styles';

const CustomButton = styled(Button)(({ theme }) => ({
  borderRadius: theme.spacing(3),
  // Your custom styles
}));
```

### Theme Customization

Create custom theme variants:

```tsx
import { getTheme } from '@unicity/design-system';

const brandTheme = getTheme('light', {
  palette: {
    primary: { main: '#1976d2' },
    secondary: { main: '#dc004e' },
  },
  shape: { borderRadius: 8 },
  typography: {
    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
  },
});
```

## 📊 Bundle Size

The library is optimized for tree shaking and minimal bundle impact:

- **Core**: ~45KB gzipped (theme system + utilities)
- **Individual Components**: 2-8KB gzipped each
- **Complete Library**: ~180KB gzipped

## 🌟 Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Support

- 📚 [Documentation](https://your-storybook-url.com)
- 🐛 [Issues](https://github.com/your-org/unicity-design-system/issues)
- 💬 [Discussions](https://github.com/your-org/unicity-design-system/discussions)
- 📧 [Email Support](mailto:support@unicity.com)

## 🚀 Roadmap

- [ ] React 19 support
- [ ] Additional neumorphism components
- [ ] Dark mode auto-detection
- [ ] Advanced animation system
- [ ] Mobile-specific components
- [ ] Performance optimizations

---

Built with ❤️ by the Unicity Design Team