/**
 * Token Helper Utilities
 * Type-safe helpers for using design tokens in inline styles
 *
 * @example
 * ```typescript
 * import { cssVar, spacing, colors } from '@ainativekit/ui/tokens';
 *
 * // Direct value access (returns actual values like '32px', '#FFFFFF')
 * <div style={{ gap: spacing[16], color: colors.light.text.primary }} />
 *
 * // CSS variable access (returns 'var(--ai-spacing-16)', useful for theme-aware styles)
 * <div style={{ gap: cssVar.spacing(16), color: cssVar.color('text-primary') }} />
 * ```
 */
import { type SpacingScale } from './spacing';
import { type ElevationLevel } from './elevation';
export type { ElevationLevel, SpacingScale };
/**
 * Color paths for accessing nested color tokens via CSS variables
 * These map to actual --ai-color-* CSS custom properties
 *
 * Brand colors are customizable via ThemeProvider and provide semantic meaning
 * for different UI states (primary actions, success, warnings, errors)
 *
 * @example 'text-primary', 'bg-secondary', 'brand-primary', 'brand-success'
 */
export type ColorPath = 'text-primary' | 'text-secondary' | 'text-tertiary' | 'text-inverted' | 'bg-primary' | 'bg-secondary' | 'bg-tertiary' | 'icon-primary' | 'icon-secondary' | 'icon-tertiary' | 'icon-inverted' | 'accent-blue' | 'accent-red' | 'accent-orange' | 'accent-green' | 'brand-primary' | 'brand-primary-hover' | 'brand-primary-active' | 'brand-on-primary' | 'brand-success' | 'brand-success-hover' | 'brand-success-active' | 'brand-on-success' | 'brand-warning' | 'brand-warning-hover' | 'brand-warning-active' | 'brand-on-warning' | 'brand-error' | 'brand-error-hover' | 'brand-error-active' | 'brand-on-error' | 'outline' | 'border-light' | 'border-default' | 'border-heavy';
/**
 * Radius scale values (none, sm, md, base, lg, xl, full)
 */
export type RadiusScale = 'none' | 'sm' | 'md' | 'base' | 'lg' | 'xl' | 'full';
/**
 * Typography style names
 */
export type TypographyStyle = 'heading1' | 'heading2' | 'heading3' | 'body' | 'bodyEmph' | 'bodySmall' | 'bodySmallEmph' | 'caption' | 'captionEmph' | 'button' | 'badge';
/**
 * Opacity presets
 */
export type OpacityPreset = 'full' | 'subtle' | 'muted' | 'disabled';
/**
 * Spacing tokens - returns actual pixel values
 * @example spacing[16] // '32px'
 */
export declare const spacing: Record<SpacingScale, string>;
/**
 * Color tokens organized by theme
 * @example colors.light.text.primary // '#0D0D0D'
 */
