@mhmo91/schmancy 0.5.35 → 0.5.37

package/ai/theme.md

@@ -1,923 +1,986 @@
-# Theme System Documentation
+# Theme Service
 
-A comprehensive theming system that provides both a visual configuration component and a programmatic service API. Built on Material Design 3 principles, it generates complete color schemes with automatic dark/light mode support and CSS custom property injection.
+Comprehensive Material Design 3 theme management with reactive observables, automatic persistence, and a complete token system for colors, typography, motion, and more.
 
-## Overview
+## Import
 
-The Schmancy theme system consists of two main parts:
-1. **Theme Component** (`<schmancy-theme>`) - Visual theme configuration interface
-2. **Theme Service API** (`themeService`) - Programmatic theme management and subscriptions
+```typescript
+import { theme } from '@schmancy/theme'
+// Alternative: schmancyTheme
+```
 
-## Quick Start
+## Core Concepts
 
-### Using the Theme Component
+- **Scheme**: Color mode (`'dark'` | `'light'` | `'auto'`)
+- **Resolved Scheme**: Actual theme after resolving `'auto'` based on system preferences
+- **Color**: Primary theme color in hex format
+- **Fullscreen**: Navigation visibility state
+- **Theme Component**: Visual theme provider that registers with service
+- **Material Design 3 Tokens**: Complete design system with colors, surfaces, typography, motion, and more
 
-```html
-<!-- Basic theme with auto color -->
-<schmancy-theme>
-  <div class="my-app">
-    <!-- All children inherit theme -->
-  </div>
-</schmancy-theme>
+## Properties (Synchronous)
 
-<!-- Custom color theme -->
-<schmancy-theme color="#6750A4" scheme="light">
-  <schmancy-card>
-    <h2>Themed Content</h2>
-  </schmancy-card>
-</schmancy-theme>
-
-<!-- Root-level theme -->
-<schmancy-theme color="#00695C" root>
-  <!-- Theme applies to entire document -->
-</schmancy-theme>
+```typescript
+theme.scheme        // 'dark' | 'light' | 'auto'
+theme.color         // '#6200ee'
+theme.fullscreen    // boolean
+theme.themeComponent // SchmancyThemeComponent | null
+theme.theme         // Partial<TSchmancyTheme> - Full M3 token system
 ```
 
-### Using the Theme Service
+## Observables
 
 ```typescript
-import { themeService } from '@schmancy/index'
-// Or specific import: import { themeService } from '@schmancy/theme'
+// Scheme changes
+theme.scheme$.subscribe(scheme => {
+  console.log(scheme) // 'dark' | 'light' | 'auto'
+})
 
-// Get current theme
-const theme = themeService.getCurrentTheme()
+// Resolved scheme (auto → actual) - NEVER returns 'auto'
+theme.resolvedScheme$.subscribe(scheme => {
+  console.log(scheme) // 'dark' | 'light' (automatically resolved)
+})
 
-// Set theme mode
-themeService.setMode('dark')
+// Color changes
+theme.color$.subscribe(color => {
+  console.log(color) // '#6200ee'
+})
 
-// Set primary color
-themeService.setPrimaryColor('#6750A4')
+// Fullscreen state
+theme.fullscreen$.subscribe(isFullscreen => {
+  console.log(isFullscreen) // true/false
+})
 
-// Subscribe to theme changes
-themeService.theme$.subscribe(theme => {
-  console.log('Theme updated:', theme)
+// Complete theme configuration
+theme.theme$.subscribe(themeConfig => {
+  console.log(themeConfig) // Full Material Design 3 theme object
 })
 ```
 
-## Component Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `color` | `string` | `random` | Source color for theme generation |
-| `scheme` | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme mode |
-| `root` | `boolean` | `false` | Apply theme to document root |
-| `theme` | `Partial<TSchmancyTheme>` | `{}` | Custom theme overrides |
-
-## Material Design 3 Integration
-
-The component uses Google's Material Color Utilities to generate a complete color system:
+## Methods
 
+### `setScheme(scheme)`
+Set color scheme with automatic persistence.
 ```typescript
-import { argbFromHex, themeFromSourceColor } from '@material/material-color-utilities';
-
-// Generates full MD3 color palette
-const theme = themeFromSourceColor(argbFromHex('#6750A4'));
+theme.setScheme('dark')   // Force dark
+theme.setScheme('light')  // Force light
+theme.setScheme('auto')   // Follow system preferences
 ```
 
-## Examples
-
-### App-Wide Theme
-```html
-<!-- In your app root -->
-<schmancy-theme color="#1976D2" root>
-  <schmancy-app>
-    <!-- Entire app uses this theme -->
-  </schmancy-app>
-</schmancy-theme>
+### `toggleScheme()`
+Toggle between light/dark modes.
+```typescript
+theme.toggleScheme() // light → dark → light
 ```
 
-### Component-Level Theming
-```html
-<!-- Different sections with different themes -->
-<div class="dashboard">
-  <schmancy-theme color="#00897B">
-    <section class="analytics">
-      <!-- Teal theme -->
-    </section>
-  </schmancy-theme>
-  
-  <schmancy-theme color="#E53935">
-    <section class="alerts">
-      <!-- Red theme for alerts -->
-    </section>
-  </schmancy-theme>
-</div>
-```
-
-### Dark Mode Support
-```html
-<!-- Automatic dark/light switching -->
-<schmancy-theme scheme="auto">
-  <schmancy-surface>
-    <p>Adapts to system preferences</p>
-  </schmancy-surface>
-</schmancy-theme>
-
-<!-- Force dark mode -->
-<schmancy-theme scheme="dark" color="#673AB7">
-  <schmancy-card>
-    <h3>Always Dark</h3>
-  </schmancy-card>
-</schmancy-theme>
+### `setColor(color)`
+Set primary color - automatically generates full M3 palette.
+```typescript
+theme.setColor('#6750A4') // Generates all tones and color roles
 ```
 
-### Theme Overrides
-```html
-<schmancy-theme 
-  color="#FF5722"
-  .theme="${{
-    sys: {
-      color: {
-        primary: {
-          default: '#FF5722',
-          onDefault: '#FFFFFF'
-        }
-      }
-    }
-  }}"
->
-  <schmancy-button variant="filled">
-    Custom Themed Button
-  </schmancy-button>
-</schmancy-theme>
+### `isDarkMode()`
+Observable that emits current dark mode state.
+```typescript
+theme.isDarkMode().subscribe(isDark => {
+  console.log(isDark) // true/false
+})
 ```
 
