react-vite-themes/README.md

A test/experimental React theme system created for learning purposes. Features atomic design components, SCSS variables, and dark/light theme support. Not intended for production use.

# React Theme System

A comprehensive, modern React theme system with TypeScript support, featuring atomic design components, dynamic theming, and a powerful gradient system.

## 🎨 Features

### **Core Features**
- **Atomic Design Architecture** - Organized component hierarchy (atoms, molecules, organisms)
- **Dynamic Theme Switching** - Light/dark mode with system preference detection
- **TypeScript Support** - Full type safety and IntelliSense
- **SCSS Variables** - Centralized design tokens and theme configuration
- **Gradient System** - 15+ pre-built gradients with easy customization
- **Responsive Design** - Mobile-first approach with flexible layouts

### **Component Library**
- **Buttons** - 30+ variants including gradients, sizes, and states
- **Cards** - Multiple variants with image support and hover effects
- **Alerts** - Auto-dismiss, closable, and multiple variants with proper theme detection
- **Modals** - Accessible with backdrop, escape key, and focus management
- **Forms** - Complete form system with validation states
- **Navigation** - Navbar and Sidebar components with mobile support
- **Icons** - 50+ SVG icons with customizable sizes and colors
- **Typography** - Complete type scale with semantic colors
- **Search** - SearchBar component with clear functionality
- **Showcase Page** - Live demonstration of all components in a learning platform context

### **Theme System**
- **Color Palette** - 11 shades per color (50-950) with semantic colors
- **Gradient Library** - Sunset, Ocean, Forest, Fire, Cosmic, Aurora, and more
- **Design Tokens** - Spacing, typography, shadows, and transitions
- **CSS Variables** - Dynamic theming with fallbacks
- **Utility Classes** - Comprehensive spacing, layout, and typography utilities
- **Numeric Spacing** - Tailwind-like numeric spacing classes (mt-3, p-4, etc.)

## 🚀 Quick Start

### Installation

```bash
npm install @your-org/react-theme-system
```

### Basic Usage

```tsx
import { ThemeProvider } from '@your-org/react-theme-system';
import { Button, Card, Alert } from '@your-org/react-theme-system';

function App() {
  return (
    <ThemeProvider>
      <div className="app">
        <Button variant="gradient-sunset" size="lg">
          Get Started
        </Button>
        
        <Card variant="elevated" header="Welcome">
          <p>This is a beautiful card with elevation.</p>
        </Card>
        
        <Alert variant="success" title="Success!">
          Your action was completed successfully.
        </Alert>
      </div>
    </ThemeProvider>
  );
}
```

## 🎯 Component Usage

### Button Component

```tsx
import { Button } from '@your-org/react-theme-system';

// Basic variants
<Button variant="primary">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>
<Button variant="success">Success Button</Button>

// Gradient variants
<Button variant="gradient-sunset">Sunset Gradient</Button>
<Button variant="gradient-ocean">Ocean Gradient</Button>
<Button variant="gradient-forest">Forest Gradient</Button>

// Sizes and states
<Button size="sm">Small Button</Button>
<Button size="lg">Large Button</Button>
<Button isDisabled>Disabled Button</Button>
<Button isLoading>Loading Button</Button>

// Color schemes
<Button colorScheme="outline">Outline Button</Button>
<Button colorScheme="ghost">Ghost Button</Button>
```

### Card Component

```tsx
import { Card } from '@your-org/react-theme-system';

// Basic variants
<Card variant="elevated" header="Card Title" footer="Card Footer">
  <p>Card content goes here.</p>
</Card>

// With images
<Card 
  variant="elevated" 
  header="Product Card"
  image={{
    src: "https://example.com/image.jpg",
    alt: "Product image",
    height: 200
  }}
>
  <h4>Product Name</h4>
  <p>Product description.</p>
</Card>

// Gradient variants
<Card variant="gradient-sunset" header="Gradient Card">
  <p>Beautiful gradient background.</p>
</Card>
```

### Alert Component

```tsx
import { Alert } from '@your-org/react-theme-system';

// Basic alerts
<Alert variant="success" title="Success!">
  Your action was completed successfully.
</Alert>

<Alert variant="warning" title="Warning">
  Please review your input before proceeding.
</Alert>

<Alert variant="error" title="Error">
  Something went wrong. Please try again.
</Alert>

// Auto-dismiss
<Alert 
  variant="info" 
  autoDismiss 
  dismissDelay={5000}
  onDismiss={() => console.log('Alert dismissed')}
>
  This alert will dismiss automatically.
</Alert>
```

### Modal Component

```tsx
import { Modal } from '@your-org/react-theme-system';
import { useState } from 'react';

function ModalExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>
        Open Modal
      </Button>
      
      <Modal 
        isOpen={isOpen} 
        onClose={() => setIsOpen(false)}
        title="Example Modal"
        size="lg"
      >
        <p>Modal content goes here.</p>
        <Button onClick={() => setIsOpen(false)}>
          Close
        </Button>
      </Modal>
    </>
  );
}
```

### Form Component

```tsx
import { Form, Input } from '@your-org/react-theme-system';

function FormExample() {
  const handleSubmit = (data: any) => {
    console.log('Form submitted:', data);
  };

  return (
    <Form onSubmit={handleSubmit} variant="elevated">
      <div className="form__field-group">
        <label className="form__label">Name</label>
        <Input 
          type="text" 
          name="name" 
          placeholder="Enter your name"
        />
      </div>
      
      <div className="form__field-group">
        <label className="form__label">Email</label>
        <Input 
          type="email" 
          name="email" 
          placeholder="Enter your email"
        />
      </div>
    </Form>
  );
}
```

### Navigation Components

