igniteui-theming/dist/mcp/utils/color.d.ts

A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.

/**
 * 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<ColorAnalysis>;
/**
 * 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<number>;
/**
 * 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<SurfaceGrayAnalysis>;
/**
 * 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<boolean>;
/**
 * 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<string, string>): Promise<Record<string, boolean>>;
/**
 * 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<number>;
/**
 * 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<string, string>): Promise<Record<string, {
    luminance: number;
    hue: number;
}>>;
/**
 * Luminance thresholds for palette shade generation suitability.
 * Colors outside this range may produce poor automatic shade generation results.
 *
 * Note: This is different from LUMINANCE_THRESHOLD (0.5) which determines
 * if a color is "light" or "dark" for variant matching. These thresholds
 * determine if a color can produce a good range of shades when used with
 * the palette() function.
 *
 * Based on color theory research:
 * - Optimal base color tone: 35-65 L* (CIELAB)
 * - Too light (L* > 70-75): darker shades compress together
 * - Too dark (L* < 25-30): lighter shades compress together
 */
export declare const PALETTE_LUMINANCE_THRESHOLDS: {
    /** Below this luminance, lighter shades (50-200) will lack contrast range */
    readonly TOO_DARK: 0.05;
    /** Above this luminance, darker shades (600-900) will appear washed out */
    readonly TOO_LIGHT: 0.45;
};
/**
 * Base fields for palette suitability analysis.
 */
interface PaletteSuitabilityBase {
    /** The original color value */
    color: string;
    /** Calculated luminance (0-1) */
    luminance: number;
}
/**
 * Result when a color is suitable for automatic shade generation.
 */
interface PaletteSuitabilitySuitable extends PaletteSuitabilityBase {
    /** The color is suitable for automatic shade generation */
    suitable: true;
}
/**
 * Result when a color is NOT suitable for automatic shade generation.
 */
interface PaletteSuitabilityUnsuitable extends PaletteSuitabilityBase {
    /** The color is not suitable for automatic shade generation */
    suitable: false;
    /** Issue type - always present when not suitable */
    issue: "too-light" | "too-dark";
    /** Human-readable description of the issue - always present when not suitable */
    description: string;
}
/**
 * Result of analyzing a color for palette shade generation suitability.
 * Uses a discriminated union: when `suitable` is false, `issue` and `description`
 * are guaranteed to be present.
 */
export type PaletteSuitabilityAnalysis = PaletteSuitabilitySuitable | PaletteSuitabilityUnsuitable;
/**
 * Analyze whether a color is suitable for automatic shade generation.
 * Colors with extreme luminance (very light or very dark) may produce
 * poor results when using the palette() function's automatic shade generation.
 *
 * @param color - CSS color value (hex, rgb, hsl, or named color)
 * @returns Analysis result indicating suitability and any issues
 */
export declare function analyzeColorForPalette(color: string): Promise<PaletteSuitabilityAnalysis>;
export {};