@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 46+ production-ready components with advanced theming capabilities, GSAP-powered animations, internationalization support, and comprehensive accessibility tools.

![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)
![i18n](https://img.shields.io/badge/i18n-11_Languages-green.svg)
![Accessibility](https://img.shields.io/badge/WCAG-2.1_AA_Compliant-blue.svg)

## ✨ Features

- **46+ Production-Ready Components** - Comprehensive component library covering all common UI patterns
- **🌍 Complete Internationalization** - Full i18n support with 11 languages and React hooks
- **♿ Advanced Accessibility Controller** - 8 dedicated accessibility categories with WCAG 2.1 AA compliance
- **🎨 Advanced Theming** - 6 built-in theme modes including neumorphism and high-contrast variants
- **📝 Enhanced Font Override Service** - Comprehensive font scaling that works with any styling method
- **📊 Advanced Data Visualization** - Interactive genealogy trees, masonry layouts, and data grids
- **🎛️ Professional Settings Controllers** - Theme and accessibility management interfaces
- **🎬 GSAP-Powered Animations** - Smooth, performant animations with modular animated icons
- **🏗️ Full TypeScript Support** - Complete type definitions and excellent developer experience
- **📚 Storybook Documentation** - Interactive component playground and comprehensive documentation
- **🔧 Accessibility First** - WCAG 2.1 compliant with extensive customization options
- **📱 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
- **High Contrast Light** - Enhanced contrast for accessibility compliance
- **High Contrast Dark** - High contrast dark mode for visual accessibility

## 📦 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@^6.0.0 @mui/icons-material@^6.0.0 @emotion/react @emotion/styled gsap
```

**Note**: This design system requires MUI v6.0.0 or v7.0.0. If you're using MUI v5, please upgrade to avoid compatibility issues.

## 🚀 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
- **GenealogyTreeView** - Interactive hierarchical genealogy trees with keyboard navigation and dual layouts
- **TreeView** - Standard hierarchical data visualization
- **Masonry** - Pinterest-style grid layouts with smooth animations
- **Card** - Content containers with media support
- **List** - Flexible list component with various item types
- **Accordion** - Collapsible content sections
- **Typography** - Enhanced typography with truncation, gradients, and text shadows
- **Tooltip** - Contextual help and information
- **Avatar** - User profile images and placeholders
- **Badge** - Notification badges and indicators
- **Chip** - Compact elements for tags and filters

### 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
- **AniButton** - Animated buttons with GSAP-powered icon animations
- **AniIconButton** - Animated icon buttons with GSAP-powered animations
- **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

### Utilities & Settings
- **AccessibilityController** - Comprehensive accessibility settings with 8 specialized categories and event tracking
- **ThemeSettingsController** - Professional theme and appearance management interface with event logging
- **ThemeToggle** - Simple theme mode switching component with interaction tracking
- **Odometer** - Animated number display with locale-aware formatting and currency support
- **TranslationProvider** - Complete internationalization system with 11 language support

### Animated Icons
- **AniCheckmarkIcon** - GSAP-powered checkmark animation for success states and verification
- **Extensible System** - Modular architecture for creating custom animated icons

## 🎛️ 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>
```

### Animated Button with GSAP Icons

```tsx
import { AniButton, AniCheckmarkIcon } from '@unicity/design-system';

// End animated icon (most common)
<AniButton 
  variant="contained"
  color="success"
  endAnimatedIcon={AniCheckmarkIcon}
>
  Save Document
</AniButton>

// Start animated icon
<AniButton 
  variant="contained"
  color="info"
  startAnimatedIcon={AniCheckmarkIcon}
  endIcon={<Send />}
>
  Verify & Send
</AniButton>

// Both start and end animated icons
<AniButton 
  variant="contained"
  color="primary"
  startAnimatedIcon={AniCheckmarkIcon}
  endAnimatedIcon={AniCheckmarkIcon}
>
  Double Verification
</AniButton>

// Permanent checkmark state
<AniButton 
  variant="outlined"
  color="success"
  endAnimatedIcon={AniCheckmarkIcon}
  showAnimatedIcon={true}
>
  Verified Account
</AniButton>

// Click to animate (most common use case)
<AniButton 
  variant="contained"
  color="success"
  endAnimatedIcon={AniCheckmarkIcon}
  onClickAnimate={true}
>
  Save Document
</AniButton>

// Custom animation settings with regular icons
<AniButton 
  variant="contained"
  color="primary"
  startIcon={<Save />}
  endAnimatedIcon={AniCheckmarkIcon}
  onClickAnimate={true}
  animationDuration={0.8}
  animatedIconSize={24}
>
  Quick Save
</AniButton>

// Without animated icon (regular button)
<AniButton 
  variant="text"
  startIcon={<Download />}
  endIcon={<Send />}
>
  Download & Send
</AniButton>
```

### Animated Icon Button

```tsx
import { AniIconButton, AniCheckmarkIcon } from '@unicity/design-system';
import { Save, Edit, Delete, ChevronRight } from '@mui/icons-material';

// Basic animated icon button with fallback icon
<AniIconButton 
  animatedIcon={AniCheckmarkIcon}
  onClickAnimate={true}
  color="success"
>
  <ChevronRight />
</AniIconButton>

// With regular icon (no animation)
<AniIconButton color="primary">
  <Save />
</AniIconButton>

// Permanent animated icon (no fallback needed)
<AniIconButton 
  animatedIcon={AniCheckmarkIcon}
  showAnimatedIcon={true}
  color="success"
  size="large"
/>

// Custom animation settings with fallback
<AniIconButton 
  animatedIcon={AniCheckmarkIcon}
  onClickAnimate={true}
  animationDuration={0.8}
  animatedIconSize={32}
  color="primary"
>
  <Save />
</AniIconButton>

// In a toolbar with mixed icons
<Box sx={{ display: 'flex', gap: 1 }}>
  <AniIconButton size="small">
    <Edit />
  </AniIconButton>
  <AniIconButton 
    size="small"
    animatedIcon={AniCheckmarkIcon}
    onClickAnimate={true}
    color="success"
  >
    <Save />
  </AniIconButton>
  <AniIconButton size="small" color="error">
    <Delete />
  </AniIconButton>
</Box>

// Floating action style
<AniIconButton 
  size="large"
  animatedIcon={AniCheckmarkIcon}
  onClickAnimate={true}
  color="primary"
  sx={{ 
    position: 'fixed', 
    bottom: 16, 
    right: 16,
    boxShadow: 3 
  }}
>
  <Add />
</AniIconButton>
```

### 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>
```

### Translation System

```tsx
import { TranslationProvider, useTranslation } from '@unicity/design-system';

// Wrap your app with TranslationProvider
function App() {
  return (
    <TranslationProvider>
      <MyComponent />
    </TranslationProvider>
  );
}

// Use translations in components
function MyComponent() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('welcome', 'Welcome')}</h1>
      <p>{t('hello_user', 'Hello {{name}}', { name: 'John' })}</p>
      <button>{t('apply', 'Apply')}</button>
    </div>
  );
}

