@shohojdhara/atomix 0.5.1 → 0.5.4

package/dist/theme.d.ts

@@ -270,6 +270,47 @@ interface DesignTokens {
     'breakpoint-lg': string;
     'breakpoint-xl': string;
     'breakpoint-xxl': string;
+    'interactive-vortex-enabled': string;
+    'interactive-vortex-strength': string;
+    'interactive-vortex-radius': string;
+    'interactive-vortex-decay': string;
+    'interactive-chromatic-enabled': string;
+    'interactive-chromatic-mode': string;
+    'interactive-chromatic-red-shift': string;
+    'interactive-chromatic-green-shift': string;
+    'interactive-chromatic-blue-shift': string;
+    'interactive-chromatic-edge-only': string;
+    'interactive-chromatic-edge-threshold': string;
+    'interactive-mouse-sensitivity': string;
+    'interactive-mouse-trail-effect': string;
+    'interactive-animation-speed-base': string;
+    'interactive-animation-speed-multiplier': string;
+    'optimization-breakpoint-mobile': string;
+    'optimization-breakpoint-tablet': string;
+    'optimization-breakpoint-desktop': string;
+    'optimization-breakpoint-wide': string;
+    'optimization-device-scaling-mobile': string;
+    'optimization-device-scaling-tablet': string;
+    'optimization-device-scaling-desktop': string;
+    'optimization-performance-fps-target': string;
+    'optimization-auto-scaling-enabled': string;
+    'optimization-auto-scaling-low-end': string;
+    'optimization-auto-scaling-mid-range': string;
+    'optimization-auto-scaling-high-end': string;
+    'visual-polish-border-iridescent-glow': string;
+    'visual-polish-border-shimmer-effect': string;
+    'visual-polish-border-beveled-edges': string;
+    'visual-polish-border-pulsing-glow': string;
+    'visual-polish-content-aware-blur-enabled': string;
+    'visual-polish-content-aware-depth-detection': string;
+    'visual-polish-content-aware-edge-preservation': string;
+    'visual-polish-content-aware-variable-radius': string;
+    'visual-polish-holographic-enabled': string;
+    'visual-polish-holographic-rainbow-diffraction': string;
+    'visual-polish-holographic-scanline-animation': string;
+    'visual-polish-holographic-grid-overlay': string;
+    'visual-polish-holographic-data-stream': string;
+    'visual-polish-holographic-pulse-rings': string;
     [key: string]: string | undefined;
 }
 /**
@@ -294,203 +335,6 @@ declare const defaultTokens: DesignTokens;
  */
 declare function createTokens(overrides?: Partial<DesignTokens>): DesignTokens;
 
-/**
- * CSS Variable Generator
- *
- * Generates CSS custom properties from design tokens.
- */
-
-/**
- * Options for CSS variable generation
- */
-interface GenerateCSSVariablesOptions {
-    /** CSS selector for the variables (default: ':root') */
-    selector?: string;
-    /** Prefix for CSS variables (default: 'atomix') */
-    prefix?: string;
-}
-/**
- * Generate CSS variables from tokens
- *
- * Converts flat token object to CSS custom properties.
- *
- * @param tokens - Design tokens object
- * @param options - Generation options
- * @returns CSS string with custom properties
- *
- * @example
- * ```typescript
- * const tokens = {
- *   'primary': '#7c3aed',
- *   'spacing-4': '1rem',
- * };
- *
- * const css = generateCSSVariables(tokens);
- * // Returns: ":root {\n  --atomix-primary: #7c3aed;\n  --atomix-spacing-4: 1rem;\n}"
- * ```
- */
-declare function generateCSSVariables(tokens: DesignTokens, options?: GenerateCSSVariablesOptions): string;
-/**
- * Generate CSS variables with custom selector
- *
- * Useful for theme-specific selectors like `[data-theme="dark"]`
- *
- * @param tokens - Design tokens object
- * @param selector - CSS selector (e.g., '[data-theme="dark"]')
- * @param prefix - CSS variable prefix
- * @returns CSS string
- *
- * @example
- * ```typescript
- * const css = generateCSSVariablesForSelector(
- *   tokens,
- *   '[data-theme="dark"]',
- *   'atomix'
- * );
- * ```
- */
-declare function generateCSSVariablesForSelector(tokens: DesignTokens, selector: string, prefix?: string): string;
-
-/**
- * Core Theme Functions
- *
- * Simplified theme system using DesignTokens only.
- * Config-first approach: loads from atomix.config.ts when no input is provided.
- */
-
-/**
- * Create theme CSS from DesignTokens
- *
- * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
- *
- * @param input - DesignTokens (partial) or undefined (loads from config)
- * @param options - CSS generation options (prefix is automatically read from config if not provided)
- * @returns CSS string with custom properties
- * @throws Error if config loading fails when no input is provided
- *
- * @example
- * ```typescript
- * // Loads from atomix.config.ts
- * const css = createTheme();
- *
- * // Using DesignTokens
- * const css = createTheme({
- *   'primary': '#7c3aed',
- *   'spacing-4': '1rem',
- * });
- *
- * // With custom options
- * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
- * ```
- */
-declare function createTheme(input?: Partial<DesignTokens>, options?: GenerateCSSVariablesOptions): string;
-
-/**
- * Theme Composition Utilities
- *
- * Simplified utilities for composing and merging DesignTokens.
- */
-/**
- * Deep merge multiple objects
- * Later objects override earlier ones
- */
-declare function deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T;
-
-/**
- * Merge multiple DesignTokens objects into a single DesignTokens object
- *
- * @param tokens - DesignTokens objects to merge
- * @returns Merged DesignTokens object
- *
- * @example
- * ```typescript
- * const baseTokens = { 'primary': '#000', 'spacing-4': '1rem' };
- * const customTokens = { 'secondary': '#fff', 'spacing-4': '1.5rem' };
- * const merged = mergeTheme(baseTokens, customTokens);
- * // Returns: { 'primary': '#000', 'secondary': '#fff', 'spacing-4': '1.5rem' }
- * ```
- */
-declare function mergeTheme(...tokens: Partial<DesignTokens>[]): Partial<DesignTokens>;
-/**
- * Extend DesignTokens with additional tokens
- *
- * @param baseTokens - Base DesignTokens to extend
- * @param extension - Additional DesignTokens to merge
- * @returns Extended DesignTokens object
- *
- * @example
- * ```typescript
- * const base = { 'primary': '#000' };
- * const extended = extendTheme(base, { 'secondary': '#fff' });
- * // Returns: { 'primary': '#000', 'secondary': '#fff' }
- * ```
- */
-declare function extendTheme(baseTokens: Partial<DesignTokens>, extension: Partial<DesignTokens>): Partial<DesignTokens>;
-
-/**
- * Theme Metadata interface
- */
-interface ThemeMetadata$1 {
-    name: string;
-    class: string;
-    description?: string;
-    version?: string;
-    [key: string]: any;
-}
-/**
- * Theme Registry type - a record of theme IDs to metadata
- */
-type ThemeRegistry = Record<string, ThemeMetadata$1>;
-/**
- * Create a new theme registry
- */
-declare function createThemeRegistry(): ThemeRegistry;
-/**
- * Register a theme
- * @param registry - Theme registry object
- * @param id - Theme identifier
- * @param metadata - Theme metadata
- */
-declare function registerTheme(registry: ThemeRegistry, id: string, metadata: ThemeMetadata$1): void;
-/**
- * Unregister a theme
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */
-declare function unregisterTheme(registry: ThemeRegistry, id: string): boolean;
-/**
- * Check if a theme is registered
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */
-declare function hasTheme(registry: ThemeRegistry, id: string): boolean;
-/**
- * Get theme metadata
- * @param registry - Theme registry object
- * @param id - Theme identifier
- */
-declare function getTheme(registry: ThemeRegistry, id: string): ThemeMetadata$1 | undefined;
-/**
- * Get all registered theme metadata
- * @param registry - Theme registry object
- */
-declare function getAllThemes(registry: ThemeRegistry): ThemeMetadata$1[];
-/**
- * Get all registered theme IDs
- * @param registry - Theme registry object
- */
-declare function getThemeIds(registry: ThemeRegistry): string[];
-/**
- * Clear all registered themes
- * @param registry - Theme registry object
- */
-declare function clearThemes(registry: ThemeRegistry): void;
-/**
- * Get the number of registered themes
- * @param registry - Theme registry object
- */
-declare function getThemeCount(registry: ThemeRegistry): number;
-
 /**
  * Theme Manager Type Definitions
  *
@@ -499,7 +343,7 @@ declare function getThemeCount(registry: ThemeRegistry): number;
 /**
  * Theme metadata interface matching themes.config.js structure
  */
