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 — 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 · Palette · Typography · Elevations

The Ignite UI theming system is built on four pillars:

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:

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

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

jsonCopy code
"styles": ["node_modules/@infragistics/igniteui-angular/styles/igniteui-angular.css"]

Available pre-built CSS files:

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

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

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

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

All color values passed to component themes must be palette tokens, not raw hex/RGB/HSL — see No Hardcoded Colors After Palette Generation below.

scssCopy code
@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):

cssCopy code
/* 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):

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

Roundness

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

cssCopy code
: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

Copy code
Tool: detect_platform

This auto-detects angular from package.json and sets the correct import paths.

Step 2 — Generate a Full Theme

Copy code
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

Copy code
Tool: get_component_design_tokens
Params: { component: "grid" }

Then use palette token references (not hardcoded hex values) for every color:

Copy code
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:

Copy code
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

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

Copy code
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:

No Hardcoded Colors After Palette Generation

This is the single most important theming rule. Once a palette exists (via palette() in Sass or create_palette / create_theme via MCP), every color reference must come from the palette tokens, which are available as CSS custom properties on :root. This applies to all style code: component theme tokens values, custom CSS rules (color, background, border-color, fill, stroke), Sass variables for derived values, Angular host bindings, and inline styles. Hardcoded values break theme switching and drift out of sync when the palette changes.

Correct: Palette Tokens

scssCopy code
// All colors come from the theme — respects palette changes and dark/light switching
.sidebar {
  background: var(--ig-surface-500);
  color: var(--ig-gray-900);
  border-right: 1px solid var(--ig-gray-200);
}

.accent-badge {
  background: var(--ig-secondary-500);
  color: var(--ig-secondary-500-contrast);
}

.hero-section {
  // Semi-transparent primary overlay
  background: hsl(from var(--ig-primary-500) h s l / 0.12);
}

Incorrect: Hardcoded Values

scssCopy code
// WRONG — these break when the palette changes and ignore dark/light mode
$primary-color: #00838f; // ✗ hardcoded
$secondary-color: #3d5afe; // ✗ hardcoded
$surface-color: #f0f5fa; // ✗ hardcoded

.sidebar {
  background: $surface-color; // ✗ not a palette token
  color: #333; // ✗ not a palette token
}

When Raw Hex Values Are OK

Raw hex values are acceptable only in these contexts:

1. palette() call — the initial seed colors that generate the full palette
2. create_palette / create_theme MCP tool inputs — the base colors passed to the tool
3. Non-palette decorative values — e.g., a one-off SVG illustration color that intentionally stays fixed regardless of theme

Everything else must use var(--ig-<family>-<shade>) tokens.

Common Patterns

Light/dark theme switching, scoped themes, and licensed package configuration are in references/common-patterns.md. Read that file for ready-to-use Sass patterns.

Key Rules

1. Preserve existing styles — apply theme code as targeted edits to existing style files; never wholesale-replace a file the user has customized
2. Always call detect_platform first — it verifies the MCP server is connected and sets the correct import paths
3. Always call get_component_design_tokens before create_component_theme to discover valid token names
4. Palette shades 50 = lightest, 900 = darkest for all chromatic colors — never invert for dark themes (only gray inverts)
5. Surface color must match the variant — light color for light, dark color for dark
6. Use @include core() once before @include theme() in your global styles
7. Component themes use @include tokens($theme) inside a selector to emit CSS custom properties
8. For compound components, follow the full checklist returned by get_component_design_tokens — theme each child component with its scoped selector
9. No hardcoded colors after palette generation — see No Hardcoded Colors After Palette Generation; raw hex/RGB/HSL is only acceptable in the initial palette seed values

Related Skills

• igniteui-angular-components — UI components (form controls, layout, data display, feedback/overlays, directives, charts)
• igniteui-angular-grids — Data Grids (Flat Grid, Tree Grid, Hierarchical Grid, Grid Lite, Pivot Grid)