React Theme System

⚠️ TESTING PURPOSES ONLY
This project is primarily intended for testing and development purposes. It serves as a comprehensive example of a React theme system implementation and should not be used in production environments without thorough review and customization.

A modern, flexible theme system built with React, Vite, TypeScript, and SCSS. This project demonstrates how to create beautiful, consistent UIs with dynamic theme switching and a comprehensive component library. This is primarily a testing and learning project.

✨ Features

• 🧪 Testing & Learning Focus - Designed primarily for testing and educational purposes
• 🎨 Dynamic Theme Switching - Light, dark, and custom themes
• 🧱 Comprehensive Component Library - Built from atomic design principles
• 🎯 TypeScript Support - Full type safety and IntelliSense
• 📱 Responsive Design - Mobile-first approach with CSS Grid and Flexbox
• ♿ Accessibility First - WCAG compliant components
• 🔧 Developer Experience - Storybook integration and hot reload
• 🎨 SCSS & CSS Custom Properties - Modern styling approach
• 📖 Documentation - Comprehensive guides and examples

🚀 Quick Start

Prerequisites

• Node.js 16+
• npm or yarn

Installation

# Clone or create your project
cd my-theme-system
npm install

# Start development server
npm run dev

# Start Storybook (for component development)
npm run storybook

🏗️ Project Structure

src/
├── components/          # Component library
│   ├── atoms/          # Basic building blocks
│   ├── molecules/      # Component combinations
│   ├── organisms/      # Complex UI sections
│   └── templates/      # Page layouts
├── styles/             # Theme system
│   ├── abstracts/      # SCSS utilities
│   ├── base/           # Base styles
│   ├── themes/         # Theme definitions
│   └── main.scss       # Main stylesheet
├── context/            # React context providers
├── hooks/              # Custom React hooks
├── types/              # TypeScript definitions
├── utils/              # Utility functions
└── pages/              # Example pages

🎨 Theme System

Using Themes

import { ThemeProvider } from './context/ThemeContext';
import { useTheme } from './hooks/useTheme';

// Wrap your app
function App() {
  return (
    <ThemeProvider defaultTheme="light">
      <MyApp />
    </ThemeProvider>
  );
}

// Use theme in components
function MyComponent() {
  const { theme, themeName, setTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme('dark')}>
      Switch to Dark Theme
    </button>
  );
}

Design Tokens

The theme system is built on design tokens:

// Colors
--color-primary-500: #3b82f6;
--color-background: #fafafa;
--color-text-primary: #18181b;

// Spacing
--spacing-xs: 0.25rem;
--spacing-md: 1rem;
--spacing-xl: 2rem;

// Typography
--font-size-base: 1rem;
--font-weight-medium: 500;

🧱 Components

Button Component

import { Button } from './components/atoms/Button';

<Button 
  variant="primary"       // primary, secondary, success, warning, error
  size="md"              // xs, sm, md, lg, xl
  colorScheme="solid"    // solid, outline, ghost, link
  isLoading={false}
  isDisabled={false}
>
  Click me
</Button>

Card Component

import { Card } from './components/atoms/Card';

<Card 
  variant="elevated"     // elevated, outline, filled
  padding="lg"          // xs, sm, md, lg, xl
  header="Card Title"
  footer={<Button>Action</Button>}
  isHoverable
>
  Card content goes here
</Card>

📚 Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build
npm run storybook    # Start Storybook
npm run build-storybook  # Build Storybook
npm run test         # Run tests

🎨 Customization

Creating Custom Themes

1. Define theme tokens in src/styles/themes/
2. Register theme in src/utils/themes.ts
3. Add to theme provider in src/context/ThemeContext.tsx

Example:

[data-theme='brand'] {
  --color-primary-500: #your-brand-color;
  --color-background: #your-background;
  // ... other properties
}

Creating Custom Components

Follow the atomic design methodology:

// 1. Define TypeScript interface
interface MyComponentProps {
  variant?: 'default' | 'special';
  size?: Size;
}

// 2. Create component
export const MyComponent: React.FC<MyComponentProps> = ({
  variant = 'default',
  size = 'md',
  ...props
}) => {
  const classes = cn(
    'my-component',
    `my-component--${variant}`,
    `my-component--${size}`
  );
  
  return <div className={classes} {...props} />;
};

// 3. Style with SCSS
.my-component {
  background-color: var(--color-surface);
  
  &--default {
    color: var(--color-text-primary);
  }
  
  &--special {
    color: var(--color-primary-500);
  }
}

📖 Documentation

• Gradient System Guide - Complete gradient system documentation
• Theme Customization Guide - Detailed customization guide
• Project Structure - Project structure overview
• Storybook - Component documentation and examples

🛠️ Built With

• React 18 - UI library
• Vite - Build tool and dev server
• TypeScript - Type safety
• SCSS - Enhanced CSS with variables and mixins
• Storybook - Component development environment
• CSS Custom Properties - Dynamic theming

🤝 Contributing

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

📄 License

MIT License - This project is intended for testing and learning purposes. Feel free to use this project for educational and development purposes, but please review thoroughly before using in production environments.

🔗 Resources

• Atomic Design Methodology
• CSS Custom Properties
• WCAG Guidelines
• React TypeScript Guide

Happy theming! 🎨