// Language selector with hooks
import { useLanguageSelector } from '@unicity/design-system';

function LanguageSelector() {
  const { changeLanguage, currentLanguage, getSupportedLanguages } = useLanguageSelector();
  
  return (
    <select value={currentLanguage} onChange={(e) => changeLanguage(e.target.value)}>
      {getSupportedLanguages().map(lang => (
        <option key={lang.i18nCode} value={lang.i18nCode}>
          {lang.label}
        </option>
      ))}
    </select>
  );
}
```

### Accessibility Controller

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

// Basic usage
function App() {
  return (
    <ThemeProvider>
      <AccessibilityController />
    </ThemeProvider>
  );
}

// Controlled with custom settings and event tracking
function MyAccessibilitySettings() {
  const [settings, setSettings] = useState({
    accessibilityMode: 'high-contrast',
    fontSize: { level: 'large', scale: 1.25 },
    motion: { reduceMotion: true, animationSpeed: 'slow' },
    contentDensity: { density: 'spacious', touchTargetSize: 'large' }
  });

  const handleAccessibilityEvent = (eventData: any) => {
    console.log('Accessibility event:', eventData);
    // Track user interactions for analytics
  };

  return (
    <ThemeProvider settings={settings} onSettingsChange={setSettings}>
      <AccessibilityController 
        value={settings}
        onChange={setSettings}
        onEvent={handleAccessibilityEvent}
        compact={true}
      />
    </ThemeProvider>
  );
}
```

