Ignite UI for Blazor - Theming and Styling

Description

This skill teaches AI agents how to theme Ignite UI for Blazor applications using built-in CSS theme files, CSS custom properties, CSS shadow parts, and the Ignite UI Theming MCP server. It covers theme switching, palette generation, component-level design tokens, global layout tokens, and scoped CSS customization.

Prerequisites

• A Blazor project using Ignite UI for Blazor components
• A theme CSS file linked in the host page (see references/common-patterns.md)
• 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 any lightweight theming MCP tool. This skill is already scoped to Ignite UI for Blazor, so use platform: "blazor" in theming tool calls. If the theming 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`](./references/mcp-setup.md). Read that file for editor-specific configuration steps and verification.

Theming Architecture

Ignite UI for Blazor theming in this skill is CSS-first. Agents should generate or edit CSS custom properties and selectors for normal app styling.

Built-In Themes

Use built-in theme CSS files for the baseline visual system. Supported design systems are Bootstrap, Material, Fluent, and Indigo, with light and dark variants.

Confirm exact file paths in references/common-patterns.md before writing host-page markup. Only one built-in theme CSS file should be active at a time.

Color Palettes

Use create_palette(platform: "blazor", output: "css", ...) for a generated palette from seed colors. Use create_custom_palette(platform: "blazor", output: "css", ...) only when the user needs explicit control over individual shade values.

Palette CSS belongs in :root and must be loaded after the Ignite UI built-in theme CSS.

For simple palette references, use get_color instead of writing color variable names from memory:

get_color(color: "primary", variant: "600")

Use contrast: true when you need the matching text color token.

Raw color values are acceptable in the initial palette seed call. After the palette exists, component themes and custom CSS should use palette CSS custom properties wherever the desired color belongs to the theme.

Palette shades: chromatic shades use 50 as the lightest shade and 900 as the darkest shade. Do not invert chromatic colors for dark themes; only gray is inverted for dark variants.

Surface color must match the variant: use a light surface for variant: "light" and a dark surface for variant: "dark".

Component-Level Theming

For component styling, first call get_component_design_tokens(component: "..."), then call create_component_theme(platform: "blazor", component: "...", tokens: {...}, output: "css") or write CSS using the returned token names. Do not use overrides; the MCP argument is tokens.

For components with variants, query the exact variant whenever possible. For example, use contained-button, flat-button, outlined-button, or fab-button instead of generic button before generating a component theme.

Use palette token references such as var(--ig-primary-500) and var(--ig-primary-500-contrast) after a palette has been established. Do not pass raw hex/RGB/HSL values to component theme tokens unless the value is intentionally outside the theme palette.

For CSS parts, call the component's Blazor get_doc entry first. Do not say a component exposes CSS parts unless the Blazor doc confirms the exact part names.

Discovering Available Tokens

Each component has its own set of design tokens. Before theming a component, call get_component_design_tokens and use only token names returned by the tool.

Compound Components

Some components are compound and may involve internally themed child components. When get_component_design_tokens returns compound guidance, follow the checklist from the tool response.

For standard compound components, generate the related themes listed by the tool and scope them under the parent component selector. For composed compound components, use only the primary parent tokens unless the user explicitly requests a specific refinement token.

Layout Controls

Use MCP layout tools for global or scoped layout changes:

Do not use legacy size names such as compact, cosy, or comfortable for Blazor theming tools.

Using the Theming MCP Server

The Ignite UI Theming MCP server provides code generation and reference tools for Blazor-ready CSS custom properties. Agents can see tool schemas directly, so this section only records the Ignite UI for Blazor theming workflow and product-specific constraints.

IMPORTANT - File Safety Rule: When generating or updating theme code, never overwrite existing style files directly. Instead, propose the changes as an update and let the user review and approve before writing to disk. If an app.css, site.css, .razor.css, or other target style 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 - Verify Blazor Theming Context

Tool: read_resource
Params: { uri: "theming://platforms/blazor" }

Use this as the lightweight availability check and platform reference for Blazor theming tasks.

Step 2 - Generate a Palette

Note: For Blazor (CSS-first, no Sass pipeline), use create_palette with output: "css" to get CSS custom properties directly. Do NOT use create_theme for Blazor — it always outputs Sass which requires a compilation step not present in standard Blazor projects. The create_palette param names are primary/secondary/surface (not primaryColor/secondaryColor/surfaceColor — those belong to create_theme).

Tool: create_palette
Params: {
  platform: "blazor",
  output: "css",
  primary: "#3f51b5",
  secondary: "#e91e63",
  surface: "#ffffff",
  variant: "light"
}

For dark themes, use a dark surface color and variant: "dark". Read theming://guidance/colors/rules first when surface or gray color choices are unclear.

Step 3 - Customize Individual Components

Tool: get_component_design_tokens
Params: { component: "contained-button" }

Then generate CSS using only valid token names returned by the tool:

Tool: create_component_theme
Params: {
  platform: "blazor",
  output: "css",
  component: "contained-button",
  tokens: {
    "background": "var(--ig-primary-500)",
    "foreground": "var(--ig-primary-500-contrast)"
  }
}

Use tokens, not overrides. If the token discovery response distinguishes primary tokens from refinement tokens, use only the primary tokens unless the user explicitly requested the refined state or subpart.

Step 4 - Adjust Global Layout Tokens

Tool: set_roundness
Params: { platform: "blazor", output: "css", radiusFactor: 0.5 }

Tool: set_spacing
Params: { platform: "blazor", output: "css", spacing: 1.25 }

Tool: set_size
Params: { platform: "blazor", output: "css", size: "small" }

Step 5 - Apply Generated CSS

Place generated CSS in an app stylesheet loaded after the Ignite UI theme CSS, such as wwwroot/css/app.css.

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
<link href="css/app.css" rel="stylesheet" />

Palette and global layout CSS normally go in :root. Component theme CSS goes on the generated igc-* selector or under a scoped wrapper selector.

In .razor.css isolation files, prefix igc-* selectors so Blazor CSS isolation does not block the override.

Loading Reference Data

Use read_resource with these URIs for preset values and documentation:

Mandatory Agent Protocol

DO NOT write CSS variable names, token names, or palette colors from memory. Design token names and values are version-specific and theme-specific. Anything generated without reading the reference files or querying the MCP theming server will produce incorrect CSS.

You are required to complete all of the following steps before producing any theming-related code or answer:

Step 1 - Identify the theming task. Map the user's request to one or more rows in the Task to Reference File table below.

Step 2 - Use the theming MCP tools for version-specific values. For any task involving design token lookup, palette generation, component theme CSS, or global layout tokens, call the relevant Ignite UI Theming MCP tool. Do not infer token names, selector names, or palette variables from memory.

Step 3 - Read the relevant reference files in parallel. Call read_file on all identified reference files in a single parallel batch.

Step 4 - Only then produce output. Base CSS and instructions on what the MCP tools return and what the reference files say.

Task to Reference File

Key Blazor Theming Notes

AGENT INSTRUCTION - CSS customization

>

For normal Ignite UI for Blazor app styling, generate CSS custom properties and selectors.

AGENT INSTRUCTION - CSS parts

>

Some Ignite UI Blazor components expose CSS shadow parts via ::part(). Use get_doc for the component to confirm whether parts are available and to get the exact part names. Use get_component_design_tokens to get token names; do not infer token names or part names from Angular, React, or Web Components examples.

AGENT INSTRUCTION - Theming MCP server platform

>

This skill already establishes the platform. When calling Ignite UI Theming MCP tools that accept a platform, always pass platform: "blazor".

Key Rules

1. Use `platform: "blazor"` and `output: "css"` on theming tools that accept those parameters
2. Always call `get_component_design_tokens` before component CSS overrides; token names are not guessable from component names
3. Use exact component variants for variant components, such as contained-button, flat-button, outlined-button, and fab-button
4. Use `tokens` with `create_component_theme`; do not use an overrides object
5. Use palette tokens after palette generation; raw colors belong in palette seed inputs, not downstream component theme values
6. Place generated CSS after the built-in Ignite UI theme CSS so overrides win in the cascade
7. *Use `igc- selectors in CSS**, not Razor component names such as IgbButton`
8. Use `::part()` only after confirming part names with Blazor docs, and prefer design tokens when a token exists
9. Surface color must match the variant; use a light surface for light and a dark surface for dark
10. Only one built-in theme CSS file should be active at a time to avoid conflicting variables and component styles

Related Skills

• igniteui-blazor-components - All non-grid UI components
• igniteui-blazor-grids - Data Grids