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

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

Basic Usage

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

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

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

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

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

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

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

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:

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

Adding New Gradients

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

Using CSS Variables

.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

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

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:

// 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

# 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
• Theme Customization Guide
• Design System Overview

🤝 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 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.