🚀 Theme System Quick Reference

📦 Which Library Should I Use?

🎯 Simple Decision Tree

Are you creating/editing themes? 
├─ YES → @theme-dev-tools
└─ NO → Are you building a production app?
    ├─ YES → @theme-runtime  
    └─ UNSURE → @theme-system (always works)

🔥 Common Use Cases

🏭 Production Application (Recommended: @theme-runtime)

// Lean imports for production apps
import { 
  ThemeApplicationService,   // Apply themes
  ThemeManagerService,       // Switch themes
  ThemeStorageService        // Save themes
} from '@theme-runtime';

@Component({...})
export class MyComponent {
  private themeManager = inject(ThemeManagerService);
  
  // Switch theme
  switchToTheme(themeId: string) {
    this.themeManager.applyTheme(themeId);
  }
  
  // Get current theme
  getCurrentTheme() {
    return this.themeManager.activeTheme();
  }
}

🛠️ Development Application (Recommended: @theme-dev-tools)

// Full toolkit for development apps
import { 
  ThemeEditorComponent,      // Visual theme editor
  ThemeDebuggerComponent,    // Debug themes
  ThemeManagerService        // Also available here
} from '@theme-dev-tools';

@Component({
  template: `
    <ux-theme-editor 
      [theme]="selectedTheme"
      (saved)="onThemeCreated($event)">
    </ux-theme-editor>
    
    <ux-theme-debugger></ux-theme-debugger>
  `
})
export class MyDevComponent {
  selectedTheme: Theme | null = null;
  
  onThemeCreated(theme: Theme) {
    console.log('New theme created:', theme);
  }
}

🔄 Existing Code (Zero Changes: @theme-system)

// This still works exactly as before!
import { ThemeManagerService } from '@theme-system';

// No changes needed - automatically gets new architecture benefits
@Component({...})
export class ExistingComponent {
  private themeManager = inject(ThemeManagerService);
  
  // Same code, better performance ✨
}

🎨 Theme Colors & Utilities

Color Manipulation

import { ColorUtils } from '@theme-runtime';

// Convert colors
const rgb = ColorUtils.hexToRgb('#ff6b6b');     // {r: 255, g: 107, b: 107}
const hex = ColorUtils.rgbToHex(255, 107, 107); // '#ff6b6b'

// Get contrast color (black/white)
const contrast = ColorUtils.getContrastColor('#ff6b6b'); // '#ffffff'

// Adjust brightness
const lighter = ColorUtils.adjustBrightness('#ff6b6b', 20);  // 20% lighter
const darker = ColorUtils.adjustBrightness('#ff6b6b', -20);  // 20% darker

CSS Variables Access

import { ThemeVariablesService } from '@theme-runtime';

@Component({...})
export class MyComponent {
  private themeVars = inject(ThemeVariablesService);
  
  // Apply custom CSS variables
  setCustomColors() {
    document.documentElement.style.setProperty('--my-custom-color', '#ff6b6b');
  }
  
  // Get computed CSS variables
  getCurrentPrimary() {
    return getComputedStyle(document.documentElement)
      .getPropertyValue('--ux-primary');
  }
}

🔧 Theme Management

Create New Theme

import { ThemeManagerService, Theme } from '@theme-dev-tools';

@Component({...})
export class ThemeCreator {
  private themeManager = inject(ThemeManagerService);
  
  createTheme() {
    const newTheme: Theme = {
      id: 'my-theme',
      metadata: {
        id: 'my-theme',
        name: 'My Custom Theme',
        description: 'A beautiful custom theme',
        mode: 'light'
      },
      mode: 'light',
      colors: {
        primary: '#007bff',
        secondary: '#6c757d',
        tertiary: '#28a745',
        background: '#ffffff',
        surface: '#f8f9fa',
        text: '#212529'
      },
      cssVariables: {}
    };
    
    this.themeManager.saveTheme(newTheme);
  }
}

Switch Themes

import { ThemeManagerService } from '@theme-runtime'; // or theme-dev-tools

