@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/ui/design-token.utils.js

@@ -0,0 +1,1428 @@
+/**
+ * Design Token Utilities
+ * Handles dynamic application of design tokens as CSS variables
+ *
+ * Types/schemas: import from @wildo-ai/presets-components-models
+ * Utilities: import from this file via @wildo-ai/saas-frontend-lib
+ */
+import { DesignTokenValueType, getDesignTokenValue, isDesignTokenLightDarkValueConfiguration, mergeDesignTokenConfiguration, TypographyRole, FontAxis, GoogleVariableFont, DEFAULT_CHART_COLOR_PALETTE, } from '@wildo-ai/presets-components-models';
+import { UserTheme } from '@wildo-ai/saas-models';
+const DARK_MODE_STORAGE_KEY = 'theme.dark';
+const DARK_MODE_PREFERENCE_STORAGE_KEY = 'theme.preference';
+/**
+ * Deep merge two FontConfiguration objects
+ */
+function mergeFontConfiguration(base, override) {
+    if (!override)
+        return base;
+    return {
+        ...base,
+        ...override,
+        fallbacks: override.fallbacks ?? base.fallbacks,
+        axisRanges: override.axisRanges
+            ? { ...base.axisRanges, ...override.axisRanges }
+            : base.axisRanges,
+        defaults: override.defaults
+            ? { ...base.defaults, ...override.defaults }
+            : base.defaults,
+    };
+}
+/**
+ * Deep merge two TypographyConfiguration objects
+ */
+function mergeTypographyConfiguration(base, override) {
+    if (!override)
+        return base;
+    const mergedFonts = { ...base.fonts };
+    if (override.fonts) {
+        for (const role of Object.values(TypographyRole)) {
+            if (override.fonts[role]) {
+                mergedFonts[role] = mergeFontConfiguration(base.fonts[role], override.fonts[role]);
+            }
+        }
+    }
+    return {
+        fonts: mergedFonts,
+        scale: override.scale
+            ? { ...base.scale, ...override.scale }
+            : base.scale,
+    };
+}
+/**
+ * Deep merge two DesignSystemConfiguration objects.
+ * Override only replaces tokens that are explicitly provided.
+ *
+ * Use cases:
+ * - Merge engine defaults with backend-provided config
+ * - Merge with apps-custom overrides
+ * - Partial token customization (only override primary color, keep rest)
+ *
+ * @param base - Base configuration (typically engine defaults)
+ * @param override - Override configuration (backend/custom, can be partial)
+ * @returns Merged configuration
+ */
+export function mergeDesignSystemConfiguration(base, override) {
+    if (!override) {
+        return base;
+    }
+    const result = {
+        ...base,
+    };
+    // Merge standard tokens (deep merge per token)
+    if (override.tokens) {
+        const baseTokens = (base.tokens || {});
+        result.tokens = { ...baseTokens };
+        for (const [tokenKey, tokenConfig] of Object.entries(override.tokens)) {
+            if (tokenConfig) {
+                const baseToken = baseTokens[tokenKey];
+                result.tokens[tokenKey] = baseToken
+                    ? mergeDesignTokenConfiguration(baseToken, tokenConfig)
+                    : tokenConfig;
+            }
+        }
+    }
+    // Merge custom tokens (deep merge per token)
+    if (override.customTokens) {
+        const baseCustomTokens = (base.customTokens || {});
+        result.customTokens = { ...baseCustomTokens };
+        for (const [tokenKey, tokenConfig] of Object.entries(override.customTokens)) {
+            if (tokenConfig) {
+                const baseToken = baseCustomTokens[tokenKey];
+                result.customTokens[tokenKey] = baseToken
+                    ? mergeDesignTokenConfiguration(baseToken, tokenConfig)
+                    : tokenConfig;
+            }
+        }
+    }
+    // Merge typography configuration
+    if (override.typography && base.typography) {
+        result.typography = mergeTypographyConfiguration(base.typography, override.typography);
+    }
+    else if (override.typography) {
+        result.typography = override.typography;
+    }
+    if (override.theme !== undefined) {
+        result.theme = override.theme;
+    }
+    return result;
+}
+/**
+ * Convert enum to CSS variable name
+ * DesignSystemToken enum values already match kebab-case CSS variable names
+ */
+const enumToCssVar = (token) => `--${token}`;
+/**
+ * Validate OKLCH color format
+ * L: 0-1 (lightness), C: 0+ (chroma), H: 0-360 (hue)
+ */
+function validateOklchValue(value) {
+    // Remove oklch() wrapper if present
+    const cleanValue = value.replace(/^oklch\(|\)$/g, '').trim();
+    // Match OKLCH format: L C H (with optional decimal places)
+    const oklchRegex = /^(0(?:\.\d+)?|1(?:\.0+)?)\s+(0|\d*\.?\d+)\s+(0|[1-9]\d{0,2}(?:\.\d+)?|360(?:\.0+)?)$/;
+    if (!oklchRegex.test(cleanValue)) {
+        return false;
+    }
+    // Additional range validation
+    const [l, c, h] = cleanValue.split(/\s+/).map(Number);
+    return l >= 0 && l <= 1 && c >= 0 && h >= 0 && h <= 360;
+}
+/**
+ * Ensure OKLCH color values are stored as full `oklch(L C H)` — a valid CSS color.
+ * This allows `var(--token)` to work directly as a color in any CSS property,
+ * and Tailwind v4's `color-mix()` opacity modifiers to compose correctly.
+ */
+function ensureOklchWrapped(oklchValue, logger) {
+    if (!validateOklchValue(oklchValue)) {
+        logger?.warn('[DesignTokens] Invalid OKLCH format detected', { value: oklchValue });
+        return 'oklch(0.5 0 0)';
+    }
+    if (oklchValue.startsWith('oklch(') && oklchValue.endsWith(')')) {
+        return oklchValue;
+    }
+    return `oklch(${oklchValue.trim()})`;
+}
+/**
+ * Convert size values to ensure proper CSS format
+ */
+function ensureProperSizeFormat(value) {
+    // If it's already a proper CSS size, return as is
+    if (value.match(/^\d+(\.\d+)?(px|rem|em|vh|vw|%)$/)) {
+        return value;
+    }
+    // If it's just a number, assume rem
+    if (value.match(/^\d+(\.\d+)?$/)) {
+        return `${value}rem`;
+    }
+    return value;
+}
+/**
+ * Check if dark mode is currently active
+ * Works with both data-theme="dark" and .dark class approaches
+ */
+function isCurrentlyDarkMode() {
+    if (typeof window === 'undefined')
+        return false;
+    const element = document.documentElement;
+    // Check data-theme attribute first (preferred method)
+    const dataTheme = element.getAttribute('data-theme');
+    if (dataTheme === 'dark')
+        return true;
+    if (dataTheme === 'light')
+        return false;
+    // Fallback to class-based approach
+    return element.classList.contains('dark');
+}
+function isUserThemePreference(value) {
+    return value === UserTheme.LIGHT || value === UserTheme.DARK || value === UserTheme.AUTO;
+}
+function resolveSystemDarkMode() {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+function resolveStoredDarkModePreference() {
+    const savedPreference = localStorage.getItem(DARK_MODE_PREFERENCE_STORAGE_KEY);
+    return isUserThemePreference(savedPreference) ? savedPreference : null;
+}
+function applyDarkModeState(enabled) {
+    const element = document.documentElement;
+    // Set data-theme attribute (primary method)
+    element.setAttribute('data-theme', enabled ? 'dark' : 'light');
+    // Also set .dark class for compatibility
+    element.classList.toggle('dark', enabled);
+}
+function persistDarkModePreference(context, preference, enabled) {
+    if (context._debounceTimeout) {
+        clearTimeout(context._debounceTimeout);
+    }
+    context._debounceTimeout = window.setTimeout(() => {
+        try {
+            localStorage.setItem(DARK_MODE_PREFERENCE_STORAGE_KEY, preference);
+            localStorage.setItem(DARK_MODE_STORAGE_KEY, enabled ? '1' : '0');
+        }
+        catch (error) {
+            console.warn('[DarkMode] Failed to persist theme preference:', error);
+        }
+        context._debounceTimeout = null;
+    }, 150);
+}
+function resolvePreferredDarkMode() {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        const savedPreference = resolveStoredDarkModePreference();
+        if (savedPreference === UserTheme.DARK)
+            return true;
+        if (savedPreference === UserTheme.LIGHT)
+            return false;
+        if (savedPreference === UserTheme.AUTO)
+            return resolveSystemDarkMode();
+        const saved = localStorage.getItem(DARK_MODE_STORAGE_KEY);
+        const prefers = resolveSystemDarkMode();
+        return saved ? saved === '1' : prefers;
+    }
+    catch (error) {
+        console.error('[DarkMode] Failed to resolve preferred dark mode:', error);
+        return false;
+    }
+}
+/**
+ * Apply design tokens as CSS variables to the document root or specified target
+ * Works with existing Tailwind v4 setup and OKLCH color space with batched DOM operations
+ */
+export function applyDesignTokens(tokens, options = {}) {
+    const { target = document.documentElement, dark = isCurrentlyDarkMode(), logger } = options;
+    const appliedCount = { light: 0, dark: 0, invalid: 0 };
+    const cssProperties = [];
+    // Batch process all tokens first
+    for (const [key, config] of Object.entries(tokens)) {
+        const varName = enumToCssVar(key);
+        const rawValue = getDesignTokenValue(config, dark ? 'dark' : 'light');
+        // Convert value based on type with validation
+        let finalValue;
+        let isValid = true;
+        try {
+            switch (config.type) {
+                case DesignTokenValueType.COLOR:
+                    finalValue = ensureOklchWrapped(rawValue, logger);
+                    isValid = finalValue !== 'oklch(0.5 0 0)' || rawValue === '0.5 0 0' || rawValue === 'oklch(0.5 0 0)';
+                    break;
+                case DesignTokenValueType.SIZE:
+                    finalValue = ensureProperSizeFormat(rawValue);
+                    break;
+                case DesignTokenValueType.NUMBER:
+                case DesignTokenValueType.STRING:
+                default:
+                    finalValue = rawValue;
+                    break;
+            }
+            // Add to batch
+            cssProperties.push({ name: varName, value: finalValue });
+            // Track what was applied
+            if (!isValid) {
+                appliedCount.invalid++;
+            }
+            else if (dark && isDesignTokenLightDarkValueConfiguration(config)) {
+                appliedCount.dark++;
+            }
+            else {
+                appliedCount.light++;
+            }
+        }
+        catch (error) {
+            logger?.error('[DesignTokens] Error processing token', {
+                token: key,
+                value: rawValue,
+                error: error.message
+            });
+            appliedCount.invalid++;
+        }
+    }
+    // Batch apply all CSS properties in single DOM operation
+    const style = target.style;
+    cssProperties.forEach(({ name, value }) => {
+        style.setProperty(name, value);
+    });
+}
+/**
+ * Apply custom tokens (non-shadcn/ui tokens) with validation and batching
+ */
+export function applyCustomTokens(customTokens, options = {}) {
+    const { target = document.documentElement, dark = isCurrentlyDarkMode(), logger } = options;
+    const appliedCount = { valid: 0, invalid: 0 };
+    const cssProperties = [];
+    // Batch process all custom tokens
+    for (const [tokenName, config] of Object.entries(customTokens)) {
+        const varName = `--${tokenName}`;
+        const rawValue = getDesignTokenValue(config, dark ? 'dark' : 'light');
+        let finalValue;
+        let isValid = true;
+        try {
+            // Format value based on type with validation
+            switch (config.type) {
+                case DesignTokenValueType.COLOR:
+                    finalValue = ensureOklchWrapped(rawValue, logger);
+                    isValid = finalValue !== 'oklch(0.5 0 0)' || rawValue === '0.5 0 0' || rawValue === 'oklch(0.5 0 0)';
+                    break;
+                case DesignTokenValueType.SIZE:
+                    finalValue = ensureProperSizeFormat(rawValue);
+                    break;
+                case DesignTokenValueType.NUMBER:
+                case DesignTokenValueType.STRING:
+                default:
+                    finalValue = rawValue;
+                    break;
+            }
+            // Add to batch
+            cssProperties.push({ name: varName, value: finalValue });
+            if (isValid) {
+                appliedCount.valid++;
+            }
+            else {
+                appliedCount.invalid++;
+            }
+        }
+        catch (error) {
+            logger?.error('[DesignTokens] Error processing custom token', {
+                token: tokenName,
+                value: rawValue,
+                error: error.message
+            });
+            appliedCount.invalid++;
+        }
+    }
+    // Batch apply all CSS properties
+    const style = target.style;
+    cssProperties.forEach(({ name, value }) => {
+        style.setProperty(name, value);
+    });
+    logger?.debug('[DesignTokens] Applied custom OKLCH CSS variables with validation', {
+        totalCustomTokens: Object.keys(customTokens).length,
+        darkMode: dark,
+        validTokens: appliedCount.valid,
+        invalidTokens: appliedCount.invalid,
+        batchSize: cssProperties.length,
+        target: target === document.documentElement ? 'document.documentElement' : 'custom element'
+    });
+}
+/**
+ * Apply complete design system configuration
+ */
+export function applyDesignSystemConfiguration(designSystem, options = {}) {
+    const { logger } = options;
+    // Apply standard tokens
+    if (designSystem.tokens) {
+        applyDesignTokens(designSystem.tokens, options);
+    }
+    // Apply custom tokens
+    if (designSystem.customTokens) {
+        applyCustomTokens(designSystem.customTokens, options);
+    }
+    // Apply typography configuration
+    if (designSystem.typography) {
+        applyTypographyConfiguration(designSystem.typography, options);
+    }
+    // logger?.debug('[DesignTokens] Complete design system applied', {
+    //   hasStandardTokens: !!designSystem.tokens,
+    //   hasCustomTokens: !!designSystem.customTokens,
+    //   hasTypography: !!designSystem.typography,
+    //   standardTokenCount: designSystem.tokens ? Object.keys(designSystem.tokens).length : 0,
+    //   customTokenCount: designSystem.customTokens ? Object.keys(designSystem.customTokens).length : 0
+    // });
+}
+// ============================================================================
+// Typography Configuration
+// ============================================================================
+/**
+ * Build CSS font-family string from FontConfiguration
+ */
+function buildFontStack(config) {
+    const primary = config.family.includes(' ') ? `'${config.family}'` : config.family;
+    const fallbacks = config.fallbacks.map(f => f.includes(' ') && !f.startsWith("'") && !f.startsWith('"') ? `'${f}'` : f);
+    return [primary, ...fallbacks].join(', ');
+}
+/**
+ * Build font-variation-settings string from defaults
+ */
+function buildVariationSettings(config) {
+    const settings = [];
+    if (config.defaults?.weight !== undefined) {
+        settings.push(`'wght' ${config.defaults.weight}`);
+    }
+    if (config.defaults?.width !== undefined) {
+        settings.push(`'wdth' ${config.defaults.width}`);
+    }
+    if (config.defaults?.opticalSize !== undefined) {
+        settings.push(`'opsz' ${config.defaults.opticalSize}`);
+    }
+    return settings.length > 0 ? settings.join(', ') : null;
+}
+/**
+ * Apply typography configuration as CSS variables
+ * Sets font families, weights, and features per typography role
+ */
+export function applyTypographyConfiguration(typography, options = {}) {
+    const { target = document.documentElement, logger } = options;
+    const cssProperties = [];
+    // Apply font configurations for each role
+    for (const role of Object.values(TypographyRole)) {
+        const config = typography.fonts[role];
+        if (!config)
+            continue;
+        // Font family
+        const fontStack = buildFontStack(config);
+        cssProperties.push({ name: `--font-${role}`, value: fontStack });
+        // Default weight
+        if (config.defaults?.weight !== undefined) {
+            cssProperties.push({
+                name: `--font-${role}-weight`,
+                value: String(config.defaults.weight)
+            });
+        }
+        // Default width
+        if (config.defaults?.width !== undefined) {
+            cssProperties.push({
+                name: `--font-${role}-width`,
+                value: String(config.defaults.width)
+            });
+        }
+        // Optical size
+        if (config.defaults?.opticalSize !== undefined) {
+            cssProperties.push({
+                name: `--font-${role}-opsz`,
+                value: String(config.defaults.opticalSize)
+            });
+        }
+        // Font feature settings
+        if (config.features) {
+            cssProperties.push({
+                name: `--font-${role}-features`,
+                value: config.features
+            });
+        }
+        // Font variation settings (combined string)
+        const variationSettings = buildVariationSettings(config);
+        if (variationSettings) {
+            cssProperties.push({
+                name: `--font-${role}-variation`,
+                value: variationSettings
+            });
+        }
+    }
+    // Apply type scale if provided
+    if (typography.scale) {
+        for (const [sizeName, entry] of Object.entries(typography.scale)) {
+            if (entry) {
+                cssProperties.push({ name: `--type-size-${sizeName}`, value: entry.size });
+                cssProperties.push({ name: `--type-lh-${sizeName}`, value: entry.lineHeight });
+                if (entry.letterSpacing) {
+                    cssProperties.push({ name: `--type-ls-${sizeName}`, value: entry.letterSpacing });
+                }
+            }
+        }
+    }
+    // Batch apply all CSS properties
+    const style = target.style;
+    cssProperties.forEach(({ name, value }) => {
+        style.setProperty(name, value);
+    });
+    // logger?.debug('[Typography] Applied typography CSS variables', {
+    //   rolesConfigured: Object.keys(typography.fonts).length,
+    //   scaleEntries: typography.scale ? Object.keys(typography.scale).length : 0,
+    //   totalProperties: cssProperties.length,
+    // });
+}
+/**
+ * Dark mode utilities with debouncing and error handling
+ * Works with existing data-theme approach while maintaining .dark class compatibility
+ */
+export const darkModeUtils = {
+    _debounceTimeout: null,
+    /**
+     * Set dark mode and persist preference with debouncing
+     * Uses both data-theme attribute and .dark class for compatibility
+     */
+    setDark(enabled) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            applyDarkModeState(enabled);
+            persistDarkModePreference(this, enabled ? UserTheme.DARK : UserTheme.LIGHT, enabled);
+        }
+        catch (error) {
+            console.error('[DarkMode] Failed to set dark mode:', error);
+        }
+    },
+    /**
+     * Apply "follow system" mode while persisting AUTO as the real preference.
+     */
+    setAuto() {
+        if (typeof window === 'undefined')
+            return false;
+        try {
+            const enabled = resolveSystemDarkMode();
+            applyDarkModeState(enabled);
+            persistDarkModePreference(this, UserTheme.AUTO, enabled);
+            return enabled;
+        }
+        catch (error) {
+            console.error('[DarkMode] Failed to apply auto theme preference:', error);
+            return false;
+        }
+    },
+    /**
+     * Initialize dark mode from localStorage or system preference
+     */
+    initDark() {
+        const shouldBeDark = resolvePreferredDarkMode();
+        if (typeof window !== 'undefined') {
+            applyDarkModeState(shouldBeDark);
+        }
+        return shouldBeDark;
+    },
+    /**
+     * Check if dark mode is currently active
+     */
+    isDark() {
+        return isCurrentlyDarkMode();
+    },
+    resolvePreferredDarkMode() {
+        return resolvePreferredDarkMode();
+    },
+    getStoredPreference() {
+        if (typeof window === 'undefined') {
+            return null;
+        }
+        try {
+            return resolveStoredDarkModePreference();
+        }
+        catch (error) {
+            console.warn('[DarkMode] Failed to read stored theme preference:', error);
+            return null;
+        }
+    },
+    isAuto() {
+        return this.getStoredPreference() === UserTheme.AUTO;
+    },
+    /**
+     * Toggle dark mode with debouncing
+     */
+    toggle() {
+        const newState = !this.isDark();
+        this.setDark(newState);
+        return newState;
+    },
+    /**
+     * Cleanup utility for memory management
+     */
+    cleanup() {
+        if (this._debounceTimeout) {
+            clearTimeout(this._debounceTimeout);
+            this._debounceTimeout = null;
+        }
+    }
+};
+/**
+ * Generate CSS string with OKLCH tokens for debugging or inspection
+ * Useful for development debugging or static CSS generation
+ */
+export function generateTokensCSS(designSystem, options = {}) {
+    const { includeDark = true, priorityTokens } = options;
+    let css = ':root {\n';
+    if (designSystem.tokens) {
+        const tokens = designSystem.tokens;
+        const tokensToInclude = priorityTokens
+            ? priorityTokens.filter(token => token in tokens)
+            : Object.keys(tokens);
+        // Light mode tokens
+        for (const token of tokensToInclude) {
+            const config = tokens[token];
+            if (config) {
+                const rawValue = getDesignTokenValue(config, 'light');
+                const value = config.type === DesignTokenValueType.COLOR
+                    ? ensureOklchWrapped(rawValue)
+                    : rawValue;
+                css += `  --${token}: ${value};\n`;
+            }
+        }
+    }
+    css += '}\n';
+    if (includeDark && designSystem.tokens) {
+        css += '.dark {\n';
+        const tokens = designSystem.tokens;
+        const tokensToInclude = priorityTokens
+            ? priorityTokens.filter(token => token in tokens)
+            : Object.keys(tokens);
+        for (const token of tokensToInclude) {
+            const config = tokens[token];
+            if (config && isDesignTokenLightDarkValueConfiguration(config)) {
+                const rawValue = getDesignTokenValue(config, 'dark');
+                const value = config.type === DesignTokenValueType.COLOR
+                    ? ensureOklchWrapped(rawValue)
+                    : rawValue;
+                css += `  --${token}: ${value};\n`;
+            }
+        }
+        css += '}\n';
+    }
+    return css;
+}
+/**
+ * Generate Google Fonts URL from font configurations
+ * Supports both static weights and variable font ranges
+ *
+ * @see https://developers.google.com/fonts/docs/css2
+ */
+export function generateGoogleFontsUrl(fonts) {
+    if (fonts.length === 0)
+        return '';
+    const families = fonts.map(font => {
+        const family = encodeURIComponent(font.family);
+        // Check if using variable font range
+        if (font.weightRange) {
+            const [minWeight, maxWeight] = font.weightRange;
+            // Variable font with weight range
+            if (font.widthRange) {
+                const [minWidth, maxWidth] = font.widthRange;
+                // Full variable with width and weight
+                if (font.italic) {
+                    return `family=${family}:ital,wdth,wght@0,${minWidth}..${maxWidth},${minWeight}..${maxWeight};1,${minWidth}..${maxWidth},${minWeight}..${maxWeight}`;
+                }
+                return `family=${family}:wdth,wght@${minWidth}..${maxWidth},${minWeight}..${maxWeight}`;
+            }
+            // Variable with only weight range
+            if (font.italic) {
+                return `family=${family}:ital,wght@0,${minWeight}..${maxWeight};1,${minWeight}..${maxWeight}`;
+            }
+            return `family=${family}:wght@${minWeight}..${maxWeight}`;
+        }
+        // Static weights (traditional approach)
+        const weights = font.weights ?? [400, 500, 600, 700];
+        const weightStr = weights.join(';');
+        if (font.italic) {
+            const italicWeights = weights.map(w => `0,${w};1,${w}`).join(';');
+            return `family=${family}:ital,wght@${italicWeights}`;
+        }
+        return `family=${family}:wght@${weightStr}`;
+    });
+    const display = fonts[0]?.display ?? 'swap';
+    return `https://fonts.googleapis.com/css2?${families.join('&')}&display=${display}`;
+}
+/**
+ * Convert FontConfiguration to GoogleFontConfig for loading
+ */
+export function fontConfigToGoogleFontConfig(config) {
+    // Check if this is a Google Font
+    if (!isGoogleFont(config.family)) {
+        return null;
+    }
+    const result = {
+        family: config.family,
+        display: 'swap',
+        italic: config.italic,
+    };
+    // Check for axis ranges (variable font)
+    const weightRange = config.axisRanges?.[FontAxis.WEIGHT];
+    const widthRange = config.axisRanges?.[FontAxis.WIDTH];
+    if (weightRange) {
+        result.weightRange = [weightRange.min, weightRange.max];
+    }
+    else {
+        // Default weights for static loading
+        result.weights = [300, 400, 500, 600, 700];
+    }
+    if (widthRange) {
+        result.widthRange = [widthRange.min, widthRange.max];
+    }
+    return result;
+}
+/**
+ * Load Google Fonts from typography configuration
+ * Automatically detects which fonts need loading and handles variable font ranges
+ *
+ * @returns Promise that resolves when all fonts are loaded (or timeout)
+ */
+export async function loadFontsFromTypography(typography, options = {}) {
+    const { logger, timeout = 5000, waitForLoad = true } = options;
+    if (typeof document === 'undefined') {
+        return {
+            success: true,
+            loadedFonts: [],
+            failedFonts: [],
+            loadTimeMs: 0,
+        };
+    }
+    // Collect unique fonts to load
+    const fontsToLoad = new Map();
+    const fontFamilies = [];
+    for (const role of Object.values(TypographyRole)) {
+        const config = typography.fonts[role];
+        if (!config)
+            continue;
+        const googleConfig = fontConfigToGoogleFontConfig(config);
+        if (googleConfig && !fontsToLoad.has(googleConfig.family)) {
+            fontsToLoad.set(googleConfig.family, googleConfig);
+            fontFamilies.push(googleConfig.family);
+        }
+    }
+    if (fontsToLoad.size === 0) {
+        logger?.debug('[Typography] No Google Fonts to load');
+        return {
+            success: true,
+            loadedFonts: [],
+            failedFonts: [],
+            loadTimeMs: 0,
+        };
+    }
+    logger?.debug('[Typography] Loading Google Fonts', {
+        fonts: fontFamilies,
+        count: fontsToLoad.size,
+    });
+    // Inject font stylesheet links
+    loadGoogleFonts(Array.from(fontsToLoad.values()));
+    // Optionally wait for fonts to actually load
+    if (waitForLoad) {
+        const result = await waitForFontsLoaded(fontFamilies, { timeout, logger });
+        logger?.debug('[Typography] Fonts loaded', {
+            success: result.success,
+            loadedFonts: result.loadedFonts,
+            failedFonts: result.failedFonts,
+            loadTimeMs: result.loadTimeMs,
+        });
+        return result;
+    }
+    return {
+        success: true,
+        loadedFonts: fontFamilies,
+        failedFonts: [],
+        loadTimeMs: 0,
+    };
+}
+/**
+ * Load Google Fonts dynamically
+ * Call this early in your application startup
+ */
+export function loadGoogleFonts(fonts) {
+    if (typeof document === 'undefined' || fonts.length === 0)
+        return;
+    const url = generateGoogleFontsUrl(fonts);
+    if (!url)
+        return;
+    // Check if already loaded with same URL
+    const existingLink = document.querySelector(`link[href^="https://fonts.googleapis.com/css2"]`);
+    if (existingLink && existingLink.getAttribute('href') === url) {
+        return; // Already loaded with same fonts
+    }
+    if (existingLink) {
+        existingLink.remove();
+    }
+    // Check/create preconnect links (only once)
+    if (!document.querySelector('link[href="https://fonts.googleapis.com"][rel="preconnect"]')) {
+        const preconnectGoogle = document.createElement('link');
+        preconnectGoogle.rel = 'preconnect';
+        preconnectGoogle.href = 'https://fonts.googleapis.com';
+        document.head.insertBefore(preconnectGoogle, document.head.firstChild);
+    }
+    if (!document.querySelector('link[href="https://fonts.gstatic.com"][rel="preconnect"]')) {
+        const preconnectGstatic = document.createElement('link');
+        preconnectGstatic.rel = 'preconnect';
+        preconnectGstatic.href = 'https://fonts.gstatic.com';
+        preconnectGstatic.crossOrigin = 'anonymous';
+        document.head.insertBefore(preconnectGstatic, document.head.firstChild.nextSibling);
+    }
+    // Create the font stylesheet link
+    const fontLink = document.createElement('link');
+    fontLink.rel = 'stylesheet';
+    fontLink.href = url;
+    document.head.appendChild(fontLink);
+}
+/**
+ * Common Google Font presets for easy usage
+ * Uses variable font weight ranges where available
+ *
+ * @see https://fonts.google.com/variablefonts
+ *
+ * Organized by category:
+ * - Sans-serif: Modern UI (40+ fonts)
+ * - Serif: Editorial/Premium (10+ fonts)
+ * - Display: Marketing/Heroes (10+ fonts)
+ * - Monospace: Code (8+ fonts)
+ */
+export const GoogleFontPresets = {
+    // ============================================================================
+    // SANS-SERIF: MODERN UI
+    // ============================================================================
+    // --- Geometric Sans ---
+    inter: {
+        family: GoogleVariableFont.INTER,
+        weightRange: [100, 900],
+    },
+    plusJakartaSans: {
+        family: GoogleVariableFont.PLUS_JAKARTA_SANS,
+        weightRange: [200, 800],
+    },
+    dmSans: {
+        family: GoogleVariableFont.DM_SANS,
+        weightRange: [100, 1000],
+        italic: true,
+    },
+    outfit: {
+        family: GoogleVariableFont.OUTFIT,
+        weightRange: [100, 900],
+    },
+    manrope: {
+        family: GoogleVariableFont.MANROPE,
+        weightRange: [200, 800],
+    },
+    spaceGrotesk: {
+        family: GoogleVariableFont.SPACE_GROTESK,
+        weightRange: [300, 700],
+    },
+    lexend: {
+        family: GoogleVariableFont.LEXEND,
+        weightRange: [100, 900],
+    },
+    sora: {
+        family: GoogleVariableFont.SORA,
+        weightRange: [100, 800],
+    },
+    figtree: {
+        family: GoogleVariableFont.FIGTREE,
+        weightRange: [300, 900],
+        italic: true,
+    },
+    urbanist: {
+        family: GoogleVariableFont.URBANIST,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    onest: {
+        family: GoogleVariableFont.ONEST,
+        weightRange: [100, 900],
+    },
+    albertSans: {
+        family: GoogleVariableFont.ALBERT_SANS,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    // --- Humanist/Friendly Sans ---
+    poppins: {
+        family: GoogleVariableFont.POPPINS,
+        weights: [100, 200, 300, 400, 500, 600, 700, 800, 900],
+        italic: true,
+    },
+    montserrat: {
+        family: GoogleVariableFont.MONTSERRAT,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    workSans: {
+        family: GoogleVariableFont.WORK_SANS,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    raleway: {
+        family: GoogleVariableFont.RALEWAY,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    nunito: {
+        family: GoogleVariableFont.NUNITO,
+        weightRange: [200, 1000],
+        italic: true,
+    },
+    nunitoSans: {
+        family: GoogleVariableFont.NUNITO_SANS,
+        weightRange: [200, 1000],
+        italic: true,
+    },
+    quicksand: {
+        family: GoogleVariableFont.QUICKSAND,
+        weightRange: [300, 700],
+    },
+    rubik: {
+        family: GoogleVariableFont.RUBIK,
+        weightRange: [300, 900],
+        italic: true,
+    },
+    karla: {
+        family: GoogleVariableFont.KARLA,
+        weightRange: [200, 800],
+        italic: true,
+    },
+    cabin: {
+        family: GoogleVariableFont.CABIN,
+        weightRange: [400, 700],
+        italic: true,
+    },
+    barlow: {
+        family: GoogleVariableFont.BARLOW,
+        weights: [100, 200, 300, 400, 500, 600, 700, 800, 900],
+        italic: true,
+    },
+    mulish: {
+        family: GoogleVariableFont.MULISH,
+        weightRange: [200, 1000],
+        italic: true,
+    },
+    josefinSans: {
+        family: GoogleVariableFont.JOSEFIN_SANS,
+        weightRange: [100, 700],
+        italic: true,
+    },
+    exo2: {
+        family: GoogleVariableFont.EXO_2,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    mavenPro: {
+        family: GoogleVariableFont.MAVEN_PRO,
+        weightRange: [400, 900],
+    },
+    archivo: {
+        family: GoogleVariableFont.ARCHIVO,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    // --- Advanced Variable (width axis) ---
+    robotoFlex: {
+        family: GoogleVariableFont.ROBOTO_FLEX,
+        weightRange: [100, 1000],
+        widthRange: [25, 151],
+    },
+    epilogue: {
+        family: GoogleVariableFont.EPILOGUE,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    hankenGrotesk: {
+        family: GoogleVariableFont.HANKEN_GROTESK,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    bricolageGrotesque: {
+        family: GoogleVariableFont.BRICOLAGE_GROTESQUE,
+        weightRange: [200, 800],
+    },
+    redHatDisplay: {
+        family: GoogleVariableFont.RED_HAT_DISPLAY,
+        weightRange: [300, 900],
+        italic: true,
+    },
+    // ============================================================================
+    // SERIF: EDITORIAL / PREMIUM
+    // ============================================================================
+    fraunces: {
+        family: GoogleVariableFont.FRAUNCES,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    playfairDisplay: {
+        family: GoogleVariableFont.PLAYFAIR_DISPLAY,
+        weightRange: [400, 900],
+        italic: true,
+    },
+    sourceSerif: {
+        family: GoogleVariableFont.SOURCE_SERIF_4,
+        weightRange: [200, 900],
+        italic: true,
+    },
+    crimsonPro: {
+        family: GoogleVariableFont.CRIMSON_PRO,
+        weightRange: [200, 900],
+        italic: true,
+    },
+    lora: {
+        family: GoogleVariableFont.LORA,
+        weightRange: [400, 700],
+        italic: true,
+    },
+    bitter: {
+        family: GoogleVariableFont.BITTER,
+        weightRange: [100, 900],
+        italic: true,
+    },
+    cormorant: {
+        family: GoogleVariableFont.CORMORANT,
+        weightRange: [300, 700],
+        italic: true,
+    },
+    literata: {
+        family: GoogleVariableFont.LITERATA,
+        weightRange: [200, 900],
+        italic: true,
+    },
+    newsreader: {
+        family: GoogleVariableFont.NEWSREADER,
+        weightRange: [200, 800],
+        italic: true,
+    },
+    // ============================================================================
+    // DISPLAY: MARKETING / HEROES
+    // ============================================================================
+    unbounded: {
+        family: GoogleVariableFont.UNBOUNDED,
+        weightRange: [200, 900],
+    },
+    familjenGrotesk: {
+        family: GoogleVariableFont.FAMILJEN_GROTESK,
+        weightRange: [400, 700],
+        italic: true,
+    },
+    oswald: {
+        family: GoogleVariableFont.OSWALD,
+        weightRange: [200, 700],
+    },
+    bebasNeue: {
+        family: GoogleVariableFont.BEBAS_NEUE,
+        weights: [400],
+    },
+    anton: {
+        family: GoogleVariableFont.ANTON,
+        weights: [400],
+    },
+    lobster: {
+        family: GoogleVariableFont.LOBSTER,
+        weights: [400],
+    },
+    pacifico: {
+        family: GoogleVariableFont.PACIFICO,
+        weights: [400],
+    },
+    // ============================================================================
+    // MONOSPACE: CODE
+    // ============================================================================
+    jetbrainsMono: {
+        family: GoogleVariableFont.JETBRAINS_MONO,
+        weightRange: [100, 800],
+        italic: true,
+    },
+    firaCode: {
+        family: GoogleVariableFont.FIRA_CODE,
+        weightRange: [300, 700],
+    },
+    sourceCodePro: {
+        family: GoogleVariableFont.SOURCE_CODE_PRO,
+        weightRange: [200, 900],
+        italic: true,
+    },
+    inconsolata: {
+        family: GoogleVariableFont.INCONSOLATA,
+        weightRange: [200, 900],
+    },
+    robotoMono: {
+        family: GoogleVariableFont.ROBOTO_MONO,
+        weightRange: [100, 700],
+        italic: true,
+    },
+    ibmPlexMono: {
+        family: GoogleVariableFont.IBM_PLEX_MONO,
+        weights: [100, 200, 300, 400, 500, 600, 700],
+        italic: true,
+    },
+    spaceMono: {
+        family: GoogleVariableFont.SPACE_MONO,
+        weights: [400, 700],
+        italic: true,
+    },
+    redHatMono: {
+        family: GoogleVariableFont.RED_HAT_MONO,
+        weightRange: [300, 700],
+        italic: true,
+    },
+};
+// ============================================================================
+// Font Loading Watcher
+// ============================================================================
+/**
+ * Wait for specific fonts to be loaded using the CSS Font Loading API
+ * Returns a promise that resolves when all fonts are loaded or timeout occurs
+ *
+ * @param fontFamilies - Array of font family names to wait for
+ * @param options - Configuration options
+ * @returns Promise with load result
+ */
+export async function waitForFontsLoaded(fontFamilies, options = {}) {
+    const { timeout = 5000, logger } = options;
+    const startTime = performance.now();
+    if (typeof document === 'undefined' || !('fonts' in document)) {
+        logger?.warn('[FontLoader] Font Loading API not available');
+        return {
+            success: true, // Assume success in non-browser environment
+            loadedFonts: fontFamilies,
+            failedFonts: [],
+            loadTimeMs: 0,
+        };
+    }
+    const loadedFonts = [];
+    const failedFonts = [];
+    try {
+        // Helper to check if a stylesheet link exists and contains the font family
+        const checkStylesheetForFont = (fontFamily) => {
+            const cleanFamily = fontFamily.replace(/['"]/g, '');
+            const stylesheetLinks = document.querySelectorAll('link[href*="fonts.googleapis.com"][rel="stylesheet"]');
+            for (const link of Array.from(stylesheetLinks)) {
+                const href = link.href || link.getAttribute('href') || '';
+                if (!href)
+                    continue;
+                // Google Fonts URLs use format:
+                // https://fonts.googleapis.com/css2?family=FontName:wght@...&family=OtherFont&display=swap
+                // Check for family parameter with this specific font name
+                // Encode the family name to match URL encoding
+                const encodedFamily = encodeURIComponent(cleanFamily);
+                // Check for family=FontName followed by:
+                // - : (colon for parameters like :wght@) or %3A (encoded colon)
+                // - & (next parameter) or %26 (encoded ampersand)
+                // - End of string/query
+                // This prevents false matches (e.g., "Roboto" matching "Roboto Mono" or "RobotoMono")
+                // The encoded family name ensures exact match (spaces become %20, etc.)
+                // We require the family name to be followed by a delimiter or end of string
+                const escapedFamily = encodedFamily.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const familyPattern = new RegExp(`[?&]family=${escapedFamily}(?:[:&%]|$|%3A|%26)`, 'i');
+                if (familyPattern.test(href)) {
+                    // Stylesheet contains this font family
+                    // Note: link.sheet might be null if stylesheet hasn't loaded yet
+                    // We'll be lenient and assume it's loading if the link exists
+                    return true;
+                }
+            }
+            return false;
+        };
+        // Wait a brief moment for stylesheet to start loading (especially important on hot reload)
+        await new Promise(resolve => setTimeout(resolve, 100));
+        // Wait for document.fonts.ready to ensure font loading API is ready
+        // Use a shorter timeout to avoid blocking too long
+        const fontsReadyTimeout = Math.min(timeout, 2000);
+        try {
+            await Promise.race([
+                document.fonts.ready,
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Fonts ready timeout')), fontsReadyTimeout)),
+            ]);
+        }
+        catch {
+            // Fonts ready timeout is not critical, continue with checks
+            logger?.debug('[FontLoader] document.fonts.ready timeout, continuing anyway');
+        }
+        // Calculate remaining timeout for individual font checks
+        const elapsed = performance.now() - startTime;
+        const remainingTimeout = Math.max(1000, timeout - elapsed - 500); // Reserve 500ms for overhead
+        // Create font check promises with timeout
+        const fontPromises = fontFamilies.map(async (fontFamily) => {
+            const cleanFamily = fontFamily.replace(/['"]/g, '');
+            const fontCheckStartTime = performance.now();
+            try {
+                const testString = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+                const fontSpec = `400 16px "${cleanFamily}"`;
+                // First check if font is already loaded (common on hot reload)
+                if (document.fonts.check(fontSpec)) {
+                    loadedFonts.push(cleanFamily);
+                    logger?.debug(`[FontLoader] Font already loaded: ${cleanFamily}`);
+                    return;
+                }
+                // Check if stylesheet exists for this specific font
+                const stylesheetExists = checkStylesheetForFont(cleanFamily);
+                // Try to load the font
+                let loadAttempted = false;
+                try {
+                    await Promise.race([
+                        document.fonts.load(fontSpec, testString),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Font load timeout')), remainingTimeout)),
+                    ]);
+                    loadAttempted = true;
+                }
+                catch (loadError) {
+                    // Font load failed or timed out, but check if it's available anyway (might be cached)
+                    loadAttempted = true;
+                }
+                // Wait a bit for font to become available after load attempt
+                await new Promise(resolve => setTimeout(resolve, 100));
+                // Verify font is available with retry logic
+                // Use remaining timeout to ensure we don't exceed total timeout
+                const checkElapsed = performance.now() - fontCheckStartTime;
+                const checkTimeout = Math.max(500, remainingTimeout - checkElapsed);
+                const maxRetries = 5;
+                const retryDelays = [50, 100, 150, 200, 250]; // Total max delay: 750ms
+                let isLoaded = false;
+                let totalRetryTime = 0;
+                for (let attempt = 0; attempt < maxRetries && totalRetryTime < checkTimeout; attempt++) {
+                    isLoaded = document.fonts.check(fontSpec);
+                    if (isLoaded)
+                        break;
+                    if (attempt < maxRetries - 1) {
+                        const delay = retryDelays[attempt] || 250;
+                        await new Promise(resolve => setTimeout(resolve, delay));
+                        totalRetryTime += delay;
+                    }
+                }
+                if (isLoaded) {
+                    loadedFonts.push(cleanFamily);
+                    logger?.debug(`[FontLoader] Font loaded: ${cleanFamily}`);
+                }
+                else {
+                    // Font check failed - decide whether to treat as failure or assume loading
+                    if (stylesheetExists && loadAttempted) {
+                        // Stylesheet exists and we attempted to load - likely a timing issue on hot reload
+                        // Be lenient and assume font will load (prevents false warnings)
+                        loadedFonts.push(cleanFamily);
+                        logger?.debug(`[FontLoader] Font assumed loaded (stylesheet present, timing issue): ${cleanFamily}`);
+                    }
+                    else if (stylesheetExists && !loadAttempted) {
+                        // Stylesheet exists but load wasn't attempted (timeout too short)
+                        // Still be lenient - stylesheet is there, font should load
+                        loadedFonts.push(cleanFamily);
+                        logger?.debug(`[FontLoader] Font assumed loaded (stylesheet present, load not attempted): ${cleanFamily}`);
+                    }
+                    else {
+                        // No stylesheet found - this is a real failure
+                        failedFonts.push(cleanFamily);
+                        logger?.warn(`[FontLoader] Font check failed: ${cleanFamily} (no stylesheet found)`);
+                    }
+                }
+            }
+            catch (error) {
+                // On error, check if font might still be available
+                const fontSpec = `400 16px "${cleanFamily}"`;
+                if (document.fonts.check(fontSpec)) {
+                    loadedFonts.push(cleanFamily);
+                    logger?.debug(`[FontLoader] Font available despite error: ${cleanFamily}`);
+                }
+                else {
+                    // Check if stylesheet exists - if so, be lenient (common on hot reload)
+                    const stylesheetExists = checkStylesheetForFont(cleanFamily);
+                    if (stylesheetExists) {
+                        loadedFonts.push(cleanFamily);
+                        logger?.debug(`[FontLoader] Font assumed loaded (stylesheet present, error): ${cleanFamily}`);
+                    }
+                    else {
+                        failedFonts.push(cleanFamily);
+                        logger?.warn(`[FontLoader] Failed to load font: ${cleanFamily}`, {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+        });
+        await Promise.all(fontPromises);
+        const loadTimeMs = Math.round(performance.now() - startTime);
+        logger?.debug('[FontLoader] Font loading complete', {
+            loadedCount: loadedFonts.length,
+            failedCount: failedFonts.length,
+            loadTimeMs,
+            loadedFonts,
+            failedFonts,
+        });
+        return {
+            success: failedFonts.length === 0,
+            loadedFonts,
+            failedFonts,
+            loadTimeMs,
+        };
+    }
+    catch (error) {
+        const loadTimeMs = Math.round(performance.now() - startTime);
+        logger?.error('[FontLoader] Font loading error', {
+            error: error instanceof Error ? error.message : String(error),
+            loadTimeMs,
+        });
+        return {
+            success: false,
+            loadedFonts,
+            failedFonts: fontFamilies.filter(f => !loadedFonts.includes(f.replace(/['"]/g, ''))),
+            loadTimeMs,
+        };
+    }
+}
+/**
+ * Extract font family name from a CSS font-family string
+ * E.g., "Inter, system-ui, sans-serif" => "Inter"
+ */
+export function extractPrimaryFontFamily(fontStack) {
+    const match = fontStack.match(/^['"]?([^'",]+)['"]?/);
+    return match ? match[1].trim() : null;
+}
+/**
+ * Check if a font family is a Google Font (not system font)
+ */
+export function isGoogleFont(fontFamily) {
+    const systemFonts = [
+        'system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI',
+        'Roboto', 'Helvetica', 'Arial', 'sans-serif', 'serif', 'monospace',
+        'Georgia', 'Times New Roman', 'Times', 'Cambria', 'Courier New',
+        'Monaco', 'Menlo', 'Consolas', 'SF Mono', 'ui-sans-serif', 'ui-serif',
+        'ui-monospace'
+    ];
+    return !systemFonts.some(sf => fontFamily.toLowerCase() === sf.toLowerCase());
+}
+// ============================================================================
+// Chart Color Utilities
+// ============================================================================
+/**
+ * Tailwind color palette with all shades
+ * Complete color values from Tailwind CSS v3/v4
+ * @see https://tailwindcss.com/docs/customizing-colors
+ */
+const TAILWIND_COLOR_SHADES = {
+    red: { 50: '#fef2f2', 100: '#fee2e2', 200: '#fecaca', 300: '#fca5a5', 400: '#f87171', 500: '#ef4444', 600: '#dc2626', 700: '#b91c1c', 800: '#991b1b', 900: '#7f1d1d', 950: '#450a0a' },
+    orange: { 50: '#fff7ed', 100: '#ffedd5', 200: '#fed7aa', 300: '#fdba74', 400: '#fb923c', 500: '#f97316', 600: '#ea580c', 700: '#c2410c', 800: '#9a3412', 900: '#7c2d12', 950: '#431407' },
+    amber: { 50: '#fffbeb', 100: '#fef3c7', 200: '#fde68a', 300: '#fcd34d', 400: '#fbbf24', 500: '#f59e0b', 600: '#d97706', 700: '#b45309', 800: '#92400e', 900: '#78350f', 950: '#451a03' },
+    yellow: { 50: '#fefce8', 100: '#fef9c3', 200: '#fef08a', 300: '#fde047', 400: '#facc15', 500: '#eab308', 600: '#ca8a04', 700: '#a16207', 800: '#854d0e', 900: '#713f12', 950: '#422006' },
+    lime: { 50: '#f7fee7', 100: '#ecfccb', 200: '#d9f99d', 300: '#bef264', 400: '#a3e635', 500: '#84cc16', 600: '#65a30d', 700: '#4d7c0f', 800: '#3f6212', 900: '#365314', 950: '#1a2e05' },
+    green: { 50: '#f0fdf4', 100: '#dcfce7', 200: '#bbf7d0', 300: '#86efac', 400: '#4ade80', 500: '#22c55e', 600: '#16a34a', 700: '#15803d', 800: '#166534', 900: '#14532d', 950: '#052e16' },
+    emerald: { 50: '#ecfdf5', 100: '#d1fae5', 200: '#a7f3d0', 300: '#6ee7b7', 400: '#34d399', 500: '#10b981', 600: '#059669', 700: '#047857', 800: '#065f46', 900: '#064e3b', 950: '#022c22' },
+    teal: { 50: '#f0fdfa', 100: '#ccfbf1', 200: '#99f6e4', 300: '#5eead4', 400: '#2dd4bf', 500: '#14b8a6', 600: '#0d9488', 700: '#0f766e', 800: '#115e59', 900: '#134e4a', 950: '#042f2e' },
+    cyan: { 50: '#ecfeff', 100: '#cffafe', 200: '#a5f3fc', 300: '#67e8f9', 400: '#22d3ee', 500: '#06b6d4', 600: '#0891b2', 700: '#0e7490', 800: '#155e75', 900: '#164e63', 950: '#083344' },
+    sky: { 50: '#f0f9ff', 100: '#e0f2fe', 200: '#bae6fd', 300: '#7dd3fc', 400: '#38bdf8', 500: '#0ea5e9', 600: '#0284c7', 700: '#0369a1', 800: '#075985', 900: '#0c4a6e', 950: '#082f49' },
+    blue: { 50: '#eff6ff', 100: '#dbeafe', 200: '#bfdbfe', 300: '#93c5fd', 400: '#60a5fa', 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8', 800: '#1e40af', 900: '#1e3a8a', 950: '#172554' },
+    indigo: { 50: '#eef2ff', 100: '#e0e7ff', 200: '#c7d2fe', 300: '#a5b4fc', 400: '#818cf8', 500: '#6366f1', 600: '#4f46e5', 700: '#4338ca', 800: '#3730a3', 900: '#312e81', 950: '#1e1b4b' },
+    violet: { 50: '#f5f3ff', 100: '#ede9fe', 200: '#ddd6fe', 300: '#c4b5fd', 400: '#a78bfa', 500: '#8b5cf6', 600: '#7c3aed', 700: '#6d28d9', 800: '#5b21b6', 900: '#4c1d95', 950: '#2e1065' },
+    purple: { 50: '#faf5ff', 100: '#f3e8ff', 200: '#e9d5ff', 300: '#d8b4fe', 400: '#c084fc', 500: '#a855f7', 600: '#9333ea', 700: '#7e22ce', 800: '#6b21a8', 900: '#581c87', 950: '#3b0764' },
+    fuchsia: { 50: '#fdf4ff', 100: '#fae8ff', 200: '#f5d0fe', 300: '#f0abfc', 400: '#e879f9', 500: '#d946ef', 600: '#c026d3', 700: '#a21caf', 800: '#86198f', 900: '#701a75', 950: '#4a044e' },
+    pink: { 50: '#fdf2f8', 100: '#fce7f3', 200: '#fbcfe8', 300: '#f9a8d4', 400: '#f472b6', 500: '#ec4899', 600: '#db2777', 700: '#be185d', 800: '#9d174d', 900: '#831843', 950: '#500724' },
+    rose: { 50: '#fff1f2', 100: '#ffe4e6', 200: '#fecdd3', 300: '#fda4af', 400: '#fb7185', 500: '#f43f5e', 600: '#e11d48', 700: '#be123c', 800: '#9f1239', 900: '#881337', 950: '#4c0519' },
+    slate: { 50: '#f8fafc', 100: '#f1f5f9', 200: '#e2e8f0', 300: '#cbd5e1', 400: '#94a3b8', 500: '#64748b', 600: '#475569', 700: '#334155', 800: '#1e293b', 900: '#0f172a', 950: '#020617' },
+    gray: { 50: '#f9fafb', 100: '#f3f4f6', 200: '#e5e7eb', 300: '#d1d5db', 400: '#9ca3af', 500: '#6b7280', 600: '#4b5563', 700: '#374151', 800: '#1f2937', 900: '#111827', 950: '#030712' },
+    zinc: { 50: '#fafafa', 100: '#f4f4f5', 200: '#e4e4e7', 300: '#d4d4d8', 400: '#a1a1aa', 500: '#71717a', 600: '#52525b', 700: '#3f3f46', 800: '#27272a', 900: '#18181b', 950: '#09090b' },
+    neutral: { 50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 300: '#d4d4d4', 400: '#a3a3a3', 500: '#737373', 600: '#525252', 700: '#404040', 800: '#262626', 900: '#171717', 950: '#0a0a0a' },
+    stone: { 50: '#fafaf9', 100: '#f5f5f4', 200: '#e7e5e4', 300: '#d6d3d1', 400: '#a8a29e', 500: '#78716c', 600: '#57534e', 700: '#44403c', 800: '#292524', 900: '#1c1917', 950: '#0c0a09' },
+};
+/**
+ * Get a single Tailwind color hex value
+ * @param colorName - Tailwind color name (e.g., 'sky', 'emerald')
+ * @param shade - Color shade (400, 500, or 600), defaults to 500
+ */
+export function getTailwindColor(colorName, shade = 500) {
+    const normalizedName = colorName.toLowerCase();
+    const color = TAILWIND_COLOR_SHADES[normalizedName];
+    if (!color) {
+        console.warn(`[ChartColors] Unknown Tailwind color: ${colorName}, falling back to gray`);
+        return TAILWIND_COLOR_SHADES.gray[shade];
+    }
+    return color[shade];
+}
+/**
+ * Parse chart color palette from CSS variable or string
+ * @param paletteValue - Comma-separated list of Tailwind color names
+ */
+export function parseChartColorPalette(paletteValue) {
+    if (!paletteValue) {
+        return DEFAULT_CHART_COLOR_PALETTE;
+    }
+    const parsedPalette = paletteValue
+        .split(',')
+        .map(c => c.trim().toLowerCase())
+        .filter(c => c in TAILWIND_COLOR_SHADES);
+    if (parsedPalette.length === 0) {
+        console.warn('[ChartColors] Chart palette resolved to no known Tailwind colors, falling back to default palette');
+        return DEFAULT_CHART_COLOR_PALETTE;
+    }
+    return parsedPalette;
+}
+/**
+ * Get chart color palette from document CSS variables
+ */
+export function getChartColorPaletteFromCSS() {
+    if (typeof document === 'undefined') {
+        return DEFAULT_CHART_COLOR_PALETTE;
+    }
+    const paletteValue = getComputedStyle(document.documentElement)
+        .getPropertyValue('--chart-color-palette')
+        .trim();
+    return parseChartColorPalette(paletteValue || null);
+}
+/**
+ * Generate chart colors array from palette
+ * @param count - Number of colors needed
+ * @param options - Configuration options
+ */
+export function getChartColors(count, options = {}) {
+    const { palette = getChartColorPaletteFromCSS(), shade = 500, cycleIfNeeded = true, } = options;
+    const safePalette = palette.length > 0 ? palette : DEFAULT_CHART_COLOR_PALETTE;
+    const colors = [];
+    for (let i = 0; i < count; i++) {
+        const colorIndex = cycleIfNeeded ? i % safePalette.length : Math.min(i, safePalette.length - 1);
+        colors.push(getTailwindColor(safePalette[colorIndex], shade));
+    }
+    return colors;
+}
+/**
+ * Generate a ChartConfig object with auto-assigned colors
+ * Compatible with ECharts chart components
+ *
+ * @example
+ * const config = generateChartConfig({
+ *   sales: { label: 'Sales' },
+ *   revenue: { label: 'Revenue' },
+ *   profit: { label: 'Profit' },
+ * });
+ * // Result: Each key gets an auto-assigned color from the palette
+ */
+export function generateChartConfig(keys, options = {}) {
+    const { palette = getChartColorPaletteFromCSS(), shade = 500, } = options;
+    const keyArray = Object.keys(keys);
+    const colors = getChartColors(keyArray.length, { palette, shade });
+    const result = { ...keys };
+    keyArray.forEach((key, index) => {
+        result[key] = {
+            ...keys[key],
+            color: colors[index],
+        };
+    });
+    return result;
+}
+/**
+ * Apply chart color palette to CSS variables
+ * Generates CHART_1 through CHART_N from the palette
+ */
+export function applyChartColorPalette(palette = DEFAULT_CHART_COLOR_PALETTE, options = {}) {
+    const { target = typeof document !== 'undefined' ? document.documentElement : null, maxColors = 10, shade = 500, } = options;
+    if (!target)
+        return;
+    const colorsToApply = Math.min(palette.length, maxColors);
+    for (let i = 0; i < colorsToApply; i++) {
+        const color = getTailwindColor(palette[i], shade);
+        target.style.setProperty(`--chart-${i + 1}`, color);
+    }
+    // Store palette for runtime access
+    target.style.setProperty('--chart-color-palette', palette.slice(0, maxColors).join(','));
+}
+//# sourceMappingURL=design-token.utils.js.map