@mhmo91/schmancy 0.5.36 → 0.5.38

package/ai/theme.md

@@ -1,6 +1,6 @@
 # Theme Service
 
-Centralized theme management with reactive observables for color schemes, fullscreen mode, and Material Design 3 integration.
+Comprehensive Material Design 3 theme management with reactive observables, automatic persistence, and a complete token system for colors, typography, motion, and more.
 
 ## Import
 
@@ -16,6 +16,7 @@ import { theme } from '@schmancy/theme'
 - **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
 
 ## Properties (Synchronous)
 
@@ -24,7 +25,7 @@ theme.scheme        // 'dark' | 'light' | 'auto'
 theme.color         // '#6200ee'
 theme.fullscreen    // boolean
 theme.themeComponent // SchmancyThemeComponent | null
-theme.theme         // Partial<TSchmancyTheme>
+theme.theme         // Partial<TSchmancyTheme> - Full M3 token system
 ```
 
 ## Observables
@@ -35,9 +36,9 @@ theme.scheme$.subscribe(scheme => {
   console.log(scheme) // 'dark' | 'light' | 'auto'
 })
 
-// Resolved scheme (auto → actual)
+// Resolved scheme (auto → actual) - NEVER returns 'auto'
 theme.resolvedScheme$.subscribe(scheme => {
-  console.log(scheme) // 'dark' | 'light' (never 'auto')
+  console.log(scheme) // 'dark' | 'light' (automatically resolved)
 })
 
 // Color changes
@@ -50,20 +51,20 @@ theme.fullscreen$.subscribe(isFullscreen => {
   console.log(isFullscreen) // true/false
 })
 
-// Theme configuration
+// Complete theme configuration
 theme.theme$.subscribe(themeConfig => {
-  console.log(themeConfig) // Material Design 3 theme object
+  console.log(themeConfig) // Full Material Design 3 theme object
 })
 ```
 
 ## Methods
 
 ### `setScheme(scheme)`
-Set color scheme.
+Set color scheme with automatic persistence.
 ```typescript
 theme.setScheme('dark')   // Force dark
 theme.setScheme('light')  // Force light
-theme.setScheme('auto')   // Follow system
+theme.setScheme('auto')   // Follow system preferences
 ```
 
 ### `toggleScheme()`
@@ -73,13 +74,13 @@ theme.toggleScheme() // light → dark → light
 ```
 
 ### `setColor(color)`
-Set primary color.
+Set primary color - automatically generates full M3 palette.
 ```typescript
