@shohojdhara/atomix 0.3.5 → 0.3.6

package/dist/theme.d.ts

@@ -2,1446 +2,1363 @@ import * as React$1 from 'react';
 import React__default, { ReactNode, ErrorInfo, Component } from 'react';
 
 /**
- * RTL (Right-to-Left) Support Utilities
+ * Design Tokens
  *
- * Provides utilities for managing RTL text direction in themes
+ * Simple flat structure for design tokens.
+ * All tokens match the actual CSS variables used in Atomix.
+ * Based on docs/tokes-list.md
  */
 /**
- * RTL configuration options
- */
-interface RTLConfig {
-    /** Enable RTL mode */
-    enabled: boolean;
-    /** Current direction ('ltr' | 'rtl') */
-    direction: 'ltr' | 'rtl';
-    /** Data attribute name for direction */
-    dataAttribute?: string;
-    /** Auto-detect from locale */
-    autoDetect?: boolean;
-    /** Locale code (e.g., 'ar', 'he', 'fa') */
-    locale?: string;
+ * Design tokens interface
+ *
+ * Flat structure - no nesting complexity.
+ * Keys use kebab-case format matching CSS variable names (without --atomix- prefix).
+ */
+interface DesignTokens {
+    'primary': string;
+    'secondary': string;
+    'success': string;
+    'info': string;
+    'warning': string;
+    'error': string;
+    'light': string;
+    'dark': string;
+    'primary-rgb': string;
+    'secondary-rgb': string;
+    'success-rgb': string;
+    'info-rgb': string;
+    'warning-rgb': string;
+    'error-rgb': string;
+    'light-rgb': string;
+    'dark-rgb': string;
+    'gray-1': string;
+    'gray-2': string;
+    'gray-3': string;
+    'gray-4': string;
+    'gray-5': string;
+    'gray-6': string;
+    'gray-7': string;
+    'gray-8': string;
+    'gray-9': string;
+    'gray-10': string;
+    'primary-1': string;
+    'primary-2': string;
+    'primary-3': string;
+    'primary-4': string;
+    'primary-5': string;
+    'primary-6': string;
+    'primary-7': string;
+    'primary-8': string;
+    'primary-9': string;
+    'primary-10': string;
+    'red-1': string;
+    'red-2': string;
+    'red-3': string;
+    'red-4': string;
+    'red-5': string;
+    'red-6': string;
+    'red-7': string;
+    'red-8': string;
+    'red-9': string;
+    'red-10': string;
+    'green-1': string;
+    'green-2': string;
+    'green-3': string;
+    'green-4': string;
+    'green-5': string;
+    'green-6': string;
+    'green-7': string;
+    'green-8': string;
+    'green-9': string;
+    'green-10': string;
+    'blue-1': string;
+    'blue-2': string;
+    'blue-3': string;
+    'blue-4': string;
+    'blue-5': string;
+    'blue-6': string;
+    'blue-7': string;
+    'blue-8': string;
+    'blue-9': string;
+    'blue-10': string;
+    'yellow-1': string;
+    'yellow-2': string;
+    'yellow-3': string;
+    'yellow-4': string;
+    'yellow-5': string;
+    'yellow-6': string;
+    'yellow-7': string;
+    'yellow-8': string;
+    'yellow-9': string;
+    'yellow-10': string;
+    'primary-text-emphasis': string;
+    'secondary-text-emphasis': string;
+    'tertiary-text-emphasis': string;
+    'disabled-text-emphasis': string;
+    'invert-text-emphasis': string;
+    'brand-text-emphasis': string;
+    'error-text-emphasis': string;
+    'success-text-emphasis': string;
+    'warning-text-emphasis': string;
+    'info-text-emphasis': string;
+    'light-text-emphasis': string;
+    'dark-text-emphasis': string;
+    'primary-bg-subtle': string;
+    'secondary-bg-subtle': string;
+    'tertiary-bg-subtle': string;
+    'invert-bg-subtle': string;
+    'brand-bg-subtle': string;
+    'error-bg-subtle': string;
+    'success-bg-subtle': string;
+    'warning-bg-subtle': string;
+    'info-bg-subtle': string;
+    'light-bg-subtle': string;
+    'dark-bg-subtle': string;
+    'primary-border-subtle': string;
+    'secondary-border-subtle': string;
+    'success-border-subtle': string;
+    'error-border-subtle': string;
+    'warning-border-subtle': string;
+    'info-border-subtle': string;
+    'brand-border-subtle': string;
+    'light-border-subtle': string;
+    'dark-border-subtle': string;
+    'primary-hover': string;
+    'secondary-hover': string;
+    'light-hover': string;
+    'dark-hover': string;
+    'error-hover': string;
+    'success-hover': string;
+    'warning-hover': string;
+    'info-hover': string;
+    'primary-gradient': string;
+    'secondary-gradient': string;
+    'light-gradient': string;
+    'dark-gradient': string;
+    'success-gradient': string;
+    'info-gradient': string;
+    'warning-gradient': string;
+    'error-gradient': string;
+    'gradient': string;
+    'font-sans-serif': string;
+    'font-monospace': string;
+    'body-font-family': string;
+    'body-font-size': string;
+    'body-font-weight': string;
+    'body-line-height': string;
+    'body-color': string;
+    'body-bg': string;
+    'heading-color': string;
+    'font-size-xl': string;
+    'font-size-2xl': string;
+    'display-1': string;
+    'font-weight-light': string;
+    'font-weight-normal': string;
+    'font-weight-medium': string;
+    'font-weight-semibold': string;
+    'font-weight-bold': string;
+    'font-weight-heavy': string;
+    'font-weight-black': string;
+    'line-height-base': string;
+    'line-height-sm': string;
+    'line-height-lg': string;
+    'letter-spacing-h1': string;
+    'letter-spacing-h2': string;
+    'letter-spacing-h3': string;
+    'letter-spacing-h4': string;
+    'letter-spacing-h5': string;
+    'letter-spacing-h6': string;
+    'link-color': string;
+    'link-color-rgb': string;
+    'link-decoration': string;
+    'link-hover-color': string;
+    'link-hover-color-rgb': string;
+    'highlight-bg': string;
+    'code-color': string;
+    'border-width': string;
+    'border-style': string;
+    'border-color': string;
+    'border-color-translucent': string;
+    'border-radius': string;
+    'border-radius-sm': string;
+    'border-radius-lg': string;
+    'border-radius-xl': string;
+    'border-radius-xxl': string;
+    'border-radius-2xl': string;
+    'border-radius-3xl': string;
+    'border-radius-4xl': string;
+    'border-radius-pill': string;
+    'box-shadow': string;
+    'box-shadow-xs': string;
+    'box-shadow-sm': string;
+    'box-shadow-lg': string;
+    'box-shadow-xl': string;
+    'box-shadow-inset': string;
+    'focus-border-color': string;
+    'focus-ring-width': string;
+    'focus-ring-offset': string;
+    'focus-ring-opacity': string;
+    'form-valid-color': string;
+    'form-valid-border-color': string;
+    'form-invalid-color': string;
+    'form-invalid-border-color': string;
+    'spacing-0': string;
+    'spacing-1': string;
+    'spacing-px-6': string;
+    'spacing-2': string;
+    'spacing-px-10': string;
+    'spacing-3': string;
+    'spacing-px-14': string;
+    'spacing-4': string;
+    'spacing-5': string;
+    'spacing-px-22': string;
+    'spacing-6': string;
+    'spacing-7': string;
+    'spacing-px-30': string;
+    'spacing-8': string;
+    'spacing-9': string;
+    'spacing-10': string;
+    'spacing-11': string;
+    'spacing-12': string;
+    'spacing-14': string;
+    'spacing-16': string;
+    'spacing-20': string;
+    'spacing-24': string;
+    'spacing-28': string;
+    'spacing-32': string;
+    'spacing-36': string;
+    'spacing-40': string;
+    'spacing-44': string;
+    'spacing-48': string;
+    'spacing-52': string;
+    'spacing-56': string;
+    'spacing-60': string;
+    'spacing-64': string;
+    'spacing-72': string;
+    'spacing-80': string;
+    'spacing-90': string;
+    'spacing-200': string;
+    'transition-duration-fast': string;
+    'transition-duration-base': string;
+    'transition-duration-slow': string;
+    'transition-duration-slower': string;
+    'easing-base': string;
+    'easing-ease-in-out': string;
+    'easing-ease-out': string;
+    'easing-ease-in': string;
+    'easing-ease-linear': string;
+    'transition-fast': string;
+    'transition-base': string;
+    'transition-slow': string;
+    'z-n1': string;
+    'z-0': string;
+    'z-1': string;
+    'z-2': string;
+    'z-3': string;
+    'z-4': string;
+    'z-5': string;
+    'z-dropdown': string;
+    'z-sticky': string;
+    'z-fixed': string;
+    'z-modal': string;
+    'z-popover': string;
+    'z-tooltip': string;
+    'z-drawer': string;
+    'breakpoint-xs': string;
+    'breakpoint-sm': string;
+    'breakpoint-md': string;
+    'breakpoint-lg': string;
+    'breakpoint-xl': string;
+    'breakpoint-xxl': string;
+    [key: string]: string | undefined;
 }
 /**
- * RTL Manager
+ * Default design tokens
  *
- * Manages RTL text direction for the theme system
+ * Based on Atomix default theme values from docs/tokes-list.md (light mode)
  */
-declare class RTLManager {
-    private config;
-    private listeners;
-    constructor(config?: Partial<RTLConfig>);
-    /**
-     * Detect locale from browser
-     */
-    private detectLocale;
-    /**
-     * Check if locale is RTL
-     */
-    isRTLLocale(locale: string): boolean;
-    /**
-     * Get current direction
-     */
-    getDirection(): 'ltr' | 'rtl';
-    /**
-     * Check if RTL is enabled
-     */
-    isEnabled(): boolean;
-    /**
-     * Set direction
-     */
-    setDirection(direction: 'ltr' | 'rtl'): void;
-    /**
-     * Toggle direction
-     */
-    toggleDirection(): 'ltr' | 'rtl';
-    /**
-     * Enable RTL
-     */
-    enable(): void;
-    /**
-     * Disable RTL
-     */
-    disable(): void;
-    /**
-     * Set locale and auto-adjust direction
-     */
-    setLocale(locale: string): void;
-    /**
-     * Get current locale
-     */
-    getLocale(): string | undefined;
-    /**
-     * Apply direction to DOM
-     */
-    private applyDirection;
-    /**
-     * Add direction change listener
-     */
-    onDirectionChange(callback: (direction: 'ltr' | 'rtl') => void): () => void;
-    /**
-     * Notify listeners of direction change
-     */
-    private notifyListeners;
-    /**
-     * Get RTL-aware value
-     *
-     * Returns different values based on direction
-     */
-    getValue<T>(ltrValue: T, rtlValue: T): T;
-    /**
-     * Get RTL-aware CSS property
-     *
-     * Returns appropriate CSS property based on direction
-     */
-    getCSSProperty(property: string): string;
-    /**
-     * Destroy RTL manager
-     */
-    destroy(): void;
-}
-
+declare const defaultTokens: DesignTokens;
 /**
- * Atomix Configuration System
- *
- * Tailwind-like configuration for customizing the Atomix Design System.
+ * Create tokens from defaults and overrides
  *
- * External developers can create `atomix.config.ts` in their project root
- * to customize design tokens, similar to Tailwind's tailwind.config.js
+ * @param overrides - Partial tokens to override defaults
+ * @returns Complete DesignTokens object
  *
  * @example
  * ```typescript
- * // atomix.config.ts (in your project)
- * import { defineConfig } from '@shohojdhara/atomix/config';
- *
- * export default defineConfig({
- *   theme: {
- *     extend: {
- *       colors: {
- *         primary: { main: '#7AFFD7' },
- *       },
- *     },
- *   },
+ * const tokens = createTokens({
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
  * });
  * ```
  */
+declare function createTokens(overrides?: Partial<DesignTokens>): DesignTokens;
 
 /**
- * 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
+ * Theme Manager Type Definitions
+ *
+ * TypeScript types and interfaces for the Atomix Design System theme management system.
  */
-interface PaletteColorOptions {
-    main: string;
-    light?: string;
-    dark?: string;
-    contrastText?: string;
-}
-/**
- * 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
+ * Theme metadata interface matching themes.config.js structure
  */
-interface CSSThemeDefinition {
-    type: 'css';
+interface ThemeMetadata {
+    /** Display name of the theme */
     name: string;
+    /** Unique identifier/class name for the theme */
     class?: string;
+    /** Theme description */
     description?: string;
+    /** Theme author */
     author?: string;
+    /** Theme version (semver) */
     version?: string;
+    /** Theme tags for categorization */
     tags?: string[];
+    /** Whether the theme supports dark mode */
     supportsDarkMode?: boolean;
+    /** Theme status: stable, beta, experimental, deprecated */
     status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    /** Accessibility information */
     a11y?: {
+        /** Target contrast ratio */
         contrastTarget?: number;
+        /** Supported color modes */
         modes?: string[];
     };
+    /** Primary theme color (for UI display) */
     color?: string;
+    /** Theme features list */
     features?: string[];
+    /** Theme dependencies (other themes required) */
     dependencies?: string[];
-    cssPath?: string;
 }
 /**
- * JavaScript Theme Definition
+ * Theme change event payload
  */
-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;
+interface ThemeChangeEvent {
+    /** Previous theme name */
+    previousTheme: string | null;
+    /** New theme name */
+    currentTheme: string;
+    /** Theme object (for JS themes) */
+    themeObject?: Theme | null;
+    /** Timestamp of the change */
+    timestamp: number;
+    /** Whether the change was from user action or system */
+    source: 'user' | 'system' | 'storage';
 }
 /**
- * Theme Definition (CSS or JS)
- */
-type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
-/**
- * Build configuration (migrated from theme.config.ts)
+ * Theme load options
  */
-interface BuildConfig {
-    output?: {
-        directory?: string;
-        formats?: {
-            expanded?: string;
-            compressed?: string;
-        };
-    };
-    sass?: {
-        style?: 'expanded' | 'compressed';
-        sourceMap?: boolean;
-        loadPaths?: string[];
-    };
+interface ThemeLoadOptions {
+    /** Force reload even if already loaded */
+    force?: boolean;
+    /** Preload without applying */
+    preload?: boolean;
+    /** Remove previous theme CSS */
+    removePrevious?: boolean;
+    /** Custom CSS path override */
+    customPath?: string;
+    /** Fallback to default theme on error */
+    fallbackOnError?: boolean;
 }
 /**
- * Runtime configuration (migrated from theme.config.ts)
+ * Theme validation result
  */
-interface RuntimeConfig {
-    basePath?: string;
-    cdnPath?: string | null;
-    preload?: string[];
-    lazy?: boolean;
-    defaultTheme?: string;
-    storageKey?: string;
-    dataAttribute?: string;
-    enablePersistence?: boolean;
-    useMinified?: boolean;
+interface ThemeValidationResult {
+    /** Whether the theme is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
 }
 /**
- * Integration settings (migrated from theme.config.ts)
+ * React hook return type for useTheme
  */
-interface IntegrationConfig {
-    cssVariables?: Record<string, string>;
-    classNames?: {
-        theme?: string;
-        colorMode?: string;
-    };
+interface UseThemeReturn {
+    /** Current theme name */
+    theme: string;
+    /** Current active theme object (for JS themes) */
+    activeTheme: Theme | null;
+    /** Function to change theme (supports string, Theme, or DesignTokens) */
+    setTheme: (theme: string | Theme | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Available themes */
+    availableThemes: ThemeMetadata[];
+    /** Whether a theme is currently loading */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Whether a specific theme is loaded */
+    isThemeLoaded: (themeName: string) => boolean;
+    /** Preload a theme */
+    preloadTheme: (themeName: string) => Promise<void>;
 }
 /**
- * Atomix Configuration Interface
- *
- * Tailwind-like configuration for external developers.
- * Focus on theme customization - build/runtime configs are internal only.
+ * Component-level theme override configuration
  */
-interface AtomixConfig {
-    /**
-     * CSS variable prefix (default: 'atomix')
-     *
-     * Change this to customize all CSS variable names.
-     * Example: prefix: 'myapp' → --myapp-primary instead of --atomix-primary
-     */
-    prefix?: string;
-    /**
-     * Theme customization (Tailwind-like)
-     *
-     * Use `extend` to add or override design tokens.
-     * Use `tokens` to completely replace the default token system (advanced).
-     */
-    theme?: {
-        /**
-         * Extend the default design tokens
-         *
-         * This is the recommended way to customize Atomix.
-         * Your values will override or extend the base tokens.
-         */
-        extend?: ThemeTokens;
-        /**
-         * Override the default tokens entirely (advanced)
-         *
-         * Use with caution - this replaces the entire token system.
-         * Most users should use `extend` instead.
-         */
-        tokens?: ThemeTokens;
-        /**
-         * Register custom themes (optional)
-         *
-         * Define CSS or JavaScript themes that can be loaded dynamically.
-         */
-        themes?: Record<string, ThemeDefinition>;
-    };
-    /** @internal Build configuration (internal use only) */
-    build?: BuildConfig;
-    /** @internal Runtime configuration (internal use only) */
-    runtime?: RuntimeConfig;
-    /** @internal Integration settings (internal use only) */
-    integration?: IntegrationConfig;
-    /** @internal Theme dependencies mapping (internal use only) */
-    dependencies?: Record<string, string[]>;
-}
-
+interface ComponentThemeOverride {
+    /** CSS variable overrides for the component */
+    cssVars?: Record<string, string | number>;
+    /** Default prop overrides */
+    defaultProps?: Record<string, any>;
+    /** Part-specific overrides */
+    parts?: Record<string, {
+        cssVars?: Record<string, string | number>;
+        className?: string;
+    }>;
+    /** Variant overrides */
+    variants?: Record<string, {
+        cssVars?: Record<string, string | number>;
+        className?: string;
+    }>;
+    /** Additional className for the component */
+    className?: string;
+}
 /**
- * Theme Configuration Types
- *
- * Type definitions for the theme configuration system
+ * Theme component overrides for all components
  */
-
+interface ThemeComponentOverrides {
+    Button?: ComponentThemeOverride;
+    Card?: ComponentThemeOverride;
+    Input?: ComponentThemeOverride;
+    Modal?: ComponentThemeOverride;
+    Dropdown?: ComponentThemeOverride;
+    Badge?: ComponentThemeOverride;
+    Tabs?: ComponentThemeOverride;
+    Progress?: ComponentThemeOverride;
+    Tooltip?: ComponentThemeOverride;
+    Select?: ComponentThemeOverride;
+    Checkbox?: ComponentThemeOverride;
+    Radio?: ComponentThemeOverride;
+    Textarea?: ComponentThemeOverride;
+    FormGroup?: ComponentThemeOverride;
+    Navbar?: ComponentThemeOverride;
+    Accordion?: ComponentThemeOverride;
+    DataTable?: ComponentThemeOverride;
+    Avatar?: ComponentThemeOverride;
+    List?: ComponentThemeOverride;
+    Popover?: ComponentThemeOverride;
+    Messages?: ComponentThemeOverride;
+    Callout?: ComponentThemeOverride;
+    Spinner?: ComponentThemeOverride;
+    [key: string]: ComponentThemeOverride | undefined;
+}
 /**
- * Loaded and validated theme configuration
+ * Theme provider props
  */
-interface LoadedThemeConfig {
-    /** Registered themes */
-    themes: Record<string, ThemeDefinition>;
-    /** Build configuration */
-    build: BuildConfig;
-    /** Runtime configuration */
-    runtime: RuntimeConfig;
-    /** Integration settings */
-    integration: IntegrationConfig;
-    /** Theme dependencies mapping */
-    dependencies: Record<string, string[]>;
-    /** Whether config was validated */
-    validated: boolean;
-    /** Validation errors (if any) */
-    errors?: string[];
-    /** Validation warnings (if any) */
-    warnings?: string[];
-    /** Internal tokens (for generator) */
-    __tokens?: any;
-    /** Internal extensions (for generator) */
-    __extend?: any;
+interface ThemeProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Default theme */
+    defaultTheme?: string | Theme;
+    /** Available themes */
+    themes?: Record<string, ThemeMetadata>;
+    /** Base path for theme CSS */
+    basePath?: string;
+    /** CDN path for theme CSS */
+    cdnPath?: string | null;
+    /** Themes to preload */
+    preload?: string[];
+    /** Enable lazy loading */
+    lazy?: boolean;
+    /** localStorage key */
+    storageKey?: string;
+    /** Data attribute name */
+    dataAttribute?: string;
+    /** Enable persistence */
+    enablePersistence?: boolean;
+    /** Use minified CSS */
+    useMinified?: boolean;
+    /** Callback when theme changes */
+    onThemeChange?: (theme: string | Theme | DesignTokens) => void;
+    /** Callback on error */
+    onError?: (error: Error, themeName: string) => void;
 }
-
 /**
- * Theme Registry
- *
- * Central registry for all themes with discovery and dependency management
+ * Theme context value
  */
-
+interface ThemeContextValue {
+    /** Current theme name */
+    theme: string;
+    /** Current active theme object (for JS themes) */
+    activeTheme: Theme | null;
+    /** Set theme function (supports string, Theme, or DesignTokens) */
+    setTheme: (theme: string | Theme | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Available themes */
+    availableThemes: ThemeMetadata[];
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Check if theme is loaded */
+    isThemeLoaded: (themeName: string) => boolean;
+    /** Preload theme */
+    preloadTheme: (themeName: string) => Promise<void>;
+}
 /**
- * Registry entry
+ * Color palette configuration for a single color
  */
-interface RegistryEntry {
-    /** Theme ID */
-    id: string;
-    /** Theme definition from config */
-    definition: ThemeDefinition;
-    /** Resolved theme object (for JS themes) */
-    theme?: Theme;
-    /** Whether theme is loaded */
-    loaded: boolean;
-    /** Loading promise (if currently loading) */
-    loading?: Promise<Theme | void>;
-    /** Dependencies */
-    dependencies: string[];
-    /** Dependent themes (themes that depend on this one) */
-    dependents: string[];
+interface PaletteColor {
+    /** Main color value */
+    main: string;
+    /** Light variant (auto-generated if not provided) */
+    light?: string;
+    /** Dark variant (auto-generated if not provided) */
+    dark?: string;
+    /** Contrast text color (auto-generated if not provided) */
+    contrastText?: string;
 }
 /**
- * Theme Registry
- *
- * Manages theme registration, discovery, and dependency resolution
+ * Palette configuration options for createTheme
  */
-declare class ThemeRegistry {
-    private entries;
-    private config;
-    private initialized;
-    /**
-     * Initialize registry from config
-     */
-    initialize(config?: LoadedThemeConfig): Promise<void>;
-    /**
-     * Register a theme
-     */
-    register(themeId: string, definition: ThemeDefinition): void;
-    /**
-     * Get theme entry
-     */
-    get(themeId: string): RegistryEntry | undefined;
-    /**
-     * Check if theme exists
-     */
-    has(themeId: string): boolean;
-    /**
-     * Get all theme IDs
-     */
-    getAllIds(): string[];
-    /**
-     * Get all theme metadata
-     */
-    getAllMetadata(): ThemeMetadata[];
-    /**
-     * Get theme definition
-     */
-    getDefinition(themeId: string): ThemeDefinition | undefined;
-    /**
-     * Get theme object (for JS themes)
-     */
-    getTheme(themeId: string): Theme | undefined;
-    /**
-     * Set theme object (for JS themes)
-     */
-    setTheme(themeId: string, theme: Theme): void;
-    /**
-     * Get dependencies for a theme
-     */
-    getDependencies(themeId: string): string[];
-    /**
-     * Get dependents for a theme (themes that depend on this one)
-     */
-    getDependents(themeId: string): string[];
-    /**
-     * Resolve all dependencies in correct order
-     */
-    resolveDependencyOrder(themeId: string): string[];
-    /**
-     * Resolve dependencies and build dependency graph
-     */
-    private resolveDependencies;
-    /**
-     * Validate all themes
-     */
-    validate(): {
-        valid: boolean;
-        errors: string[];
+interface PaletteOptions {
+    /** Primary color configuration */
+    primary?: Partial<PaletteColor> | string;
+    /** Secondary color configuration */
+    secondary?: Partial<PaletteColor> | string;
+    /** Error color configuration */
+    error?: Partial<PaletteColor> | string;
+    /** Warning color configuration */
+    warning?: Partial<PaletteColor> | string;
+    /** Info color configuration */
+    info?: Partial<PaletteColor> | string;
+    /** Success color configuration */
+    success?: Partial<PaletteColor> | string;
+    /** Background colors */
+    background?: {
+        default?: string;
+        subtle?: string;
     };
-    /**
-     * Clear registry
-     */
-    clear(): void;
+    /** Text colors */
+    text?: {
+        primary?: string;
+        secondary?: string;
+        disabled?: string;
+    };
+    /** Additional custom colors */
+    [key: string]: any;
+}
+/**
+ * Typography configuration options for createTheme
+ */
+interface TypographyOptions {
+    /** Font family */
+    fontFamily?: string;
+    /** Base font size in pixels */
+    fontSize?: number;
+    /** Font weight scale */
+    fontWeightLight?: number;
+    fontWeightRegular?: number;
+    fontWeightMedium?: number;
+    fontWeightSemiBold?: number;
+    fontWeightBold?: number;
+    /** Heading configurations */
+    h1?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    h2?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    h3?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    h4?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    h5?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    h6?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+        letterSpacing?: string;
+    };
+    /** Body text configurations */
+    body1?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+    };
+    body2?: {
+        fontSize?: string | number;
+        fontWeight?: number;
+        lineHeight?: number | string;
+    };
+    /** Additional custom typography */
+    [key: string]: any;
+}
+/**
+ * Spacing function type
+ */
+type SpacingFunction = (...values: number[]) => string;
+/**
+ * Spacing configuration options for createTheme
+ */
+type SpacingOptions = number | number[] | SpacingFunction;
+/**
+ * Breakpoint values configuration
+ */
+interface BreakpointValues {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    [key: string]: number | undefined;
+}
+/**
+ * Breakpoints configuration options for createTheme
+ */
+interface BreakpointsOptions {
+    /** Breakpoint values in pixels */
+    values?: BreakpointValues;
+    /** Unit for breakpoints (default: 'px') */
+    unit?: string;
+}
+/**
+ * Shadow configuration
+ */
+interface ShadowOptions {
+    xs?: string;
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Transition configuration
+ */
+interface TransitionOptions {
+    /** Transition duration values */
+    duration?: {
+        shortest?: number;
+        shorter?: number;
+        short?: number;
+        standard?: number;
+        complex?: number;
+        enteringScreen?: number;
+        leavingScreen?: number;
+    };
+    /** Easing functions */
+    easing?: {
+        easeInOut?: string;
+        easeOut?: string;
+        easeIn?: string;
+        sharp?: string;
+    };
+}
+/**
+ * Z-index configuration
+ */
+interface ZIndexOptions {
+    mobileStepper?: number;
+    speedDial?: number;
+    appBar?: number;
+    drawer?: number;
+    modal?: number;
+    snackbar?: number;
+    tooltip?: number;
+    [key: string]: number | undefined;
+}
+/**
+ * Border radius configuration
+ */
+interface BorderRadiusOptions {
+    /** Base border radius */
+    base?: string | number;
+    /** Small border radius */
+    sm?: string | number;
+    /** Medium border radius */
+    md?: string | number;
+    /** Large border radius */
+    lg?: string | number;
+    /** Extra large border radius */
+    xl?: string | number;
+    /** 2X large border radius */
+    xxl?: string | number;
+    /** 3X large border radius */
+    '3xl'?: string | number;
+    /** 4X large border radius */
+    '4xl'?: string | number;
+    /** Pill shape (fully rounded) */
+    pill?: string | number;
+    [key: string]: string | number | undefined;
+}
+/**
+ * Custom theme properties for extension
+ * Users can augment this interface via module augmentation
+ */
+interface ThemeCustomProperties {
+    [key: string]: any;
+}
+/**
+ * Theme configuration options for createTheme
+ * Extends ThemeMetadata to support both CSS and JS theme properties
+ */
+interface ThemeOptions extends Partial<ThemeMetadata> {
+    /** Color palette configuration */
+    palette?: PaletteOptions;
+    /** Typography configuration */
+    typography?: TypographyOptions;
+    /** Spacing configuration */
+    spacing?: SpacingOptions;
+    /** Breakpoints configuration */
+    breakpoints?: BreakpointsOptions;
+    /** Shadow configuration */
+    shadows?: ShadowOptions;
+    /** Transition configuration */
+    transitions?: TransitionOptions;
+    /** Z-index configuration */
+    zIndex?: ZIndexOptions;
+    /** Border radius configuration */
+    borderRadius?: BorderRadiusOptions;
+    /** Custom properties */
+    custom?: ThemeCustomProperties;
+}
+/**
+ * Complete theme object with computed values
+ * Generated by createTheme function
+ */
+interface Theme extends ThemeMetadata {
+    /** Color palette with computed values */
+    palette: {
+        primary: PaletteColor;
+        secondary: PaletteColor;
+        error: PaletteColor;
+        warning: PaletteColor;
+        info: PaletteColor;
+        success: PaletteColor;
+        background: {
+            default: string;
+            paper: string;
+            subtle: string;
+        };
+        text: {
+            primary: string;
+            secondary: string;
+            disabled: string;
+        };
+        [key: string]: any;
+    };
+    /** Typography with computed values */
+    typography: {
+        fontFamily: string;
+        fontSize: number;
+        fontWeightLight: number;
+        fontWeightRegular: number;
+        fontWeightMedium: number;
+        fontWeightSemiBold: number;
+        fontWeightBold: number;
+        h1: Required<NonNullable<TypographyOptions['h1']>>;
+        h2: Required<NonNullable<TypographyOptions['h2']>>;
+        h3: Required<NonNullable<TypographyOptions['h3']>>;
+        h4: Required<NonNullable<TypographyOptions['h4']>>;
+        h5: Required<NonNullable<TypographyOptions['h5']>>;
+        h6: Required<NonNullable<TypographyOptions['h6']>>;
+        body1: Required<NonNullable<TypographyOptions['body1']>>;
+        body2: Required<NonNullable<TypographyOptions['body2']>>;
+        [key: string]: any;
+    };
+    /** Spacing function */
+    spacing: SpacingFunction;
+    /** Breakpoints with computed values */
+    breakpoints: {
+        values: Required<BreakpointValues>;
+        unit: string;
+        up: (key: keyof BreakpointValues | number) => string;
+        down: (key: keyof BreakpointValues | number) => string;
+        between: (start: keyof BreakpointValues | number, end: keyof BreakpointValues | number) => string;
+    };
+    /** Shadows */
+    shadows: Required<ShadowOptions>;
+    /** Transitions */
+    transitions: Required<TransitionOptions>;
+    /** Z-index values */
+    zIndex: Required<ZIndexOptions>;
+    /** Border radius values */
+    borderRadius: Required<BorderRadiusOptions>;
+    /** Custom properties */
+    custom: ThemeCustomProperties;
+    /** Global CSS variables to apply */
+    cssVars?: Record<string, string | number>;
+    /** Indicates this is a JS theme (not CSS-only) */
+    __isJSTheme: true;
 }
 
 /**
- * Theme Cache
+ * CSS Variable Generator
  *
- * Performance caching layer for loaded themes (CSS and JS)
+ * Generates CSS custom properties from design tokens.
  */
 
 /**
- * Cache entry for CSS theme
- */
-interface CSSCacheEntry {
-    type: 'css' | 'js';
-    themeId: string;
-    cssContent?: string;
-    loaded: boolean;
-    loading: Promise<void> | null;
-    timestamp: number;
-}
-/**
- * Cache entry for JS theme
+ * Options for CSS variable generation
  */
-interface JSCacheEntry {
-    type: 'js';
-    themeId: string;
-    theme: Theme;
-    loaded: boolean;
-    timestamp: number;
+interface GenerateCSSVariablesOptions {
+    /** CSS selector for the variables (default: ':root') */
+    selector?: string;
+    /** Prefix for CSS variables (default: 'atomix') */
+    prefix?: string;
 }
 /**
- * Theme cache configuration
+ * 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}"
+ * ```
  */
-interface CacheConfig {
-    /** Maximum cache size (number of themes) */
-    maxSize?: number;
-    /** Cache TTL in milliseconds (0 = no expiration) */
-    ttl?: number;
-    /** Enable cache */
-    enabled?: boolean;
-}
+declare function generateCSSVariables(tokens: DesignTokens, options?: GenerateCSSVariablesOptions): string;
 /**
- * Theme Cache
+ * Generate CSS variables with custom selector
  *
- * Manages caching of loaded themes for performance optimization
+ * 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 class ThemeCache {
-    private cache;
-    private config;
-    private accessOrder;
-    constructor(config?: CacheConfig);
-    /**
-     * Get cached CSS theme
-     */
-    getCSS(themeId: string): CSSCacheEntry | null;
-    /**
-     * Get cached JS theme
-     */
-    getJS(themeId: string): JSCacheEntry | null;
-    /**
-     * Set CSS theme cache entry
-     */
-    setCSS(themeId: string, entry: Partial<CSSCacheEntry>): void;
-    /**
-     * Set JS theme cache entry
-     */
-    setJS(themeId: string, theme: Theme): void;
-    /**
-     * Check if theme is cached
-     */
-    has(themeId: string): boolean;
-    /**
-     * Remove theme from cache
-     */
-    delete(themeId: string): boolean;
-    /**
-     * Clear all cache
-     */
-    clear(): void;
-    /**
-     * Get cache statistics
-     */
-    getStats(): {
-        size: number;
-        maxSize: number;
-        cssThemes: number;
-        jsThemes: number;
-    };
-    /**
-     * Update access order for LRU
-     */
-    private updateAccessOrder;
-    /**
-     * Remove from access order
-     */
-    private removeFromAccessOrder;
-    /**
-     * Evict least recently used entries if cache is full
-     */
-    private evictIfNeeded;
-}
+declare function generateCSSVariablesForSelector(tokens: DesignTokens, selector: string, prefix?: string): string;
 
 /**
- * Theme Engine
+ * Core Theme Functions
  *
- * Core engine for unified CSS and JS theme support
+ * Unified theme system that handles both DesignTokens and Theme objects.
+ * Config-first approach: loads from atomix.config.ts when no input is provided.
+ * Config file is required for automatic loading.
  */
 
 /**
- * Theme change event
+ * 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' });
+ * ```
  */
-interface ThemeChangeEvent$1 {
-    /** Previous theme ID */
-    previousTheme: string | null;
-    /** Current theme ID */
-    currentTheme: string;
-    /** Theme object (for JS themes) */
-    themeObject?: Theme | null;
-    /** Timestamp */
-    timestamp: number;
-    /** Source of change */
-    source: 'user' | 'system' | 'storage';
-}
+declare function createTheme(input?: Partial<DesignTokens> | Theme, options?: GenerateCSSVariablesOptions): string;
+
 /**
- * Theme load options
+ * createThemeObject - Create a theme object with computed values
+ *
+ * Similar to Material-UI's createTheme, this function accepts theme configuration
+ * options and returns a complete theme object with computed values.
+ *
+ * NOTE: For most use cases, use the simple theme system's `createTheme` instead,
+ * which generates CSS from DesignTokens. This function is for advanced use cases
+ * that need the full Theme object structure.
+ *
+ * @example
+ * ```typescript
+ * const theme = createThemeObject({
+ *   palette: {
+ *     primary: { main: '#7AFFD7' },
+ *     secondary: { main: '#FF5733' },
+ *   },
+ *   typography: {
+ *     fontFamily: 'Inter, sans-serif',
+ *   },
+ * });
+ * ```
  */
-interface ThemeLoadOptions$1 {
-    /** Force reload even if already loaded */
-    force?: boolean;
-    /** Preload without applying */
-    preload?: boolean;
-    /** Remove previous theme CSS */
-    removePrevious?: boolean;
-    /** Custom CSS path override */
-    customPath?: string;
-    /** Fallback to default theme on error */
-    fallbackOnError?: boolean;
-}
+
 /**
- * Theme revert event
+ * Create a theme object with computed values
+ *
+ * @param options - Theme configuration options
+ * @returns Complete theme object
  */
-interface ThemeRevertEvent {
-    /** Theme ID that was attempted */
-    attemptedTheme: string;
-    /** Theme ID that was reverted to (null if no previous theme) */
-    revertedToTheme: string | null;
-    /** Error that caused the revert */
-    error: Error;
-    /** Timestamp */
-    timestamp: number;
-}
+declare function createThemeObject(...options: ThemeOptions[]): Theme;
+
 /**
- * Event listener types
+ * Theme Composition Utilities
+ *
+ * Utilities for composing, merging, and extending themes.
  */
-type ThemeChangeListener = (event: ThemeChangeEvent$1) => void;
-type ThemeLoadListener = (themeId: string) => void;
-type ThemeErrorListener = (error: Error, themeId: string) => void;
-type ThemeRevertListener = (event: ThemeRevertEvent) => void;
+
 /**
- * Theme Engine Configuration
+ * Deep merge multiple objects
+ * Later objects override earlier ones
  */
-interface ThemeEngineConfig {
-    /** Base path for CSS themes */
-    basePath?: string;
-    /** CDN path for CSS themes */
-    cdnPath?: string | null;
-    /** Use minified CSS */
-    useMinified?: boolean;
-    /** Data attribute name */
-    dataAttribute?: string;
-    /** Enable caching */
-    enableCache?: boolean;
-    /** Cache configuration */
-    cacheConfig?: {
-        maxSize?: number;
-        ttl?: number;
-    };
-    /** Custom style ID for JS theme CSS injection */
-    styleId?: string;
-}
+declare function deepMerge<T extends Record<string, any>>(...objects: Partial<T>[]): T;
 /**
- * Theme Engine
+ * Merge multiple theme options into a single theme options object
+ *
+ * @param themes - Theme options to merge
+ * @returns Merged theme options
  *
- * Unified engine for managing CSS and JS themes
+ * @example
+ * ```typescript
+ * const baseTheme = { palette: { primary: { main: '#000' } } };
+ * const customTheme = { palette: { secondary: { main: '#fff' } } };
+ * const merged = mergeTheme(baseTheme, customTheme);
+ * ```
  */
-declare class ThemeEngine {
-    private registry;
-    private cache;
-    private validator;
-    private config;
-    private currentTheme;
-    private activeTheme;
-    private loadedThemes;
-    private loadingThemes;
-    private failedThemes;
-    private changeListeners;
-    private loadListeners;
-    private errorListeners;
-    private revertListeners;
-    private logger;
-    constructor(config?: ThemeEngineConfig);
-    /**
-     * Initialize engine with theme registry
-     */
-    initialize(): Promise<void>;
-    /**
-     * Get current theme ID
-     */
-    getCurrentTheme(): string | null;
-    /**
-     * Get active theme object
-     */
-    getActiveTheme(): Theme | null;
-    /**
-     * Check if theme is loaded
-     */
-    isThemeLoaded(themeId: string): boolean;
-    /**
-     * Load and apply theme
-     */
-    setTheme(themeId: string | Theme, options?: ThemeLoadOptions$1): Promise<void>;
-    /**
-     * Load theme (CSS or JS)
-     */
-    private loadTheme;
-    /**
-     * Load CSS theme
-     */
-    private loadCSSTheme;
-    /**
-     * Load JS theme
-     */
-    private loadJSTheme;
-    /**
-     * Apply theme (set as active)
-     */
-    private applyTheme;
-    /**
-     * Apply CSS theme
-     */
-    private applyCSSTheme;
-    /**
-     * Apply JS theme
-     */
-    private applyJSTheme;
-    /**
-     * Remove theme
-     */
-    private removeTheme;
-    /**
-     * Preload theme
-     */
-    preloadTheme(themeId: string): Promise<void>;
-    /**
-     * Get registry
-     */
-    getRegistry(): ThemeRegistry;
-    /**
-     * Get cache
-     */
-    getCache(): ThemeCache;
-    /**
-     * Clear failed theme tracking (allows retry of previously failed themes)
-     */
-    clearFailedThemes(): void;
-    /**
-     * Clear specific failed theme (allows retry of a specific theme)
-     */
-    clearFailedTheme(themeId: string): void;
-    /**
-     * Check if theme has failed to load
-     */
-    hasFailedTheme(themeId: string): boolean;
-    /**
-     * Add change listener
-     */
-    on(event: 'change', listener: ThemeChangeListener): void;
-    on(event: 'load', listener: ThemeLoadListener): void;
-    on(event: 'error', listener: ThemeErrorListener): void;
-    on(event: 'revert', listener: ThemeRevertListener): void;
-    /**
-     * Remove listener
-     */
-    off(event: 'change', listener: ThemeChangeListener): void;
-    off(event: 'load', listener: ThemeLoadListener): void;
-    off(event: 'error', listener: ThemeErrorListener): void;
-    off(event: 'revert', listener: ThemeRevertListener): void;
-    /**
-     * Emit change event
-     */
-    private emitChange;
-    /**
-     * Emit load event
-     */
-    private emitLoad;
-    /**
-     * Emit error event
-     * Emits error to listeners (error emission is controlled at call site)
-     */
-    private emitError;
-    /**
-     * Emit revert event
-     */
-    private emitRevert;
-}
-
+declare function mergeTheme(...themes: ThemeOptions[]): ThemeOptions;
 /**
- * Theme Manager
+ * Extend an existing theme with new options
  *
- * Core theme management class for the Atomix Design System.
- * Rewritten to use the new ThemeEngine architecture.
- * Handles theme loading, switching, persistence, and events.
- * Supports both CSS-based themes and JavaScript-based themes.
+ * @param baseTheme - Base theme to extend (can be Theme or ThemeOptions)
+ * @param extension - Theme options to extend with
+ * @returns New theme with extended options
+ *
+ * @example
+ * ```typescript
+ * const base = createTheme({ palette: { primary: { main: '#000' } } });
+ * const extended = extendTheme(base, {
+ *   palette: { secondary: { main: '#fff' } }
+ * });
+ * ```
  */
+declare function extendTheme(baseTheme: Theme | ThemeOptions, extension: ThemeOptions): Theme;
 
 /**
- * ThemeManager class
+ * Atomix Configuration System
  *
- * Manages theme loading, switching, and persistence for Atomix Design System.
- * Uses the new ThemeEngine architecture for unified CSS/JS theme support.
+ * Tailwind-like configuration for customizing the Atomix Design System.
+ *
+ * External developers can create `atomix.config.ts` in their project root
+ * to customize design tokens, similar to Tailwind's tailwind.config.js
  *
  * @example
  * ```typescript
- * const themeManager = new ThemeManager({
- *   // No defaultTheme - uses built-in styles
- * });
+ * // atomix.config.ts (in your project)
+ * import { defineConfig } from '@shohojdhara/atomix/config';
  *
- * await themeManager.setTheme('my-custom-theme');
+ * export default defineConfig({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: { main: '#7AFFD7' },
+ *       },
+ *     },
+ *   },
+ * });
  * ```
- */
-declare class ThemeManager {
-    private engine;
-    private config;
-    private currentTheme;
-    private activeTheme;
-    private eventListeners;
-    private storageAdapter;
-    private initialized;
-    private rtlManager?;
-    private logger;
-    /**
-     * Create a new ThemeManager instance
-     *
-     * @param config - Theme manager configuration
-     */
-    constructor(config: ThemeManagerConfig);
-    /**
-     * Initialize the theme manager
-     */
-    private initialize;
-    /**
-     * Get default theme
-     */
-    private getDefaultTheme;
-    /**
-     * Set theme
-     */
-    setTheme(theme: string | Theme, options?: ThemeLoadOptions): Promise<void>;
-    /**
-     * Get current theme
-     */
-    getTheme(): string;
-    /**
-     * Get active theme object (for JS themes)
-     */
-    getActiveTheme(): Theme | null;
-    /**
-     * Get available themes
-     */
-    getAvailableThemes(): ThemeMetadata[];
-    /**
-     * Check if theme is loaded
-     */
-    isThemeLoaded(themeName: string): boolean;
-    /**
-     * Preload theme
-     */
-    preloadTheme(themeName: string): Promise<void>;
-    /**
-     * Add event listener
-     */
-    on(event: 'themeChange', callback: ThemeChangeCallback): void;
-    on(event: 'themeLoad', callback: ThemeLoadCallback): void;
-    on(event: 'themeError', callback: ThemeErrorCallback): void;
-    /**
-     * Remove event listener
-     */
-    off(event: 'themeChange', callback: ThemeChangeCallback): void;
-    off(event: 'themeLoad', callback: ThemeLoadCallback): void;
-    off(event: 'themeError', callback: ThemeErrorCallback): void;
-    /**
-     * Emit theme change event
-     */
-    private emitThemeChange;
-    /**
-     * Emit theme load event
-     */
-    private emitThemeLoad;
-    /**
-     * Emit theme error event
-     */
-    private emitThemeError;
-    /**
-     * Get engine instance (for advanced usage)
-     */
-    getEngine(): ThemeEngine;
-    /**
-     * Get RTL manager
-     */
-    getRTLManager(): RTLManager | undefined;
-    /**
-     * Set RTL direction
-     */
-    setDirection(direction: 'ltr' | 'rtl'): void;
-    /**
-     * Get current direction
-     */
-    getDirection(): 'ltr' | 'rtl';
-    /**
-     * Destroy theme manager
-     */
-    destroy(): void;
-}
+ */
 
 /**
- * Theme metadata interface matching themes.config.js structure
+ * CSS Theme Definition
  */
-interface ThemeMetadata {
-    /** Display name of the theme */
+interface CSSThemeDefinition {
+    type: 'css';
     name: string;
-    /** Unique identifier/class name for the theme */
     class?: string;
-    /** Theme description */
     description?: string;
-    /** Theme author */
     author?: string;
-    /** Theme version (semver) */
     version?: string;
-    /** Theme tags for categorization */
     tags?: string[];
-    /** Whether the theme supports dark mode */
     supportsDarkMode?: boolean;
-    /** Theme status: stable, beta, experimental, deprecated */
     status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
-    /** Accessibility information */
     a11y?: {
-        /** Target contrast ratio */
         contrastTarget?: number;
-        /** Supported color modes */
         modes?: string[];
     };
-    /** Primary theme color (for UI display) */
     color?: string;
-    /** Theme features list */
     features?: string[];
-    /** Theme dependencies (other themes required) */
     dependencies?: string[];
+    cssPath?: string;
 }
 /**
- * Theme manager configuration options
- */
-interface ThemeManagerConfig {
-    /** Available themes metadata */
-    themes: Record<string, ThemeMetadata>;
-    /** Default theme to use */
-    defaultTheme?: string | Theme;
-    /** Base path for theme CSS files */
-    basePath?: string;
-    /** CDN path for theme CSS files (optional) */
-    cdnPath?: string | null;
-    /** Themes to preload on initialization */
-    preload?: string[];
-    /** Enable lazy loading of themes */
-    lazy?: boolean;
-    /** localStorage key for persistence */
-    storageKey?: string;
-    /** Data attribute name for theme */
-    dataAttribute?: string;
-    /** Enable persistence */
-    enablePersistence?: boolean;
-    /** Custom CSS file extension */
-    cssExtension?: string;
-    /** Use minified CSS files */
-    useMinified?: boolean;
-    /** Callback when theme changes */
-    onThemeChange?: (theme: string | Theme) => void;
-    /** Callback when theme load fails */
-    onError?: (error: Error, themeName: string) => void;
-    /** RTL configuration */
-    rtl?: RTLConfig;
-}
-/**
- * Theme change event payload
- */
-interface ThemeChangeEvent {
-    /** Previous theme name */
-    previousTheme: string | null;
-    /** New theme name */
-    currentTheme: string;
-    /** Theme object (for JS themes) */
-    themeObject?: Theme | null;
-    /** Timestamp of the change */
-    timestamp: number;
-    /** Whether the change was from user action or system */
-    source: 'user' | 'system' | 'storage';
-}
-/**
- * Theme load options
- */
-interface ThemeLoadOptions {
-    /** Force reload even if already loaded */
-    force?: boolean;
-    /** Preload without applying */
-    preload?: boolean;
-    /** Remove previous theme CSS */
-    removePrevious?: boolean;
-    /** Custom CSS path override */
-    customPath?: string;
-    /** Fallback to default theme on error */
-    fallbackOnError?: boolean;
-}
-/**
- * Theme validation result
- */
-interface ThemeValidationResult {
-    /** Whether the theme is valid */
-    valid: boolean;
-    /** Validation errors */
-    errors: string[];
-    /** Validation warnings */
-    warnings: string[];
-}
-/**
- * Theme change callback function
- */
-type ThemeChangeCallback = (event: ThemeChangeEvent) => void;
-/**
- * Theme load callback function
- */
-type ThemeLoadCallback = (themeName: string) => void;
-/**
- * Theme error callback function
- */
-type ThemeErrorCallback = (error: Error, themeName: string) => void;
-/**
- * React hook return type for useTheme
- */
-interface UseThemeReturn {
-    /** Current theme name */
-    theme: string;
-    /** Current active theme object (for JS themes) */
-    activeTheme: Theme | null;
-    /** Function to change theme */
-    setTheme: (theme: string | Theme, options?: ThemeLoadOptions) => Promise<void>;
-    /** Available themes */
-    availableThemes: ThemeMetadata[];
-    /** Whether a theme is currently loading */
-    isLoading: boolean;
-    /** Current error, if any */
-    error: Error | null;
-    /** Whether a specific theme is loaded */
-    isThemeLoaded: (themeName: string) => boolean;
-    /** Preload a theme */
-    preloadTheme: (themeName: string) => Promise<void>;
-}
-/**
- * Component-level theme override configuration
- */
-interface ComponentThemeOverride {
-    /** CSS variable overrides for the component */
-    cssVars?: Record<string, string | number>;
-    /** Default prop overrides */
-    defaultProps?: Record<string, any>;
-    /** Part-specific overrides */
-    parts?: Record<string, {
-        cssVars?: Record<string, string | number>;
-        className?: string;
-    }>;
-    /** Variant overrides */
-    variants?: Record<string, {
-        cssVars?: Record<string, string | number>;
-        className?: string;
-    }>;
-    /** Additional className for the component */
-    className?: string;
-}
-/**
- * Theme component overrides for all components
- */
-interface ThemeComponentOverrides {
-    Button?: ComponentThemeOverride;
-    Card?: ComponentThemeOverride;
-    Input?: ComponentThemeOverride;
-    Modal?: ComponentThemeOverride;
-    Dropdown?: ComponentThemeOverride;
-    Badge?: ComponentThemeOverride;
-    Tabs?: ComponentThemeOverride;
-    Progress?: ComponentThemeOverride;
-    Tooltip?: ComponentThemeOverride;
-    Select?: ComponentThemeOverride;
-    Checkbox?: ComponentThemeOverride;
-    Radio?: ComponentThemeOverride;
-    Textarea?: ComponentThemeOverride;
-    FormGroup?: ComponentThemeOverride;
-    Navbar?: ComponentThemeOverride;
-    Accordion?: ComponentThemeOverride;
-    DataTable?: ComponentThemeOverride;
-    Avatar?: ComponentThemeOverride;
-    List?: ComponentThemeOverride;
-    Popover?: ComponentThemeOverride;
-    Messages?: ComponentThemeOverride;
-    Callout?: ComponentThemeOverride;
-    Spinner?: ComponentThemeOverride;
-    [key: string]: ComponentThemeOverride | undefined;
-}
-/**
- * Theme provider props
- */
-interface ThemeProviderProps {
-    /** Child components */
-    children: React.ReactNode;
-    /** Default theme */
-    defaultTheme?: string | Theme;
-    /** Available themes */
-    themes?: Record<string, ThemeMetadata>;
-    /** Base path for theme CSS */
-    basePath?: string;
-    /** CDN path for theme CSS */
-    cdnPath?: string | null;
-    /** Themes to preload */
-    preload?: string[];
-    /** Enable lazy loading */
-    lazy?: boolean;
-    /** localStorage key */
-    storageKey?: string;
-    /** Data attribute name */
-    dataAttribute?: string;
-    /** Enable persistence */
-    enablePersistence?: boolean;
-    /** Use minified CSS */
-    useMinified?: boolean;
-    /** Callback when theme changes */
-    onThemeChange?: (theme: string | Theme) => void;
-    /** Callback on error */
-    onError?: (error: Error, themeName: string) => void;
-}
-/**
- * Theme context value
+ * JavaScript Theme Definition
  */
-interface ThemeContextValue {
-    /** Current theme name */
-    theme: string;
-    /** Current active theme object (for JS themes) */
-    activeTheme: Theme | null;
-    /** Set theme function */
-    setTheme: (theme: string | Theme, options?: ThemeLoadOptions) => Promise<void>;
-    /** Available themes */
-    availableThemes: ThemeMetadata[];
-    /** Loading state */
-    isLoading: boolean;
-    /** Error state */
-    error: Error | null;
-    /** Check if theme is loaded */
-    isThemeLoaded: (themeName: string) => boolean;
-    /** Preload theme */
-    preloadTheme: (themeName: string) => Promise<void>;
-    /** Theme manager instance */
-    themeManager: ThemeManager;
+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;
 }
 /**
- * Color palette configuration for a single color
+ * Theme Definition (CSS or JS)
  */
-interface PaletteColor {
-    /** Main color value */
-    main: string;
-    /** Light variant (auto-generated if not provided) */
-    light?: string;
-    /** Dark variant (auto-generated if not provided) */
-    dark?: string;
-    /** Contrast text color (auto-generated if not provided) */
-    contrastText?: string;
-}
+type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
 /**
- * Palette configuration options for createTheme
+ * Build configuration (migrated from theme.config.ts)
  */
-interface PaletteOptions {
-    /** Primary color configuration */
-    primary?: Partial<PaletteColor> | string;
-    /** Secondary color configuration */
-    secondary?: Partial<PaletteColor> | string;
-    /** Error color configuration */
-    error?: Partial<PaletteColor> | string;
-    /** Warning color configuration */
-    warning?: Partial<PaletteColor> | string;
-    /** Info color configuration */
-    info?: Partial<PaletteColor> | string;
-    /** Success color configuration */
-    success?: Partial<PaletteColor> | string;
-    /** Background colors */
-    background?: {
-        default?: string;
-        subtle?: string;
+interface BuildConfig {
+    output?: {
+        directory?: string;
+        formats?: {
+            expanded?: string;
+            compressed?: string;
+        };
     };
-    /** Text colors */
-    text?: {
-        primary?: string;
-        secondary?: string;
-        disabled?: string;
+    sass?: {
+        style?: 'expanded' | 'compressed';
+        sourceMap?: boolean;
+        loadPaths?: string[];
     };
-    /** Additional custom colors */
-    [key: string]: any;
 }
 /**
- * Typography configuration options for createTheme
+ * Runtime configuration (migrated from theme.config.ts)
  */
-interface TypographyOptions {
-    /** Font family */
-    fontFamily?: string;
-    /** Base font size in pixels */
-    fontSize?: number;
-    /** Font weight scale */
-    fontWeightLight?: number;
-    fontWeightRegular?: number;
-    fontWeightMedium?: number;
-    fontWeightSemiBold?: number;
-    fontWeightBold?: number;
-    /** Heading configurations */
-    h1?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    h2?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    h3?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    h4?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    h5?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    h6?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-        letterSpacing?: string;
-    };
-    /** Body text configurations */
-    body1?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-    };
-    body2?: {
-        fontSize?: string | number;
-        fontWeight?: number;
-        lineHeight?: number | string;
-    };
-    /** Additional custom typography */
-    [key: string]: any;
+interface RuntimeConfig {
+    basePath?: string;
+    cdnPath?: string | null;
+    preload?: string[];
+    lazy?: boolean;
+    defaultTheme?: string;
+    storageKey?: string;
+    dataAttribute?: string;
+    enablePersistence?: boolean;
+    useMinified?: boolean;
 }
 /**
- * Spacing function type
+ * Integration settings (migrated from theme.config.ts)
  */
-type SpacingFunction = (...values: number[]) => string;
+interface IntegrationConfig {
+    cssVariables?: Record<string, string>;
+    classNames?: {
+        theme?: string;
+        colorMode?: string;
+    };
+}
+
 /**
- * Spacing configuration options for createTheme
+ * Theme Configuration Types
+ *
+ * Type definitions for the theme configuration system
  */
-type SpacingOptions = number | number[] | SpacingFunction;
+
 /**
- * Breakpoint values configuration
+ * Loaded and validated theme configuration
  */
-interface BreakpointValues {
-    xs?: number;
-    sm?: number;
-    md?: number;
-    lg?: number;
-    xl?: number;
-    [key: string]: number | undefined;
+interface LoadedThemeConfig {
+    /** Registered themes */
+    themes: Record<string, ThemeDefinition>;
+    /** Build configuration */
+    build: BuildConfig;
+    /** Runtime configuration */
+    runtime: RuntimeConfig;
+    /** Integration settings */
+    integration: IntegrationConfig;
+    /** Theme dependencies mapping */
+    dependencies: Record<string, string[]>;
+    /** Whether config was validated */
+    validated: boolean;
+    /** Validation errors (if any) */
+    errors?: string[];
+    /** Validation warnings (if any) */
+    warnings?: string[];
+    /** Internal tokens (for generator) */
+    __tokens?: any;
+    /** Internal extensions (for generator) */
+    __extend?: any;
 }
+
 /**
- * Breakpoints configuration options for createTheme
+ * Theme Registry
+ *
+ * Central registry for all themes with discovery and dependency management
  */
-interface BreakpointsOptions {
-    /** Breakpoint values in pixels */
-    values?: BreakpointValues;
-    /** Unit for breakpoints (default: 'px') */
-    unit?: string;
+
+/**
+ * Registry entry
+ */
+interface RegistryEntry {
+    /** Theme ID */
+    id: string;
+    /** Theme definition from config */
+    definition: ThemeDefinition;
+    /** Resolved theme object (for JS themes) */
+    theme?: Theme;
+    /** Whether theme is loaded */
+    loaded: boolean;
+    /** Loading promise (if currently loading) */
+    loading?: Promise<Theme | void>;
+    /** Dependencies */
+    dependencies: string[];
+    /** Dependent themes (themes that depend on this one) */
+    dependents: string[];
 }
 /**
- * Shadow configuration
+ * Theme Registry
+ *
+ * Manages theme registration, discovery, and dependency resolution
  */
-interface ShadowOptions {
-    xs?: string;
-    sm?: string;
-    md?: string;
-    lg?: string;
-    xl?: string;
-    [key: string]: string | undefined;
+declare class ThemeRegistry {
+    private entries;
+    private config;
+    private initialized;
+    /**
+     * Initialize registry from config
+     */
+    initialize(config?: LoadedThemeConfig): Promise<void>;
+    /**
+     * Register a theme
+     */
+    register(themeId: string, definition: ThemeDefinition): void;
+    /**
+     * Get theme entry
+     */
+    get(themeId: string): RegistryEntry | undefined;
+    /**
+     * Check if theme exists
+     */
+    has(themeId: string): boolean;
+    /**
+     * Get all theme IDs
+     */
+    getAllIds(): string[];
+    /**
+     * Get all theme metadata
+     */
+    getAllMetadata(): ThemeMetadata[];
+    /**
+     * Get theme definition
+     */
+    getDefinition(themeId: string): ThemeDefinition | undefined;
+    /**
+     * Check if a theme is loaded
+     */
+    isThemeLoaded(themeId: string): boolean;
+    /**
+     * Mark a theme as loaded
+     */
+    markLoaded(themeId: string, theme?: Theme): void;
+    /**
+     * Get theme object (for JS themes)
+     */
+    getTheme(themeId: string): Theme | undefined;
+    /**
+     * Get dependencies for a theme
+     */
+    getDependencies(themeId: string): string[];
+    /**
+     * Get dependents for a theme (themes that depend on this one)
+     */
+    getDependents(themeId: string): string[];
+    /**
+     * Resolve all dependencies in correct order
+     */
+    resolveDependencyOrder(themeId: string): string[];
+    /**
+     * Resolve dependencies and build dependency graph
+     */
+    private resolveDependencies;
+    /**
+     * Validate all themes
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Clear registry
+     */
+    clear(): void;
 }
+
+/**
+ * CSS File Utilities
+ *
+ * Save CSS to file system (Node.js only).
+ */
+/**
+ * Save CSS to file
+ *
+ * Writes CSS string to a file. Only works in Node.js environment.
+ *
+ * @param css - CSS string to save
+ * @param filePath - Output file path
+ * @throws Error if called in browser environment
+ *
+ * @example
+ * ```typescript
+ * const css = ':root { --atomix-color-primary: #7AFFD7; }';
+ * await saveCSSFile(css, './themes/custom.css');
+ * ```
+ */
+declare function saveCSSFile(css: string, filePath: string): Promise<void>;
+/**
+ * Save CSS to file (synchronous version)
+ *
+ * Synchronous version of saveCSSFile. Only works in Node.js environment.
+ *
+ * @param css - CSS string to save
+ * @param filePath - Output file path
+ * @throws Error if called in browser environment
+ */
+declare function saveCSSFileSync(css: string, filePath: string): void;
+
 /**
- * Transition configuration
+ * CSS Injection Utilities
+ *
+ * Inject CSS into HTML head via <style> element.
  */
-interface TransitionOptions {
-    /** Transition duration values */
-    duration?: {
-        shortest?: number;
-        shorter?: number;
-        short?: number;
-        standard?: number;
-        complex?: number;
-        enteringScreen?: number;
-        leavingScreen?: number;
-    };
-    /** Easing functions */
-    easing?: {
-        easeInOut?: string;
-        easeOut?: string;
-        easeIn?: string;
-        sharp?: string;
-    };
-}
 /**
- * Z-index configuration
+ * Inject CSS into HTML head via <style> element
+ *
+ * Creates or updates a style element in the document head.
+ * If an element with the same ID exists, it will be updated.
+ *
+ * @param css - CSS string to inject
+ * @param id - Style element ID (default: 'atomix-theme')
+ *
+ * @example
+ * ```typescript
+ * const css = ':root { --atomix-color-primary: #7AFFD7; }';
+ * injectCSS(css);
+ *
+ * // With custom ID
+ * injectCSS(css, 'my-custom-theme');
+ * ```
  */
-interface ZIndexOptions {
-    mobileStepper?: number;
-    speedDial?: number;
-    appBar?: number;
-    drawer?: number;
-    modal?: number;
-    snackbar?: number;
-    tooltip?: number;
-    [key: string]: number | undefined;
-}
+declare function injectCSS(css: string, id?: string): void;
 /**
- * Border radius configuration
+ * Remove injected CSS from DOM
+ *
+ * Removes the style element with the given ID from the document head.
+ *
+ * @param id - Style element ID to remove (default: 'atomix-theme')
+ *
+ * @example
+ * ```typescript
+ * removeCSS(); // Removes default 'atomix-theme'
+ * removeCSS('my-custom-theme'); // Removes custom ID
+ * ```
  */
-interface BorderRadiusOptions {
-    /** Base border radius */
-    base?: string | number;
-    /** Small border radius */
-    sm?: string | number;
-    /** Medium border radius */
-    md?: string | number;
-    /** Large border radius */
-    lg?: string | number;
-    /** Extra large border radius */
-    xl?: string | number;
-    /** 2X large border radius */
-    xxl?: string | number;
-    /** 3X large border radius */
-    '3xl'?: string | number;
-    /** 4X large border radius */
-    '4xl'?: string | number;
-    /** Pill shape (fully rounded) */
-    pill?: string | number;
-    [key: string]: string | number | undefined;
-}
+declare function removeCSS(id?: string): void;
 /**
- * Custom theme properties for extension
- * Users can augment this interface via module augmentation
+ * Check if CSS is already injected
+ *
+ * @param id - Style element ID to check (default: 'atomix-theme')
+ * @returns True if style element exists
  */
-interface ThemeCustomProperties {
-    [key: string]: any;
-}
+declare function isCSSInjected(id?: string): boolean;
+
 /**
- * Theme configuration options for createTheme
- * Extends ThemeMetadata to support both CSS and JS theme properties
+ * Config Loader
+ *
+ * Load design tokens from atomix.config.ts and convert to flat token format.
  */
-interface ThemeOptions extends Partial<ThemeMetadata> {
-    /** Color palette configuration */
-    palette?: PaletteOptions;
-    /** Typography configuration */
-    typography?: TypographyOptions;
-    /** Spacing configuration */
-    spacing?: SpacingOptions;
-    /** Breakpoints configuration */
-    breakpoints?: BreakpointsOptions;
-    /** Shadow configuration */
-    shadows?: ShadowOptions;
-    /** Transition configuration */
-    transitions?: TransitionOptions;
-    /** Z-index configuration */
-    zIndex?: ZIndexOptions;
-    /** Border radius configuration */
-    borderRadius?: BorderRadiusOptions;
-    /** Custom properties */
-    custom?: ThemeCustomProperties;
-}
+
 /**
- * Complete theme object with computed values
- * Generated by createTheme function
+ * Load theme tokens from atomix.config.ts
+ *
+ * Loads atomix.config.ts and extracts theme tokens.
+ * Config file is required - throws error if not found.
+ *
+ * @param configPath - Optional custom config path (default: 'atomix.config.ts')
+ * @returns Partial DesignTokens from config
+ * @throws Error if config file is not found or cannot be loaded
+ *
+ * @example
+ * ```typescript
+ * const tokens = await loadThemeFromConfig();
+ * const css = createTheme(tokens);
+ * injectTheme(css);
+ * ```
  */
-interface Theme extends ThemeMetadata {
-    /** Color palette with computed values */
-    palette: {
-        primary: PaletteColor;
-        secondary: PaletteColor;
-        error: PaletteColor;
-        warning: PaletteColor;
-        info: PaletteColor;
-        success: PaletteColor;
-        background: {
-            default: string;
-            paper: string;
-            subtle: string;
-        };
-        text: {
-            primary: string;
-            secondary: string;
-            disabled: string;
-        };
-        [key: string]: any;
-    };
-    /** Typography with computed values */
-    typography: {
-        fontFamily: string;
-        fontSize: number;
-        fontWeightLight: number;
-        fontWeightRegular: number;
-        fontWeightMedium: number;
-        fontWeightSemiBold: number;
-        fontWeightBold: number;
-        h1: Required<NonNullable<TypographyOptions['h1']>>;
-        h2: Required<NonNullable<TypographyOptions['h2']>>;
-        h3: Required<NonNullable<TypographyOptions['h3']>>;
-        h4: Required<NonNullable<TypographyOptions['h4']>>;
-        h5: Required<NonNullable<TypographyOptions['h5']>>;
-        h6: Required<NonNullable<TypographyOptions['h6']>>;
-        body1: Required<NonNullable<TypographyOptions['body1']>>;
-        body2: Required<NonNullable<TypographyOptions['body2']>>;
-        [key: string]: any;
-    };
-    /** Spacing function */
-    spacing: SpacingFunction;
-    /** Breakpoints with computed values */
-    breakpoints: {
-        values: Required<BreakpointValues>;
-        unit: string;
-        up: (key: keyof BreakpointValues | number) => string;
-        down: (key: keyof BreakpointValues | number) => string;
-        between: (start: keyof BreakpointValues | number, end: keyof BreakpointValues | number) => string;
-    };
-    /** Shadows */
-    shadows: Required<ShadowOptions>;
-    /** Transitions */
-    transitions: Required<TransitionOptions>;
-    /** Z-index values */
-    zIndex: Required<ZIndexOptions>;
-    /** Border radius values */
-    borderRadius: Required<BorderRadiusOptions>;
-    /** Custom properties */
-    custom: ThemeCustomProperties;
-    /** Global CSS variables to apply */
-    cssVars?: Record<string, string | number>;
-    /** Indicates this is a JS theme (not CSS-only) */
-    __isJSTheme: true;
-}
+declare function loadThemeFromConfig(configPath?: string): Promise<Partial<DesignTokens>>;
+/**
+ * Load theme tokens from atomix.config.ts (synchronous version)
+ *
+ * Synchronous version that uses require() instead of dynamic import.
+ * Only works in Node.js environment.
+ * Config file is required - throws error if not found.
+ *
+ * @param configPath - Optional custom config path
+ * @returns Partial DesignTokens from config
+ * @throws Error if config file is not found or cannot be loaded
+ */
+declare function loadThemeFromConfigSync(configPath?: string): Partial<DesignTokens>;
 
 /**
  * Theme Provider
  *
  * React context provider for theme management
- * Updated to use the new ThemeEngine architecture
  */
 
 /**
  * ThemeProvider component
  *
  * Provides theme context to child components and manages theme state.
- * Uses the new ThemeEngine-based ThemeManager.
+ *
+ * **Config-First Approach**: If `defaultTheme` is not provided, loads from `atomix.config.ts`.
+ * Config file is required when `defaultTheme` is not provided.
  *
  * @example
  * ```tsx
  * import { ThemeProvider } from '@shohojdhara/atomix/theme';
  *
+ * // Loads from atomix.config.ts (config file required)
  * function App() {
  *   return (
  *     <ThemeProvider>
@@ -1449,6 +1366,15 @@ interface Theme extends ThemeMetadata {
  *     </ThemeProvider>
  *   );
  * }
+ *
+ * // Provide explicit theme (bypasses config)
+ * function App() {
+ *   return (
+ *     <ThemeProvider defaultTheme="dark">
+ *       <YourApp />
+ *     </ThemeProvider>
+ *   );
+ * }
  * ```
  */
 declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
@@ -1457,7 +1383,6 @@ declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
  * useTheme Hook
  *
  * React hook for accessing theme context
- * Updated to work with new ThemeEngine architecture
  */
 
 /**
@@ -1514,185 +1439,103 @@ interface ThemeErrorBoundaryProps {
     children: ReactNode;
     /** Fallback UI to render when error occurs */
     fallback?: (error: Error, errorInfo: ErrorInfo) => ReactNode;
-    /** Callback when error occurs */
-    onError?: (error: Error, errorInfo: ErrorInfo) => void;
-    /** Whether to reset error on children change */
-    resetOnPropsChange?: boolean;
-    /** Custom error message */
-    errorMessage?: string;
-}
-/**
- * Theme Error Boundary Component
- *
- * Catches errors in the theme system and displays a fallback UI
- * instead of crashing the entire application.
- */
-declare class ThemeErrorBoundary extends Component<ThemeErrorBoundaryProps, ThemeErrorBoundaryState> {
-    private logger;
-    constructor(props: ThemeErrorBoundaryProps);
-    static getDerivedStateFromError(error: Error): Partial<ThemeErrorBoundaryState>;
-    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
-    componentDidUpdate(prevProps: ThemeErrorBoundaryProps): void;
-    render(): ReactNode;
-}
-
-/**
- * createTheme - Create a theme object with computed values
- *
- * Similar to Material-UI's createTheme, this function accepts theme configuration
- * options and returns a complete theme object with computed values.
- *
- * @example
- * ```typescript
- * const theme = createTheme({
- *   palette: {
- *     primary: { main: '#7AFFD7' },
- *     secondary: { main: '#FF5733' },
- *   },
- *   typography: {
- *     fontFamily: 'Inter, sans-serif',
- *   },
- * });
- * ```
- */
-
-/**
- * Create a theme object with computed values
- *
- * @param options - Theme configuration options
- * @returns Complete theme object
- */
-declare function createTheme(...options: ThemeOptions[]): Theme;
-
-/**
- * Create a theme from Atomix configuration
- *
- * This function converts atomix.config.ts format to a theme object
- * that can be used with ThemeProvider.
- *
- * @param config - Atomix configuration object
- * @returns Theme object ready for use
- *
- * @example
- * ```typescript
- * import { createThemeFromConfig } from '@shohojdhara/atomix/theme';
- * import config from './atomix.config';
- *
- * const theme = createThemeFromConfig(config);
- * ```
- */
-declare function createThemeFromConfig(config: AtomixConfig): Theme;
-
-/**
- * Theme Tools for Library Users
- *
- * Developer-friendly utilities for working with Atomix themes
- */
-
-/**
- * Quick theme creator with sensible defaults
- */
-declare function quickTheme(name: string, primaryColor: string, secondaryColor?: string): Theme;
-/**
- * Create a dark theme variant from a light theme
- */
-declare function createDarkVariant(lightTheme: Theme): Theme;
-/**
- * Validate theme structure
- */
-declare function validateTheme(theme: Theme): {
-    valid: boolean;
-    errors: string[];
-};
-/**
- * Generate CSS string from theme
- */
-declare function themeToCSS(theme: Theme, selector?: string): string;
-/**
- * Export theme as JSON
- */
-declare function exportTheme(theme: Theme): string;
+    /** Callback when error occurs */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Whether to reset error on children change */
+    resetOnPropsChange?: boolean;
+    /** Custom error message */
+    errorMessage?: string;
+}
 /**
- * Import theme from JSON
+ * Theme Error Boundary Component
+ *
+ * Catches errors in the theme system and displays a fallback UI
+ * instead of crashing the entire application.
  */
-declare function importTheme(json: string): Theme;
+declare class ThemeErrorBoundary extends Component<ThemeErrorBoundaryProps, ThemeErrorBoundaryState> {
+    private logger;
+    constructor(props: ThemeErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ThemeErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    componentDidUpdate(prevProps: ThemeErrorBoundaryProps): void;
+    render(): ReactNode;
+}
 
 /**
- * Theme CLI
+ * Theme Applicator
  *
- * Command-line interface for theme management
- */
-/**
- * CLI command interface
+ * Applies theme configurations to the DOM, including CSS variables,
+ * component overrides, typography, spacing, and color palettes.
+ *
+ * Uses the unified theme system for CSS generation and injection.
  */
-interface CLICommand {
-    name: string;
-    description: string;
-    options?: Record<string, string>;
-    handler: (args: string[], options: Record<string, any>) => Promise<void> | void;
-}
+
 /**
- * Theme CLI
+ * Theme applicator class for runtime theme application
  *
- * Command-line interface for theme operations
+ * Uses the unified theme system for efficient CSS variable generation and injection.
  */
-declare class ThemeCLI {
-    private commands;
-    constructor();
-    /**
-     * Register default commands
-     */
-    private registerDefaultCommands;
+declare class ThemeApplicator {
+    private root;
+    private styleId;
+    constructor(root?: HTMLElement);
     /**
-     * Register a command
+     * Apply a complete theme configuration
+     *
+     * Uses the unified theme system to convert Theme to DesignTokens and inject CSS.
+     * Automatically respects atomix.config.ts when using DesignTokens.
      */
-    register(command: CLICommand): void;
+    applyTheme(theme: Theme | DesignTokens): void;
     /**
-     * Run CLI with arguments
+     * Apply DesignTokens using unified theme system
+     *
+     * Uses createTheme() which automatically loads from atomix.config.ts
+     * if no tokens are provided, ensuring config is always respected.
      */
-    run(args: string[]): Promise<void>;
+    private applyDesignTokens;
     /**
-     * Parse command arguments
+     * Check if object is DesignTokens
      */
-    private parseArgs;
+    private isDesignTokens;
     /**
-     * Handle validate command
+     * Apply global CSS variables (for component overrides)
      */
-    private handleValidate;
+    private applyGlobalCSSVars;
     /**
-     * Handle list command
+     * Apply component-level overrides
      */
-    private handleList;
+    private applyComponentOverrides;
     /**
-     * Handle inspect command
+     * Apply override for a specific component
      */
-    private handleInspect;
+    private applyComponentOverride;
     /**
-     * Handle compare command
+     * Clear all applied CSS variables
      */
-    private handleCompare;
+    private clearAppliedVars;
     /**
-     * Handle export command
+     * Remove theme application
      */
-    private handleExport;
+    removeTheme(): void;
     /**
-     * Handle help command
+     * Update specific CSS variables without clearing all
      */
-    private handleHelp;
+    updateCSSVars(vars: Record<string, string | number>): void;
 }
 /**
- * Create CLI instance
+ * Get or create global theme applicator
  */
-declare function createCLI(): ThemeCLI;
+declare function getThemeApplicator(): ThemeApplicator;
 /**
- * Run CLI with process arguments
+ * Apply theme using global applicator
  */
-declare function runCLI(): void;
+declare function applyTheme(theme: Theme): void;
 
 /**
  * Theme Preview Component
  *
  * React component for previewing themes in development
+ * Enhanced with interactive components, viewport controls, and dark mode toggle
  */
 
 /**
@@ -1727,6 +1570,7 @@ declare const ThemePreview: React__default.FC<ThemePreviewProps>;
  * Theme Inspector Component
  *
  * React component for inspecting and debugging themes
+ * Enhanced with search/filter and copy path functionality
  */
 
 /**
@@ -1757,6 +1601,7 @@ declare const ThemeInspector: React__default.FC<ThemeInspectorProps>;
  * Theme Comparator Component
  *
  * React component for comparing two themes side-by-side
+ * Enhanced with search/filter and improved visual diff styling
  */
 
 /**
@@ -1785,6 +1630,7 @@ declare const ThemeComparator: React__default.FC<ThemeComparatorProps>;
  * Theme Live Editor Component
  *
  * React component for live editing themes in development
+ * Enhanced with undo/redo, keyboard shortcuts, resizable layout, and better color pickers
  */
 
 /**
@@ -1808,76 +1654,185 @@ interface ThemeLiveEditorProps {
 declare const ThemeLiveEditor: React__default.FC<ThemeLiveEditorProps>;
 
 /**
- * Theme Applicator
+ * Theme Validator
  *
- * Applies theme configurations to the DOM, including CSS variables,
- * component overrides, typography, spacing, and color palettes.
+ * Runtime theme validation including color contrast and accessibility checks
  */
 
 /**
- * Theme applicator class for runtime theme application
+ * Validation result
  */
-declare class ThemeApplicator {
-    private appliedVars;
-    private root;
-    constructor(root?: HTMLElement);
+interface ValidationResult {
+    /** Whether theme is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+    /** Accessibility issues */
+    a11yIssues: A11yIssue[];
+}
+/**
+ * Accessibility issue
+ */
+interface A11yIssue {
+    /** Issue type */
+    type: 'contrast' | 'color' | 'missing';
+    /** Severity */
+    severity: 'error' | 'warning';
+    /** Issue message */
+    message: string;
+    /** Affected property */
+    property?: string;
+    /** Current value */
+    value?: string;
+    /** Recommended value */
+    recommended?: string;
+}
+/**
+ * Theme Validator
+ *
+ * Validates themes for correctness and accessibility
+ */
+declare class ThemeValidator {
     /**
-     * Apply a complete theme configuration
+     * Validate theme
      */
-    applyTheme(theme: Theme): void;
+    validate(theme: Theme, metadata?: ThemeMetadata): ValidationResult;
     /**
-     * Apply global CSS variables
+     * Validate palette
      */
-    private applyGlobalCSSVars;
+    private validatePalette;
     /**
-     * Apply typography system
+     * Validate typography
      */
-    private applyTypography;
+    private validateTypography;
     /**
-     * Apply spacing system
+     * Validate spacing
      */
-    private applySpacing;
+    private validateSpacing;
     /**
-     * Apply color palette
+     * Validate breakpoints
      */
-    private applyPalette;
+    private validateBreakpoints;
     /**
-     * Apply component-level overrides
+     * Check color contrast ratio
      */
-    private applyComponentOverrides;
+    private checkContrast;
     /**
-     * Apply override for a specific component
+     * Check if color is valid
      */
-    private applyComponentOverride;
+    private isValidColor;
     /**
-     * Clear all applied CSS variables
+     * Validate transitions
      */
-    private clearAppliedVars;
+    private validateTransitions;
     /**
-     * Get all currently applied variables
+     * Validate z-index
      */
-    getAppliedVars(): string[];
+    private validateZIndex;
     /**
-     * Remove theme application
+     * Validate border radius
      */
-    removeTheme(): void;
+    private validateBorderRadius;
     /**
-     * Update specific CSS variables without clearing all
+     * Validate custom properties
      */
-    updateCSSVars(vars: Record<string, string | number>): void;
+    private validateCustom;
 }
+
 /**
- * Get or create global theme applicator
+ * useHistory Hook
+ *
+ * React hook for managing undo/redo history
  */
-declare function getThemeApplicator(): ThemeApplicator;
+interface UseHistoryOptions {
+    /** Maximum number of history entries (default: 50) */
+    maxHistorySize?: number;
+    /** Initial state */
+    initialState?: any;
+}
+interface UseHistoryReturn<T> {
+    /** Current state */
+    state: T;
+    /** Update state and add to history */
+    setState: (newState: T) => void;
+    /** Undo last change */
+    undo: () => void;
+    /** Redo last undone change */
+    redo: () => void;
+    /** Check if undo is available */
+    canUndo: boolean;
+    /** Check if redo is available */
+    canRedo: boolean;
+    /** Clear history */
+    clearHistory: () => void;
+    /** Get history statistics */
+    getHistoryStats: () => {
+        currentIndex: number;
+        totalEntries: number;
+    };
+}
 /**
- * Apply theme using global applicator
+ * useHistory hook
+ *
+ * Provides undo/redo functionality for state management
+ *
+ * @example
+ * ```tsx
+ * const { state, setState, undo, redo, canUndo, canRedo } = useHistory({
+ *   initialState: theme,
+ *   maxHistorySize: 50
+ * });
+ * ```
  */
-declare function applyTheme(theme: Theme): void;
+declare function useHistory<T>(options?: UseHistoryOptions): UseHistoryReturn<T>;
+
+/**
+ * Theme Adapter
+ *
+ * Converts between Theme objects and DesignTokens.
+ */
+
+/**
+ * Convert Theme object to DesignTokens
+ *
+ * Extracts values from a Theme object and converts them to flat DesignTokens format.
+ *
+ * @param theme - Theme object to convert
+ * @returns Partial DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * const theme = createTheme({ palette: { primary: { main: '#7c3aed' } } });
+ * const tokens = themeToDesignTokens(theme);
+ * // Returns: { 'primary': '#7c3aed', ... }
+ * ```
+ */
+declare function themeToDesignTokens(theme: Theme): Partial<DesignTokens>;
+/**
+ * Convert DesignTokens to Theme-compatible CSS variables
+ *
+ * @param tokens - DesignTokens object
+ * @returns CSS variables object compatible with Theme.cssVars
+ */
+declare function designTokensToCSSVars(tokens: Partial<DesignTokens>): Record<string, string>;
+/**
+ * Create DesignTokens from Theme with defaults
+ *
+ * Converts a Theme to DesignTokens and merges with default tokens.
+ *
+ * @param theme - Theme object to convert
+ * @returns Complete DesignTokens object
+ */
+declare function createDesignTokensFromTheme(theme: Theme): DesignTokens;
 /**
- * Remove theme using global applicator
+ * Create a minimal Theme object from DesignTokens
+ *
+ * @param tokens - DesignTokens to convert
+ * @returns Minimal Theme object with cssVars populated
  */
-declare function removeTheme(): void;
+declare function designTokensToTheme(tokens: Partial<DesignTokens>): Partial<Theme>;
 
 /**
  * CSS Variable Mapper
@@ -1988,5 +1943,180 @@ declare function isValidCSSVariableName(name: string): boolean;
  */
 declare function extractComponentName(varName: string, prefix?: string): string | null;
 
-export { RTLManager, ThemeApplicator, ThemeCLI, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemeManager, ThemePreview, ThemeProvider, applyCSSVariables, applyTheme, createCLI, createDarkVariant, createTheme, createThemeFromConfig, cssVarsToStyle, exportTheme, extractComponentName, generateCSSVariableName, generateComponentCSSVars, getCSSVariable, getThemeApplicator, importTheme, isValidCSSVariableName, mapSCSSTokensToCSSVars, mergeCSSVars, quickTheme, removeCSSVariables, removeTheme, runCLI, themeToCSS, useTheme, validateTheme };
-export type { CLICommand, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOverride, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemeManagerConfig, ThemeMetadata, ThemePreviewProps, ThemeProviderProps, ThemeValidationResult, UseThemeReturn };
+/**
+ * Theme Helper Functions
+ *
+ * Utility functions for working with themes and DesignTokens
+ */
+
+/**
+ * Get DesignTokens from current theme
+ *
+ * Converts a Theme object to DesignTokens. Useful when you need to
+ * work with DesignTokens but have a Theme object.
+ *
+ * @param theme - Theme object to convert
+ * @returns DesignTokens object
+ *
+ * @example
+ * ```typescript
+ * // If you have a Theme object, convert it to DesignTokens
+ * const tokens = getDesignTokensFromTheme(theme);
+ * // Now you can use tokens with unified theme system
+ * const css = createTheme(tokens);
+ * ```
+ */
+declare function getDesignTokensFromTheme(theme: Theme | null): DesignTokens | null;
+/**
+ * Check if a value is DesignTokens
+ *
+ * Type guard to check if an object is DesignTokens format.
+ *
+ * @param value - Value to check
+ * @returns True if value is DesignTokens
+ */
+declare function isDesignTokens(value: unknown): value is DesignTokens;
+/**
+ * Check if a value is a Theme object
+ *
+ * Type guard to check if an object is a Theme.
+ *
+ * @param value - Value to check
+ * @returns True if value is Theme
+ */
+declare function isThemeObject(value: unknown): value is Theme;
+
+/**
+ * RTL (Right-to-Left) Support Utilities
+ *
+ * Provides utilities for managing RTL text direction in themes
+ */
+/**
+ * RTL configuration options
+ */
+interface RTLConfig {
+    /** Enable RTL mode */
+    enabled: boolean;
+    /** Current direction ('ltr' | 'rtl') */
+    direction: 'ltr' | 'rtl';
+    /** Data attribute name for direction */
+    dataAttribute?: string;
+    /** Auto-detect from locale */
+    autoDetect?: boolean;
+    /** Locale code (e.g., 'ar', 'he', 'fa') */
+    locale?: string;
+}
+/**
+ * RTL Manager
+ *
+ * Manages RTL text direction for the theme system
+ */
+declare class RTLManager {
+    private config;
+    private listeners;
+    constructor(config?: Partial<RTLConfig>);
+    /**
+     * Detect locale from browser
+     */
+    private detectLocale;
+    /**
+     * Check if locale is RTL
+     */
+    isRTLLocale(locale: string): boolean;
+    /**
+     * Get current direction
+     */
+    getDirection(): 'ltr' | 'rtl';
+    /**
+     * Check if RTL is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set direction
+     */
+    setDirection(direction: 'ltr' | 'rtl'): void;
+    /**
+     * Toggle direction
+     */
+    toggleDirection(): 'ltr' | 'rtl';
+    /**
+     * Enable RTL
+     */
+    enable(): void;
+    /**
+     * Disable RTL
+     */
+    disable(): void;
+    /**
+     * Set locale and auto-adjust direction
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get current locale
+     */
+    getLocale(): string | undefined;
+    /**
+     * Apply direction to DOM
+     */
+    private applyDirection;
+    /**
+     * Add direction change listener
+     */
+    onDirectionChange(callback: (direction: 'ltr' | 'rtl') => void): () => void;
+    /**
+     * Notify listeners of direction change
+     */
+    private notifyListeners;
+    /**
+     * Get RTL-aware value
+     *
+     * Returns different values based on direction
+     */
+    getValue<T>(ltrValue: T, rtlValue: T): T;
+    /**
+     * Get RTL-aware CSS property
+     *
+     * Returns appropriate CSS property based on direction
+     */
+    getCSSProperty(property: string): string;
+    /**
+     * Destroy RTL manager
+     */
+    destroy(): void;
+}
+
+/**
+ * Theme System Exports
+ *
+ * Unified theme system - handles both DesignTokens and Theme objects.
+ *
+ * @example
+ * ```typescript
+ * import { createTheme, injectTheme } from '@shohojdhara/atomix/theme';
+ *
+ * // Using DesignTokens (recommended - flat structure)
+ * const css = createTheme({ 'primary': '#7AFFD7', 'spacing-4': '1rem' });
+ * injectTheme(css);
+ *
+ * // Or use with ThemeProvider
+ * import { ThemeProvider } from '@shohojdhara/atomix/theme';
+ * const tokens = { 'primary': '#7c3aed' };
+ * <ThemeProvider defaultTheme={tokens}>...</ThemeProvider>
+ * ```
+ */
+
+/**
+ * Inject theme CSS into DOM
+ */
+declare function injectTheme(css: string, id?: string): void;
+/**
+ * Remove theme from DOM
+ */
+declare function removeTheme(id?: string): void;
+/**
+ * Save theme to CSS file
+ */
+declare function saveTheme(css: string, filePath: string): Promise<void>;
+
+export { RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeRegistry, ThemeValidator, applyCSSVariables, applyTheme, createDesignTokensFromTheme, createTheme, createThemeObject, createTokens, cssVarsToStyle, deepMerge, defaultTokens, designTokensToCSSVars, designTokensToTheme, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables, generateCSSVariablesForSelector, generateComponentCSSVars, getCSSVariable, getDesignTokensFromTheme, getThemeApplicator, injectCSS, injectTheme, isCSSInjected, isDesignTokens, isThemeObject, isValidCSSVariableName, loadThemeFromConfig, loadThemeFromConfigSync, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, removeCSS, removeCSSVariables, removeTheme, saveCSSFile, saveCSSFileSync, saveTheme, themeToDesignTokens, useHistory, useTheme };
+export type { A11yIssue, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOverride, DesignTokens, GenerateCSSVariablesOptions, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemeMetadata, ThemePreviewProps, ThemeProviderProps, ThemeValidationResult, UseHistoryOptions, UseHistoryReturn, UseThemeReturn, ValidationResult };