igniteui-angular-theming

# Ignite UI for Angular — Theming Skill ## Description This skill teaches AI agents how to theme Ignite UI for Angular applications using the Sass-based theming system and the **Ignite UI Theming MCP server**. It covers global themes, palettes, typography, elevations, component-level theming, layout controls (spacing, sizing, roundness), and how to use the MCP tools for code generation. ## Prerequisites - An Angular project with `igniteui-angular` installed, **or** `@infragistics/igniteui-angular` for licensed users - Sass support enabled in the project (default for Angular CLI projects) - The **Ignite UI Theming MCP server** (`igniteui-theming`) available as a tool provider > **AGENT INSTRUCTION — MCP Server Setup (REQUIRED)** > > Before using any theming tools, you MUST verify the MCP server is available > by calling `detect_platform`. If the tool is not available or the call fails, > you MUST automatically configure it by following the setup process steps described below. > > After writing the file, inform the user that the MCP server has been > configured and they may need to reload the editor for the tools to activate. > Start the MCP server and wait for that MCP server to start before continuing the theming related work. > Do NOT skip this step or ask the user to do it manually. ## Setting Up the Theming MCP Server > **Full setup instructions for VS Code, Cursor, Claude Desktop, and JetBrains IDEs are in [`references/mcp-setup.md`](./references/mcp-setup.md).** Read that file for editor-specific configuration steps and verification. ## Theming Architecture > **Docs:** [Theming Overview](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/index) · [Palette](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/palettes) · [Typography](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/typography) · [Elevations](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/elevations) The Ignite UI theming system is built on four pillars: | Concept | Purpose | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Palette** | Color system with primary, secondary, surface, gray, info, success, warn, error families, each with shades 50–900 + accents A100–A700 | | **Typography** | Font family, type scale (h1–h6, subtitle, body, button, caption, overline) | | **Elevations** | Box-shadow levels 0–24 for visual depth | | **Schema** | Per-component recipes mapping palette colors to component tokens | ### Design Systems Four built-in design systems are available: - **Material** (default) — Material Design 3 - **Bootstrap** — Bootstrap-inspired - **Fluent** — Microsoft Fluent Design - **Indigo** — Infragistics Indigo Design Each has light and dark variants (e.g., `$light-material-schema`, `$dark-fluent-schema`). ## Pre-built Themes The quickest way to theme an app is to include a pre-built CSS file in `angular.json`: ```json "styles": ["node_modules/igniteui-angular/styles/igniteui-angular.css"] ``` > **Licensed package users:** replace `igniteui-angular` with `@infragistics/igniteui-angular` in the path: > ```json > "styles": ["node_modules/@infragistics/igniteui-angular/styles/igniteui-angular.css"] > ``` Available pre-built CSS files: | File | Theme | | ------------------------------ | --------------- | | `igniteui-angular.css` | Material Light | | `igniteui-angular-dark.css` | Material Dark | | `igniteui-fluent-light.css` | Fluent Light | | `igniteui-fluent-dark.css` | Fluent Dark | | `igniteui-bootstrap-light.css` | Bootstrap Light | | `igniteui-bootstrap-dark.css` | Bootstrap Dark | | `igniteui-indigo-light.css` | Indigo Light | | `igniteui-indigo-dark.css` | Indigo Dark | All files are located under `node_modules/igniteui-angular/styles/` (or `node_modules/@infragistics/igniteui-angular/styles/` for the licensed package). ## Custom Sass Theme (Manual) > **AGENT INSTRUCTION — Sass Theming Docs**: If the user explicitly asks to build a Sass-based theme or configure Sass, refer to the dedicated Sass documentation: > > - [Sass Theming Overview](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/sass/index) > - [Sass Configuration](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/sass/configuration) > - [Sass Palettes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/sass/palettes) > - [Sass Component Themes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/sass/component-themes) Create a `styles.scss` file and include it in `angular.json`: ```scss // Open-source package @use 'igniteui-angular/theming' as *; // Licensed package — same Sass API, different import path // @use '@infragistics/igniteui-angular/theming' as *; $my-palette: palette( $primary: #1976d2, $secondary: #ff9800, $surface: #fafafa, ); // 2. Typography (optional) @include typography($font-family: $material-typeface, $type-scale: $material-type-scale); // 3. Core reset & base styles @include core(); // 4. Apply theme @include theme($palette: $my-palette, $schema: $light-material-schema); ``` For dark themes, use a dark surface color and a dark schema: ```scss $dark-palette: palette( $primary: #90caf9, $secondary: #ffb74d, $surface: #121212, ); @include theme($palette: $dark-palette, $schema: $dark-material-schema); ``` ## Component-Level Theming > **Docs:** [Component Themes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/sass/component-themes) Override individual component appearance using component theme functions and the `tokens` mixin. > **AGENT INSTRUCTION — No Hardcoded Colors (CRITICAL)** > > Once a palette has been generated (via `palette()` in Sass or `create_palette` / `create_theme` via MCP), > **every color reference MUST come from the generated palette tokens** — never hardcode hex/RGB/HSL values. > > Use `var(--ig-primary-500)`, `var(--ig-secondary-300)`, `var(--ig-surface-500)`, etc. in CSS, > or the `get_color` MCP tool to obtain the correct token reference. > > **WRONG** (hardcoded hex — breaks theme switching, ignores the palette): > > ```scss > $custom-avatar: avatar-theme( > $background: #e91e63, > $color: #ffffff, > ); > ``` > > **RIGHT** (palette token — stays in sync with the theme): > > ```scss > $custom-avatar: avatar-theme( > $schema: $light-material-schema, > $background: var(--ig-primary-500), > $color: var(--ig-primary-500-contrast), > ); > ``` > > This applies to **all** style code: component themes, custom CSS rules, Sass variables used > for borders/backgrounds/text, Angular `host` bindings, and inline styles. > The only place raw hex values belong is the **initial `palette()` call** that seeds the color system. > Everything downstream must reference the palette. ```scss @use 'igniteui-angular/theming' as *; $custom-avatar: avatar-theme( $schema: $light-material-schema, $background: var(--ig-primary-500), $color: var(--ig-primary-500-contrast), ); igx-avatar { @include tokens($custom-avatar); } ``` ### Discovering Available Tokens Each component has its own set of design tokens (themeable CSS custom properties). Before theming a component, you must know which tokens exist. Use the **MCP tool** `get_component_design_tokens` to discover them. ### Compound Components Some components (e.g., `combo`, `grid`, `date-picker`, `select`) are **compound** — they contain internal child components, each requiring their own theme. For example, `date-picker` uses `calendar`, `flat-button`, and `input-group` internally. Workflow for compound components: 1. Call `get_component_design_tokens` for the parent (e.g., `date-picker`) 2. The response lists related themes and scope selectors 3. Call `create_component_theme` for each child, using the parent's selector as the wrapper ## Layout Controls ### Sizing > **Docs:** [Display Density / Sizing](https://www.infragistics.com/products/ignite-ui-angular/angular/components/display-density) Controls the size of components via `--ig-size` (values: 1 = small, 2 = medium, 3 = large): ```css /* Global */ :root { --ig-size: 2; } /* Component-scoped */ igx-grid { --ig-size: 1; } ``` ### Spacing > **Docs:** [Spacing](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/spacing) Controls internal padding via `--ig-spacing` (1 = default, 0.5 = compact, 2 = spacious): ```css :root { --ig-spacing: 1; } .compact-section { --ig-spacing: 0.75; } ``` ### Roundness Controls border-radius via `--ig-radius-factor` (0 = square, 1 = maximum radius): ```css :root { --ig-radius-factor: 1; } igx-avatar { --ig-radius-factor: 0.5; } ``` ## Using the Theming MCP Server The Ignite UI Theming MCP server provides tools for AI-assisted theme code generation. > **IMPORTANT — File Safety Rule**: When generating or updating theme code, **never overwrite existing style files directly**. Instead, always **propose the changes as an update** and let the user review and approve before writing to disk. If a `styles.scss` (or any target file) already exists, show the generated code as a diff or suggestion rather than replacing the file contents. This prevents accidental loss of custom styles the user has already written. Always follow this workflow: ### Step 1 — Detect Platform ``` Tool: detect_platform ``` This auto-detects `angular` from `package.json` and sets the correct import paths. ### Step 2 — Generate a Full Theme ``` Tool: create_theme Params: { platform: "angular", designSystem: "material", primaryColor: "#1976D2", secondaryColor: "#FF9800", surfaceColor: "#FAFAFA", variant: "light", fontFamily: "'Roboto', sans-serif", includeTypography: true, includeElevations: true } ``` Generates a complete Sass file with palette, typography, elevations, and the `theme()` mixin call. ### Step 3 — Customize Individual Components ``` Tool: get_component_design_tokens Params: { component: "grid" } ``` Then use **palette token references** (not hardcoded hex values) for every color: ``` Tool: create_component_theme Params: { platform: "angular", designSystem: "material", variant: "light", component: "grid", tokens: { "header-background": "var(--ig-primary-50)", "header-text-color": "var(--ig-primary-800)" } } ``` > **Reminder**: After a palette is generated, all token values passed to > `create_component_theme` must reference palette CSS custom properties > (e.g., `var(--ig-primary-500)`, `var(--ig-secondary-A200)`, > `var(--ig-gray-100)`). Never pass raw hex values like `"#E3F2FD"`. ### Step 4 — Generate a Palette For simple mid-luminance base colors: ``` Tool: create_palette Params: { platform: "angular", primary: "#1976D2", secondary: "#FF9800", surface: "#FAFAFA", variant: "light" } ```