### Event Tracking

Track user interactions across theme and accessibility components:

```tsx
import { 
  AccessibilityController, 
  ThemeSettingsController, 
  ThemeToggle 
} from '@unicity/design-system';

function MyApp() {
  const handleEvent = (eventData: any) => {
    console.log('User interaction:', eventData);
    
    // Examples of event data:
    switch (eventData.type) {
      case 'font_size_change':
        // { type: 'font_size_change', value: 1.125, percentage: 112.5, level: 'large' }
        break;
      case 'accessibility_mode_change':
        // { type: 'accessibility_mode_change', value: 'high-contrast', enabled: true }
        break;
      case 'theme_mode_change':
        // { type: 'theme_mode_change', value: 'dark', previousMode: 'light' }
        break;
      case 'theme_toggle':
        // { type: 'theme_toggle', value: 'dark', previousMode: 'light' }
        break;
    }
  };

  return (
    <div>
      <ThemeToggle onEvent={handleEvent} />
      <ThemeSettingsController onEvent={handleEvent} />
      <AccessibilityController onEvent={handleEvent} />
    </div>
  );
}
```

### Interactive Genealogy Tree

```tsx
import { GenealogyTreeView, completeApiData, SortBy } from '@unicity/design-system';

function MyGenealogyPage() {
  const [sortBy, setSortBy] = useState(SortBy.Alphabetical);
  
  return (
    <div>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as SortBy)}>
        <option value={SortBy.Alphabetical}>Alphabetical</option>
        <option value={SortBy.MostDownlineCountDescending}>Most Downline</option>
        <option value={SortBy.OVDescending}>Highest OV</option>
      </select>
      
      <GenealogyTreeView
        data={completeApiData}
        width="100%"
        height="600px"
        sortBy={sortBy}
        autoFocus={true}
        onNodeClick={(node) => console.log('Selected:', node.firstName, node.lastName)}
        onFilterModeChange={(isFilterMode) => 
          console.log('Layout:', isFilterMode ? 'Tiled' : 'Tree')
        }
      />
    </div>
  );
}
```

### Animated Masonry Layout

```tsx
import { Masonry, Card } from '@unicity/design-system';

function PhotoGallery() {
  return (
    <Masonry 
      columns={4}
      gap={16}
      animated={true}
      animationType="fadeScale"
      staggerDelay={100}
      hoverAnimation={true}
      breakpoints={{
        480: 1,   // 1 column on mobile
        768: 2,   // 2 columns on tablet  
        1024: 3,  // 3 columns on desktop
        1280: 4   // 4 columns on large screens
      }}
    >
      {photos.map(photo => (
        <Card key={photo.id}>
          <img src={photo.url} alt={photo.title} />
          <h3>{photo.title}</h3>
        </Card>
      ))}
    </Masonry>
  );
}
```

## 🛠️ 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';
```

### Font Override Service

Configure comprehensive font scaling that works with any styling method:

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

// Enable font override with custom settings
fontOverrideService.updateConfig({
  scale: 1.25,
  aggressive: false,
  excludeSelectors: ['code', '.my-special-class'],
  excludeClasses: ['no-scale', 'fixed-size'],
  minFontSize: 12,
  maxFontSize: 40,
});

// Use CSS variables in styled components
import styled from 'styled-components';

const ResponsiveText = styled.div`
  font-size: clamp(
    var(--unicity-min-font-size, 10px),
    calc(16px * var(--unicity-font-scale, 1)),
    var(--unicity-max-font-size, 32px)
  );