-## Generated CSS Properties
-
-The theme generates a comprehensive set of CSS custom properties:
-
-```css
-/* Primary colors */
---schmancy-sys-color-primary-default
---schmancy-sys-color-primary-onDefault
---schmancy-sys-color-primary-container
---schmancy-sys-color-primary-onContainer
+### `setFullscreen(value)`
+Control fullscreen mode for immersive experiences.
+```typescript
+theme.setFullscreen(true)  // Hide navigation
+theme.setFullscreen(false) // Show navigation
+```
 
-/* Secondary colors */
---schmancy-sys-color-secondary-default
---schmancy-sys-color-secondary-onDefault
---schmancy-sys-color-secondary-container
---schmancy-sys-color-secondary-onContainer
+### `toggleFullscreen()`
+Toggle fullscreen state.
+```typescript
+theme.toggleFullscreen()
+```
 
-/* Tertiary colors */
---schmancy-sys-color-tertiary-default
---schmancy-sys-color-tertiary-onDefault
+### `next(values)`
+Update multiple properties atomically.
+```typescript
+theme.next({
+  fullscreen: true,
+  scheme: 'dark',
+  color: '#6750A4'
+})
+```
 
-/* Surface colors */
---schmancy-sys-color-surface-default
---schmancy-sys-color-surface-on
---schmancy-sys-color-surface-container
---schmancy-sys-color-surface-containerHigh
---schmancy-sys-color-surface-containerHighest
+### `getCSSVariable(name)`
+Get computed CSS variable value.
+```typescript
+const primary = theme.getCSSVariable('color-primary')
+const elevation = theme.getCSSVariable('elevation-3')
+// Returns computed value of --schmancy-{name}
+```
 
-/* And many more... */
+### `watchCSSVariable(name)`
+Watch CSS variable changes reactively.
+```typescript
+theme.watchCSSVariable('color-primary').subscribe(color => {
+  console.log('Primary changed:', color)
+})
 ```
 
-## Auto Color Scheme Detection
+## Theme Controls Component
 
-```javascript
-// Automatically detects system preference
-const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+Ready-to-use UI component for complete theme control:
 
-// Reactive updates when system preference changes
-scheme === 'auto' && mediaQuery.addEventListener('change', updateTheme);
+```html
+<schmancy-theme-controls
+  .customColors=${['#6750A4', '#0061A4', '#006E1C']}
+></schmancy-theme-controls>
 ```
 
-## Random Color Generation
+### Features
+- **Color Picker**: Visual color selection with debounced input
+- **Scheme Toggle**: Beautiful icons for light/dark/auto modes
+- **Random Color**: Generate random theme colors
+- **Custom Presets**: Define your own color palette
 
-When no color is specified, generates a random color:
+### Implementation Example
+```typescript
+import '@schmancy/theme-controls'
+
+@customElement('my-settings')
+export class MySettings extends $LitElement() {
+  private brandColors = [
+    '#6750A4', // Brand primary
+    '#0061A4', // Brand secondary
+    '#006E1C', // Brand success
+    '#BA1B1B'  // Brand error
+  ]
 
-```javascript
-generateRandomColor() {
-  const randomColor = Math.floor(Math.random() * 16777215).toString(16);
-  return '#' + randomColor.padStart(6, '0');
+  render() {
+    return html`
+      <schmancy-surface type="container" class="p-4">
+        <schmancy-typography type="title" token="medium">
+          Theme Settings
+        </schmancy-typography>
+
+        <schmancy-theme-controls
+          .customColors=${this.brandColors}
+        ></schmancy-theme-controls>
+      </schmancy-surface>
+    `
+  }
 }
 ```
 
-## Context Provider
-
-The theme component provides its theme via Lit Context:
+## Complete Material Design 3 Token System
 
-```javascript
-import { consume } from '@lit/context';
-import { themeContext } from '@schmancy/index';
-// Or specific import: import { themeContext } from '@schmancy/index'
-// Or specific import: import { themeContext } from '@schmancy/theme';
+The theme service generates a COMPLETE M3 design system with hundreds of tokens:
 
-// In child components
-@consume({ context: themeContext })
-theme: TSchmancyTheme;
-```
+### Extended Color System
 
-## Advanced Usage
+Beyond primary/secondary/tertiary/error, the theme includes:
 
-### Nested Themes
-```html
-<schmancy-theme color="#2196F3" scheme="light">
-  <div class="main-content">
-    <!-- Blue light theme -->
-    
-    <schmancy-theme color="#F44336" scheme="dark">
-      <aside class="sidebar">
-        <!-- Red dark theme -->
-      </aside>
-    </schmancy-theme>
-  </div>
-</schmancy-theme>
-```
-
-### Dynamic Theme Changes
-```javascript
-const themeEl = document.querySelector('schmancy-theme');
-
-// Change color
-themeEl.color = '#9C27B0';
+```typescript
+// Additional semantic colors
+theme.theme.success     // Success states (#006E1C base)
+theme.theme.onSuccess    // Text on success backgrounds
+theme.theme.successContainer
+theme.theme.onSuccessContainer
 
-// Switch scheme
-themeEl.scheme = 'dark';
+theme.theme.warning     // Warning states (#FFB800 base)
+theme.theme.onWarning
+theme.theme.warningContainer
+theme.theme.onWarningContainer
 
-// Apply custom overrides
-themeEl.theme = {
-  sys: {
-    color: {
-      error: {
-        default: '#FF0000'
-      }
-    }
-  }
-};
+theme.theme.info        // Info states (#0061A4 base)
+theme.theme.onInfo
+theme.theme.infoContainer
+theme.theme.onInfoContainer
 ```
 
-## Theme Service API
+### Surface System
 
-The theme service provides programmatic control over the theme system with reactive observables for state management.
+Complete surface hierarchy with proper elevation:
 
-### Service Methods
+```typescript
+// Base surfaces
+theme.theme.surface           // Default surface
+theme.theme.surfaceDim        // Dimmed surface
+theme.theme.surfaceBright     // Bright surface
 
-#### `getCurrentTheme()`
-Returns the current theme configuration.
+// Container hierarchy
+theme.theme.surfaceContainerLowest   // Lowest elevation
+theme.theme.surfaceContainerLow      // Low elevation
+theme.theme.surfaceContainer         // Default container
+theme.theme.surfaceContainerHigh     // High elevation
+theme.theme.surfaceContainerHighest  // Highest elevation
 
-```typescript
-const theme = themeService.getCurrentTheme()
-console.log(theme.mode) // 'light' | 'dark' | 'auto'
-console.log(theme.primaryColor) // hex color string
-console.log(theme.isDark) // boolean
+// Fixed color variants (don't change with theme)
+theme.theme.primaryFixed        // Fixed primary
+theme.theme.primaryFixedDim     // Dimmed fixed primary
+theme.theme.onPrimaryFixed      // Text on fixed primary
+theme.theme.onPrimaryFixedVariant
+// (Same for secondary, tertiary)
 ```
 
-#### `setMode(mode: 'light' | 'dark' | 'auto')`
-Sets the theme mode.
+### Typography System
+
+Complete type scale with three axes:
 
 ```typescript