export declare const colors: {
    readonly light: {
        readonly background: {
            readonly primary: "#FFFFFF";
            readonly secondary: "#E8E8E8";
            readonly tertiary: "#F3F3F3";
        };
        readonly text: {
            readonly primary: "#0D0D0D";
            readonly secondary: "#5D5D5D";
            readonly tertiary: "#8F8F8F";
            readonly inverted: "#1B1B1F";
        };
        readonly icon: {
            readonly primary: "#0D0D0D";
            readonly secondary: "#5D5D5D";
            readonly tertiary: "#8F8F8F";
            readonly inverted: "#1B1B1F";
        };
        readonly accent: {
            readonly blue: "#0285FF";
            readonly red: "#E02E2A";
            readonly orange: "#E25507";
            readonly green: "#008635";
        };
        readonly brand: {
            readonly primary: {
                readonly base: "#0285FF";
                readonly hover: "#016FDB";
                readonly active: "#0159B8";
                readonly onColor: "#FFFFFF";
            };
            readonly success: {
                readonly base: "#008635";
                readonly hover: "#00722E";
                readonly active: "#005E25";
                readonly onColor: "#FFFFFF";
            };
            readonly warning: {
                readonly base: "#E25507";
                readonly hover: "#C14906";
                readonly active: "#A03E05";
                readonly onColor: "#FFFFFF";
            };
            readonly error: {
                readonly base: "#E02E2A";
                readonly hover: "#BF2723";
                readonly active: "#9E201D";
                readonly onColor: "#FFFFFF";
            };
        };
        readonly outline: "#79747E";
        readonly border: {
            readonly light: "rgba(13, 13, 13, 0.05)";
            readonly default: "rgba(13, 13, 13, 0.10)";
            readonly heavy: "rgba(13, 13, 13, 0.15)";
        };
        readonly state: {
            readonly hover: {
                readonly background: "rgba(13, 13, 13, 0.08)";
                readonly opacity: 0.9;
            };
            readonly active: {
                readonly opacity: 1;
                readonly scale: 0.98;
            };
            readonly disabled: {
                readonly opacity: 0.4;
            };
            readonly focus: {
                readonly outline: "#0285FF";
                readonly offset: "2px";
            };
        };
    };
    readonly dark: {
        readonly background: {
            readonly primary: "#212121";
            readonly secondary: "#303030";
            readonly tertiary: "#414141";
        };
        readonly text: {
            readonly primary: "#FFFFFF";
            readonly secondary: "#CDCDCD";
            readonly tertiary: "#AFAFAF";
            readonly inverted: "#FFFFFF";
        };
        readonly icon: {
            readonly primary: "#FFFFFF";
            readonly secondary: "#CDCDCD";
            readonly tertiary: "#AFAFAF";
            readonly inverted: "#FFFFFF";
        };
        readonly accent: {
            readonly blue: "#0285FF";
            readonly red: "#FF8583";
            readonly orange: "#FF9E6C";
            readonly green: "#40C977";
        };
        readonly brand: {
            readonly primary: {
                readonly base: "#0285FF";
                readonly hover: "#1A92FF";
                readonly active: "#339FFF";
                readonly onColor: "#FFFFFF";
            };
            readonly success: {
                readonly base: "#40C977";
                readonly hover: "#56D487";
                readonly active: "#6BDF97";
                readonly onColor: "#000000";
            };
            readonly warning: {
                readonly base: "#FF9E6C";
                readonly hover: "#FFAB82";
                readonly active: "#FFB898";
                readonly onColor: "#000000";
            };
            readonly error: {
                readonly base: "#FF8583";
                readonly hover: "#FF9D9B";
                readonly active: "#FFB5B3";
                readonly onColor: "#000000";
            };
        };
        readonly outline: "#938F99";
        readonly border: {
            readonly light: "rgba(255, 255, 255, 0.08)";
            readonly default: "rgba(255, 255, 255, 0.12)";
            readonly heavy: "rgba(255, 255, 255, 0.16)";
        };
        readonly state: {
            readonly hover: {
                readonly background: "rgba(255, 255, 255, 0.08)";
                readonly opacity: 0.9;
            };
            readonly active: {
                readonly opacity: 1;
                readonly scale: 0.98;
            };
            readonly disabled: {
                readonly opacity: 0.4;
            };
            readonly focus: {
                readonly outline: "#0285FF";
                readonly offset: "2px";
            };
        };
    };
};
/**
 * Border radius tokens
 * @example radius.xl // '24px'
 */
export declare const radius: {
    readonly none: "0px";
    readonly sm: "4px";
    readonly md: "8px";
    readonly base: "12px";
    readonly lg: "16px";
    readonly xl: "24px";
    readonly full: "9999px";
};
/**
 * Typography tokens with full style definitions
 * @example typography.heading1 // { fontSize: '36px', lineHeight: '40px', fontWeight: 600, ... }
 */
