igniteui-theming
Version:
A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.
60 lines (59 loc) • 3.98 kB
TypeScript
/**
* Embedded palette presets from the Ignite UI Theming framework.
* These are loaded from the JSON files generated by buildJSON.mjs
* which is the single source of truth from the Sass code.
*/
export interface PaletteColors {
primary: string;
secondary: string;
gray: string;
surface: string;
info: string;
success: string;
warn: string;
error: string;
}
export type PalettePresetName = "light-bootstrap-palette" | "dark-bootstrap-palette" | "light-material-palette" | "dark-material-palette" | "light-fluent-palette" | "dark-fluent-palette" | "light-indigo-palette" | "dark-indigo-palette";
/**
* All palette presets loaded from JSON.
*/
export declare const PALETTE_PRESETS: Record<PalettePresetName, PaletteColors>;
/**
* Get light palette presets only.
*/
export declare const LIGHT_PALETTE_PRESETS: {
readonly "light-bootstrap-palette": PaletteColors;
readonly "light-material-palette": PaletteColors;
readonly "light-fluent-palette": PaletteColors;
readonly "light-indigo-palette": PaletteColors;
};
/**
* Get dark palette presets only.
*/
export declare const DARK_PALETTE_PRESETS: {
readonly "dark-bootstrap-palette": PaletteColors;
readonly "dark-material-palette": PaletteColors;
readonly "dark-fluent-palette": PaletteColors;
readonly "dark-indigo-palette": PaletteColors;
};
/**
* Documentation about color luminance and shade generation suitability.
*
* The theming system uses two different luminance concepts:
*
* 1. **LUMINANCE_THRESHOLD (0.5)** - Determines if a color is "light" or "dark"
* for variant matching. Used to validate that surface/gray colors match
* the theme variant (light themes need light surfaces, dark themes need
* dark surfaces).
*
* 2. **PALETTE_LUMINANCE_THRESHOLDS** - Determines if a color is suitable for
* automatic shade generation with the palette() function:
* - TOO_DARK (< 0.05): Lighter shades (50-200) will lack contrast range
* - TOO_LIGHT (> 0.45): Darker shades (600-900) will appear washed out
* - Ideal range: 0.05 - 0.45 luminance
*
* When a color falls outside the ideal range for shade generation, the
* create_theme tool will warn and recommend using create_custom_palette
* with explicit shade values instead.
*/
export declare const PALETTE_LUMINANCE_GUIDANCE = "\n## Color Luminance and Shade Generation\n\n### Why Luminance Matters\n\nThe palette() function generates 10 shades (50-900) from a base color by\nadjusting lightness. This works well when the base color has moderate\nluminance, but produces poor results for extreme values:\n\n- **Very light colors (luminance > 0.45)**: The darker shades (600-900)\n will appear washed out because there's limited \"darkening room\"\n- **Very dark colors (luminance < 0.05)**: The lighter shades (50-200)\n will lack contrast range because there's limited \"lightening room\"\n\n### Ideal Base Color Range\n\nFor best results with automatic shade generation:\n- **Luminance**: 0.05 - 0.45\n- **CIELAB L***: 25 - 73 (approximately)\n- **Examples**: Medium blues, greens, purples, oranges work well\n- **Problematic**: Near-white (#f5f5f5), near-black (#1a1a1a), pastels\n\n### When to Use create_custom_palette\n\nUse create_custom_palette with explicit shade values when:\n1. Base color luminance is outside 0.05-0.45 range\n2. Brand guidelines specify exact shades\n3. Accessibility requirements need specific contrast ratios\n4. You need precise control over the shade progression\n\n### Example: Problematic vs. Ideal Colors\n\n| Color | Luminance | Suitability |\n|-------|-----------|-------------|\n| #2196F3 | 0.28 | \u2705 Ideal - good shade range |\n| #4CAF50 | 0.30 | \u2705 Ideal - good shade range |\n| #FF5722 | 0.18 | \u2705 Ideal - good shade range |\n| #f5f5f5 | 0.91 | \u274C Too light - use explicit shades |\n| #1a1a1a | 0.02 | \u274C Too dark - use explicit shades |\n| #e3f2fd | 0.88 | \u274C Too light - use explicit shades |\n";