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

See references/mcp-setup.md for VS Code, Cursor, Claude Desktop, and WebStorm configuration instructions.

Verify the server is running by calling detect_platform — it reads your package.json and returns the detected platform (e.g., webcomponents).

Theming Architecture

The theming system is built on four pillars:

Four built-in design systems are available — each with light and dark variants:

For the full live reference (palette families, design system schemas, variant constraints, and preset palettes) call:

read_resource({ uri: "theming://platforms/webcomponents" })

Additional guidance resources:

• read_resource({ uri: "theming://guidance/colors/roles" }) — which components use primary vs secondary vs surface, and which shade (50/500/900) to use where
• read_resource({ uri: "theming://guidance/colors/rules" }) — surface and gray luminance rules for light/dark variants (why gray is inverted from surface, WCAG contrast thresholds)

Pre-built Themes

The quickest way to theme an app is to import a pre-built CSS file in your entry point:

import 'igniteui-webcomponents/themes/light/bootstrap.css';

Available pre-built CSS files:

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 the *-500 base shade to change a color family. All other shades (50–900) derive from the 500 value automatically via CSS relative color syntax:

:root {
  /* Override the 500 (base) shade — all other shades update automatically */
  --ig-primary-500: #1976D2;
  --ig-secondary-500: #FF9800;
}

To scope overrides to a specific container:

.admin-panel {
  --ig-primary-500: #6200EA;
}

For dark mode, either import a dark theme CSS file directly or toggle overrides with a class or media query:

@media (prefers-color-scheme: dark) {
  :root {
    --ig-surface-500: #121212;
    --ig-primary-500: #90CAF9; /* lighter tint works better on dark backgrounds */
  }
}

/* Or manually with a class */
.dark-theme {
  --ig-surface-500: #222;
}

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.

Call create_theme to generate production-ready Sass for palette + typography + elevations in a single step:

create_theme({
  platform: "webcomponents",
  designSystem: "material",    // or "bootstrap", "fluent", "indigo"
  primaryColor: "#1976D2",
  secondaryColor: "#FF9800",
  surfaceColor: "#FAFAFA",
  variant: "light",
  fontFamily: "'Roboto', sans-serif",
  includeTypography: true,
  includeElevations: true
})

For a dark theme pass a dark surfaceColor (e.g. "#121212") and variant: "dark" — create_theme selects the correct dark schema automatically.

For palette-only generation (when typography/elevations are already set) use create_palette. For scoping a theme to a container, pass the generated @include palette(...) block inside the target selector.

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):

igc-avatar {
  --ig-avatar-background: #E91E63;  /* ✗ hardcoded */
  --ig-avatar-color: #FFFFFF;       /* ✗ hardcoded */
}

RIGHT — CSS (palette token — stays in sync with the theme):

igc-avatar {
  --ig-avatar-background: var(--ig-primary-500);
  --ig-avatar-color: var(--ig-primary-500-contrast);
}

RIGHT — Sass (when Sass is configured):

$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.

igc-avatar {
  --ig-avatar-background: var(--ig-primary-500);
  --ig-avatar-color: var(--ig-primary-500-contrast);
}

When Sass is configured, use create_component_theme to generate the correct avatar-theme(...) + @include tokens(...) block:

create_component_theme({
  platform: "webcomponents",
  component: "avatar",
  tokens: { "background": "var(--ig-primary-500)", "color": "var(--ig-primary-500-contrast)" }
})

Pass output: "css" if you want CSS custom properties instead of Sass.

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

Use the MCP layout tools to generate the correct CSS or Sass output:

set_size({ size: "medium" })                              // global, CSS
set_size({ size: "small", component: "grid" })            // component-scoped, CSS
set_size({ size: "medium", output: "sass" })              // Sass output

set_spacing({ spacing: 0.75 })                            // compact, global
set_spacing({ spacing: 0.75, component: "grid" })         // component-scoped

set_roundness({ radiusFactor: 0.5 })                      // global
set_roundness({ radiusFactor: 0.0 })                      // square

All three tools default to CSS output. Add output: "sass" when the project has Sass configured.

The underlying CSS custom properties are --ig-size, --ig-spacing, and --ig-radius-factor. You can also set them directly on :root or a scoped selector if a one-off override is simpler than a tool call.