igniteui-wc-customize-component-theme

# Ignite UI Web Components — Theming Skill ## Description This skill teaches AI agents how to theme Ignite UI Web Components (and React via `igniteui-react`) applications. Two approaches are supported: - **CSS custom properties** — works in any project without additional build tooling - **Sass** — available when the project has Sass configured; provides the full palette/typography/elevation API The skill also covers component-level theming, layout controls (spacing, sizing, roundness), and how to use the **Ignite UI Theming MCP server** for AI-assisted code generation. ## Prerequisites - A project with `igniteui-webcomponents` (or `igniteui-react`) installed - The **Ignite UI Theming MCP server** (`igniteui-theming`) available as a tool provider - **Optional**: Sass configured in the project (enables the Sass-based theming API) > **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 The Ignite UI Theming MCP server enables AI assistants to generate production-ready theming code. It must be configured in your editor before the theming tools become available. ### VS Code Create or edit `.vscode/mcp.json` in your project: ```json { "servers": { "igniteui-theming": { "command": "npx", "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] } } } ``` This works whether `igniteui-theming` is installed locally in `node_modules` or needs to be pulled from the npm registry — `npx -y` handles both cases. ### Cursor Create or edit `.cursor/mcp.json`: ```json { "mcpServers": { "igniteui-theming": { "command": "npx", "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] } } } ``` ### Claude Desktop Edit the Claude Desktop config file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "igniteui-theming": { "command": "npx", "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] } } } ``` ### WebStorm / JetBrains IDEs 1. Go to **Settings → Tools → AI Assistant → MCP Servers** 2. Click **+ Add MCP Server** 3. Set Command to `npx` and Arguments to `igniteui-theming igniteui-theming-mcp` 4. Click OK and restart the AI Assistant ### Verifying the Setup After configuring the MCP server, ask your AI assistant: > "Detect which Ignite UI platform my project uses" If the MCP server is running, the `detect_platform` tool will analyze your `package.json` and return the detected platform (e.g., `webcomponents`). ## Theming Architecture 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 import a pre-built CSS file in your entry point: ```typescript import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` Available pre-built CSS files: | Import path | Theme | |---|---| | `igniteui-webcomponents/themes/light/bootstrap.css` | Bootstrap Light | | `igniteui-webcomponents/themes/dark/bootstrap.css` | Bootstrap Dark | | `igniteui-webcomponents/themes/light/material.css` | Material Light | | `igniteui-webcomponents/themes/dark/material.css` | Material Dark | | `igniteui-webcomponents/themes/light/fluent.css` | Fluent Light | | `igniteui-webcomponents/themes/dark/fluent.css` | Fluent Dark | | `igniteui-webcomponents/themes/light/indigo.css` | Indigo Light | | `igniteui-webcomponents/themes/dark/indigo.css` | Indigo Dark | ## Custom Theme via CSS Custom Properties > No Sass required. Works in any project after importing a pre-built theme. After importing a pre-built theme, override individual design tokens with CSS custom properties on `:root` or a scoped selector: ```css :root { /* Override palette hue/saturation/lightness channels */ --ig-primary-h: 211deg; --ig-primary-s: 100%; --ig-primary-l: 50%; --ig-secondary-h: 33deg; --ig-secondary-s: 100%; --ig-secondary-l: 50%; } ``` To scope overrides to a specific container: ```css .admin-panel { --ig-primary-h: 260deg; --ig-primary-s: 60%; --ig-primary-l: 45%; } ``` For dark mode, either import a dark theme CSS file directly or toggle overrides with a class or media query: ```css @media (prefers-color-scheme: dark) { :root { --ig-surface-h: 0deg; --ig-surface-s: 0%; --ig-surface-l: 7%; } } /* Or manually with a class */ .dark-theme { --ig-surface-h: 0deg; --ig-surface-s: 0%; --ig-surface-l: 7%; } ``` ## Custom Theme via Sass > Requires Sass configured in the project. First check whether the project has a Sass setup (e.g., a `styles.scss` entry file, `sass` in `devDependencies`, or a Vite/webpack Sass plugin). The Sass API for `igniteui-webcomponents` uses `@use 'igniteui-theming'` with individual mixins — **not** the Angular-specific `core()` / `theme()` combined mixins. ```scss @use 'igniteui-theming' as *; // 1. Define a palette $my-palette: palette( $primary: #1976D2, $secondary: #FF9800, $surface: #FAFAFA ); // 2. Apply the palette @include palette($my-palette); // 3. Optional: Typography @include typography($font-family: "'Roboto', sans-serif"); // 4. Optional: Elevations @include elevations(); // 5. Optional: Spacing @include spacing(); ``` For dark themes, use a dark surface color and a dark schema: ```scss @use 'igniteui-theming' as *; $dark-palette: palette( $primary: #90CAF9, $secondary: #FFB74D, $surface: #121212 ); @include palette($dark-palette, $schema: $dark-material-schema); ``` To scope a Sass theme to a container: ```scss .admin-panel { @include palette($admin-palette, $schema: $light-indigo-schema); } ``` ## Component-Level Theming 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): > ```css > igc-avatar { > --ig-avatar-background: #E91E63; /* ✗ hardcoded */ > --ig-avatar-color: #FFFFFF; /* ✗ hardcoded */ > } > ``` > > **RIGHT — CSS** (palette token — stays in sync with the theme): > ```css > igc-avatar { > --ig-avatar-background: var(--ig-primary-500); > --ig-avatar-color: var(--ig-primary-500-contrast); > } > ``` > > **RIGHT — Sass** (when Sass is configured): > ```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, 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. ```css igc-avatar { --ig-avatar-background: var(--ig-primary-500); --ig-avatar-color: var(--ig-primary-500-contrast); } ``` When Sass is available, use the component theme function and `tokens` mixin: ```scss @use 'igniteui-theming' as *; $custom-avatar: avatar-theme( $schema: $light-material-schema, $background: var(--ig-primary-500), $color: var(--ig-primary-500-contrast) ); igc-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 Controls the size of components via `--ig-size` (values: 1 = small, 2 = medium, 3 = large): ```css /* Global */ :root { --ig-size: 2; } /* Component-scoped */ igc-grid { --ig-size: 1; } ``` ### 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; } igc-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 `webcomponents` from `package.json` and sets the correct import paths. ### Step 2 — Generate a Full Theme ``` Tool: create_theme Params: { platform: "webcomponents", 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: "webcomponents", designSystem: "material",