---
name: igniteui-react-customize-theme
description: This skill customizes Ignite UI for React component styling using CSS custom properties and the full theming system and should be used when applying brand colors, dark mode, component-level overrides, or scoped themes in a React application
user-invocable: true
---

# Ignite UI for React — Theming Skill

## Prerequisites

- A React project with `igniteui-react` installed
- A theme CSS file imported in your entry point (see [igniteui-react-components](../igniteui-react-components/SKILL.md))
- The **Ignite UI Theming MCP server** (`igniteui-theming`)

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

## Description

This skill teaches AI agents how to theme Ignite UI for React applications. One approach is supported:

- **CSS custom properties** — works in any project without additional build tooling

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 — all in a React application context.

## Example Usage

- "How do I change the primary color in my Ignite UI React app?"
- "Apply a dark theme to my React app"
- "Customize the grid header colors"
- "How do I scope a theme to a specific section of my React app?"
- "Set up Material Design theming for Ignite UI components"

## Setting Up the Theming MCP Server

> **Full setup instructions for VS Code, Cursor, Claude Desktop, and JetBrains IDEs are in [`reference/MCP-SERVER.md`](./reference/MCP-SERVER.md).** Read that file for editor-specific configuration steps and verification.

## Related Skills

- [igniteui-react-components](../igniteui-react-components/SKILL.md) — Choose the right components and set up your React project
- [igniteui-react-optimize-bundle-size](../igniteui-react-optimize-bundle-size/SKILL.md) — Optimize after theming

## When to Use

- Applying custom brand colors or a dark theme to an Ignite UI React app
- Overriding individual component styles (e.g., grid header color, button appearance)
- Switching between light and dark mode in a React app
- Scoping different themes to different sections of a React app
- Setting up the Ignite UI Theming MCP server for AI-assisted theming

---

## Content Guide

This skill is organized into focused sections. Refer to the appropriate file for detailed instructions:

| Topic | File | When to Use |
|---|---|---|
| CSS Theming | [CSS-THEMING.md](./reference/CSS-THEMING.md) | Pre-built themes, CSS custom properties, scoped overrides, layout controls, light/dark switching |
| MCP Server | [MCP-SERVER.md](./reference/MCP-SERVER.md) | AI-assisted theming code generation |
| Troubleshooting | [TROUBLESHOOTING.md](./reference/TROUBLESHOOTING.md) | Common issues and solutions |

---

## Quick Start

### 1. Import a Pre-built Theme (REQUIRED)

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

**For grids**, also import:

```tsx
import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
```

### 2. Override with CSS Custom Properties

```css
/* src/index.css */
:root {
  --ig-primary-h: 211deg;
  --ig-primary-s: 100%;
  --ig-primary-l: 50%;
}
```

```tsx
// main.tsx
import 'igniteui-webcomponents/themes/light/bootstrap.css'; // Theme first
import './index.css'; // Overrides second
```

---

## Theming Architecture

The Ignite UI theming system is built on **palette**, **typography**, **elevations**, and per-component **schemas**. Use the MCP theming tools at the right stage:

- **`create_palette`** — when the user provides brand colors; generates luminance-safe shades for all palette roles
- **`create_theme`** — generates the complete global theme CSS; call after `create_palette`
- **`create_typography`** — when the user wants to change fonts, type scale, or weights
- **`create_elevations`** — when the user wants to adjust shadow depth
- **`get_component_design_tokens`** - before writing any component-level CSS; retrieves the current token names for a specific component
- **`set_size`**, **`set_spacing`**, or **`set_roundness`** - adjust component size, content spacing, and roundness.

### Design Systems

- **Bootstrap** (default), **Material**, **Fluent**, **Indigo**
- Each has light and dark variants

---

## Key Concepts

### CSS Custom Properties

Override tokens in your CSS:

```css
:root { --ig-primary-h: 211deg; }
.admin-panel { --ig-primary-h: 260deg; }
```

### Component-Level Theming

Target web component tag names in CSS:

```css
igc-button { --ig-button-foreground: var(--ig-secondary-500); }
```

### CSS `::part()` Selectors

```css
igc-input::part(input) { font-size: 1.1rem; }
```

### Layout Controls

```css
:root {
  --ig-size: 2;          /* 1=small, 2=medium, 3=large */
  --ig-spacing: 1;       /* 0.5=compact, 1=default, 2=spacious */
  --ig-radius-factor: 1; /* 0=square, 1=max radius */
}
```

### Light/Dark Switching

See [CSS-THEMING.md](./reference/CSS-THEMING.md) for approaches: class toggle, media query, or stylesheet swap.

---

## Best Practices

1. **Import theme CSS first**, then your custom overrides
2. **Use palette tokens** (`var(--ig-primary-500)`) for all colors — never hardcode hex values
3. **Use CSS custom properties on `:root`** for global theme adjustments
4. **Scope overrides with CSS classes** for different sections
5. **Use `::part()` selectors** to style shadow DOM internals
6. **In CSS selectors, use web component tag names** (`igc-button`), not React names (`IgrButton`)
7. **Test both light and dark themes**
8. **Use the MCP server** for AI-assisted theme generation when available

## Key Rules

1. **Never overwrite existing files directly** — propose theme code as an update for user review
2. **Always call `detect_platform` first** when using MCP tools
3. **Always call `get_component_design_tokens` before `create_component_theme`**
4. **Palette shades**: 50 = lightest, 900 = darkest
5. **Surface color must match variant** — light color for `light`, dark for `dark`
6. **Never hardcode colors after palette generation**