igniteui-theming/dist/mcp/knowledge/docs/colors/usage.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/usage.md?raw
var usage_default = "# Ignite UI Color Usage Guide\n\n## Overview\n\nThe Ignite UI theming system uses **8 color families**, each with **10 shade levels** (50-900). Understanding how these colors interact with components helps you create cohesive, accessible themes.\n\n## Color Families\n\n### Primary Color\n**Role:** Brand identity and primary actions\n\nThe primary color is your brand's signature color. It draws attention to the most important interactive elements.\n\n**Used For:**\n- Primary action buttons (filled/contained style)\n- Links and navigation highlights\n- Active/selected states (tabs, list items, checkboxes, radios, switches)\n- Progress indicators and sliders\n- Focus rings and outlines\n- Calendar date selection\n- Grid row selection\n\n**Shade Usage:**\n| Shades | Purpose | Examples |\n|--------|---------|----------|\n| 50-100 | Subtle backgrounds, disabled | Focus backgrounds, disabled button fills |\n| 200-300 | Focus outlines, selections with opacity | Focus rings, selected backgrounds (Indigo) |\n| **500** | **Default/main color** | Button backgrounds, link text, checkbox fills |\n| 600-700 | Hover and active states | Button hover, pressed states |\n| 800-900 | Dark mode, maximum emphasis | Dark theme selections |\n\n---\n\n### Secondary Color\n**Role:** Accent and secondary emphasis\n\nMost prominent in Material Design. Provides accent without competing with primary.\n\n**Used For:**\n- Flat/outlined button text (Material)\n- List and dropdown headers\n- Alternative selection backgrounds\n- Secondary action buttons\n\n**Shade Usage:**\n| Shades | Purpose |\n|--------|---------|\n| 100-200 | Selected backgrounds, light accents |\n| **500** | Default accent |\n| 600-700 | Headers (Fluent), strong accents |\n\n---\n\n### Gray Color\n**Role:** Neutral UI foundation\n\nThe most used color family. Creates text hierarchy, borders, and backgrounds.\n\n**Used For:**\n- All text (primary, secondary, disabled, placeholder)\n- Borders and dividers\n- Backgrounds (hover, selected, disabled)\n- Icons\n- Tooltips\n\n**Shade Usage:**\n| Shade | Purpose | Examples |\n|-------|---------|----------|\n| 50 | Lightest backgrounds | Dark mode bg, group areas |\n| 100 | Hover/focus backgrounds | Item hover, light borders |\n| 200 | Selected backgrounds, borders | Selected items (Fluent), borders |\n| 300 | Borders, dividers | Default borders, dividers |\n| 400 | Disabled elements, placeholders | Disabled text, placeholder |\n| 500 | Secondary text, icons | Disabled text, secondary content |\n| 600 | Labels, secondary text | Header text (Indigo), labels |\n| 700 | Descriptions, tooltips | Tooltip bg, descriptions |\n| 800 | Primary text | Main text, titles |\n| **900** | **Maximum contrast text** | Headings, emphasis |\n\n---\n\n### Surface Color\n**Role:** Component background foundation\n\nThe \"canvas\" color. Typically white (light) or dark gray (dark themes).\n\n**Used For:**\n- Card, dialog, dropdown backgrounds\n- Input field backgrounds\n- List and panel backgrounds\n- Navigation backgrounds\n\n**Note:** Usually only shade 500 is used. The surface determines whether gray shades appear light or dark.\n\n---\n\n### Error Color\n**Role:** Validation errors and destructive actions\n\nCommunicates problems. Use sparingly for maximum impact.\n\n**Used For:**\n- Form validation errors (borders, text)\n- Invalid state indicators\n- Destructive action buttons\n- Error progress state\n\n**Shade Usage:**\n| Shades | Purpose |\n|--------|---------|\n| 200-400 | Focus rings, light errors |\n| **500** | Default error |\n| 600-800 | Hover states, Material errors |\n\n---\n\n### Success, Warn, Info Colors\n**Role:** Feedback states\n\n| Color | Purpose |\n|-------|---------|\n| **Success** | Completion, positive feedback |\n| **Warn** | Caution, potential issues |\n| **Info** | Neutral information |\n\nThese primarily use shade **500** for their default state.\n\n---\n\n## Interaction State Patterns\n\n### Button States\n```\nidle    → primary-500 background\nhover   → primary-600 (or 500 + overlay)\nfocus   → primary-500 + focus ring (200-300)\nactive  → primary-700\ndisabled → gray-300 bg, gray-500 text\n```\n\n### List Item States\n```\nidle     → surface bg, gray-800 text\nhover    → gray-100 or 200 bg\nfocus    → gray-100 bg + outline\nselected → primary-100/200 bg (or 300 @ 0.3 opacity)\ndisabled → gray-400 text\n```\n\n### Input States\n```\nidle    → surface bg, gray-300/400 border\nhover   → gray-400/500 border\nfocus   → primary-500 border + ring\nerror   → error-500 border/text\ndisabled → gray-100 bg, gray-400 text\n```\n\n---\n\n## Opacity Usage\n\nOpacity modifiers adjust color intensity while maintaining relationships:\n\n| Opacity | Use Case |\n|---------|----------|\n| 0.05-0.1 | Subtle hover overlays |\n| 0.12-0.15 | Active states, disabled bg |\n| 0.2 | Disabled elements |\n| 0.3 | Selected backgrounds (Indigo) |\n| **0.38** | Material disabled (standard) |\n| 0.5 | Focus outlines |\n| 0.8-0.9 | Strong overlays, tooltips |\n\n---\n\n## Contrast Colors\n\nAlways use `contrast-color` for text on colored backgrounds:\n\n```scss\n// Text on primary button\ncolor: contrast-color('primary', 500);\n\n// Text with opacity\ncolor: contrast-color('gray', 50, 0.8);\n```\n\n---\n\n## Theme Variations\n\n### Material Design\n- Secondary color for accents\n- Ripple effects\n- A100-A700 accent shades\n- Elevation through shadows\n\n### Fluent Design\n- Gray-based, subtle\n- 100-200 for hovers\n- Border-focused styling\n\n### Bootstrap\n- Primary for accents\n- 600 for hover states\n- Strong borders\n\n### Indigo Design\n- Transparent backgrounds\n- Primary 300 @ 0.3 opacity for selections\n- Clean, modern aesthetic\n\n---\n\n## Dark Mode Guidelines\n\nIMPORTANT: Chromatic color shades (primary, secondary, etc.) are NEVER inverted.\nThe shade order is always 50=lightest, 900=darkest regardless of theme variant.\nOnly GRAY inverts its shade progression for dark themes.\n\n1. **Gray shades invert**: Lower numbers become darker (50=darkest in dark mode)\n2. **Use lighter primary shades**: In dark mode UI, reference lighter shades (100-300) \n   instead of darker ones (500-700) for better visibility. The palette itself is NOT \n   inverted - you just USE different shades from the same palette.\n3. **Surface becomes dark**: #222, #1a1a1a, etc.\n4. **Contrast still works**: `contrast-color` adapts automatically\n\n---\n\n## Quick Reference\n\n| Need | Color | Shade |\n|------|-------|-------|\n| Primary button bg | primary | 500 |\n| Link text | primary | 500 |\n| Main body text | gray | 800-900 |\n| Secondary text | gray | 600-700 |\n| Disabled text | gray | 400-500 |\n| Component bg | surface | 500 |\n| Hover bg | gray | 100-200 |\n| Border | gray | 200-400 |\n| Error state | error | 500 |\n| Success state | success | 500 |\n| Focus ring | primary | 200-300 |\n";
//#endregion
export { usage_default as default };