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.
license: MIT
---

# 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 (recommended, not 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). When its tools are available, prefer them over writing theme Sass from memory — start by calling `detect_platform`.

If the tools are not available, do not block the task — use the manual Sass workflow in this file. Suggest that the user run `npx -y igniteui-cli ai-config` from the project root (it configures both the `igniteui-cli` and `igniteui-theming` MCP servers) and reload the editor. MCP servers cannot be started mid-session; the configuration takes effect on the next session. Editor-specific details are in [`references/mcp-setup.md`](./references/mcp-setup.md).

## 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                        |
| --------------------------------- | ------------------------------ |
| `theming://presets/palettes`      | Preset palette colors          |
| `theming://presets/typography`    | Typography presets             |
| `theming://presets/elevations`    | Elevation shadow presets       |
| `theming://guidance/colors/usage` | Which shades for which purpose |
| `theming://guidance/colors/roles` | Semantic color roles           |
| `theming://guidance/colors/rules` | Light/dark theme rules         |
| `theming://platforms/angular`     | Angular platform specifics     |

## 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

```scss
// 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

```scss
// 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`](./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** when using MCP tools
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](#no-hardcoded-colors-after-palette-generation); raw hex/RGB/HSL is only acceptable in the initial palette seed values

## Related Skills

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