export declare const typography: {
    readonly heading1: {
        readonly fontSize: "36px";
        readonly lineHeight: "40px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.1px";
        readonly className: "ai-heading1";
        readonly meta: {
            readonly description: "Primary heading for page titles and hero sections";
            readonly usage: "Use for the main heading of a page or section. Should be used once per page.";
            readonly a11y: "Should map to semantic <h1> elements for proper document structure";
        };
    };
    readonly heading2: {
        readonly fontSize: "24px";
        readonly lineHeight: "28px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.25px";
        readonly className: "ai-heading2";
        readonly meta: {
            readonly description: "Secondary heading for major sections";
            readonly usage: "Use for section headings and subsections within a page";
            readonly a11y: "Should map to semantic <h2> elements";
        };
    };
    readonly heading3: {
        readonly fontSize: "18px";
        readonly lineHeight: "26px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.45px";
        readonly className: "ai-heading3";
        readonly meta: {
            readonly description: "Tertiary heading for subsections";
            readonly usage: "Use for subsection headings and card titles";
            readonly a11y: "Should map to semantic <h3> elements";
        };
    };
    readonly body: {
        readonly fontSize: "16px";
        readonly lineHeight: "26px";
        readonly fontWeight: 400;
        readonly letterSpacing: "-0.4px";
        readonly className: "ai-body";
        readonly meta: {
            readonly description: "Default body text for main content";
            readonly usage: "Use for paragraphs, descriptions, and general content";
            readonly a11y: "Standard reading size optimized for readability";
        };
    };
    readonly bodyEmph: {
        readonly fontSize: "16px";
        readonly lineHeight: "26px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.4px";
        readonly className: "ai-body-emph";
        readonly meta: {
            readonly description: "Emphasized body text";
            readonly usage: "Use to emphasize key points within body text";
            readonly a11y: "Use <strong> or <b> for semantic emphasis";
        };
    };
    readonly bodyLight: {
        readonly fontSize: "16px";
        readonly lineHeight: "26px";
        readonly fontWeight: 300;
        readonly letterSpacing: "-0.4px";
        readonly className: "ai-body-light";
        readonly meta: {
            readonly description: "Light weight body text";
            readonly usage: "Use for subtle, less prominent body text or decorative elements";
            readonly a11y: "Ensure sufficient contrast when using lighter weights";
        };
    };
    readonly bodySmall: {
        readonly fontSize: "14px";
        readonly lineHeight: "18px";
        readonly fontWeight: 400;
        readonly letterSpacing: "-0.3px";
        readonly className: "ai-body-small";
        readonly meta: {
            readonly description: "Smaller body text for secondary information";
            readonly usage: "Use for supporting text, metadata, and less prominent content";
            readonly a11y: "Ensure text remains readable at this size";
        };
    };
    readonly bodySmallEmph: {
        readonly fontSize: "14px";
        readonly lineHeight: "18px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.3px";
        readonly className: "ai-body-small-emph";
        readonly meta: {
            readonly description: "Emphasized smaller body text";
            readonly usage: "Use for emphasized secondary information";
            readonly a11y: "Use <strong> or <b> for semantic emphasis";
        };
    };
    readonly bodySmallLight: {
        readonly fontSize: "14px";
        readonly lineHeight: "18px";
        readonly fontWeight: 300;
        readonly letterSpacing: "-0.3px";
        readonly className: "ai-body-small-light";
        readonly meta: {
            readonly description: "Light weight smaller body text";
            readonly usage: "Use for subtle secondary information or decorative text";
            readonly a11y: "Ensure sufficient contrast and readability at this smaller size";
        };
    };
    readonly caption: {
        readonly fontSize: "12px";
        readonly lineHeight: "16px";
        readonly fontWeight: 400;
        readonly letterSpacing: "-0.1px";
        readonly className: "ai-caption";
        readonly meta: {
            readonly description: "Small text for captions and labels";
            readonly usage: "Use for image captions, input labels, and fine print";
            readonly a11y: "Minimum recommended size for readability";
        };
    };
    readonly captionEmph: {
        readonly fontSize: "12px";
        readonly lineHeight: "16px";
        readonly fontWeight: 600;
        readonly letterSpacing: "-0.1px";
        readonly className: "ai-caption-emph";
        readonly meta: {
            readonly description: "Emphasized caption text";
            readonly usage: "Use for emphasized labels and important captions";
            readonly a11y: "Ensure adequate contrast for accessibility";
        };
    };
    readonly button: {
        readonly fontSize: "15px";
        readonly lineHeight: "24px";
        readonly fontWeight: 500;
        readonly letterSpacing: "-0.24px";
        readonly className: "ai-button";
        readonly meta: {
            readonly description: "Button and interactive element text";
            readonly usage: "Use for buttons, links, and interactive controls";
            readonly a11y: "Size optimized for touch targets (min 44px height)";
        };
    };
    readonly badge: {
        readonly fontSize: "14px";
        readonly lineHeight: "18px";
        readonly fontWeight: 600;
        readonly letterSpacing: "0px";
        readonly className: "ai-badge";
        readonly meta: {
            readonly description: "Badge and tag text";
            readonly usage: "Use for status badges, tags, and chips";
            readonly a11y: "Ensure badges have proper semantic meaning";
        };
    };
};
/**
 * Elevation/shadow tokens
 * @example elevation[2] // { shadow: '0px 6px 24px rgba(0,0,0,0.08)', ... }
 */
export declare const elevation: Record<ElevationLevel, import("./elevation").ElevationDefinition>;
/**
 * Opacity tokens
 * @example opacity.subtle // 0.7
 */
