npm package: @manaslab/global-themes
Description: A production-grade React theme management system with built-in UI controls, scoped CSS support, and extensive color palettes.
Author: Manas Barman
Latest version: 1.0.4

# @manaslab/global-themes

<div align="center">
  <img src="https://raw.githubusercontent.com/ManasBarman229/global-themes/main/media/banner.svg" alt="Global Themes Banner" width="100%" />
</div>

<div align="center">
  
  [![npm version](https://img.shields.io/npm/v/@manaslab/global-themes.svg?style=flat-square)](https://www.npmjs.com/package/@manaslab/global-themes)
  [![License](https://img.shields.io/npm/l/@manaslab/global-themes.svg?style=flat-square)](LICENSE)
  [![Downloads](https://img.shields.io/npm/dm/@manaslab/global-themes.svg?style=flat-square)](https://www.npmjs.com/package/@manaslab/global-themes)
  
</div>

<br />

<div align="center">
  <img src="https://raw.githubusercontent.com/ManasBarman229/global-themes/main/media/preview.svg" alt="Component Preview" width="600px" />
</div>

<br />

> **A production-grade React theme management system.** 
> Built for modern applications requiring robust dark mode support, dynamic color palettes, and a beautiful pre-built UI.

## ✨ Features

- 🌓 **First-Class Dark Mode**: Automatic system detection with manual override and local storage persistence.
- 🎨 **Dynamic Color Palettes**: Over 20+ preset professional color schemes (Emerald, Violet, Rose, Sky, etc.).
- 🚀 **CSS Variables Strategy**: Efficient variable injection for high-performance styling without runtime overhead.
- 🧩 **Ready-to-Use UI**: Includes a beautiful `ThemeControls` component for instant theme switching.
- 🛡️ **Type-Safe**: Written in TypeScript with full type definitions included.

## 📦 Installation

```bash
npm install @manaslab/global-themes lucide-react
# or
yarn add @manaslab/global-themes lucide-react
# or
pnpm add @manaslab/global-themes lucide-react
```
*(Note: `lucide-react` is a peer dependency for the UI icons)*

## 🚀 Quick Start

### 1. Wrap your application

Wrap your root component with `ThemeProvider`. This is usually done in `main.tsx` or `App.tsx`.

```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ThemeProvider } from '@manaslab/global-themes';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </React.StrictMode>
);
```

### 2. Add the UI Controls

Place the `ThemeControls` component anywhere in your app (it's fixed positioned by default).

```tsx
import { ThemeControls } from '@manaslab/global-themes';

function App() {
  return (
    <div className="min-h-screen transition-colors duration-300 bg-slate-50 dark:bg-zinc-900">
      <ThemeControls />
      {/* ... your app content */}
    </div>
  );
}
```

## 🔧 Hook Usage

Access theme state programmatically using `useTheme`.

```tsx
import { useTheme } from '@manaslab/global-themes';

const MyComponent = () => {
  const { isDark, toggleTheme, themeColor, setThemeColor } = useTheme();

  return (
    <button onClick={toggleTheme}>
      {isDark ? 'Switch to Light' : 'Switch to Dark'}
    </button>
  );
};
```

## 🎨 Tailwind Configuration

To use the dynamic colors in your Tailwind project, update your `tailwind.config.js` to reference the CSS variables injected by this package.

```js
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
    content: [
      "./index.html",
      "./src/**/*.{js,ts,jsx,tsx}",
    ],
    darkMode: 'class', // Required for manual dark mode
    theme: {
        extend: {
            colors: {
                // Map your theme colors to the variables
                theme: {
                    500: 'var(--theme-500)',
                    600: 'var(--theme-600)',
                    400: 'var(--theme-400)',
                    100: 'var(--theme-100)',
                    200: 'var(--theme-200)',
                },
                // Optional: Map secondary accent
                secondary: {
                    500: 'var(--secondary-500)',
                    // ...
                }
            },
        },
    },
    plugins: [],
}
```

## 📜 License

MIT © [Manas Barman](https://github.com/ManasBarman229)