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) ## Ignite UI Theming MCP Server (required) The `igniteui-theming` MCP server generates production-ready theme code (`create_theme`, `create_palette`, `create_component_theme`, `get_component_design_tokens`, `get_color`, and more). Use its tools for all theme code — never write theme Sass or component token names from memory. **Verify the server before any other step** by calling `detect_platform`. If the tool is not available: 1. **Configure it yourself — do not just suggest it.** From the project root, run `npx -y igniteui-cli ai-config` (or `ig ai-config` when `igniteui-cli` is installed globally). It configures both the `igniteui-theming` and `igniteui-cli` MCP servers, preserves existing server entries, and copies the Agent Skills. If the client is not covered, add the entry manually from [`references/mcp-setup.md`](./references/mcp-setup.md) — the server command is `npx -y igniteui-theming igniteui-theming-mcp`. 2. **Ask the user to reload the editor or agent session, then stop.** MCP tools cannot be loaded into a running session. 3. **Continue without the server only if the user explicitly asks to.** In that case, use the manual Sass workflow in this file and mark every token name you could not verify with `get_component_design_tokens` as unverified. ## 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) > **Important — 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. All color values passed to component themes must be palette tokens, not raw hex/RGB/HSL — see [No Hardcoded Colors After Palette Generation](#no-hardcoded-colors-after-palette-generation) below. ```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. > **File safety**: When applying generated theme code to an existing style file, make targeted edits that preserve the user's existing custom styles — never wholesale-replace the file contents. If the environment does not gate file writes behind user approval, present the change as a diff for review before writing. 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)" } } ``` ### 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" } ``` For brand-specific exact shade values, use `create_custom_palette` with `mode: "explicit"` for full control over each shade. ### Step 5 — Adjust Layout ``` Tool: set_size → { size: "medium" } Tool: set_spacing → { spacing: 0.75, component: "grid" } Tool: set_roundness → { radiusFactor: 0.8 } ``` ### Step 6 — Reference Palette Colors via `get_color` After a palette is generated, use the `get_color` tool to obtain the correct CSS custom property reference for any color you need (see [No Hardcoded Colors After Palette Generation](#no-hardcoded-colors-after-palette-generation)): ``` Tool: get_color Params: { color: "primary", variant: "600" } → var(--ig-primary-600) Params: { color: "primary", variant: "600", contrast: true } → var(--ig-primary-600-contrast) Params: { color: "primary", opacity: 0.5 } → hsl(from var(--ig-primary-500) h s l / 0.5) ``` ### Loading Reference Data Use `read_resource` with these URIs for preset values and documentation: | URI | Content |