-// Force light mode
-themeService.setMode('light')
+// Display - Largest, for hero text
+theme.theme.typeface.scale.display.large  // 57px
+theme.theme.typeface.scale.display.medium // 45px
+theme.theme.typeface.scale.display.small  // 36px
 
-// Force dark mode
-themeService.setMode('dark')
+// Headline - For section headers
+theme.theme.typeface.scale.headline.large  // 32px
+theme.theme.typeface.scale.headline.medium // 28px
+theme.theme.typeface.scale.headline.small  // 24px
 
-// Auto mode (follows system preference)
-themeService.setMode('auto')
-```
+// Title - For cards and lists
+theme.theme.typeface.scale.title.large    // 22px
+theme.theme.typeface.scale.title.medium   // 16px
+theme.theme.typeface.scale.title.small    // 14px
 
-#### `setPrimaryColor(color: string)`
-Sets the primary color and regenerates the theme palette.
+// Body - For content
+theme.theme.typeface.scale.body.large     // 16px
+theme.theme.typeface.scale.body.medium    // 14px
+theme.theme.typeface.scale.body.small     // 12px
 
-```typescript
-themeService.setPrimaryColor('#6750A4')
+// Label - For UI elements
+theme.theme.typeface.scale.label.large    // 14px
+theme.theme.typeface.scale.label.medium   // 12px
+theme.theme.typeface.scale.label.small    // 11px
 ```
 
-#### `setTheme(theme: ThemeConfig)`
-Sets the complete theme configuration at once.
+### Motion System
 
-```typescript
-themeService.setTheme({
-  mode: 'dark',
-  primaryColor: '#00897B',
-  fontFamily: 'Roboto',
-  borderRadius: 'medium'
-})
-```
+Sophisticated animation tokens:
 
-#### `reset()`
-Resets the theme to default settings.
+```typescript
+// Easing curves
+theme.theme.motion.easing.emphasized           // Expressive motion
+theme.theme.motion.easing.emphasizedDecelerate // Enter animations
+theme.theme.motion.easing.emphasizedAccelerate // Exit animations
+theme.theme.motion.easing.standard            // Standard transitions
+theme.theme.motion.easing.standardDecelerate
+theme.theme.motion.easing.standardAccelerate
+theme.theme.motion.easing.legacy              // Backward compatibility
+theme.theme.motion.easing.linear              // Constant speed
+
+// Duration scales (in ms)
+theme.theme.motion.duration.short1    // 50ms  - Micro interactions
+theme.theme.motion.duration.short2    // 100ms
+theme.theme.motion.duration.short3    // 150ms
+theme.theme.motion.duration.short4    // 200ms
+
+theme.theme.motion.duration.medium1   // 250ms - Standard transitions
+theme.theme.motion.duration.medium2   // 300ms
+theme.theme.motion.duration.medium3   // 350ms
+theme.theme.motion.duration.medium4   // 400ms
+
+theme.theme.motion.duration.long1     // 450ms - Complex animations
+theme.theme.motion.duration.long2     // 500ms
+theme.theme.motion.duration.long3     // 550ms
+theme.theme.motion.duration.long4     // 600ms
+
+theme.theme.motion.duration.extraLong1 // 700ms - Dramatic effects
+theme.theme.motion.duration.extraLong2 // 800ms
+theme.theme.motion.duration.extraLong3 // 900ms
+theme.theme.motion.duration.extraLong4 // 1000ms
+```
+
+### Shape System
+
+Corner radius tokens:
 
 ```typescript
-themeService.reset()
+theme.theme.shape.corner.none       // 0px
+theme.theme.shape.corner.extraSmall // 4px
+theme.theme.shape.corner.small      // 8px
+theme.theme.shape.corner.medium     // 12px
+theme.theme.shape.corner.large      // 16px
+theme.theme.shape.corner.extraLarge // 28px
+theme.theme.shape.corner.full       // 9999px (pill shape)
 ```
 
-### Reactive Subscriptions
+### Elevation System
 
-The theme service exposes RxJS observables for reactive updates:
+Elevation with tinted shadows in dark mode:
 
-#### `theme$` - Complete Theme State
 ```typescript
-import { takeUntil } from 'rxjs'
+theme.theme.elevation.level0 // Flat
+theme.theme.elevation.level1 // Cards
+theme.theme.elevation.level2 // Raised cards
+theme.theme.elevation.level3 // Floating action buttons
+theme.theme.elevation.level4 // Dialogs
+theme.theme.elevation.level5 // Highest elevation
 
-themeService.theme$
-  .pipe(takeUntil(this.disconnecting))
-  .subscribe(theme => {
-    console.log('Theme updated:', theme)
-    // theme.mode, theme.primaryColor, theme.isDark, etc.
-  })
+// In dark mode, shadows are tinted with primary color
 ```
 
-#### `mode$` - Mode Changes Only
-```typescript
-themeService.mode$
-  .pipe(takeUntil(this.disconnecting))
-  .subscribe(mode => {
-    console.log('Mode changed to:', mode)
-  })
-```
+### State Layer Opacities
+
+Interaction state opacities:
 
-#### `primaryColor$` - Color Changes Only
 ```typescript
-themeService.primaryColor$
-  .pipe(takeUntil(this.disconnecting))
-  .subscribe(color => {
-    console.log('Primary color changed to:', color)
-  })
+theme.theme.states.hover.stateLayerOpacity    // 0.08
+theme.theme.states.focus.stateLayerOpacity    // 0.1
+theme.theme.states.pressed.stateLayerOpacity  // 0.1
+theme.theme.states.dragged.stateLayerOpacity  // 0.15
+theme.theme.states.disabled.containerOpacity  // 0.12
+theme.theme.states.disabled.contentOpacity    // 0.38
 ```
 
-### Using with Lit Context
+### Spacing System
 
-Components can also access theme state via context:
+4dp grid spacing:
 
 ```typescript
-import { select } from '@schmancy/index'
-// Or specific import: import { select } from '@schmancy/store'
-import { themeContext } from '@schmancy/index'
-// Or specific import: import { themeContext } from '@schmancy/theme'
-
-@customElement('my-component')
-class MyComponent extends LitElement {
-  @select(themeContext) theme!: ThemeState
-
-  render() {
-    return html`
-      <div>Current mode: ${this.theme.mode}</div>
-      <div>Is dark: ${this.theme.isDark}</div>
-      <div>Primary: ${this.theme.primaryColor}</div>
-    `
-  }
-}
+theme.theme.spacing.size.none   // 0px
+theme.theme.spacing.size.s1     // 4px
+theme.theme.spacing.size.s2     // 8px
+theme.theme.spacing.size.s3     // 12px
+theme.theme.spacing.size.s4     // 16px
+theme.theme.spacing.size.s5     // 20px
+theme.theme.spacing.size.s6     // 24px
+theme.theme.spacing.size.s7     // 28px
+theme.theme.spacing.size.s8     // 32px
+theme.theme.spacing.size.s9     // 36px
+theme.theme.spacing.size.s10    // 40px
+theme.theme.spacing.size.s11    // 44px
+theme.theme.spacing.size.s12    // 48px
 ```
 
-### Practical Examples
+## State Management & Persistence
+
+The theme service uses a **persistent context** that automatically saves to localStorage:
 
-#### Theme Toggle Button
 ```typescript
