@ruhff/theme-editor

Interactive theme editor for the Ruhff design system. Provides a comprehensive interface for creating, editing, and managing themes with real-time preview capabilities.

Features

• Interactive Theme Editing: Visual interface for modifying component themes
• Design Token Management: Edit and organize design tokens (colors, typography, etc.)
• Real-time Preview: See changes instantly in the preview panel
• Import/Export: Support for importing and exporting themes as JSON or ZIP files
• Floating Interface: Non-intrusive floating editor that can be positioned anywhere
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• Framework Integration: Built for Vue 3 with seamless integration into existing projects

Installation

npm install @ruhff/theme-editor

Basic Usage

Using the Theme Editor Component

<template>
  <ThemeEditor
    :components="componentsMeta"
    :config="{ enableFloating: true }"
    @theme-changed="handleThemeChange"
    @tokens-changed="handleTokensChange"
  />
</template>

<script setup>
import { ThemeEditor } from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'

const componentsMeta = [
  {
    name: 'Button',
    variants: ['primary', 'secondary', 'danger'],
    styleCssVars: ['--button-bg', '--button-color', '--button-border']
  }
]

function handleThemeChange(themes) {
  console.log('Themes updated:', themes)
}

function handleTokensChange(tokens) {
  console.log('Tokens updated:', tokens)
}
</script>

Using the Floating Theme Editor

<template>
  <FloatingThemeEditor
    :components="componentsMeta"
    :config="{ keyboardShortcuts: true }"
  />
</template>

<script setup>
import { FloatingThemeEditor } from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'
</script>

Vue Plugin Installation

import { createApp } from 'vue'
import ThemeEditorPlugin from '@ruhff/theme-editor'
import '@ruhff/theme-editor/style.css'

const app = createApp()
app.use(ThemeEditorPlugin)

Advanced Usage

Custom Configuration

import type { ThemeEditorConfig } from '@ruhff/theme-editor'

const config: ThemeEditorConfig = {
  enableFloating: true,
  enableInlineEditing: true,
  keyboardShortcuts: true,
  defaultThemeSet: 'dark',
  autoSave: false
}

Import/Export Functionality

import { useThemeImportExport } from '@ruhff/theme-editor'

const { exportAsZip, exportAsJson, importFromFile } = useThemeImportExport()

// Export themes as ZIP
await exportAsZip(tokens, themes, {
  format: 'zip',
  includeTokens: true,
  includeThemes: true,
  separateFiles: true
})

// Import from file
const fileInput = document.querySelector('input[type="file"]')
const file = fileInput.files[0]
const { tokens, themes } = await importFromFile(file)

Theme Validation

import { useThemeValidation } from '@ruhff/theme-editor'

const { validateTokens, validateThemes } = useThemeValidation(componentsMeta)

const tokenValidation = validateTokens(tokens)
const themeValidation = validateThemes(themes)

if (!tokenValidation.isValid) {
  console.error('Token errors:', tokenValidation.errors)
}

Component Props

ThemeEditor

| Prop | Type | Default | Description | |------|------|---------|-------------| | components | ComponentMeta[] | [] | Array of component metadata | | initialTokens | ThemeTokens | undefined | Initial design tokens | | initialThemes | AllThemes | undefined | Initial theme configurations | | config | ThemeEditorConfig | {} | Editor configuration options |

Events

| Event | Payload | Description | |-------|---------|-------------| | theme-changed | ThemeSet | Emitted when themes are modified | | tokens-changed | ThemeTokens | Emitted when tokens are modified | | export-requested | { tokens, themes } | Emitted when export is triggered |

Types

interface ComponentMeta {
  name: string
  styleCssVars: string[]
  variants: string[]
}

interface ThemeEditorConfig {
  enableFloating?: boolean
  enableInlineEditing?: boolean
  keyboardShortcuts?: boolean
  defaultThemeSet?: string
  autoSave?: boolean
}

Styling

The theme editor uses CSS custom properties for styling. You can customize the appearance by overriding these variables:

:root {
  --te-color-primary: #3b82f6;
  --te-color-bg: #ffffff;
  --te-color-text: #1e293b;
  --te-border-radius: 6px;
}

useComponentEditor

The useComponentEditor composable provides visual component editing that automatically opens the theme editor with the selected component.

Basic Usage

<script setup>
import { useComponentEditor } from '@ruhff/theme-editor'
import { FloatingThemeEditor } from '@ruhff/theme-editor'
import componentsMeta from '@ruhff/blocks/components-meta.json'

// Set up component editor - integrates automatically with FloatingThemeEditor
const { isEditMode, enableEditMode, disableEditMode } = useComponentEditor(componentsMeta)
</script>

<template>
  <!-- Your components in .example containers -->
  <div class="example">
    <button data-component="Button" class="primary">Click me</button>
    <div data-component="Card">Card content</div>
  </div>

  <!-- FloatingThemeEditor handles the integration automatically -->
  <FloatingThemeEditor :components="componentsMeta" />
</template>

Features

• Visual Component Editing: Press Cmd/Ctrl + Shift + E to enable edit mode
• Click to Edit: Click any component in edit mode to open the theme editor
• Automatic Detection: Detects components via data-component attributes or CSS selectors
• Variant Detection: Automatically detects component variants from CSS classes
• Real-time Integration: Uses the new theme engine for instant theme updates

How it Works

1. Enable Edit Mode: Use Cmd/Ctrl + Shift + E or call enableEditMode()
2. Click Component: Click any component in an .example container
3. Auto-Open Editor: Theme editor opens with component and variant pre-selected
4. Edit Theme: Changes apply in real-time through the theme engine

Component Detection Priority

1. data-component attribute: data-component="Button" (most reliable)
2. CSS selectors: .button, .btn, .card, .badge, etc.
3. Class names: Capitalized classes like Button, Card

Variant Detection

Variants are detected from CSS classes matching component metadata:

• class="button primary" → variant &.primary
• class="button" → variant & (base)

Integration with @ruhff/theme-engine

This package works seamlessly with @ruhff/theme-engine for runtime theming:

import { useDesignTokens, useMultiTheme } from '@ruhff/theme-engine'

// The theme editor automatically integrates with theme-engine
// when both packages are installed

Contributing

See the main repository for contribution guidelines.

License

MIT