igniteui-angular-theming

name	igniteui-angular-theming
description	Generates and customizes Ignite UI for Angular themes including color palettes, typography, elevations, and component-level styles using the Sass theming system and the igniteui-theming MCP server. Use when users ask to theme, restyle, or style Ignite UI components, change colors or the color palette, switch between light and dark themes, create or apply a global theme, customize typography or elevation shadows, adjust spacing, sizing, or roundness, or configure per-component design tokens. Do NOT use for component behavior, APIs, or data binding — use igniteui-angular-components or igniteui-angular-grids instead.
user-invocable	true

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. Read that file for editor-specific configuration steps and verification.

Theming Architecture

Docs: Theming Overview · Palette · Typography · 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:

"styles": ["node_modules/igniteui-angular/styles/igniteui-angular.css"]

Licensed package users: replace igniteui-angular with @infragistics/igniteui-angular in the path:

"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
• Sass Configuration
• Sass Palettes
• Sass Component Themes

Create a styles.scss file and include it in angular.json:

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

$dark-palette: palette(
  $primary: #90caf9,
  $secondary: #ffb74d,
  $surface: #121212,
);

@include theme($palette: $dark-palette, $schema: $dark-material-schema);

Component-Level Theming

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

$custom-avatar: avatar-theme(
  $background: #e91e63,
  $color: #ffffff,
);

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

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

@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

Controls the size of components via --ig-size (values: 1 = small, 2 = medium, 3 = large):

/* Global */
:root {
  --ig-size: 2;
}

/* Component-scoped */
igx-grid {
  --ig-size: 1;
}

Spacing

Docs: Spacing

Controls internal padding via --ig-spacing (1 = default, 0.5 = compact, 2 = spacious):

:root {
  --ig-spacing: 1;
}
.compact-section {
  --ig-spacing: 0.75;
}

Roundness

Controls border-radius via --ig-radius-factor (0 = square, 1 = maximum radius):

: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"
}