export declare const opacity: {
    readonly full: 1;
    readonly subtle: 0.7;
    readonly muted: 0.5;
    readonly disabled: 0.3;
    readonly hover: 0.9;
    readonly pressed: 1;
    readonly overlay: 0.4;
    readonly scrim: 0.6;
};
/**
 * Default elevation level
 * Use this with the elevation helper: elevation[defaultElevation]
 * @example elevation[defaultElevation] // elevation[1]
 */
export declare const defaultElevation: ElevationLevel;
/**
 * Default border radius value
 * @example defaultRadius // '24px'
 */
export declare const defaultRadius: "24px";
/**
 * CSS variable helpers for theme-aware styling
 * Returns CSS variable references that respond to theme changes
 */
export declare const cssVar: {
    /**
     * Get spacing CSS variable
     * @example cssVar.spacing(16) // 'var(--ai-spacing-16)'
     */
    readonly spacing: (scale: SpacingScale) => string;
    /**
     * Get color CSS variable
     * @example cssVar.color('text-primary') // 'var(--ai-color-text-primary)'
     */
    readonly color: (path: ColorPath) => string;
    /**
     * Get radius CSS variable
     * @example cssVar.radius('xl') // 'var(--ai-radius-xl)'
     */
    readonly radius: (scale: RadiusScale) => string;
    /**
     * Get typography CSS variables as a style object
     * @example cssVar.typography('heading1') // { fontSize: 'var(--ai-font-size-h1)', ... }
     */
    readonly typography: (style: TypographyStyle) => {
        fontSize: string;
        lineHeight: string;
        fontWeight: string;
        letterSpacing: string;
    };
    /**
     * Get elevation CSS variable (shadow)
     * @example cssVar.elevation(2) // 'var(--ai-elevation-2)'
     */
    readonly elevation: (level: ElevationLevel) => string;
    /**
     * Get opacity CSS variable
     * @example cssVar.opacity('subtle') // 'var(--ai-opacity-subtle)'
     */
    readonly opacity: (preset: OpacityPreset) => string;
};
/**
 * Create a custom CSS variable reference
 * @example customVar('my-custom-color') // 'var(--my-custom-color)'
 */
export declare function customVar(name: string): string;
/**
 * Create a CSS variable reference with a fallback value
 * @example varWithFallback('ai-spacing-16', '32px') // 'var(--ai-spacing-16, 32px)'
 */
export declare function varWithFallback(name: string, fallback: string): string;
/**
 * Apply typography style as inline style object
 * @example applyTypography('heading1') // { fontSize: '36px', lineHeight: '40px', fontWeight: 600, letterSpacing: '-0.1px' }
 */
export declare function applyTypography(style: TypographyStyle): {
    fontSize: "16px" | "12px" | "18px" | "15px" | "24px" | "36px" | "14px";
    lineHeight: "16px" | "18px" | "24px" | "40px" | "28px" | "26px";
    fontWeight: 600 | 400 | 500;
    letterSpacing: "0px" | "-0.1px" | "-0.25px" | "-0.45px" | "-0.4px" | "-0.3px" | "-0.24px";
};
/**
 * Apply elevation as inline style object (for light theme)
 * @example applyElevation(2) // { boxShadow: '0px 6px 24px rgba(0,0,0,0.08)' }
 */
export declare function applyElevation(level: ElevationLevel): {
    boxShadow: string;
};
/**
 * @fileoverview Color utilities for brand customization and WCAG validation
 *
 * ## Token Structure Mapping
 *
 * The color token system uses different structures in TypeScript vs CSS:
 *
 * ### TypeScript Structure (Nested Objects)
 * Defined in `colors.ts`:
 * ```typescript
 * colors.light.brand.primary.base    // '#0285FF'
 * colors.light.brand.primary.hover   // '#016FDB'
 * colors.light.brand.primary.active  // '#0159B8'
 * colors.light.brand.primary.onColor // '#FFFFFF'
 * ```
 *
 * ### CSS Variables (Flat Naming)
 * Defined in `tokens.css`:
 * ```css
 * --ai-color-brand-primary        (maps to .base)
 * --ai-color-brand-primary-hover  (maps to .hover)
 * --ai-color-brand-primary-active (maps to .active)
 * --ai-color-brand-on-primary     (maps to .onColor)
 * ```
 *
 * ### Usage in Components
 * ```typescript
 * // Direct value access (TypeScript)
 * import { colors } from '@ainativekit/ui/tokens';
 * const buttonBg = colors.light.brand.primary.base; // '#0285FF'
 *
 * // CSS variable access (theme-aware)
 * import { cssVar } from '@ainativekit/ui/tokens';
 * <div style={{ color: cssVar.color('brand-primary') }} />
 * ```
 *
 * ### ThemeProvider Runtime Customization
 * The `brandColors` prop in ThemeProvider generates CSS variables dynamically:
 * ```typescript
 * <ThemeProvider brandColors={{ primary: '#6B46C1' }}>
 *   // This overrides --ai-color-brand-primary at runtime
 * </ThemeProvider>
 * ```
 */
