igniteui-theming/dist/mcp/knowledge/docs/colors/guidance.js

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

//#region src/knowledge/docs/colors/guidance.md?raw
var guidance_default = "# Ignite UI Theming - Color Guidance\n\n## Understanding Theme Variants\n\nIgnite UI themes support two variants: **light** and **dark**. The variant affects how colors are chosen and how the palette generates shades.\n\n## Surface Color Rules\n\nThe **surface** color is the main background color used throughout your application.\n\n| Variant | Surface Requirement | Luminance | Examples |\n|---------|---------------------|-----------|----------|\n| light | Light color | > 0.5 | white, #ffffff, #f5f5f5, #e8e8e8 |\n| dark | Dark color | ≤ 0.5 | #121212, #1a1a1a, #1e1e1e, #212121 |\n\n## Gray Color Rules\n\nThe **gray** parameter sets the base color used to generate the grayscale palette. This is INVERTED from the surface because the grayscale shades need to contrast against the surface.\n\n| Variant | Gray Base Requirement | Luminance | Examples |\n|---------|----------------------|-----------|----------|\n| light | Dark color | ≤ 0.5 | #333333, #212121, #424242, #2c2c2c |\n| dark | Light color | > 0.5 | #f5f5f5, #e0e0e0, #d0d0d0, #cccccc |\n\n### Why is Gray Inverted?\n\nThe `palette()` function generates grayscale shades that are used for text, borders, and UI elements. These shades need to be readable against the surface:\n\n- **Light theme**: Light surface needs dark gray shades for readable text → use dark gray base\n- **Dark theme**: Dark surface needs light gray shades for readable text → use light gray base\n\n## Luminance Calculation\n\nLuminance is calculated using the WCAG 2.0 formula:\n- 0 = pure black\n- 1 = pure white\n- 0.5 = threshold between \"light\" and \"dark\" colors\n\n## Contrast Ratio\n\nWhen both surface and gray are provided, the system checks their contrast ratio. A minimum of 4.5:1 is recommended for good readability.\n\n## Best Practices\n\n1. **Let the system auto-calculate gray**: If you're unsure, omit the `gray` parameter. The palette() function will automatically derive an appropriate gray base from the surface color.\n\n2. **Match surface to variant**: Always use a light surface for light themes and a dark surface for dark themes.\n\n3. **Test contrast**: Ensure your color combinations meet accessibility standards (WCAG 2.0).\n\n## Common Mistakes\n\n❌ **Light theme with dark surface**: Creates visual confusion\n❌ **Dark theme with light surface**: Defeats the purpose of dark mode\n❌ **Light theme with light gray base**: Produces unreadable gray shades\n❌ **Dark theme with dark gray base**: Produces unreadable gray shades\n\n## Examples\n\n### Correct Light Theme\n```scss\n$palette: palette(\n  $primary: #06c,\n  $secondary: #f60,\n  $surface: white,      // ✅ Light surface for light theme\n  $gray: #333           // ✅ Dark gray base (optional)\n);\n```\n\n### Correct Dark Theme\n```scss\n$palette: palette(\n  $primary: #39f,\n  $secondary: #f93,\n  $surface: #1a1a1a,    // ✅ Dark surface for dark theme\n  $gray: #f5f5f5        // ✅ Light gray base (optional)\n);\n```\n";
//#endregion
export { guidance_default as default };