-theme.setColor('#6750A4')
+theme.setColor('#6750A4') // Generates all tones and color roles
 ```
 
 ### `isDarkMode()`
-Check if currently in dark mode.
+Observable that emits current dark mode state.
 ```typescript
 theme.isDarkMode().subscribe(isDark => {
   console.log(isDark) // true/false
@@ -87,7 +88,7 @@ theme.isDarkMode().subscribe(isDark => {
 ```
 
 ### `setFullscreen(value)`
-Control fullscreen mode.
+Control fullscreen mode for immersive experiences.
 ```typescript
 theme.setFullscreen(true)  // Hide navigation
 theme.setFullscreen(false) // Show navigation
@@ -100,7 +101,7 @@ theme.toggleFullscreen()
 ```
 
 ### `next(values)`
-Update multiple properties at once.
+Update multiple properties atomically.
 ```typescript
 theme.next({
   fullscreen: true,
@@ -110,243 +111,876 @@ theme.next({
 ```
 
 ### `getCSSVariable(name)`
-Get CSS variable value.
+Get computed CSS variable value.
 ```typescript
 const primary = theme.getCSSVariable('color-primary')
-// Returns computed value of --schmancy-color-primary
+const elevation = theme.getCSSVariable('elevation-3')
+// Returns computed value of --schmancy-{name}
 ```
 
 ### `watchCSSVariable(name)`
-Watch CSS variable changes.
+Watch CSS variable changes reactively.
 ```typescript
 theme.watchCSSVariable('color-primary').subscribe(color => {
   console.log('Primary changed:', color)
 })
 ```
 
-## Fullscreen Integration
+## Theme Controls Component
 
-Navigation components automatically respond to fullscreen:
+Ready-to-use UI component for complete theme control:
 
-```typescript
-// Enter fullscreen (hides navigation)
-theme.setFullscreen(true)
-
-// Custom component integration
-fromEvent(window, 'fullscreen').pipe(
-  tap((e: CustomEvent) => {
-    this.hidden = e.detail
-  }),
-  takeUntil(this.disconnecting)
-).subscribe()
+```html
+<schmancy-theme-controls
+  .customColors=${['#6750A4', '#0061A4', '#006E1C']}
+></schmancy-theme-controls>
 ```
 
-## Component Usage
+### 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
 
-### Basic Theme Controls
+### Implementation Example
 ```typescript
-@customElement('theme-controls')
-export class ThemeControls extends $LitElement() {
-  @state() private currentScheme = theme.scheme
-  @state() private isFullscreen = theme.fullscreen
+import '@schmancy/theme-controls'
 
-  connectedCallback() {
-    super.connectedCallback()
-
-    theme.scheme$.pipe(
-      tap(scheme => this.currentScheme = scheme),
-      takeUntil(this.disconnecting)
-    ).subscribe()
-
-    theme.fullscreen$.pipe(
-      tap(fullscreen => this.isFullscreen = fullscreen),
-      takeUntil(this.disconnecting)
-    ).subscribe()
-  }
+@customElement('my-settings')
+export class MySettings extends $LitElement() {
+  private brandColors = [
+    '#6750A4', // Brand primary
+    '#0061A4', // Brand secondary
+    '#006E1C', // Brand success
+    '#BA1B1B'  // Brand error
+  ]
 
   render() {
     return html`
-      <button @click=${() => theme.toggleScheme()}>
-        ${this.currentScheme}
-      </button>
-      <button @click=${() => theme.toggleFullscreen()}>
-        ${this.isFullscreen ? 'Exit' : 'Enter'} Fullscreen
-      </button>
+      <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>
     `
   }
 }
 ```
 
-### Theme-Aware Component
+## Complete Material Design 3 Token System
+
+The theme service generates a COMPLETE M3 design system with hundreds of tokens:
+
+### Extended Color System
+
+Beyond primary/secondary/tertiary/error, the theme includes:
+
+```typescript
+// Additional semantic colors
+theme.theme.success     // Success states (#006E1C base)
+theme.theme.onSuccess    // Text on success backgrounds
+theme.theme.successContainer
+theme.theme.onSuccessContainer
+
+theme.theme.warning     // Warning states (#FFB800 base)
+theme.theme.onWarning
+theme.theme.warningContainer
+theme.theme.onWarningContainer
+
+theme.theme.info        // Info states (#0061A4 base)
+theme.theme.onInfo
+theme.theme.infoContainer
+theme.theme.onInfoContainer
+```
+
+### Surface System
+
+Complete surface hierarchy with proper elevation:
+
+```typescript
+// Base surfaces
+theme.theme.surface           // Default surface
+theme.theme.surfaceDim        // Dimmed surface
+theme.theme.surfaceBright     // Bright surface
+
+// 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
+
+// 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)
+```
+
+### Typography System
+
+Complete type scale with three axes:
+
 ```typescript
-@customElement('theme-aware')
-export class ThemeAware extends $LitElement() {
-  @state() private isDark = false
+// 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
+
+// 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
+
+// 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
+
+// Body - For content
+theme.theme.typeface.scale.body.large     // 16px
+theme.theme.typeface.scale.body.medium    // 14px
+theme.theme.typeface.scale.body.small     // 12px
+
+// 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
+```
+
+### Motion System
+
+Sophisticated animation tokens:
+
+```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
+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)
+```
+
+### Elevation System
+
+Elevation with tinted shadows in dark mode:
+
+```typescript
+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
+
+// In dark mode, shadows are tinted with primary color
+```
+
+### State Layer Opacities
+
+Interaction state opacities:
+
+```typescript
+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
+```
+
+### Spacing System
+
+4dp grid spacing:
+
+```typescript
+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
+```
+
+## State Management & Persistence
+
+The theme service uses a **persistent context** that automatically saves to localStorage:
+
+```typescript
+// No manual localStorage code needed!
+// Settings persist automatically via context
+
+// The context key 'schmancy-theme-settings' stores:
+// - scheme: 'dark' | 'light' | 'auto'
+// - color: hex color string
+
+// Automatic restoration on page load
+// Just use the service - persistence is handled
+```
+
+## Theme Discovery Pattern
+
+The service uses a sophisticated bidirectional event system:
+
+```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')
+  }
+})
+```
+
+## Advanced Patterns
+
+### Activity Logging for Debugging
+
+```typescript
+@customElement('theme-debugger')
+export class ThemeDebugger extends $LitElement() {
+  @state() private activities: string[] = []
 
   connectedCallback() {
     super.connectedCallback()
 
-    theme.isDarkMode().pipe(
-      tap(isDark => this.isDark = isDark),
+    // 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=${this.isDark ? 'dark-theme' : 'light-theme'}>
-        Content adapts to theme
+      <div class="font-mono text-xs">
+        ${this.activities.map(a => html`<div>${a}</div>`)}
       </div>
     `
   }
 }
 ```
 
-### Color Picker
+### Custom Color Presets with Categories
+
 ```typescript
-@customElement('color-picker')
-export class ColorPicker extends $LitElement() {
-  private colors = ['#6750A4', '#0061A4', '#006E1C']
+interface ColorPreset {
+  category: string
+  colors: Array<{ name: string; value: string }>
+}
 
-  render() {
-    return html`
-      ${this.colors.map(color => html`
+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}"
-          @click=${() => theme.setColor(color)}
+          style="background: ${color.value}"
+          @click=${() => theme.setColor(color.value)}
+          title=${color.name}
         ></button>
       `)}
-    `
+    </div>
+  `)}
+`
+```
+
+### Animated Theme Transitions
+
+```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()
+
+    // 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()
   }
 }
 ```
 
-## System Preference Detection
-
-Auto mode follows system preferences:
+### Responsive Theme Based on Time
 
 ```typescript
-// Internally handles MediaQueryList
-theme.setScheme('auto')
+@customElement('time-aware-theme')
+export class TimeAwareTheme extends $LitElement() {
+  connectedCallback() {
+    super.connectedCallback()
 
-// Resolved scheme updates automatically
-theme.resolvedScheme$.subscribe(scheme => {
-  // 'dark' or 'light' based on system
-})
+    // 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()
+  }
+}
 ```
 
-## Theme Discovery
-
-Service automatically discovers theme components:
+### Theme-Aware Data Visualization
 
 ```typescript
-// Manual discovery (rarely needed)
-theme.discoverTheme().subscribe(component => {
-  if (component) {
-    console.log('Found theme component')
+@customElement('theme-chart')
+export class ThemeChart extends $LitElement() {
+  @state() private chartColors = {
+    primary: '',
+    surface: '',
+    error: ''
   }
-})
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    // 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
+  }
+}
 ```
 
-## CSS Variables
+## Complete CSS Variable Reference
+
+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
+```
 
-Access Material Design 3 variables:
+### Typography Variables
+```css
+/* Display scale */
+--schmancy-typeface-scale-display-large
+--schmancy-typeface-scale-display-medium
+--schmancy-typeface-scale-display-small
+
+/* Headline scale */
+--schmancy-typeface-scale-headline-large
+--schmancy-typeface-scale-headline-medium
+--schmancy-typeface-scale-headline-small
+
+/* Title scale */
+--schmancy-typeface-scale-title-large
+--schmancy-typeface-scale-title-medium
+--schmancy-typeface-scale-title-small
+
+/* Body scale */
+--schmancy-typeface-scale-body-large
+--schmancy-typeface-scale-body-medium
+--schmancy-typeface-scale-body-small
+
+/* Label scale */
+--schmancy-typeface-scale-label-large
+--schmancy-typeface-scale-label-medium
+--schmancy-typeface-scale-label-small
+```
 
-```typescript
-// Get current value
-const surface = theme.getCSSVariable('color-surface')
+### 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 */
+```
 
-// Watch for changes
-theme.watchCSSVariable('color-primary').pipe(
-  tap(color => updateUI(color)),
-  takeUntil(this.disconnecting)
-).subscribe()
+### 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 */
 ```
 
-Common variables:
-- `color-primary`
-- `color-surface`
-- `color-error`
-- `elevation-1` through `elevation-5`
+### Elevation Variables
+```css
+--schmancy-elevation-level0
+--schmancy-elevation-level1
+--schmancy-elevation-level2
+--schmancy-elevation-level3
+--schmancy-elevation-level4
+--schmancy-elevation-level5
+```
 
-## Events
+### State Variables
+```css
+--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 */
+```
 
-### Fullscreen Event
-```typescript
-window.addEventListener('fullscreen', (e: CustomEvent) => {
-  const isFullscreen = e.detail
-  // Hide/show UI elements
-})
+### 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 */
 ```
 
-## State Management Pattern
+## Fullscreen Integration
+
+Navigation components automatically respond to fullscreen:
 
 ```typescript
-// All state changes through pipelines
-of(newColor).pipe(
-  tap(() => theme.setColor(newColor)),
-  switchMap(() => theme.color$),
-  tap(color => console.log('Color updated:', color)),
+// Enter fullscreen (hides navigation)
+theme.setFullscreen(true)
+
+// Custom component integration
+fromEvent(window, 'fullscreen').pipe(
+  tap((e: CustomEvent) => {
+    this.hidden = e.detail
+  }),
   takeUntil(this.disconnecting)
 ).subscribe()
 ```
 
+## System Preference Detection
+
+Auto mode follows system preferences with automatic updates:
+
+```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
+})
+```
+
 ## Best Practices
 
 1. **Always use observables** for reactive updates
-2. **Call `super.connectedCallback()`** when subscribing
-3. **Use `takeUntil(this.disconnecting)`** for cleanup
-4. **Prefer `resolvedScheme$`** over `scheme$` for UI logic
-5. **Use `next()` method** for batch updates
-6. **Let navigation components** handle fullscreen automatically
+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
 
 ## Common Patterns
 
-### Persist User Preference
+### Complete Theme Toggle Component
 ```typescript
-theme.scheme$.pipe(
-  skip(1), // Skip initial value
-  tap(scheme => localStorage.setItem('theme-scheme', scheme)),
-  takeUntil(this.disconnecting)
-).subscribe()
+@customElement('advanced-theme-toggle')
+export class AdvancedThemeToggle extends $LitElement() {
+  @state() private resolvedScheme: 'dark' | 'light' = 'light'
+  @state() private actualScheme: string = 'auto'
 
-// Restore on load
-const saved = localStorage.getItem('theme-scheme')
-if (saved) theme.setScheme(saved as any)
-```
+  connectedCallback() {
+    super.connectedCallback()
 
-### Theme Toggle Button
-```typescript
-html`
-  <button @click=${() => theme.toggleScheme()}>
-    ${theme.scheme === 'dark' ? '🌙' : '☀️'}
-  </button>
-`
+    // 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="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>
+    `
+  }
+}
 ```
 
 ### Fullscreen Video Player
 ```typescript
-class VideoPlayer extends $LitElement() {
+@customElement('video-player')
+export class VideoPlayer extends $LitElement() {
+  private videoRef = createRef<HTMLVideoElement>()
+
   private enterFullscreen() {
     theme.setFullscreen(true)
-    this.video.requestFullscreen()
+    this.videoRef.value?.requestFullscreen()
   }
 
   private exitFullscreen() {
     theme.setFullscreen(false)
     document.exitFullscreen()
   }
+
+  render() {
+    return html`
+      <video ${ref(this.videoRef)}>
+        <!-- Video content -->
+      </video>
+    `
+  }
+}
+```
+
+### Dynamic Motion Timing
+```typescript
+@customElement('animated-component')
+export class AnimatedComponent extends $LitElement() {
+  @state() private isExpanded = false
+
+  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);
+        }
+
+        @keyframes fadeIn {
+          from { opacity: 0; }
+          to { opacity: 1; }
+        }
+      </style>
+
+      <div class="panel ${this.isExpanded ? 'expanded' : ''}">
+        <!-- Content with smooth animations -->
+      </div>
+    `
+  }
 }
 ```
 
 ## Integration with Theme Component
 
-The service works with `<schmancy-theme>` component:
+The service works bidirectionally with `<schmancy-theme>` component:
 
 ```html
 <schmancy-theme color="#6750A4" scheme="auto">
-  <!-- Content -->
+  <!-- All children have access to theme tokens -->
 </schmancy-theme>
 ```
 
-Component automatically registers with service and syncs state bidirectionally.
+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
+
+## Error Handling
+
+```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 Considerations
+
+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
+// Old way
+localStorage.setItem('theme', 'dark')
+document.body.classList.add('dark-theme')
+
+// New way
+theme.setScheme('dark') // Automatic persistence & styling
+```
+
+From custom CSS variables:
+```typescript
+// Old way
+:root {
+  --primary: #6750A4;
+}
+
+// New way - Full M3 system generated
+theme.setColor('#6750A4') // Generates 100+ tokens
+```
+
+## Summary
+
+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
+
+Use the theme service as your single source of truth for all design tokens and theming needs.