-@customElement('theme-toggle')
-export class ThemeToggle extends LitElement {
-  @state() private currentMode: 'light' | 'dark' | 'auto' = 'auto'
+// No manual localStorage code needed!
+// Settings persist automatically via context
 
-  connectedCallback() {
-    super.connectedCallback()
+// The context key 'schmancy-theme-settings' stores:
+// - scheme: 'dark' | 'light' | 'auto'
+// - color: hex color string
 
-    themeService.mode$
-      .pipe(takeUntil(this.disconnecting))
-      .subscribe(mode => {
-        this.currentMode = mode
-      })
-  }
+// Automatic restoration on page load
+// Just use the service - persistence is handled
+```
 
-  private toggleMode() {
-    const modes: Array<'light' | 'dark' | 'auto'> = ['light', 'dark', 'auto']
-    const currentIndex = modes.indexOf(this.currentMode)
-    const nextMode = modes[(currentIndex + 1) % modes.length]
-    themeService.setMode(nextMode)
-  }
+## Theme Discovery Pattern
 
-  render() {
-    const icon = this.currentMode === 'light' ? 'light_mode' :
-                 this.currentMode === 'dark' ? 'dark_mode' : 'brightness_auto'
+The service uses a sophisticated bidirectional event system:
 
-    return html`
-      <schmancy-button @click=${this.toggleMode}>
-        <schmancy-icon slot="leading">${icon}</schmancy-icon>
-        ${this.currentMode}
-      </schmancy-button>
-    `
+```typescript
+// Service dispatches discovery event
+dispatchEvent(new CustomEvent('ThemeWhereAreYou'))
+
+// Theme component responds
+dispatchEvent(new CustomEvent('ThemeHereIAm', {
+  detail: themeComponent
+}))
+
+// Automatic registration with timeout
+theme.discoverTheme().pipe(
+  timeout(1000), // 1 second timeout
+  catchError(() => of(null))
+).subscribe(component => {
+  if (component) {
+    console.log('Theme component found and registered')
   }
-}
+})
 ```
 
-#### Dynamic Color Picker
-```typescript
-@customElement('color-picker')
-export class ColorPicker extends LitElement {
-  @state() private selectedColor = '#6750A4'
+## Advanced Patterns
 
-  private colors = [
-    { name: 'Purple', value: '#6750A4' },
-    { name: 'Blue', value: '#0061A4' },
-    { name: 'Green', value: '#006E1C' },
-    { name: 'Orange', value: '#D84315' },
-    { name: 'Pink', value: '#C2185B' }
-  ]
+### Activity Logging for Debugging
+
+```typescript
+@customElement('theme-debugger')
+export class ThemeDebugger extends $LitElement() {
+  @state() private activities: string[] = []
 
   connectedCallback() {
     super.connectedCallback()
 
-    themeService.primaryColor$
-      .pipe(takeUntil(this.disconnecting))
-      .subscribe(color => {
-        this.selectedColor = color
-      })
-  }
-
-  private selectColor(color: string) {
-    themeService.setPrimaryColor(color)
+    // Log all theme changes
+    combineLatest([
+      theme.scheme$,
+      theme.color$,
+      theme.fullscreen$
+    ]).pipe(
+      tap(([scheme, color, fullscreen]) => {
+        const activity = `[${new Date().toLocaleTimeString()}] ` +
+          `Scheme: ${scheme}, Color: ${color}, Fullscreen: ${fullscreen}`
+        this.activities = [...this.activities, activity].slice(-10)
+      }),
+      takeUntil(this.disconnecting)
+    ).subscribe()
   }
 
   render() {
     return html`
-      <div class="flex gap-2 p-4">
-        ${this.colors.map(color => html`
-          <button
-            @click=${() => this.selectColor(color.value)}
-            style="background-color: ${color.value}"
-            class="w-10 h-10 rounded-full border-2 transition-all ${
-              this.selectedColor === color.value ?
-              'border-white shadow-lg scale-110' :
-              'border-transparent'
-            }"
-            title=${color.name}
-          ></button>
-        `)}
+      <div class="font-mono text-xs">
+        ${this.activities.map(a => html`<div>${a}</div>`)}
       </div>
     `
   }
 }
 ```
 
-#### Persisting Theme Preferences
-```typescript
-import { debounceTime } from 'rxjs'
+### Custom Color Presets with Categories
 
-// Save theme to localStorage
-class ThemePersistence {
-  constructor() {
-    // Load saved theme on initialization
-    this.loadTheme()
+```typescript
+interface ColorPreset {
+  category: string
+  colors: Array<{ name: string; value: string }>
+}
 
-    // Save theme changes
-    themeService.theme$
-      .pipe(
-        debounceTime(500) // Debounce to avoid excessive saves
-      )
-      .subscribe(theme => {
-        this.saveTheme(theme)
-      })
+const presets: ColorPreset[] = [
+  {
+    category: 'Brand',
+    colors: [
+      { name: 'Primary', value: '#6750A4' },
+      { name: 'Secondary', value: '#625B71' }
+    ]
+  },
+  {
+    category: 'Semantic',
+    colors: [
+      { name: 'Success', value: '#006E1C' },
+      { name: 'Warning', value: '#FFB800' },
+      { name: 'Error', value: '#BA1B1B' },
+      { name: 'Info', value: '#0061A4' }
+    ]
   }
+]
+
+// Use in component
+html`
+  ${presets.map(preset => html`
+    <div>
+      <h3>${preset.category}</h3>
+      ${preset.colors.map(color => html`
+        <button
+          style="background: ${color.value}"
+          @click=${() => theme.setColor(color.value)}
+          title=${color.name}
+        ></button>
+      `)}
+    </div>
+  `)}
+`
+```
+
+### Animated Theme Transitions
 
-  private loadTheme() {
-    const saved = localStorage.getItem('user-theme')
-    if (saved) {
-      try {
-        const theme = JSON.parse(saved)
-        themeService.setTheme(theme)
-      } catch (e) {
-        console.error('Failed to load saved theme', e)
-      }
-    }
+```typescript
+@customElement('smooth-theme')
+export class SmoothTheme extends $LitElement(css`
+  :host {
+    transition: background-color
+      var(--schmancy-motion-duration-medium2)
+      var(--schmancy-motion-easing-standard);
   }
+`) {
+  connectedCallback() {
+    super.connectedCallback()
 
-  private saveTheme(theme: ThemeState) {
-    localStorage.setItem('user-theme', JSON.stringify({
-      mode: theme.mode,
-      primaryColor: theme.primaryColor
-    }))
+    // Apply smooth transitions using motion tokens
+    theme.resolvedScheme$.pipe(
+      tap(() => {
+        // Background transitions automatically via CSS variables
+        this.style.setProperty('background-color',
+          'var(--schmancy-color-surface)')
+      }),
+      takeUntil(this.disconnecting)
+    ).subscribe()
   }
 }
-
-// Initialize once in your app
-new ThemePersistence()
 ```
 
-#### Responding to System Preferences
-```typescript
-@customElement('system-aware')
-export class SystemAware extends LitElement {
-  @state() private isDark = false
-  @state() private isAuto = false
+### Responsive Theme Based on Time
 
+```typescript
+@customElement('time-aware-theme')
+export class TimeAwareTheme extends $LitElement() {
   connectedCallback() {
     super.connectedCallback()
 
-    // Subscribe to theme changes
-    themeService.theme$
-      .pipe(takeUntil(this.disconnecting))
-      .subscribe(theme => {
-        this.isAuto = theme.mode === 'auto'
-        this.isDark = theme.isDark
-      })
-
-    // Listen to system preference changes
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    mediaQuery.addEventListener('change', (e) => {
-      if (this.isAuto) {
-        this.isDark = e.matches
-      }
-    })
-  }
-
-  render() {
-    return html`
-      <div class="p-4">
-        <p>Mode: ${this.isAuto ? 'Auto' : this.isDark ? 'Dark' : 'Light'}</p>
-        <p>System prefers: ${
-          window.matchMedia('(prefers-color-scheme: dark)').matches ?
-          'Dark' : 'Light'
-        }</p>
-      </div>
-    `
+    // Auto-switch theme based on time
+    interval(60000).pipe( // Check every minute
+      startWith(0),
+      map(() => new Date().getHours()),
+      map(hour => hour >= 6 && hour < 18 ? 'light' : 'dark'),
+      distinctUntilChanged(),
+      tap(scheme => theme.setScheme(scheme)),
+      takeUntil(this.disconnecting)
+    ).subscribe()
   }
 }
 ```
 
-## TypeScript Types
+### Theme-Aware Data Visualization
 
 ```typescript
-interface ThemeConfig {
-  mode: 'light' | 'dark' | 'auto'
-  primaryColor: string
-  fontFamily?: string
-  borderRadius?: 'none' | 'small' | 'medium' | 'large' | 'full'
-  contrast?: 'standard' | 'medium' | 'high'
-}
+@customElement('theme-chart')
+export class ThemeChart extends $LitElement() {
+  @state() private chartColors = {
+    primary: '',
+    surface: '',
+    error: ''
+  }
 
-interface ThemeState extends ThemeConfig {
-  isDark: boolean
-  isAuto: boolean
-  systemPreference: 'light' | 'dark'
-  theme: TSchmancyTheme // Full Material Design 3 theme object
-}
+  connectedCallback() {
+    super.connectedCallback()
 
-interface ThemeService {
-  // Observables
-  theme$: Observable<ThemeState>
-  mode$: Observable<'light' | 'dark' | 'auto'>
-  primaryColor$: Observable<string>
-
-  // Methods
-  getCurrentTheme(): ThemeState
-  setMode(mode: 'light' | 'dark' | 'auto'): void
-  setPrimaryColor(color: string): void
-  setTheme(theme: ThemeConfig): void
-  reset(): void
+    // Update chart colors when theme changes
+    theme.theme$.pipe(
+      tap(themeData => {
+        this.chartColors = {
+          primary: themeData.primary,
+          surface: themeData.surface,
+          error: themeData.error
+        }
+        this.updateChart()
+      }),
+      takeUntil(this.disconnecting)
+    ).subscribe()
+  }
+
+  private updateChart() {
+    // Use theme colors in charts/visualizations
+    // Colors automatically adapt to light/dark mode
+  }
 }
 ```
 
-## Best Practices
-
-1. **Root Theme**: Use one root theme for consistency
-2. **Color Choice**: Pick colors with good contrast ratios
-3. **Scheme Handling**: Respect user preferences with 'auto'
-4. **Performance**: Limit nested themes, debounce theme changes
-5. **Accessibility**: Test themes with contrast checkers
-6. **Persistence**: Save user preferences to localStorage
-7. **Cleanup**: Always use `takeUntil(this.disconnecting)` in components
-8. **Type Safety**: Use provided TypeScript interfaces
+## Complete CSS Variable Reference
 
-## CSS Variables Reference
-
-### Using Theme Variables in Styles
+All tokens are available as CSS variables with `--schmancy-` prefix:
 
+### Color Variables
+```css
+/* Core colors */
+--schmancy-color-primary
+--schmancy-color-onPrimary
+--schmancy-color-primaryContainer
+--schmancy-color-onPrimaryContainer
+
+--schmancy-color-secondary
+--schmancy-color-onSecondary
+--schmancy-color-secondaryContainer
+--schmancy-color-onSecondaryContainer
+
+--schmancy-color-tertiary
+--schmancy-color-onTertiary
+--schmancy-color-tertiaryContainer
+--schmancy-color-onTertiaryContainer
+
+--schmancy-color-error
+--schmancy-color-onError
+--schmancy-color-errorContainer
+--schmancy-color-onErrorContainer
+
+/* Extended semantic colors */
+--schmancy-color-success
+--schmancy-color-onSuccess
+--schmancy-color-successContainer
+--schmancy-color-onSuccessContainer
+
+--schmancy-color-warning
+--schmancy-color-onWarning
+--schmancy-color-warningContainer
+--schmancy-color-onWarningContainer
+
+--schmancy-color-info
+--schmancy-color-onInfo
+--schmancy-color-infoContainer
+--schmancy-color-onInfoContainer
+
+/* Surface hierarchy */
+--schmancy-color-surface
+--schmancy-color-onSurface
+--schmancy-color-surfaceVariant
+--schmancy-color-onSurfaceVariant
+--schmancy-color-surfaceDim
+--schmancy-color-surfaceBright
+--schmancy-color-surfaceContainerLowest
+--schmancy-color-surfaceContainerLow
+--schmancy-color-surfaceContainer
+--schmancy-color-surfaceContainerHigh
+--schmancy-color-surfaceContainerHighest
+
+/* Fixed variants */
+--schmancy-color-primaryFixed
+--schmancy-color-primaryFixedDim
+--schmancy-color-onPrimaryFixed
+--schmancy-color-onPrimaryFixedVariant
+/* (Same pattern for secondary, tertiary) */
+
+/* Other */
+--schmancy-color-outline
+--schmancy-color-outlineVariant
+--schmancy-color-shadow
+--schmancy-color-scrim
+--schmancy-color-inverseSurface
+--schmancy-color-inverseOnSurface
+--schmancy-color-inversePrimary
+```
+
+### Typography Variables
 ```css
-/* Always use CSS variables for theme-aware styling */
-.my-component {
-  /* Backgrounds */
-  background: var(--schmancy-sys-color-surface-default);
+/* Display scale */
+--schmancy-typeface-scale-display-large
+--schmancy-typeface-scale-display-medium
+--schmancy-typeface-scale-display-small
 
-  /* Text colors */
-  color: var(--schmancy-sys-color-surface-on);
+/* Headline scale */
+--schmancy-typeface-scale-headline-large
+--schmancy-typeface-scale-headline-medium
+--schmancy-typeface-scale-headline-small
 
-  /* Borders */
-  border: 1px solid var(--schmancy-sys-color-outline);
+/* Title scale */
+--schmancy-typeface-scale-title-large
+--schmancy-typeface-scale-title-medium
+--schmancy-typeface-scale-title-small
 
-  /* Elevation/shadows */
-  box-shadow: var(--schmancy-sys-elevation-1);
-}
+/* Body scale */
+--schmancy-typeface-scale-body-large
+--schmancy-typeface-scale-body-medium
+--schmancy-typeface-scale-body-small
 
-/* Semantic color usage */
-.primary-action {
-  background: var(--schmancy-sys-color-primary-default);
-  color: var(--schmancy-sys-color-primary-onDefault);
-}
-
-.error-message {
-  background: var(--schmancy-sys-color-error-container);
-  color: var(--schmancy-sys-color-error-onContainer);
-}
+/* Label scale */
+--schmancy-typeface-scale-label-large
+--schmancy-typeface-scale-label-medium
+--schmancy-typeface-scale-label-small
 ```
 
-### Complete Variable List
-
-#### Primary Colors
-- `--schmancy-sys-color-primary-default`
-- `--schmancy-sys-color-primary-onDefault`
-- `--schmancy-sys-color-primary-container`
-- `--schmancy-sys-color-primary-onContainer`
-
-#### Secondary Colors
-- `--schmancy-sys-color-secondary-default`
-- `--schmancy-sys-color-secondary-onDefault`
-- `--schmancy-sys-color-secondary-container`
-- `--schmancy-sys-color-secondary-onContainer`
-
-#### Tertiary Colors
-- `--schmancy-sys-color-tertiary-default`
-- `--schmancy-sys-color-tertiary-onDefault`
-- `--schmancy-sys-color-tertiary-container`
-- `--schmancy-sys-color-tertiary-onContainer`
-
-#### Error Colors
-- `--schmancy-sys-color-error-default`
-- `--schmancy-sys-color-error-onDefault`
-- `--schmancy-sys-color-error-container`
-- `--schmancy-sys-color-error-onContainer`
-
-#### Surface Colors
-- `--schmancy-sys-color-surface-default`
-- `--schmancy-sys-color-surface-on`
-- `--schmancy-sys-color-surface-onVariant`
-- `--schmancy-sys-color-surface-container`
-- `--schmancy-sys-color-surface-containerLow`
-- `--schmancy-sys-color-surface-containerHigh`
-- `--schmancy-sys-color-surface-containerHighest`
-
-#### Background & Outline
-- `--schmancy-sys-color-background-default`
-- `--schmancy-sys-color-background-on`
-- `--schmancy-sys-color-outline-default`
-- `--schmancy-sys-color-outline-variant`
-
-## Migration Guide
+### Motion Variables
+```css
+/* Easing curves */
+--schmancy-motion-easing-emphasized
+--schmancy-motion-easing-emphasizedDecelerate
+--schmancy-motion-easing-emphasizedAccelerate
+--schmancy-motion-easing-standard
+--schmancy-motion-easing-standardDecelerate
+--schmancy-motion-easing-standardAccelerate
+--schmancy-motion-easing-legacy
+--schmancy-motion-easing-linear
+
+/* Duration scales */
+--schmancy-motion-duration-short1    /* 50ms */
+--schmancy-motion-duration-short2    /* 100ms */
+--schmancy-motion-duration-short3    /* 150ms */
+--schmancy-motion-duration-short4    /* 200ms */
+
+--schmancy-motion-duration-medium1   /* 250ms */
+--schmancy-motion-duration-medium2   /* 300ms */
+--schmancy-motion-duration-medium3   /* 350ms */
+--schmancy-motion-duration-medium4   /* 400ms */
+
+--schmancy-motion-duration-long1     /* 450ms */
+--schmancy-motion-duration-long2     /* 500ms */
+--schmancy-motion-duration-long3     /* 550ms */
+--schmancy-motion-duration-long4     /* 600ms */
+
+--schmancy-motion-duration-extraLong1 /* 700ms */
+--schmancy-motion-duration-extraLong2 /* 800ms */
+--schmancy-motion-duration-extraLong3 /* 900ms */
+--schmancy-motion-duration-extraLong4 /* 1000ms */
+```
+
+### Shape Variables
+```css
+--schmancy-shape-corner-none       /* 0px */
+--schmancy-shape-corner-extraSmall /* 4px */
+--schmancy-shape-corner-small      /* 8px */
+--schmancy-shape-corner-medium     /* 12px */
+--schmancy-shape-corner-large      /* 16px */
+--schmancy-shape-corner-extraLarge /* 28px */
+--schmancy-shape-corner-full       /* 9999px */
+```
 
-### From Hardcoded Colors
+### Elevation Variables
+```css
+--schmancy-elevation-level0
+--schmancy-elevation-level1
+--schmancy-elevation-level2
+--schmancy-elevation-level3
+--schmancy-elevation-level4
+--schmancy-elevation-level5
+```
 
+### State Variables
 ```css
-/* Before - Hardcoded colors */
-.card {
-  background: #ffffff;
-  color: #000000;
-  border: 1px solid #e0e0e0;
-}
+--schmancy-states-hover-stateLayerOpacity      /* 0.08 */
+--schmancy-states-focus-stateLayerOpacity      /* 0.1 */
+--schmancy-states-pressed-stateLayerOpacity    /* 0.1 */
+--schmancy-states-dragged-stateLayerOpacity    /* 0.15 */
+--schmancy-states-disabled-containerOpacity    /* 0.12 */
+--schmancy-states-disabled-contentOpacity      /* 0.38 */
+```
 
-/* After - Theme-aware */
-.card {
-  background: var(--schmancy-sys-color-surface-default);
-  color: var(--schmancy-sys-color-surface-on);
-  border: 1px solid var(--schmancy-sys-color-outline-variant);
-}
+### Spacing Variables
+```css
+--schmancy-spacing-size-none  /* 0px */
+--schmancy-spacing-size-s1    /* 4px */
+--schmancy-spacing-size-s2    /* 8px */
+--schmancy-spacing-size-s3    /* 12px */
+--schmancy-spacing-size-s4    /* 16px */
+--schmancy-spacing-size-s5    /* 20px */
+--schmancy-spacing-size-s6    /* 24px */
+--schmancy-spacing-size-s7    /* 28px */
+--schmancy-spacing-size-s8    /* 32px */
+--schmancy-spacing-size-s9    /* 36px */
+--schmancy-spacing-size-s10   /* 40px */
+--schmancy-spacing-size-s11   /* 44px */
+--schmancy-spacing-size-s12   /* 48px */
 ```
 
-### From CSS-in-JS
+## Fullscreen Integration
+
+Navigation components automatically respond to fullscreen:
 
 ```typescript
-// Before - CSS-in-JS theme object
-const styles = {
-  card: {
-    backgroundColor: theme.colors.background,
-    color: theme.colors.text
-  }
-}
+// Enter fullscreen (hides navigation)
+theme.setFullscreen(true)
 
-// After - CSS with variables
-static styles = css`
-  .card {
-    background: var(--schmancy-sys-color-surface-default);
-    color: var(--schmancy-sys-color-surface-on);
-  }
-`
+// Custom component integration
+fromEvent(window, 'fullscreen').pipe(
+  tap((e: CustomEvent) => {
+    this.hidden = e.detail
+  }),
+  takeUntil(this.disconnecting)
+).subscribe()
 ```
 
-### From Manual Dark Mode
-
-```typescript
-// Before - Manual dark mode handling
-@state() isDark = false
+## System Preference Detection
 
-render() {
-  return html`
-    <div class=${this.isDark ? 'dark-theme' : 'light-theme'}>
-      <!-- content -->
-    </div>
-  `
-}
+Auto mode follows system preferences with automatic updates:
 
-// After - Automatic with theme service
-render() {
-  // CSS variables automatically update
-  return html`
-    <div>
-      <!-- content automatically themed -->
-    </div>
-  `
-}
+```typescript
+// Set to auto - follows system preference
+theme.setScheme('auto')
+
+// resolvedScheme$ automatically updates when system changes
+// Uses MediaQueryList with listeners for real-time updates
+theme.resolvedScheme$.subscribe(scheme => {
+  // Always 'dark' or 'light', never 'auto'
+  // Updates immediately when user changes OS theme
+})
 ```
 
-## Advanced Patterns
+## Best Practices
 
-### Theme-Aware Component
+1. **Always use observables** for reactive updates
+2. **Prefer `resolvedScheme$`** over `scheme$` for UI logic (never returns 'auto')
+3. **Use `next()` method** for batch updates to avoid multiple emissions
+4. **Let theme persist automatically** - no manual localStorage needed
+5. **Use motion tokens** for consistent animations across the app
+6. **Leverage extended colors** (success, warning, info) for semantic meaning
+7. **Use surface hierarchy** for proper elevation and depth
+8. **Apply state opacities** for consistent interaction feedback
+9. **Call `super.connectedCallback()`** when subscribing to observables
+10. **Use `takeUntil(this.disconnecting)`** for proper cleanup
 
-```typescript
-@customElement('themed-card')
-export class ThemedCard extends LitElement {
-  @select(themeContext) theme!: ThemeState
+## Common Patterns
 
-  static styles = css`
-    :host {
-      display: block;
-      background: var(--schmancy-sys-color-surface-container);
-      color: var(--schmancy-sys-color-surface-on);
-      border-radius: var(--schmancy-sys-shape-corner-medium);
-      padding: 16px;
-      transition: all 200ms ease-in-out;
-    }
+### Complete Theme Toggle Component
+```typescript
+@customElement('advanced-theme-toggle')
+export class AdvancedThemeToggle extends $LitElement() {
+  @state() private resolvedScheme: 'dark' | 'light' = 'light'
+  @state() private actualScheme: string = 'auto'
 
-    :host([elevated]) {
-      box-shadow: var(--schmancy-sys-elevation-2);
-    }
+  connectedCallback() {
+    super.connectedCallback()
 
-    .header {
-      color: var(--schmancy-sys-color-primary-default);
-      font-size: var(--schmancy-sys-typescale-headline-small-size);
-    }
-  `
+    // Track both actual and resolved scheme
+    combineLatest([
+      theme.scheme$,
+      theme.resolvedScheme$
+    ]).pipe(
+      tap(([scheme, resolved]) => {
+        this.actualScheme = scheme
+        this.resolvedScheme = resolved
+      }),
+      takeUntil(this.disconnecting)
+    ).subscribe()
+  }
 
   render() {
     return html`
-      <div class="header">
-        <slot name="header"></slot>
+      <div class="flex gap-2">
+        <button
+          @click=${() => theme.setScheme('light')}
+          class=${this.actualScheme === 'light' ? 'active' : ''}
+        >
+          ☀️ Light
+        </button>
+        <button
+          @click=${() => theme.setScheme('dark')}
+          class=${this.actualScheme === 'dark' ? 'active' : ''}
+        >
+          🌙 Dark
+        </button>
+        <button
+          @click=${() => theme.setScheme('auto')}
+          class=${this.actualScheme === 'auto' ? 'active' : ''}
+        >
+          🔄 Auto (${this.resolvedScheme})
+        </button>
       </div>
-      <slot></slot>
     `
   }
 }
 ```
 
-### Theme Presets
-
-```typescript
-class ThemePresets {
-  static readonly presets = {
-    corporate: {
-      mode: 'light' as const,
-      primaryColor: '#003D82',
-      fontFamily: 'Inter, system-ui',
-      borderRadius: 'small'
-    },
-
-    vibrant: {
-      mode: 'auto' as const,
-      primaryColor: '#FF6B6B',
-      fontFamily: 'Poppins, sans-serif',
-      borderRadius: 'large'
-    },
-
-    minimal: {
-      mode: 'auto' as const,
-      primaryColor: '#2C3E50',
-      fontFamily: 'system-ui',
-      borderRadius: 'none'
-    },
-
-    accessibility: {
-      mode: 'light' as const,
-      primaryColor: '#0055AA',
-      contrast: 'high',
-      fontFamily: 'Arial, sans-serif',
-      borderRadius: 'medium'
-    }
+### Fullscreen Video Player
+```typescript
+@customElement('video-player')
+export class VideoPlayer extends $LitElement() {
+  private videoRef = createRef<HTMLVideoElement>()
+
+  private enterFullscreen() {
+    theme.setFullscreen(true)
+    this.videoRef.value?.requestFullscreen()
   }
 
-  static apply(presetName: keyof typeof ThemePresets.presets) {
-    const preset = ThemePresets.presets[presetName]
-    themeService.setTheme(preset)
+  private exitFullscreen() {
+    theme.setFullscreen(false)
+    document.exitFullscreen()
   }
-}
 
-// Usage
-ThemePresets.apply('corporate')
+  render() {
+    return html`
+      <video ${ref(this.videoRef)}>
+        <!-- Video content -->
+      </video>
+    `
+  }
+}
 ```
 
-### Multi-Brand Support
-
+### Dynamic Motion Timing
 ```typescript
-class BrandManager {
-  private brands = {
-    main: {
-      primaryColor: '#6750A4',
-      logo: '/assets/main-logo.svg'
-    },
-    partner: {
-      primaryColor: '#00897B',
-      logo: '/assets/partner-logo.svg'
-    }
-  }
+@customElement('animated-component')
+export class AnimatedComponent extends $LitElement() {
+  @state() private isExpanded = false
 
-  switchBrand(brandKey: keyof typeof this.brands) {
-    const brand = this.brands[brandKey]
-    themeService.setPrimaryColor(brand.primaryColor)
-    // Update logo and other brand assets
-    this.updateBrandAssets(brand)
-  }
+  render() {
+    return html`
+      <style>
+        .panel {
+          transition: height
+            var(--schmancy-motion-duration-medium2)
+            var(--schmancy-motion-easing-emphasized);
+        }
+
+        .fade-in {
+          animation: fadeIn
+            var(--schmancy-motion-duration-short3)
+            var(--schmancy-motion-easing-emphasizedDecelerate);
+        }
 
-  private updateBrandAssets(brand: any) {
-    // Update logos, fonts, etc.
+        @keyframes fadeIn {
+          from { opacity: 0; }
+          to { opacity: 1; }
+        }
+      </style>
+
+      <div class="panel ${this.isExpanded ? 'expanded' : ''}">
+        <!-- Content with smooth animations -->
+      </div>
+    `
   }
 }
 ```
 
-## Testing Themes
+## Integration with Theme Component
 
-```typescript
-// Test component in different themes
-describe('ThemedComponent', () => {
-  beforeEach(() => {
-    themeService.reset()
-  })
+The service works bidirectionally with `<schmancy-theme>` component:
 
-  it('renders correctly in light mode', async () => {
-    themeService.setMode('light')
-    const el = await fixture(html`<themed-component></themed-component>`)
-    // Test light mode rendering
-  })
-
-  it('renders correctly in dark mode', async () => {
-    themeService.setMode('dark')
-    const el = await fixture(html`<themed-component></themed-component>`)
-    // Test dark mode rendering
-  })
+```html
+<schmancy-theme color="#6750A4" scheme="auto">
+  <!-- All children have access to theme tokens -->
+</schmancy-theme>
+```
 
-  it('responds to theme changes', async () => {
-    const el = await fixture(html`<themed-component></themed-component>`)
+Component automatically:
+- Registers with service via discovery events
+- Syncs state bidirectionally
+- Generates full M3 token system
+- Updates CSS variables in real-time
+- Persists settings to localStorage
 
-    themeService.setPrimaryColor('#FF5722')
-    await el.updateComplete
+## Error Handling
 
-    // Verify component updated with new theme
+```typescript
+// Graceful fallback when theme component is missing
+theme.discoverTheme().pipe(
+  timeout(1000),
+  catchError(() => {
+    console.warn('Theme component not found, using defaults')
+    return of(null)
   })
-})
+).subscribe()
+
+// Validate color input
+const isValidHex = (color: string) => /^#[0-9A-F]{6}$/i.test(color)
+
+if (isValidHex(newColor)) {
+  theme.setColor(newColor)
+} else {
+  console.error('Invalid color format')
+}
 ```
 
-## Performance Optimization
+## Performance Considerations
 
-### Debouncing Theme Changes
+1. **Token Generation**: Full M3 theme is generated once per color change
+2. **CSS Variables**: Updated atomically via `adoptedStyleSheets`
+3. **Persistence**: Debounced writes to localStorage (via context)
+4. **Discovery**: One-time discovery with 1s timeout
+5. **MediaQuery**: Single listener for system preference changes
+6. **Observables**: Multicast for efficient subscriptions
 
+## Migration Guide
+
+From manual theme management:
 ```typescript
-import { debounceTime, distinctUntilChanged } from 'rxjs'
+// Old way
+localStorage.setItem('theme', 'dark')
+document.body.classList.add('dark-theme')
 
-themeService.theme$
-  .pipe(
-    debounceTime(300), // Debounce rapid changes
-    distinctUntilChanged((a, b) =>
-      a.primaryColor === b.primaryColor &&
-      a.mode === b.mode
-    ),
-    takeUntil(this.disconnecting)
-  )
-  .subscribe(theme => {
-    // Handle theme changes
-  })
+// New way
+theme.setScheme('dark') // Automatic persistence & styling
 ```
 
-### Lazy Loading Theme Components
-
+From custom CSS variables:
 ```typescript
-// Only load theme UI when needed
-async function openThemeSettings() {
-  const { ThemeSettings } = await import('./theme-settings')
-  const settings = new ThemeSettings()
-  document.body.appendChild(settings)
+// Old way
+:root {
+  --primary: #6750A4;
 }
-```
-
-## Troubleshooting
 
-### Common Issues
-
-1. **Theme not applying**: Ensure theme component or service is initialized at app root
-2. **CSS variables undefined**: Check that schmancy-theme is imported before use
-3. **Dark mode not working**: Verify `scheme="auto"` and system preferences
-4. **Performance issues**: Use debouncing and avoid excessive nesting
-5. **Colors not updating**: Ensure using CSS variables, not hardcoded values
-
-## Related Components
+// New way - Full M3 system generated
+theme.setColor('#6750A4') // Generates 100+ tokens
+```
 
-- [Theme Button](./theme-button.md) - Theme switcher
-- [Surface](./surface.md) - Themed containers
-- [Button](./button.md) - Themed interactions
-- [Card](./card.md) - Themed content
+## Summary
 
-## Use Cases
+The theme service provides a complete Material Design 3 implementation with:
+- 🎨 **Extended color system** with semantic colors
+- 📐 **Complete surface hierarchy** for proper elevation
+- 🔤 **Full typography scale** across 5 categories
+- 🎬 **Sophisticated motion system** with easing and duration
+- 🔲 **Shape tokens** for consistent corner radii
+- 💾 **Automatic persistence** via context
+- 🔍 **Smart discovery** with bidirectional events
+- 🌓 **System preference detection** with real-time updates
+- 🎯 **Ready-to-use controls** component
+- ⚡ **Reactive observables** for all properties
 
-1. **App Theming**: Consistent app-wide styling
-2. **White-Label**: Dynamic branding for multiple clients
-3. **User Preferences**: Personalized themes saved per user
-4. **Section Theming**: Different themes for app sections
-5. **A/B Testing**: Theme variations for testing
-6. **Accessibility**: High contrast modes for better readability
-7. **Dark Mode**: Automatic or manual dark mode support
-8. **Brand Compliance**: Enforce brand colors across components
+Use the theme service as your single source of truth for all design tokens and theming needs.