npm package: @ruhff/theme-engine
Description: A powerful, flexible theme engine for modern web applications with design token support and CSS nesting.
Latest version: 0.0.3

# Theme Engine

A powerful, flexible theme engine for modern web applications with design token support and CSS nesting.

## Features

- 🎨 **Design Token Integration** - Reference tokens using `$colors.primary.500` syntax
- 🔄 **CSS Nesting** - Modern CSS nesting with `&` selectors and @ directives  
- 📱 **Responsive Design** - Built-in breakpoint aliases (`@mobile`, `@desktop`)
- 🎯 **Component Theming** - Granular control over component variants
- 🔧 **Vite Integration** - Virtual module system for seamless development
- ⚡ **Hot Reload** - Live theme updates during development

## Quick Start

### Installation

```bash
npm install @ruhff/theme-engine
```

### Basic Usage

```javascript
import { themeToCss } from '@ruhff/theme-engine'

// Define design tokens (W3C format)
const tokens = {
  colors: {
    primary: { 500: { $value: '#3b82f6', $type: 'color' } },
    gray: { 
      100: { $value: '#f3f4f6', $type: 'color' }, 
      800: { $value: '#1f2937', $type: 'color' } 
    }
  },
  spacing: {
    md: { $value: '1rem', $type: 'dimension' }
  }
}

// Create theme with token references
const buttonTheme = {
  default: {
    background: '$colors.gray.100',
    color: '$colors.gray.800', 
    padding: '$spacing.md',
    
    hover: {
      background: '$colors.primary.500',
      color: 'white'
    }
  },
  primary: {
    background: '$colors.primary.500',
    color: 'white'
  }
}

// Generate CSS
const css = themeToCss({ theme: buttonTheme, selector: 'button', tokens })
```

### Generated CSS

```css
.button {
  --button-background: #f3f4f6;
  --button-color: #1f2937;
  --button-padding: 1rem;

  &:hover {
    --button-background: #3b82f6;
    --button-color: white;
  }
}

.button.primary {
  --button-background: #3b82f6;
  --button-color: white;
}
```

## Vite Plugin

```javascript
// vite.config.js
import { runtimeThemePlugin } from '@ruhff/theme-engine'

export default {
  plugins: [
    runtimeThemePlugin({
      tokens: './design-tokens.json'
    })
  ]
}
```

```css
/* Import themes directly */
@import "virtual:theme-engine-css?file=./themes/button.json";
```

## Core Concepts

### Design Tokens

Centralized design values that can be referenced throughout your themes:

```json
{
  "colors": {
    "primary": { "500": { "$value:": "#3b82f6", "$type": "color" } },
    "gray": { "100": { "$value:": "#f3f4f6", "$type": "color" } }
  },
  "spacing": { "md": { "$value:": "1rem", "$type": "dimension" } },
  "typography": {
    "fontSize": { "base": { "$value:": "1rem", "$type": "fontsize" } }
  }
}
```

### CSS Nesting

Modern CSS nesting with automatic selector resolution:

```json
{
  "default": {
    "color": "blue",
    "hover": { "color": "darkblue" },
    "@mobile": { "font-size": "0.875rem" }
  }
}
```

### Component Variants

Define multiple variants for the same component:

```json
{
  "default": { "background": "gray" },
  "primary": { "background": "blue" },
  "danger": { "background": "red" }
}
```

## Documentation

- [Design Token Integration](./docs/design-tokens.md)
- [Quick Start with Tokens](./docs/quick-start-with-tokens.md)
- [CSS Nesting Guide](./docs/css-nesting.md)
- [Vite Plugin Usage](./docs/vite-plugin.md)

## API Reference

### `themeToCss(options: UnifiedThemeCssOptions)`

Unified function that generates CSS for single or multiple themes.

**Options:**
- For single theme: `{ theme, selector, scopeSelector?, tokens?, sharedTokenParser? }`
- For multiple themes: `{ themes, scopeSelector?, minify?, tokens?, sharedTokenParser? }`

### `TokenParser`

Utility class for resolving design token references.

### `runtimeThemePlugin(options)`

Vite plugin for theme processing with automatic token loading.

## Examples

See the [examples](./examples/) directory for complete usage examples:

- [Basic theme with tokens](./examples/theme-with-tokens.json)
- [Design token file](./examples/design-tokens.json)
- [Vite integration](./examples/vite-config.js)

## License

MIT