```tsx
import { Navbar, Sidebar } from '@your-org/react-theme-system';

// Navbar
<Navbar brand={<span>My App</span>} variant="primary">
  <a href="/" className="nav-item">Home</a>
  <a href="/about" className="nav-item">About</a>
  <a href="/contact" className="nav-item">Contact</a>
</Navbar>

// Sidebar
const [isSidebarOpen, setIsSidebarOpen] = useState(false);

<Sidebar 
  isOpen={isSidebarOpen} 
  onClose={() => setIsSidebarOpen(false)}
  direction="left"
>
  <h3>Sidebar Content</h3>
  <ul>
    <li>Menu Item 1</li>
    <li>Menu Item 2</li>
    <li>Menu Item 3</li>
  </ul>
</Sidebar>
```

### Icon Component

```tsx
import { Icon } from '@your-org/react-theme-system';

// Basic usage
<Icon name="heart" size="lg" />

// Custom size and color
<Icon name="star" size={24} color="var(--color-primary-500)" />

// Spinning animation
<Icon name="spinner" size="lg" className="icon--spinning" />

// Available icons: success, warning, error, info, search, 
// hamburger, close, login, chevronDown, chevronUp, 
// chevronLeft, chevronRight, check, plus, minus, play, 
// pause, volume, settings, user, home, mail, phone, 
// heart, star, eye, eyeOff, download, upload, edit, 
// trash, copy, link, externalLink, calendar, clock, 
// mapPin, tag, filter, refresh, spinner, menu, palette,
// components, responsive, book, check-circle, lock, circle
```

## 🎨 Theme Customization

### Adding New Colors

Edit `src/styles/themes/_config.scss`:

```scss
$color-definitions: (
  // Existing colors...
  'custom': #ff6b35,  // Add your custom color
);
```

### Adding New Gradients

```scss
$gradient-definitions: (
  // Existing gradients...
  'custom-gradient': (to right, #ff6b35, #f7931e),  // Add your gradient
);
```

### Using CSS Variables

```css
.my-component {
  background-color: var(--color-primary-500);
  color: var(--color-neutral-900);
  border-radius: var(--border-radius-md);
  box-shadow: var(--shadow-md);
}
```

## 🔧 Theme Context

### Using the Theme Hook

```tsx
import { useTheme } from '@your-org/react-theme-system';

function ThemeToggle() {
  const { theme, toggleTheme, setSystemTheme } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      <Button onClick={toggleTheme}>Toggle Theme</Button>
      <Button onClick={setSystemTheme}>Use System Theme</Button>
    </div>
  );
}
```

### Theme Provider Setup

```tsx
import { ThemeProvider } from '@your-org/react-theme-system';

function App() {
  return (
    <ThemeProvider>
      {/* Your app components */}
    </ThemeProvider>
  );
}
```

## 📱 Responsive Design

The theme system includes responsive utilities and mobile-first design:

```scss
// Responsive breakpoints
$breakpoints: (
  'sm': 640px,
  'md': 768px,
  'lg': 1024px,
  'xl': 1280px,
  '2xl': 1536px
);
```

## 🎯 Available Variants

### Button Variants
- **Solid**: `primary`, `secondary`, `success`, `warning`, `error`, `neutral`
- **Gradients**: `gradient-sunset`, `gradient-ocean`, `gradient-forest`, `gradient-fire`, `gradient-cosmic`, `gradient-aurora`, `gradient-rainbow`, `gradient-wizard`
- **Sizes**: `xs`, `sm`, `md`, `lg`, `xl`
- **Color Schemes**: `solid`, `outline`, `ghost`, `link`

### Card Variants
- **Basic**: `elevated`, `outline`, `filled`, `glass`, `bordered`
- **Colors**: All solid and gradient variants
- **Padding**: `xs`, `sm`, `md`, `lg`, `xl`

### Alert Variants
- **Types**: `success`, `warning`, `error`, `info`
- **Sizes**: `sm`, `md`, `lg`

### Modal Variants
- **Styles**: `default`, `elevated`, `glass`, `bordered`
- **Sizes**: `xs`, `sm`, `md`, `lg`, `xl`, `full`
- **Colors**: All solid and gradient variants

## 🛠️ Development

### Project Structure

```
src/
├── components/
│   ├── atoms/           # Basic components
│   │   ├── Button/
│   │   ├── Card/
│   │   ├── Alert/
│   │   ├── Modal/
│   │   ├── Form/
│   │   ├── Input/
│   │   ├── Icon/
│   │   ├── Navbar/
│   │   ├── Sidebar/
│   │   └── SearchBar/
│   ├── molecules/       # Composite components
│   ├── organisms/       # Complex components
│   └── showcase/        # Component examples
├── context/
│   └── ThemeContext.tsx # Theme management
├── hooks/
│   └── useTheme.ts      # Theme hook
├── styles/
│   ├── themes/          # Theme configuration
│   ├── abstracts/       # Variables and mixins
│   ├── base/           # Base styles
│   └── layout/         # Layout styles
└── types/
    └── components.ts    # TypeScript definitions
```

### Available Scripts

```bash
# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run preview          # Preview production build

# Type generation
npm run generate-types   # Generate TypeScript types from SCSS
npm run watch-types      # Watch and regenerate types

# Publishing
npm run publish          # Publish to npm
```

## 📚 Documentation

For detailed documentation, see:
- [Component API Reference](./docs/COMPONENT_API.md)
- [Theme Customization Guide](./docs/THEME_CUSTOMIZATION.md)
- [Design System Overview](./docs/DESIGN_SYSTEM.md)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

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

---

**Note**: This is a test/demo project showcasing a comprehensive React theme system. While functional, it's primarily intended for learning and demonstration purposes.