@Component({
  template: `
    <select (change)="switchTheme($event)">
      <option *ngFor="let theme of availableThemes()" [value]="theme.id">
        {{ theme.metadata.name }}
      </option>
    </select>
  `
})
export class ThemeSwitcher {
  private themeManager = inject(ThemeManagerService);
  
  availableThemes = this.themeManager.availableThemes;
  
  switchTheme(event: Event) {
    const themeId = (event.target as HTMLSelectElement).value;
    this.themeManager.applyTheme(themeId);
  }
}

📱 Components

Ready-to-Use Components

// Theme Switcher (dropdown)
import { ThemeSwitcherComponent } from '@theme-system';

@Component({
  template: `<ux-theme-switcher></ux-theme-switcher>`
})
export class MyApp {}

// Theme Picker (visual picker)
import { ThemePickerComponent } from '@theme-system';

@Component({
  template: `
    <ux-theme-picker 
      (themeSelected)="onThemeChange($event)">
    </ux-theme-picker>
  `
})
export class MyApp {
  onThemeChange(theme: Theme) {
    console.log('Theme selected:', theme);
  }
}

Development Components (ux-test and theme creation apps)

// Theme Editor (full visual editor)
import { ThemeEditorComponent } from '@theme-dev-tools';

@Component({
  template: `
    <ux-theme-editor 
      [theme]="currentTheme"
      (saved)="onThemeSaved($event)"
      (cancelled)="onEditCancelled()">
    </ux-theme-editor>
  `
})
export class ThemeCreationApp {
  currentTheme: Theme | null = null;
  
  onThemeSaved(theme: Theme) {
    console.log('Theme saved:', theme);
  }
  
  onEditCancelled() {
    console.log('Theme editing cancelled');
  }
}

// Theme Debugger (development debugging)
import { ThemeDebuggerComponent } from '@theme-dev-tools';

@Component({
  template: `<ux-theme-debugger></ux-theme-debugger>`
})
export class DebugApp {}

🎯 CSS Classes & Variables

Utility Classes

<!-- Background colors -->
<div class="ux-bg-primary">Primary background</div>
<div class="ux-bg-secondary">Secondary background</div>
<div class="ux-bg-surface">Surface background</div>

<!-- Text colors -->
<span class="ux-text-primary">Primary text</span>
<span class="ux-text-on-primary">Text on primary background</span>

<!-- Spacing -->
<div class="ux-p-lg ux-m-md">Padding large, margin medium</div>

<!-- Hover effects -->
<button class="ux-bg-primary ux-hover:ux-bg-secondary">
  Hover to change color
</button>

CSS Variables

.my-component {
  /* Core colors */
  background: var(--ux-primary);
  color: var(--ux-on-primary);
  border: 1px solid var(--ux-outline);
  
  /* Spacing */
  padding: var(--ux-spacing-md);
  margin: var(--ux-spacing-lg);
  
  /* Typography */
  font-size: var(--ux-text-lg);
  
  /* Opacity variants */
  box-shadow: 0 2px 8px var(--ux-primary-opacity-20);
}

⚡ Performance Tips

Bundle Size Optimization

// ✅ Good: Import only what you need
import { ThemeManagerService } from '@theme-runtime';     // ~50KB

// ❌ Avoid: Importing everything when you don't need creation tools
import { ThemeManagerService } from '@theme-dev-tools';  // ~120KB

Tree Shaking

// ✅ Good: Specific imports
import { ThemeApplicationService, ColorUtils } from '@theme-runtime';

// ❌ Avoid: Wildcard imports
import * as ThemeEngine from '@theme-runtime';

🆘 Troubleshooting

Common Issues

Quick Fixes

// Problem: Import not working
// Solution: Use compatibility bridge
import { ThemeManagerService } from '@theme-system'; // Always works

// Problem: Theme not persisting
// Solution: Use storage service
import { ThemeStorageService } from '@theme-runtime';
const storage = inject(ThemeStorageService);
storage.saveTheme(theme);

// Problem: Need debugging
// Solution: Use debug component (development apps only)
import { ThemeDebuggerComponent } from '@theme-dev-tools';

🎉 You're Ready!

This reference covers 90% of common theme system usage. For advanced scenarios, see the full architecture documentation.

Happy theming! 🎨✨