/** * Color analysis utilities using Sass-embedded. * Calls the actual Sass luminance() and contrast() functions for accurate validation. */ /** * Luminance threshold for determining light vs dark colors. * Colors with luminance > 0.5 are considered "light". * Colors with luminance <= 0.5 are considered "dark". */ export declare const LUMINANCE_THRESHOLD = 0.5; /** * Minimum recommended contrast ratio for surface/gray combinations. * This is the WCAG 2.0 AA standard for large text (3:1). * Note: The actual contrast ratio can be configured via the palette mixin. */ export declare const DEFAULT_MINIMUM_CONTRAST_RATIO = 3; /** * Result of analyzing a single color. */ export interface ColorAnalysis { /** The original color value */ color: string; /** Calculated luminance (0-1) */ luminance: number; /** Whether the color is considered light (luminance > 0.5) */ isLight: boolean; } /** * Result of analyzing surface and gray colors together. */ export interface SurfaceGrayAnalysis { /** Analysis of the surface color */ surface?: ColorAnalysis; /** Analysis of the gray color */ gray?: ColorAnalysis; /** Contrast ratio between surface and gray (if both provided) */ contrastRatio?: number; } /** * Suggested colors for different variants. */ export declare const SUGGESTED_COLORS: { readonly light: { readonly surface: readonly ["white", "#ffffff", "#f8f9fa", "#fafafa", "#f5f5f5"]; readonly gray: readonly ["black", "#000000", "#333333", "#212121", "#424242"]; }; readonly dark: { readonly surface: readonly ["#222222", "#1a1a1a", "#121212", "#181818", "#2d2d2d"]; readonly gray: readonly ["white", "#ffffff", "#e5e5e5", "#f5f5f5", "#eeeeee"]; }; }; /** * Analyze a single color using Sass luminance() function. * * @param color - CSS color value (hex, rgb, hsl, or named color) * @returns Color analysis with luminance and isLight flag * @throws Error if Sass compilation fails or color is invalid */ export declare function analyzeColor(color: string): Promise; /** * Calculate the contrast ratio between two colors using Sass contrast() function. * * @param color1 - First CSS color value * @param color2 - Second CSS color value * @returns Contrast ratio (1 to 21) * @throws Error if Sass compilation fails or colors are invalid */ export declare function calculateContrast(color1: string, color2: string): Promise; /** * Analyze surface and gray colors together in a single Sass compilation. * This is more efficient than calling analyzeColor twice. * * @param params - Object containing surface and/or gray colors * @returns Combined analysis results */ export declare function analyzeSurfaceGrayColors(params: { surface?: string; gray?: string; }): Promise; /** * Check if a color is valid by attempting to analyze it. * * @param color - CSS color value to validate * @returns true if the color is valid, false otherwise */ export declare function isValidColor(color: string): Promise; /** * Validate multiple colors in a single Sass compilation for efficiency. * This is much faster than calling isValidColor() for each color individually. * * @param colors - Map of key names to color values * @returns Map of key names to validation results (true = valid, false = invalid) */ export declare function validateColorsInBatch(colors: Record): Promise>; /** * Default hue tolerance in degrees for monochromatic validation. * Allows for slight hue variation within a color family. */ export declare const DEFAULT_HUE_TOLERANCE = 30; /** * Extract the hue value (0-360) from a color using Sass color.channel() function. * * @param color - CSS color value (hex, rgb, hsl, or named color) * @returns Hue value in degrees (0-360) * @throws Error if Sass compilation fails or color is invalid */ export declare function extractHue(color: string): Promise; /** * Check if two hue values are within tolerance of each other, * accounting for the circular nature of hue (0° = 360°). * * @param hue1 - First hue value (0-360) * @param hue2 - Second hue value (0-360) * @param tolerance - Maximum allowed difference in degrees (default: 30) * @returns true if hues are within tolerance */ export declare function huesAreClose(hue1: number, hue2: number, tolerance?: number): boolean; /** * Analyze multiple colors in a single Sass compilation for efficiency. * Returns luminance and hue for each color. * * @param colors - Map of key names to color values * @returns Map of key names to analysis results */ export declare function analyzeColorsWithHue(colors: Record): Promise>;