/**
 * Validate if a string is a valid hex color format
 * Supports 3-digit (#RGB), 6-digit (#RRGGBB), and 8-digit (#RRGGBBAA) hex formats
 * @param color - Color string to validate
 * @returns true if valid hex color format
 * @example
 * isValidHexColor('#FFF') // true (3-digit)
 * isValidHexColor('#FF5733') // true (6-digit)
 * isValidHexColor('FF5733') // true (without #)
 * isValidHexColor('#FF5733AA') // true (8-digit with alpha)
 * isValidHexColor('not-a-color') // false
 * isValidHexColor('#GG5733') // false (invalid characters)
 */
export declare function isValidHexColor(color: string): boolean;
/**
 * Normalize hex color to standard format with # prefix
 * Preserves alpha channel if present
 * @param hex - Hex color string (3, 6, or 8 digits, with or without #)
 * @returns Normalized hex with # prefix, or null if invalid
 * @example
 * normalizeHexColor('#FFF') // '#FFFFFF' (expand 3-digit)
 * normalizeHexColor('FF5733') // '#FF5733' (add #)
 * normalizeHexColor('#FF5733AA') // '#FF5733AA' (preserve alpha)
 * normalizeHexColor('FF5733AA') // '#FF5733AA' (add # and preserve alpha)
 */
export declare function normalizeHexColor(hex: string): string | null;
/**
 * Convert hex color to RGB values
 * Supports 3-digit, 6-digit, and 8-digit hex formats
 * Alpha channel is stripped for contrast calculations
 * @param hex - Hex color string (with or without #)
 * @returns RGB object or null if invalid
 * @example
 * hexToRgb('#FF5733') // { r: 255, g: 87, b: 51 }
 * hexToRgb('#FFF') // { r: 255, g: 255, b: 255 }
 * hexToRgb('FF5733') // { r: 255, g: 87, b: 51 }
 * hexToRgb('#FF5733AA') // { r: 255, g: 87, b: 51 } (alpha stripped)
 */
export declare function hexToRgb(hex: string): {
    r: number;
    g: number;
    b: number;
} | null;
/**
 * Calculate relative luminance of a color (WCAG formula)
 * @param r - Red value (0-255)
 * @param g - Green value (0-255)
 * @param b - Blue value (0-255)
 * @returns Relative luminance (0-1)
 */
export declare function getRelativeLuminance(r: number, g: number, b: number): number;
/**
 * Calculate contrast ratio between two colors (WCAG formula)
 * @param color1 - First color (hex)
 * @param color2 - Second color (hex)
 * @returns Contrast ratio (1-21) or null if invalid colors
 * @example getContrastRatio('#FFFFFF', '#000000') // 21
 */
export declare function getContrastRatio(color1: string, color2: string): number | null;
/**
 * Check if contrast ratio meets WCAG standards
 * @param ratio - Contrast ratio
 * @param level - WCAG level ('AA' or 'AAA')
 * @param size - Text size ('normal' or 'large')
 * @returns true if meets standard
 * @example meetsWCAG(4.5, 'AA', 'normal') // true
 */
export declare function meetsWCAG(ratio: number, level?: 'AA' | 'AAA', size?: 'normal' | 'large'): boolean;
/**
 * Get appropriate text color (black or white) for a background color
 * @param backgroundColor - Background color (hex)
 * @returns '#ffffff' or '#000000'
 * @example getContrastColor('#0285FF') // '#ffffff'
 */
export declare function getContrastColor(backgroundColor: string): '#ffffff' | '#000000';
/**
 * Validate if a color pair has sufficient contrast for UI elements
 * @param foreground - Foreground color (hex)
 * @param background - Background color (hex)
 * @returns Object with validation result and contrast ratio
 * @example validateContrast('#FFFFFF', '#0285FF')
 * // { valid: true, ratio: 5.2, level: 'AA' }
 */
export declare function validateContrast(foreground: string, background: string): {
    valid: boolean;
    ratio: number | null;
    level: 'AAA' | 'AA' | 'fail';
};
//# sourceMappingURL=token-helpers.d.ts.map