-interface ThemeMetadata {
+interface ThemeMetadata$1 {
     /** Display name of the theme */
     name: string;
     /** Unique identifier/class name for the theme */
@@ -581,8 +425,10 @@ interface UseThemeReturn {
     activeTokens: DesignTokens | null;
     /** Function to change theme (supports string or DesignTokens) */
     setTheme: (theme: string | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Update a specific theme section */
+    updateTheme: (section: ThemeSection, values: any) => Promise<void>;
     /** Available themes */
-    availableThemes: ThemeMetadata[];
+    availableThemes: ThemeMetadata$1[];
     /** Whether a theme is currently loading */
     isLoading: boolean;
     /** Current error, if any */
@@ -651,7 +497,7 @@ interface ThemeProviderProps {
     /** Default theme (string name or DesignTokens) */
     defaultTheme?: string | DesignTokens | Partial<DesignTokens>;
     /** Available themes */
-    themes?: Record<string, ThemeMetadata>;
+    themes?: Record<string, ThemeMetadata$1>;
     /** Base path for theme CSS */
     basePath?: string;
     /** CDN path for theme CSS */
@@ -673,6 +519,10 @@ interface ThemeProviderProps {
     /** Callback on error */
     onError?: (error: Error, themeName: string) => void;
 }
+/**
+ * Theme section name
+ */
+type ThemeSection = keyof DesignTokens;
 /**
  * Theme context value
  */
@@ -683,8 +533,10 @@ interface ThemeContextValue {
     activeTokens: DesignTokens | null;
     /** Set theme function (supports string or DesignTokens) */
     setTheme: (theme: string | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Update a specific theme section */
+    updateTheme: (section: ThemeSection, values: any) => Promise<void>;
     /** Available themes */
-    availableThemes: ThemeMetadata[];
+    availableThemes: ThemeMetadata$1[];
     /** Loading state */
     isLoading: boolean;
     /** Error state */
@@ -776,6 +628,10 @@ interface TypographyOptions {
  * Spacing function type
  */
 type SpacingFunction = (...values: number[]) => string;
+/**
+ * Spacing configuration options for createTheme
+ */
+type SpacingOptions = number | number[] | SpacingFunction;
 /**
  * Breakpoint values configuration
  */
@@ -862,13 +718,87 @@ interface BorderRadiusOptions {
  * Users can augment this interface via module augmentation
  */
 interface ThemeCustomProperties {
+    interactiveEffects?: {
+        vortex?: {
+            enabled?: boolean;
+            strength?: number;
+            radius?: number;
+            decay?: number;
+        };
+        chromaticAberration?: {
+            enabled?: boolean;
+            mode?: 'longitudinal' | 'lateral' | 'hybrid';
+            redShift?: number;
+            greenShift?: number;
+            blueShift?: number;
+            edgeOnly?: boolean;
+            edgeThreshold?: number;
+        };
+        mouseInteraction?: {
+            sensitivity?: number;
+            trailEffect?: boolean;
+        };
+        animationSpeed?: {
+            base?: number;
+            timeMultiplier?: number;
+        };
+    };
+    optimization?: {
+        responsive?: {
+            breakpoints?: {
+                mobile?: string;
+                tablet?: string;
+                desktop?: string;
+                wide?: string;
+            };
+            deviceScaling?: {
+                mobile?: number;
+                tablet?: number;
+                desktop?: number;
+            };
+        };
+        performance?: {
+            fpsTarget?: number;
+            autoScaling?: boolean;
+        };
+        autoScaling?: {
+            enabled?: boolean;
+            qualityThresholds?: {
+                lowEnd?: number;
+                midRange?: number;
+                highEnd?: number;
+            };
+        };
+    };
+    visualPolish?: {
+        borders?: {
+            iridescentGlow?: boolean;
+            shimmerEffect?: boolean;
+            beveledEdges?: boolean;
+            pulsingGlow?: boolean;
+        };
+        contentAwareBlur?: {
+            enabled?: boolean;
+            depthDetection?: boolean;
+            edgePreservation?: boolean;
+            variableRadius?: boolean;
+        };
+        holographicEffects?: {
+            enabled?: boolean;
+            rainbowDiffraction?: boolean;
+            scanlineAnimation?: boolean;
+            gridOverlay?: boolean;
+            dataStream?: boolean;
+            pulseRings?: boolean;
+        };
+    };
     [key: string]: any;
 }
 /**
  * Complete theme object with computed values
  * Generated by createTheme function
  */
-interface Theme extends ThemeMetadata {
+interface Theme extends ThemeMetadata$1 {
     /** Color palette with computed values */
     palette: {
         primary: PaletteColor;
@@ -935,67 +865,207 @@ interface Theme extends ThemeMetadata {
 }
 
 /**
- * Naming Utilities
+ * CSS Variable Generator
  *
- * Provides consistent naming conventions across the theme system
- */
-interface NamingOptions {
-    prefix?: string;
-    component?: string;
-    variant?: string;
-    state?: string;
-}
-/**
- * Generate consistent CSS class names following BEM methodology
- */
-declare function generateClassName(block: string, element?: string, modifiers?: Record<string, boolean | string>): string;
-/**
- * Generate consistent CSS variable names
- */
-declare function generateCSSVariableName(property: string, options?: NamingOptions): string;
-/**
- * Normalize theme tokens to consistent naming convention
- */
-declare function normalizeThemeTokens(tokens: Record<string, any>): Record<string, any>;
-/**
- * Convert camelCase to kebab-case for CSS custom properties
- */
-declare function camelToKebab(str: string): string;
-/**
- * Convert theme property to CSS variable name
+ * Generates CSS custom properties from design tokens.
  */
-declare function themePropertyToCSSVar(propertyPath: string, prefix?: string): string;
 
 /**
- * Component Theming Utilities
- *
- * Provides consistent patterns for applying theme values to components
- * using DesignTokens and CSS variables
+ * Options for CSS variable generation
  */
-
-interface ComponentThemeOptions {
-    component: string;
-    variant?: string;
-    size?: string;
-    tokens?: Partial<DesignTokens>;
+interface GenerateCSSVariablesOptions {
+    /** CSS selector for the variables (default: ':root') */
+    selector?: string;
+    /** Prefix for CSS variables (default: 'atomix') */
+    prefix?: string;
 }
 /**
- * Get a theme value for a specific component using CSS variables
- * This ensures all components access theme values consistently
- */
-declare function getComponentThemeValue(component: string, property: string, variant?: string, size?: string): string;
+ * Generate CSS variables from tokens
+ *
+ * Converts flat token object to CSS custom properties.
+ *
+ * @param tokens - Design tokens object
+ * @param options - Generation options
+ * @returns CSS string with custom properties
+ *
+ * @example
+ * ```typescript
+ * const tokens = {
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
+ * };
+ *
+ * const css = generateCSSVariables(tokens);
+ * // Returns: ":root {\n  --atomix-primary: #7c3aed;\n  --atomix-spacing-4: 1rem;\n}"
+ * ```
+ */
+declare function generateCSSVariables(tokens: DesignTokens, options?: GenerateCSSVariablesOptions): string;
 /**
- * Generate component-specific CSS variables from DesignTokens
+ * Generate CSS variables with custom selector
+ *
+ * Useful for theme-specific selectors like `[data-theme="dark"]`
+ *
+ * @param tokens - Design tokens object
+ * @param selector - CSS selector (e.g., '[data-theme="dark"]')
+ * @param prefix - CSS variable prefix
+ * @returns CSS string
+ *
+ * @example
+ * ```typescript
+ * const css = generateCSSVariablesForSelector(
+ *   tokens,
+ *   '[data-theme="dark"]',
+ *   'atomix'
+ * );
+ * ```
  */
-declare function generateComponentCSSVars(component: string, tokens?: Partial<DesignTokens>, variant?: string, size?: string): Record<string, string>;
+declare function generateCSSVariablesForSelector(tokens: DesignTokens, selector: string, prefix?: string): string;
+
 /**
- * Apply consistent theme to component style object using DesignTokens
+ * Core Theme Functions
+ *
+ * Unified theme system that handles both DesignTokens and Theme objects.
+ * Config-first approach: loads from atomix.config.ts when no input is provided.
+ * Config-first approach: loads advanced features from config when available.
  */
-declare function applyComponentTheme(component: string, style?: React.CSSProperties, variant?: string, size?: string, tokens?: Partial<DesignTokens>): React.CSSProperties;
+
 /**
- * Create a hook for consistent component theming
+ * Create theme CSS from tokens or Theme object
+ *
+ * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
+ * Config file is required for automatic loading.
+ *
+ * @param input - DesignTokens (partial), Theme object, or undefined (loads from config)
+ * @param options - CSS generation options (prefix is automatically read from config if not provided)
+ * @returns CSS string with custom properties
+ * @throws Error if config loading fails when no input is provided
+ *
+ * @example
+ * ```typescript
+ * // Loads from atomix.config.ts (config file required)
+ * const css = createTheme();
+ *
+ * // Using DesignTokens
+ * const css = createTheme({
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
+ * });
+ *
+ * // Using Theme object
+ * const theme = createThemeObject({ palette: { primary: { main: '#7c3aed' } } });
+ * const css = createTheme(theme);
+ *
+ * // With custom options
+ * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
+ * ```
  */
-declare function useComponentTheme(component: string, variant?: string, size?: string, tokens?: Partial<DesignTokens>): (property: string) => string;
+declare function createTheme(input?: Partial<DesignTokens> | Theme, options?: GenerateCSSVariablesOptions): string;
+
+/**
+ * Theme Composition Utilities
+ *
+ * Simplified utilities for composing and merging DesignTokens.
+ */
+/**
+ * Deep merge multiple objects
+ * Later objects override earlier ones
+ */
+declare function deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T;
+
+/**
+ * Merge multiple DesignTokens objects into a single DesignTokens object
+ *
+ * @param tokens - DesignTokens objects to merge
+ * @returns Merged DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * const baseTokens = { 'primary': '#000', 'spacing-4': '1rem' };
+ * const customTokens = { 'secondary': '#fff', 'spacing-4': '1.5rem' };
+ * const merged = mergeTheme(baseTokens, customTokens);
+ * // Returns: { 'primary': '#000', 'secondary': '#fff', 'spacing-4': '1.5rem' }
+ * ```
+ */
+declare function mergeTheme(...tokens: Partial<DesignTokens>[]): Partial<DesignTokens>;
+/**
+ * Extend DesignTokens with additional tokens
+ *
+ * @param baseTokens - Base DesignTokens to extend
+ * @param extension - Additional DesignTokens to merge
+ * @returns Extended DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * const base = { 'primary': '#000' };
+ * const extended = extendTheme(base, { 'secondary': '#fff' });
+ * // Returns: { 'primary': '#000', 'secondary': '#fff' }
+ * ```
+ */
+declare function extendTheme(baseTokens: Partial<DesignTokens>, extension: Partial<DesignTokens>): Partial<DesignTokens>;
+
+/**
+ * Theme Metadata interface
+ */
+interface ThemeMetadata {
+    name: string;
+    class: string;
+    description?: string;
+    version?: string;
+    [key: string]: any;
+}
+/**
+ * Theme Registry type - a record of theme IDs to metadata
+ */
+type ThemeRegistry = Record<string, ThemeMetadata>;
+/**
+ * Create a new theme registry
+ */
+declare function createThemeRegistry(): ThemeRegistry;
+/**
+ * Register a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ * @param metadata - Theme metadata
+ */
+declare function registerTheme(registry: ThemeRegistry, id: string, metadata: ThemeMetadata): void;
+/**
+ * Unregister a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */
+declare function unregisterTheme(registry: ThemeRegistry, id: string): boolean;
+/**
+ * Check if a theme is registered
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */
+declare function hasTheme(registry: ThemeRegistry, id: string): boolean;
+/**
+ * Get theme metadata
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */
+declare function getTheme(registry: ThemeRegistry, id: string): ThemeMetadata | undefined;
+/**
+ * Get all registered theme metadata
+ * @param registry - Theme registry object
+ */
+declare function getAllThemes(registry: ThemeRegistry): ThemeMetadata[];
+/**
+ * Get all registered theme IDs
+ * @param registry - Theme registry object
+ */
+declare function getThemeIds(registry: ThemeRegistry): string[];
+/**
+ * Clear all registered themes
+ * @param registry - Theme registry object
+ */
+declare function clearThemes(registry: ThemeRegistry): void;
+/**
+ * Get the number of registered themes
+ * @param registry - Theme registry object
+ */
+declare function getThemeCount(registry: ThemeRegistry): number;
 
 /**
  * CSS Injection Utilities
@@ -1043,6 +1113,353 @@ declare function removeCSS(id?: string): void;
  */
 declare function isCSSInjected(id?: string): boolean;
 
+/**
+ * Naming Utilities
+ *
+ * Provides consistent naming conventions across the theme system
+ */
+interface NamingOptions {
+    prefix?: string;
+    component?: string;
+    variant?: string;
+    state?: string;
+}
+/**
+ * Generate consistent CSS class names following BEM methodology
+ */
+declare function generateClassName(block: string, element?: string, modifiers?: Record<string, boolean | string>): string;
+/**
+ * Generate consistent CSS variable names
+ */
+declare function generateCSSVariableName(property: string, options?: NamingOptions): string;
+/**
+ * Normalize theme tokens to consistent naming convention
+ */
+declare function normalizeThemeTokens(tokens: Record<string, any>): Record<string, any>;
+/**
+ * Convert camelCase to kebab-case for CSS custom properties
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Convert theme property to CSS variable name
+ */
+declare function themePropertyToCSSVar(propertyPath: string, prefix?: string): string;
+
+/**
+ * Component Theming Utilities
+ *
+ * Provides consistent patterns for applying theme values to components
+ * using DesignTokens and CSS variables
+ */
+
+interface ComponentThemeOptions {
+    component: string;
+    variant?: string;
+    size?: string;
+    tokens?: Partial<DesignTokens>;
+}
+/**
+ * Get a theme value for a specific component using CSS variables
+ * This ensures all components access theme values consistently
+ */
+declare function getComponentThemeValue(component: string, property: string, variant?: string, size?: string): string;
+/**
+ * Generate component-specific CSS variables from DesignTokens
+ */
+declare function generateComponentCSSVars(component: string, tokens?: Partial<DesignTokens>, variant?: string, size?: string): Record<string, string>;
+/**
+ * Apply consistent theme to component style object using DesignTokens
+ */
+declare function applyComponentTheme(component: string, style?: React.CSSProperties, variant?: string, size?: string, tokens?: Partial<DesignTokens>): React.CSSProperties;
+/**
+ * Create a hook for consistent component theming
+ */
+declare function useComponentTheme(component: string, variant?: string, size?: string, tokens?: Partial<DesignTokens>): (property: string) => string;
+
+/**
+ * Theme Utilities
+ *
+ * Helper functions for common theme operations including:
+ * - Theme switching (dark/light mode)
+ * - Theme persistence (localStorage)
+ * - System preference detection
+ * - Smooth transitions
+ * - Color manipulation
+ */
+
+type ThemeMode = 'light' | 'dark' | 'system';
+interface ThemeSwitcherOptions {
+    /** CSS selector for root element (default: ':root') */
+    selector?: string;
+    /** Storage key for theme persistence (default: 'atomix-theme') */
+    storageKey?: string;
+    /** Enable smooth transitions (default: true) */
+    enableTransition?: boolean;
+    /** Transition duration in ms (default: 300) */
+    transitionDuration?: number;
+}
+interface ThemePersistenceOptions {
+    /** Storage key (default: 'atomix-theme') */
+    storageKey?: string;
+    /** Storage type (default: 'localStorage') */
+    storageType?: 'localStorage' | 'sessionStorage';
+}
+/**
+ * Switch between light and dark themes
+ *
+ * Automatically toggles a class on the root element and persists the choice.
+ *
+ * @param mode - Theme mode ('light', 'dark', or 'system')
+ * @param options - Configuration options
+ *
+ * @example
+ * ```typescript
+ * import { switchTheme } from '@shohojdhara/atomix/theme/utils';
+ *
+ * // Switch to dark mode
+ * switchTheme('dark');
+ *
+ * // Toggle between light/dark
+ * const current = getCurrentTheme();
+ * switchTheme(current === 'dark' ? 'light' : 'dark');
+ * ```
+ */
+declare function switchTheme(mode: ThemeMode, options?: ThemeSwitcherOptions): void;
+/**
+ * Toggle between light and dark themes
+ *
+ * @param options - Configuration options
+ * @returns The new theme mode
+ *
+ * @example
+ * ```typescript
+ * const newMode = toggleTheme();
+ * console.log('Switched to:', newMode);
+ * ```
+ */
+declare function toggleTheme(options?: ThemeSwitcherOptions): ThemeMode;
+/**
+ * Get current theme mode
+ *
+ * @param storageKey - Storage key (default: 'atomix-theme')
+ * @returns Current theme mode or 'light' if not set
+ */
+declare function getCurrentTheme(storageKey?: string): ThemeMode;
+/**
+ * Get system theme preference
+ *
+ * @returns 'dark' if system prefers dark mode, 'light' otherwise
+ */
+declare function getSystemTheme(): ThemeMode;
+/**
+ * Initialize theme based on saved preference or system preference
+ *
+ * Call this once at app startup.
+ *
+ * @param options - Configuration options
+ * @returns The initialized theme mode
+ *
+ * @example
+ * ```typescript
+ * // In your app entry point
+ * import { initializeTheme } from '@shohojdhara/atomix/theme/utils';
+ *
+ * const theme = initializeTheme();
+ * console.log('Theme initialized:', theme);
+ * ```
+ */
+declare function initializeTheme(options?: ThemeSwitcherOptions): ThemeMode;
+/**
+ * Listen for system theme changes
+ *
+ * @param callback - Function to call when system theme changes
+ * @returns Cleanup function to stop listening
+ *
+ * @example
+ * ```typescript
+ * const cleanup = listenToSystemTheme((mode) => {
+ *   console.log('System theme changed to:', mode);
+ *   switchTheme(mode);
+ * });
+ *
+ * // Later, when component unmounts
+ * cleanup();
+ * ```
+ */
+declare function listenToSystemTheme(callback: (mode: ThemeMode) => void): () => void;
+/**
+ * Save theme preference to storage
+ *
+ * @param mode - Theme mode to save
+ * @param options - Persistence options
+ */
+declare function persistTheme(mode: ThemeMode, options?: ThemePersistenceOptions): void;
+/**
+ * Clear saved theme preference
+ *
+ * @param options - Persistence options
+ */
+declare function clearThemePreference(options?: ThemePersistenceOptions): void;
+/**
+ * Merge multiple token sets
+ *
+ * Deep merges token objects, with later tokens overriding earlier ones.
+ *
+ * @param tokens - Token objects to merge
+ * @returns Merged tokens
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeTokens(
+ *   baseTokens,
+ *   { colors: { primary: { main: '#custom' } } }
+ * );
+ * ```
+ */
+declare function mergeTokens(...tokens: Array<Partial<DesignTokens>>): Partial<DesignTokens>;
+/**
+ * Override specific tokens
+ *
+ * Creates a new token object with specific overrides.
+ *
+ * @param base - Base tokens
+ * @param overrides - Tokens to override
+ * @returns New tokens with overrides applied
+ *
+ * @example
+ * ```typescript
+ * const customized = overrideTokens(defaultTokens, {
+ *   colors: {
+ *     primary: { main: '#ff0000' }
+ *   }
+ * });
+ * ```
+ */
+declare function overrideTokens(base: Partial<DesignTokens>, overrides: Partial<DesignTokens>): Partial<DesignTokens>;
+/**
+ * Pick specific token categories
+ *
+ * Extracts only the specified categories from tokens.
+ *
+ * @param tokens - Source tokens
+ * @param categories - Categories to pick
+ * @returns Tokens with only selected categories
+ *
+ * @example
+ * ```typescript
+ * const colorTokens = pickTokens(allTokens, ['colors']);
+ * ```
+ */
+declare function pickTokens(tokens: Partial<DesignTokens>, categories: Array<keyof DesignTokens>): Partial<DesignTokens>;
+/**
+ * Omit specific token categories
+ *
+ * Removes specified categories from tokens.
+ *
+ * @param tokens - Source tokens
+ * @param categories - Categories to omit
+ * @returns Tokens without omitted categories
+ *
+ * @example
+ * ```typescript
+ * const withoutColors = omitTokens(allTokens, ['colors']);
+ * ```
+ */
+declare function omitTokens(tokens: Partial<DesignTokens>, categories: Array<keyof DesignTokens>): Partial<DesignTokens>;
+/**
+ * Convert hex color to RGB
+ *
+ * @param hex - Hex color (with or without #)
+ * @returns RGB object { r, g, b }
+ */
+declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Convert RGB to hex
+ *
+ * @param r - Red (0-255)
+ * @param g - Green (0-255)
+ * @param b - Blue (0-255)
+ * @returns Hex color with #
+ */
+declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Calculate luminance of a color
+ *
+ * Used for determining contrast ratios.
+ *
+ * @param hex - Hex color
+ * @returns Luminance value (0-1)
+ */
+declare function getLuminance(hex: string): number;
+/**
+ * Calculate contrast ratio between two colors
+ *
+ * @param hex1 - First hex color
+ * @param hex2 - Second hex color
+ * @returns Contrast ratio (1-21)
+ */
+declare function getContrastRatio(hex1: string, hex2: string): number;
+/**
+ * Check if text color passes WCAG AA standard
+ *
+ * @param textColor - Text color hex
+ * @param backgroundColor - Background color hex
+ * @param size - Font size ('small' or 'large')
+ * @returns true if passes WCAG AA
+ */
+declare function isAccessible(textColor: string, backgroundColor: string, size?: 'small' | 'large'): boolean;
+/**
+ * Get appropriate text color (black or white) for a background
+ *
+ * @param backgroundColor - Background hex color
+ * @param threshold - Contrast threshold (default: 3)
+ * @returns '#000000' or '#FFFFFF'
+ */
+declare function getContrastText(backgroundColor: string, threshold?: number): string;
+/**
+ * Lighten a color
+ *
+ * @param hex - Base hex color
+ * @param amount - Amount to lighten (0-1)
+ * @returns Lightened hex color
+ */
+declare function lighten(hex: string, amount?: number): string;
+/**
+ * Darken a color
+ *
+ * @param hex - Base hex color
+ * @param amount - Amount to darken (0-1)
+ * @returns Darkened hex color
+ */
+declare function darken(hex: string, amount?: number): string;
+/**
+ * Add alpha to a color
+ *
+ * @param hex - Hex color
+ * @param opacity - Opacity value (0-1)
+ * @returns RGBA color string
+ */
+declare function alpha(hex: string, opacity: number): string;
+/**
+ * Emphasize a color (lighten if dark, darken if light)
+ *
+ * @param hex - Hex color
+ * @param amount - Amount to emphasize (0-1)
+ * @returns Emphasized hex color
+ */
+declare function emphasize(hex: string, amount?: number): string;
+/**
+ * Create a spacing utility
+ *
+ * @param spacingInput - Spacing configuration
+ * @returns Spacing function
+ */
+declare function createSpacing(spacingInput?: SpacingOptions): SpacingFunction;
+
 /**
  * Theme Provider
  *
@@ -1098,7 +1515,7 @@ declare function useTheme(): UseThemeReturn;
  * Provides consistent access to theme values using CSS custom properties
  * and DesignTokens.
  */
-type ThemeTokens = {
+type ThemeTokens$1 = {
     theme: string;
     activeTokens: DesignTokens | null;
     getToken: (tokenName: string, fallback?: string) => string;
@@ -1122,7 +1539,7 @@ type ThemeTokens = {
     shadows: Record<string, string>;
     transitions: Record<string, string>;
 };
-declare function useThemeTokens(): ThemeTokens;
+declare function useThemeTokens(): ThemeTokens$1;
 
 /**
  * Theme context with default values
@@ -1177,6 +1594,85 @@ declare class ThemeErrorBoundary extends Component<ThemeErrorBoundaryProps, Them
     render(): ReactNode;
 }
 
+/**
+ * useThemeSwitcher Hook
+ *
+ * React hook for managing theme switching with persistence and system preference detection.
+ * Provides an easy-to-use API for dark/light mode toggling.
+ *
+ * @example
+ * ```tsx
+ * import { useThemeSwitcher } from '@shohojdhara/atomix/theme';
+ *
+ * function ThemeToggle() {
+ *   const { mode, toggle, setMode, isDark } = useThemeSwitcher();
+ *
+ *   return (
+ *     <button onClick={toggle}>
+ *       {isDark ? '☀️ Light' : '🌙 Dark'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+interface UseThemeSwitcherOptions extends ThemeSwitcherOptions {
+    /** Initial theme mode (default: 'system') */
+    initialMode?: ThemeMode;
+    /** Automatically sync with system preference (default: false) */
+    syncWithSystem?: boolean;
+}
+interface UseThemeSwitcherReturn {
+    /** Current theme mode */
+    mode: ThemeMode;
+    /** Whether current theme is dark */
+    isDark: boolean;
+    /** Whether current theme is light */
+    isLight: boolean;
+    /** Toggle between light and dark */
+    toggle: () => ThemeMode;
+    /** Set specific theme mode */
+    setMode: (mode: ThemeMode) => void;
+    /** Reset to system preference */
+    resetToSystem: () => void;
+    /** Clear saved preference */
+    clearPreference: () => void;
+}
+/**
+ * Hook for managing theme switching
+ *
+ * @param options - Configuration options
+ * @returns Theme switcher controls
+ */
+declare function useThemeSwitcher(options?: UseThemeSwitcherOptions): UseThemeSwitcherReturn;
+
+interface ThemeToggleProps extends Omit<UseThemeSwitcherOptions, 'initialMode'> {
+    /** Custom class name */
+    className?: string;
+    /** Show text label (default: false) */
+    showLabel?: boolean;
+    /** Label for light mode (default: 'Light') */
+    lightLabel?: string;
+    /** Label for dark mode (default: 'Dark') */
+    darkLabel?: string;
+    /** Icon size in pixels (default: 20) */
+    iconSize?: number;
+    /** Button variant (default: 'icon') */
+    variant?: 'icon' | 'button' | 'switch';
+    /** Custom render function */
+    render?: (props: {
+        isDark: boolean;
+        toggle: () => void;
+        mode: ThemeMode;
+    }) => React__default.ReactNode;
+    /** Aria label (default: 'Toggle theme') */
+    ariaLabel?: string;
+}
+/**
+ * ThemeToggle component with multiple variants
+ */
+declare const ThemeToggle: React__default.FC<ThemeToggleProps>;
+
 /**
  * Theme Applicator
  *
@@ -1420,7 +1916,7 @@ declare class ThemeValidator {
     /**
      * Validate theme
      */
-    validate(theme: Theme, metadata?: ThemeMetadata): ValidationResult;
+    validate(theme: Theme, metadata?: ThemeMetadata$1): ValidationResult;
     /**
      * Validate palette
      */
@@ -1510,17 +2006,378 @@ interface UseHistoryReturn<T> {
  */
 declare function useHistory<T>(options?: UseHistoryOptions): UseHistoryReturn<T>;
 
+/**
+ * Configuration Types
+ *
+ * Type definitions for the Atomix configuration system.
+ */
+
+/**
+ * Color Scale (1-10)
+ */
+interface ColorScale {
+    1?: string;
+    2?: string;
+    3?: string;
+    4?: string;
+    5?: string;
+    6?: string;
+    7?: string;
+    8?: string;
+    9?: string;
+    10?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Palette Color Options
+ */
+interface PaletteColorOptions {
+    main: string;
+    light?: string;
+    dark?: string;
+    contrastText?: string;
+}
+/**
+ * Interactive Effect Configuration
+ */
+interface InteractiveEffectsConfig {
+    /** Vortex & flow field effects */
+    vortex?: {
+        enabled?: boolean;
+        strength?: number;
+        radius?: number;
+        decay?: number;
+        curlNoise?: boolean;
+        velocityTracking?: boolean;
+    };
+    /** Chromatic aberration effects */
+    chromaticAberration?: {
+        enabled?: boolean;
+        mode?: 'longitudinal' | 'lateral' | 'hybrid';
+        redShift?: number;
+        greenShift?: number;
+        blueShift?: number;
+        edgeOnly?: boolean;
+        edgeThreshold?: number;
+    };
+    /** Mouse interaction settings */
+    mouseInteraction?: {
+        sensitivity?: number;
+        trailEffect?: boolean;
+        pressureSensitivity?: boolean;
+    };
+    /** Animation speed controls */
+    animationSpeed?: {
+        base?: number;
+        timeMultiplier?: number;
+    };
+}
+/**
+ * Optimization Configuration
+ */
+interface OptimizationConfig {
+    /** Responsive breakpoint system */
+    responsive?: {
+        breakpoints?: {
+            mobile?: string;
+            tablet?: string;
+            desktop?: string;
+            wide?: string;
+        };
+        /** Device-aware parameter scaling */
+        deviceScaling?: {
+            mobile?: number;
+            tablet?: number;
+            desktop?: number;
+        };
+    };
+    /** Performance monitoring */
+    performance?: {
+        enabled?: boolean;
+        fpsTarget?: number;
+        autoScaling?: boolean;
+        monitorDashboard?: boolean;
+    };
+    /** Auto-scaling logic based on device capabilities */
+    autoScaling?: {
+        enabled?: boolean;
+        qualityThresholds?: {
+            lowEnd?: number;
+            midRange?: number;
+            highEnd?: number;
+        };
+    };
+}
+/**
+ * Visual Polish Configuration
+ */
+interface VisualPolishConfig {
+    /** Advanced border effects */
+    borders?: {
+        iridescentGlow?: boolean;
+        shimmerEffect?: boolean;
+        beveledEdges?: boolean;
+        pulsingGlow?: boolean;
+    };
+    /** Content-aware blur */
+    contentAwareBlur?: {
+        enabled?: boolean;
+        depthDetection?: boolean;
+        edgePreservation?: boolean;
+        variableRadius?: boolean;
+    };
+    /** Holographic effect modes */
+    holographicEffects?: {
+        enabled?: boolean;
+        rainbowDiffraction?: boolean;
+        scanlineAnimation?: boolean;
+        gridOverlay?: boolean;
+        dataStream?: boolean;
+        pulseRings?: boolean;
+    };
+}
+/**
+ * Design Tokens Schema (Tailwind-like)
+ */
+interface ThemeTokens {
+    /** Color palette */
+    colors?: Record<string, string | PaletteColorOptions | ColorScale | Record<string, string>>;
+    /** Spacing scale */
+    spacing?: Record<string, string>;
+    /** Border radius scale */
+    borderRadius?: Record<string, string>;
+    /** Typography scale and settings */
+    typography?: {
+        fontFamilies?: Record<string, string>;
+        fontSizes?: Record<string, string>;
+        fontWeights?: Record<string, string | number>;
+        lineHeights?: Record<string, string | number>;
+        letterSpacings?: Record<string, string>;
+    };
+    /** Shadow scale */
+    shadows?: Record<string, string>;
+    /** Z-index scale */
+    zIndex?: Record<string, string | number>;
+    /** Breakpoints scale */
+    breakpoints?: Record<string, string | number>;
+    /** Transitions settings */
+    transitions?: {
+        durations?: Record<string, string>;
+        easings?: Record<string, string>;
+    };
+}
+/**
+ * CSS Theme Definition
+ */
+interface CSSThemeDefinition {
+    type: 'css';
+    name: string;
+    class?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+    supportsDarkMode?: boolean;
+    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    a11y?: {
+        contrastTarget?: number;
+        modes?: string[];
+    };
+    color?: string;
+    features?: string[];
+    dependencies?: string[];
+    cssPath?: string;
+}
+/**
+ * JavaScript Theme Definition
+ */
+interface JSThemeDefinition {
+    type: 'js';
+    name: string;
+    class?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+    supportsDarkMode?: boolean;
+    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    a11y?: {
+        contrastTarget?: number;
+        modes?: string[];
+    };
+    color?: string;
+    features?: string[];
+    dependencies?: string[];
+    createTheme: () => Theme;
+}
+/**
+ * Theme Definition (CSS or JS)
+ */
+type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
+/**
+ * Build configuration
+ */
+interface BuildConfig {
+    output?: {
+        directory?: string;
+        formats?: {
+            expanded?: string;
+            compressed?: string;
+        };
+    };
+    sass?: {
+        style?: 'expanded' | 'compressed';
+        sourceMap?: boolean;
+        loadPaths?: string[];
+    };
+}
+/**
+ * Runtime configuration
+ */
+interface RuntimeConfig {
+    basePath?: string;
+    cdnPath?: string | null;
+    preload?: string[];
+    lazy?: boolean;
+    defaultTheme?: string;
+    storageKey?: string;
+    dataAttribute?: string;
+    enablePersistence?: boolean;
+    useMinified?: boolean;
+}
+/**
+ * Integration settings
+ */
+interface IntegrationConfig {
+    cssVariables?: Record<string, string>;
+    classNames?: {
+        theme?: string;
+        colorMode?: string;
+    };
+}
+/**
+ * Plugin Configuration
+ */
+interface PluginConfig {
+    name: string;
+    options?: Record<string, any>;
+}
+/**
+ * Token Provider Configuration
+ */
+interface TokenProviderConfig {
+    type: 'figma' | 'style-dictionary' | 'w3c' | string;
+    options?: Record<string, any>;
+}
+/**
+ * Token Engine Configuration
+ */
+interface TokenEngineConfig {
+    providers?: Record<string, TokenProviderConfig>;
+    sync?: {
+        pull?: boolean;
+        push?: boolean;
+        onBuild?: boolean;
+    };
+}
+/**
+ * CLI component generator defaults
+ */
+interface GeneratorConfig {
+    /** Default output directory for generated components */
+    outputPath?: string;
+    /** Override detected framework */
+    framework?: 'react' | 'next' | 'vanilla';
+    /** Per-feature defaults */
+    features?: {
+        storybook?: boolean;
+        hook?: boolean;
+        styles?: boolean;
+        tests?: boolean;
+    };
+    /** Composable hooks directory relative to project root */
+    hookOutputDir?: string;
+    /** Story file: side-effect import for global Atomix styles */
+    storybookCssImport?: string;
+    /** Barrel file strategy for new components */
+    barrel?: 'index' | 'none';
+}
+/**
+ * Atomix Configuration Interface
+ *
+ * Tailwind-like configuration for external developers.
+ */
+interface AtomixConfig {
+    prefix?: string;
+    plugins?: (string | PluginConfig)[];
+    tokenEngine?: TokenEngineConfig;
+    ai?: {
+        provider?: 'openai' | 'anthropic';
+        model?: string;
+        apiKey?: string;
+        temperature?: number;
+        maxTokens?: number;
+        rateLimit?: {
+            requests: number;
+            windowMs: number;
+        };
+    };
+    telemetry?: {
+        enabled?: boolean;
+        path?: string;
+        anonymize?: boolean;
+    };
+    generator?: GeneratorConfig;
+    interactiveEffects?: InteractiveEffectsConfig;
+    optimization?: OptimizationConfig;
+    visualPolish?: VisualPolishConfig;
+    theme?: {
+        extend?: ThemeTokens;
+        tokens?: ThemeTokens;
+        themes?: Record<string, ThemeDefinition>;
+    };
+    /** @internal Build configuration */
+    build?: BuildConfig;
+    /** @internal Runtime configuration */
+    runtime?: RuntimeConfig;
+    /** @internal Integration settings */
+    integration?: IntegrationConfig;
+    /** @internal Theme dependencies mapping */
+    dependencies?: Record<string, string[]>;
+}
+
 /**
  * Theme Adapter
  *
- * Converts between Theme objects and DesignTokens.
+ * Converts between Theme objects and DesignTokens
  */
 
 /**
- * Convert DesignTokens to Theme-compatible CSS variables
+ * Converts an AtomixConfig to DesignTokens
  *
- * @param tokens - DesignTokens object
- * @returns CSS variables object compatible with Theme.cssVars
+ * This function maps the configuration from the user-facing format
+ * to the internal DesignTokens format used by the theme system.
+ *
+ * @param config - The configuration object to convert
+ * @returns DesignTokens object ready for theme generation
+ *
+ * @example
+ * ```typescript
+ * import { configToTokens } from '@shohojdhara/atomix/theme';
+ *
+ * const config = {
+ *   prefix: 'myapp',
+ *   theme: { extend: { colors: { primary: { main: '#7AFFD7' } } } }
+ * };
+ * const tokens = configToTokens(config);
+ * ```
+ */
+declare function configToTokens(config: AtomixConfig): DesignTokens;
+/**
+ * Converts DesignTokens to CSS variables
+ *
+ * @param tokens - The tokens to convert
+ * @returns A record of CSS variable names and values
  */
 declare function designTokensToCSSVars(tokens: Partial<DesignTokens>): Record<string, string>;
 
@@ -1630,6 +2487,265 @@ declare function extractComponentName(varName: string, prefix?: string): string
  */
 declare function isDesignTokens(value: unknown): value is DesignTokens;
 
+/**
+ * Performance Monitor Utility
+ *
+ * Provides performance monitoring and metrics collection for the Atomix theme system.
+ * Used to measure and optimize performance of advanced visual effects.
+ */
+/**
+ * Performance metrics collected by the monitor
+ */
+interface PerformanceMetrics {
+    /** Frames per second */
+    fps: number;
+    /** Average frame render time in ms */
+    frameTime: number;
+    /** Peak frame render time in ms */
+    peakFrameTime: number;
+    /** Memory usage statistics */
+    memory?: {
+        usedJSHeapSize: number;
+        totalJSHeapSize: number;
+        jsHeapSizeLimit: number;
+    };
+    /** Timestamp of measurement */
+    timestamp: number;
+    /** Whether performance is degrading */
+    isDegraded: boolean;
+}
+/**
+ * Performance monitor configuration
+ */
+interface PerformanceMonitorConfig {
+    /** Target FPS threshold (default: 60) */
+    fpsTarget?: number;
+    /** How frequently to sample (default: 500ms) */
+    sampleInterval?: number;
+    /** Callback for performance updates */
+    onUpdate?: (metrics: PerformanceMetrics) => void;
+    /** Callback when performance degrades */
+    onDegraded?: (metrics: PerformanceMetrics) => void;
+    /** Enable/disable memory monitoring */
+    enableMemoryMonitoring?: boolean;
+}
+/**
+ * Performance monitor class
+ */
+declare class PerformanceMonitor {
+    config: Required<PerformanceMonitorConfig>;
+    private frameCount;
+    private lastSampleTime;
+    private lastFpsUpdate;
+    private frameTimes;
+    private animationFrameId;
+    private isActive;
+    private startTime;
+    /**
+     * Create a new performance monitor
+     *
+     * @param config Configuration options
+     */
+    constructor(config?: PerformanceMonitorConfig);
+    /**
+     * Start monitoring performance
+     */
+    start(): void;
+    /**
+     * Stop monitoring performance
+     */
+    stop(): void;
+    /**
+     * Get current performance metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Get the current FPS
+     */
+    getFps(): number;
+    /**
+     * Check if performance is degraded
+     */
+    isPerformanceDegraded(): boolean;
+    /**
+     * Private method called on each animation frame
+     */
+    private onFrame;
+    /**
+     * Run a performance test for a specific function
+     *
+     * @param fn Function to test
+     * @param iterations Number of iterations (default: 100)
+     * @returns Average execution time in ms
+     */
+    testFunctionPerformance(fn: () => void, iterations?: number): Promise<number>;
+}
+/**
+ * Create a performance monitor instance
+ *
+ * @param config Configuration options
+ * @returns PerformanceMonitor instance
+ *
+ * @example
+ * ```typescript
+ * import { createPerformanceMonitor } from '@shohojdhara/atomix/theme';
+ *
+ * const monitor = createPerformanceMonitor({
+ *   fpsTarget: 60,
+ *   onUpdate: (metrics) => console.log('FPS:', metrics.fps),
+ *   onDegraded: (metrics) => console.warn('Performance degraded!', metrics),
+ * });
+ *
+ * monitor.start();
+ *
+ * // Later...
+ * monitor.stop();
+ * ```
+ */
+declare function createPerformanceMonitor(config?: PerformanceMonitorConfig): PerformanceMonitor;
+/**
+ * Hook for React components to monitor performance
+ *
+ * @param config Configuration options
+ * @returns Performance metrics and monitor controls
+ *
+ * @example
+ * ```typescript
+ * import { usePerformanceMonitor } from '@shohojdhara/atomix/theme';
+ *
+ * function MyComponent() {
+ *   const { metrics, start, stop } = usePerformanceMonitor({ fpsTarget: 60 });
+ *
+ *   useEffect(() => {
+ *     start();
+ *     return () => stop();
+ *   }, []);
+ *
+ *   return <div>FPS: {metrics.fps}</div>;
+ * }
+ * ```
+ */
+declare function usePerformanceMonitor(config?: PerformanceMonitorConfig): {
+    metrics: PerformanceMetrics;
+    start: () => void;
+    stop: () => void;
+};
+
+/**
+ * Responsive Utility for Atomix Theme System
+ *
+ * Provides responsive breakpoint detection and device-aware parameter scaling
+ * based on configuration from the advanced optimization features.
+ */
+/**
+ * Breakpoint definitions
+ */
+interface Breakpoints {
+    mobile: string;
+    tablet: string;
+    desktop: string;
+    wide: string;
+}
+/**
+ * Device scaling factors
+ */
+interface DeviceScaling {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+}
+/**
+ * Responsive configuration
+ */
+interface ResponsiveConfig {
+    breakpoints: Breakpoints;
+    deviceScaling: DeviceScaling;
+}
+/**
+ * Current device type
+ */
+type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'wide';
+/**
+ * Responsive utility class
+ */
+declare class ResponsiveUtil {
+    private config;
+    private currentDevice;
+    private resizeHandler;
+    private observer;
+    constructor(config: ResponsiveConfig);
+    /**
+     * Get the current device type based on viewport width
+     */
+    getCurrentDeviceType(): DeviceType;
+    /**
+     * Get the scaling factor for the current device
+     */
+    getCurrentScalingFactor(): number;
+    /**
+     * Scale a value based on the current device's scaling factor
+     */
+    scaleValue(value: number): number;
+    /**
+     * Check if the current device matches a specific type
+     */
+    isDevice(device: DeviceType): boolean;
+    /**
+     * Check if the current device is mobile or smaller
+     */
+    isMobileOrSmaller(): boolean;
+    /**
+     * Check if the current device is tablet or smaller
+     */
+    isTabletOrSmaller(): boolean;
+    /**
+     * Check if the current device is desktop or larger
+     */
+    isDesktopOrLarger(): boolean;
+    /**
+     * Update the responsive configuration
+     */
+    updateConfig(config: ResponsiveConfig): void;
+    /**
+     * Destroy the responsive utility and clean up listeners
+     */
+    destroy(): void;
+    /**
+     * Parse a CSS value to pixels
+     */
+    private parsePxValue;
+    /**
+     * Set up the resize listener
+     */
+    private setupResizeListener;
+}
+/**
+ * Create a responsive utility instance
+ *
+ * @param config Responsive configuration
+ * @returns ResponsiveUtil instance
+ */
+declare function createResponsiveUtil(config: ResponsiveConfig): ResponsiveUtil;
+/**
+ * Hook for React components to use responsive features
+ *
+ * @param config Responsive configuration
+ * @returns Current device type and utility functions
+ */
+declare function useResponsive(config: ResponsiveConfig): {
+    deviceType: DeviceType;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+    isWide: boolean;
+    scaleValue: (value: number) => number;
+    getCurrentDeviceType: () => DeviceType;
+    getCurrentScalingFactor: () => number;
+    isMobileOrSmaller: () => boolean;
+    isTabletOrSmaller: () => boolean;
+    isDesktopOrLarger: () => boolean;
+};
+
 /**
  * RTL (Right-to-Left) Support Utilities
  *
@@ -1728,26 +2844,24 @@ declare class RTLManager {
      */
     destroy(): void;
 }
-
 /**
- * Theme System Exports
- *
- * Simplified theme system using DesignTokens only.
- *
- * @example
- * ```typescript
- * import { createTheme, injectTheme } from '@shohojdhara/atomix/theme';
- *
- * // Using DesignTokens
- * const css = createTheme({ 'primary': '#7AFFD7', 'spacing-4': '1rem' });
- * injectTheme(css);
+ * Create RTL manager instance
+ */
+declare function createRTLManager(config?: RTLConfig): RTLManager;
+/**
+ * Check if locale is RTL
+ */
+declare function isRTLLocale(locale: string): boolean;
+/**
+ * Get direction from locale
+ */
+declare function getDirectionFromLocale(locale: string): 'ltr' | 'rtl';
+/**
+ * RTL-aware CSS helper
  *
- * // Or use with ThemeProvider
- * import { ThemeProvider } from '@shohojdhara/atomix/theme';
- * const tokens = { 'primary': '#7c3aed' };
- * <ThemeProvider defaultTheme={tokens}>...</ThemeProvider>
- * ```
+ * Returns appropriate CSS based on direction
  */
+declare function rtlCSS(ltrCSS: string, rtlCSS: string, direction?: 'ltr' | 'rtl'): string;
 
 /**
  * Inject theme CSS into DOM
@@ -1758,5 +2872,5 @@ declare function injectTheme(css: string, id?: string): void;
  */
 declare function removeTheme(id?: string): void;
 
-export { DesignTokensCustomizer, RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeValidator, applyCSSVariables, applyComponentTheme, applyTheme, camelToKebab, clearThemes, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, deepMerge, defaultTokens, designTokensToCSSVars, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, getAllThemes, getCSSVariable, getComponentThemeValue, getTheme, getThemeApplicator, getThemeCount, getThemeIds, hasTheme, injectCSS, injectTheme, isCSSInjected, isDesignTokens, isValidCSSVariableName, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, normalizeThemeTokens, registerTheme, removeCSS, removeCSSVariables, removeTheme, themePropertyToCSSVar, unregisterTheme, useComponentTheme, useHistory, useTheme, useThemeTokens };
-export type { A11yIssue, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOptions, ComponentThemeOverride, DesignTokens, DesignTokensCustomizerProps, GenerateCSSVariablesOptions, NamingOptions, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemePreviewProps, ThemeProviderProps, ThemeValidationResult, UseHistoryOptions, UseHistoryReturn, UseThemeReturn, ValidationResult };
+export { DesignTokensCustomizer, RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeToggle, ThemeValidator, alpha, applyCSSVariables, applyComponentTheme, applyTheme, camelToKebab, clearThemePreference, clearThemes, configToTokens, createPerformanceMonitor, createRTLManager, createResponsiveUtil, createSpacing, createTheme, createThemeRegistry, createTokens, cssVarsToStyle, darken, deepMerge, defaultTokens, designTokensToCSSVars, emphasize, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, getAllThemes, getCSSVariable, getComponentThemeValue, getContrastRatio, getContrastText, getCurrentTheme, getDirectionFromLocale, getLuminance, getSystemTheme, getTheme, getThemeApplicator, getThemeCount, getThemeIds, hasTheme, hexToRgb, initializeTheme, injectCSS, injectTheme, isAccessible, isCSSInjected, isDesignTokens, isRTLLocale, isValidCSSVariableName, lighten, listenToSystemTheme, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, mergeTokens, normalizeThemeTokens, omitTokens, overrideTokens, persistTheme, pickTokens, registerTheme, removeCSS, removeCSSVariables, removeTheme, rgbToHex, rtlCSS, switchTheme, themePropertyToCSSVar, toggleTheme, unregisterTheme, useComponentTheme, useHistory, usePerformanceMonitor, useResponsive, useTheme, useThemeSwitcher, useThemeTokens };
+export type { A11yIssue, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOptions, ComponentThemeOverride, DesignTokens, DesignTokensCustomizerProps, GenerateCSSVariablesOptions, NamingOptions, PerformanceMetrics, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemeMode, ThemePersistenceOptions, ThemePreviewProps, ThemeProviderProps, ThemeSwitcherOptions, ThemeToggleProps, ThemeValidationResult, UseHistoryOptions, UseHistoryReturn, UseThemeReturn, UseThemeSwitcherOptions, UseThemeSwitcherReturn, ValidationResult };