`;

// Exclude specific elements from scaling
<div className="unicity-font-exclude">Won't be scaled</div>
<div data-unicity-font-exclude="true">Also won't be scaled</div>
```

### Translation Configuration

Configure internationalization with external APIs or custom translations:

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

// External API configuration
<TranslationProvider config={{
  translationUrl: 'https://cdn.unicity.com/translations/qa/newOffice/',
  enableDebug: process.env.NODE_ENV === 'development',
  fallbackLanguage: 'en-US', // Use full language codes like 'en-US', 'de-DE', etc.
  enableCache: true,
  localTranslationUrl: localTranslationTable
}}>
  <App />
</TranslationProvider>

// Environment-based configuration
// Set in your .env file:
// REACT_APP_TRANSLATION_URL=https://cdn.unicity.com/translations/
// REACT_APP_TRANSLATION_DEBUG=false
// REACT_APP_TRANSLATION_CACHE=true

<TranslationProvider>
  <App />
</TranslationProvider>

// Programmatic translation utilities
import { translationUtils } from '@unicity/design-system';

const currentLang = translationUtils.getLanguage();
translationUtils.changeLanguage('es');
const languages = translationUtils.getSupportedLanguages();
```

### Accessibility Integration

Combine accessibility features with your existing theme system:

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

function AccessibilityAwareApp() {
  const { settings } = useTheme();
  
  // Access current accessibility settings
  const isHighContrast = settings.accessibilityMode === 'high-contrast';
  const reduceMotion = settings.motion?.reduceMotion;
  const fontSize = settings.fontSize?.scale;
  
  return (
    <div 
      className={isHighContrast ? 'high-contrast-mode' : ''}
      style={{
        // Apply settings to custom components
        fontSize: `${fontSize}rem`,
        animation: reduceMotion ? 'none' : 'fadeIn 0.3s ease'
      }}
    >
      <AccessibilityController />
      <MyContent />
    </div>
  );
}

// Individual accessibility tools
import { 
  VisualAccessibility,
  TextSize,
  MotionAnimation,
  ColorVisibility 
} from '@unicity/design-system';

<Stack spacing={3}>
  <VisualAccessibility />
  <TextSize enableFontOverride={true} />
  <ColorVisibility />
</Stack>
```

### 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 with accessibility support:

```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',
  },
  // Accessibility-aware spacing
  spacing: (factor) => `${0.25 * factor}rem`,
});

// High contrast theme variant
const highContrastTheme = getTheme('high-contrast-light', {
  palette: {
    primary: { main: '#000000' },
    background: { default: '#ffffff', paper: '#ffffff' },
    text: { primary: '#000000', secondary: '#000000' }
  }
});
```

## 📊 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

### Core Library
- **Chrome 90+** - Full feature support including accessibility APIs
- **Firefox 88+** - Complete compatibility with translation and theming
- **Safari 14+** - All features supported including CSS custom properties
- **Edge 90+** - Full support for advanced components and services

### Internationalization Features
- **Intl API Support**: Modern browsers with `Intl.NumberFormat` and `Intl.DateTimeFormat`
- **Unicode Support**: Full UTF-8 character set support for 11 languages
- **LocalStorage**: For language preference persistence
- **Fetch API**: For dynamic translation loading

### Accessibility Features
- **CSS Custom Properties**: For dynamic theming and font scaling
- **MutationObserver**: For font override service functionality
- **Web Audio API**: Optional for sound effect controls
- **Vibration API**: Optional for haptic feedback (mobile)
- **Intersection Observer**: For reading guide features
- **Media Queries**: For `prefers-reduced-motion` and contrast preferences

### Performance Optimization
- **ES2020 Support**: For optimal bundle size and performance
- **CSS Grid & Flexbox**: For layout components
- **CSS Transforms**: For smooth animations and transitions

## 📄 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