@ruhff/theme-engine

v0.0.3

Published

3 months ago

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

0High
0Medium
0Low

munaibhussain

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

npm install @ruhff/theme-engine

Basic Usage

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

.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

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

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

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

{
  "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:

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

Component Variants

Define multiple variants for the same component:

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

Documentation

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 directory for complete usage examples:

License

MIT