igniteui-cli 15.5.1 → 15.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/package.json +4 -4
  2. package/templates/blazor/igb/projects/ai-config/files/skills/AGENTS.md +6 -3
  3. package/templates/blazor/igb/projects/ai-config/files/skills/README.md +30 -45
  4. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/SKILL.md +48 -96
  5. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/charts.md +61 -238
  6. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/data-display.md +60 -193
  7. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/feedback.md +36 -92
  8. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +66 -224
  9. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout-manager.md +39 -88
  10. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md +75 -152
  11. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +40 -149
  12. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md +58 -243
  13. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +89 -280
  14. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +143 -431
  15. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/SKILL.md +91 -157
  16. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/data-operations.md +50 -228
  17. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +61 -222
  18. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/features.md +67 -360
  19. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/grid-migration.md +55 -236
  20. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md +53 -202
  21. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md +31 -232
  22. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/state.md +27 -119
  23. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/structure.md +88 -363
  24. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/types.md +87 -415
  25. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/SKILL.md +8 -4
  26. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +42 -6
  27. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/SKILL.md +83 -211
  28. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/common-patterns.md +93 -184
  29. package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
  30. package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
  31. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
  32. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
  33. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
  34. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
  35. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
  36. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
  37. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
  38. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
  39. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
  40. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
  41. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
  42. package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
  43. package/templates/webcomponents/igc-ts/constants.js +5 -5
  44. package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
  45. package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
  46. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
  47. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
  48. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
  49. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
  50. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
  51. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
  52. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
  53. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
  54. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
  55. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
  56. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
  57. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
  58. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
@@ -1,136 +1,93 @@
1
1
  # Common Theming Patterns
2
2
 
3
- > **Part of the [`igniteui-blazor-theming`](../SKILL.md) skill hub.**
3
+ ## Built-in themes
4
4
 
5
- ## Contents
6
-
7
- - [Built-in Themes](#built-in-themes)
8
- - [Switching Theme at Build Time](#switching-theme-at-build-time)
9
- - [Dark Mode Toggle at Runtime](#dark-mode-toggle-at-runtime)
10
- - [CSS Custom Properties (Design Tokens)](#css-custom-properties-design-tokens)
11
- - [Scoped Component Theming](#scoped-component-theming)
12
- - [CSS Parts](#css-parts)
13
- - [Global Design Tokens](#global-design-tokens)
14
- - [Key Rules](#key-rules)
15
-
16
- ---
17
-
18
- ## Built-in Themes
19
-
20
- Ignite UI for Blazor ships 8 built-in themes (4 families × 2 modes):
21
-
22
- | Theme | Light CSS path | Dark CSS path |
23
- |---|---|---|
24
- | Bootstrap | `themes/light/bootstrap.css` | `themes/dark/bootstrap.css` |
25
- | Material | `themes/light/material.css` | `themes/dark/material.css` |
26
- | Fluent | `themes/light/fluent.css` | `themes/dark/fluent.css` |
27
- | Indigo | `themes/light/indigo.css` | `themes/dark/indigo.css` |
28
-
29
- All paths are relative to `_content/IgniteUI.Blazor/`.
30
-
31
- ---
32
-
33
- ## Switching Theme at Build Time
34
-
35
- Add a single `<link>` tag in your host page:
36
-
37
- ### Blazor Server / Web App - `Components/App.razor` or `Pages/_Host.cshtml`
5
+ Eight stylesheets under `_content/IgniteUI.Blazor/themes/`: `{light|dark}/{bootstrap|material|fluent|indigo}.css`. Link **one** in the host page — `wwwroot/index.html` (WASM), `Pages/_Host.cshtml` (Server), or `Components/App.razor` (Web App):
38
6
 
39
7
  ```html
40
8
  <link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
9
+ <link href="css/app.css" rel="stylesheet" />
10
+ <script src="_content/IgniteUI.Blazor/app.bundle.js"></script>
41
11
  ```
42
12
 
43
- ### Blazor WASM - `wwwroot/index.html`
13
+ .NET 9+ Web App projects can use the fingerprinted asset collection:
44
14
 
45
- ```html
46
- <link href="_content/IgniteUI.Blazor/themes/light/material.css" rel="stylesheet" />
15
+ ```razor
16
+ <link rel="stylesheet" href="@Assets["_content/IgniteUI.Blazor/themes/light/fluent.css"]" />
47
17
  ```
48
18
 
49
- ### Additional
50
-
51
- Also add the Ignite UI runtime script before the Blazor framework script:
19
+ If the page hosts any full-featured grid, add the grid stylesheet in the **same variant**:
52
20
 
53
21
  ```html
54
- <script src="_content/IgniteUI.Blazor/app.bundle.js"></script>
22
+ <link href="_content/IgniteUI.Blazor/themes/grid/light/bootstrap.css" rel="stylesheet" />
55
23
  ```
56
24
 
57
- ### .NET 9+ Web App - use `Assets` collection
25
+ `IgbGridLite` replaces both with its own: `_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css`.
26
+
27
+ ## Switching theme at runtime
28
+
29
+ ### `IgbThemeProvider` — preferred
30
+
31
+ Bind the parameters to state; no JS interop, no stylesheet swapping, and it can theme one region rather than the whole page.
58
32
 
59
33
  ```razor
60
- <link rel="stylesheet" href="@Assets["_content/IgniteUI.Blazor/themes/light/fluent.css"]" />
61
- ```
34
+ <IgbSwitch @bind-Checked="IsDark">Dark mode</IgbSwitch>
62
35
 
63
- Replace the file name to switch the entire application theme. Only **one** theme CSS file should be loaded at a time.
36
+ <IgbThemeProvider Theme="Theme.Bootstrap" Variant="@(IsDark ? ThemeVariant.Dark : ThemeVariant.Light)">
37
+ @Body
38
+ </IgbThemeProvider>
64
39
 
65
- ---
40
+ @code { bool IsDark; }
41
+ ```
42
+
43
+ Register `IgbThemeProviderModule`. Providers nest — an inner one overrides the outer for its subtree.
66
44
 
67
- ## Dark Mode Toggle at Runtime
45
+ ### Swapping the stylesheet
68
46
 
69
- Switch themes dynamically by updating the `href` attribute of the theme `<link>` tag via JavaScript interop or by using a CSS class on the `<body>`:
47
+ Use this when the whole document, including your own CSS that reads palette variables, has to follow the theme.
70
48
 
71
- ### Approach 1 - Replace the stylesheet href (JS Interop)
49
+ ```html
50
+ <link id="igTheme" href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
51
+ <script>
52
+ window.setIgTheme = href => document.getElementById('igTheme').setAttribute('href', href);
53
+ </script>
54
+ ```
72
55
 
73
56
  ```razor
74
57
  @inject IJSRuntime JS
75
58
 
76
- <IgbButton @onclick="ToggleDark">Toggle Dark Mode</IgbButton>
77
-
78
59
  @code {
79
- bool IsDark = false;
60
+ bool IsDark;
80
61
 
81
62
  async Task ToggleDark()
82
63
  {
83
64
  IsDark = !IsDark;
84
- var theme = IsDark ? "dark/bootstrap" : "light/bootstrap";
85
- await JS.InvokeVoidAsync("setTheme", $"_content/IgniteUI.Blazor/themes/{theme}.css");
65
+ var variant = IsDark ? "dark" : "light";
66
+ await JS.InvokeVoidAsync("setIgTheme", $"_content/IgniteUI.Blazor/themes/{variant}/bootstrap.css");
86
67
  }
87
68
  }
88
69
  ```
89
70
 
90
- ```html
91
- <!-- wwwroot/index.html or App.razor -->
92
- <link id="igTheme" href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
93
-
94
- <script>
95
- window.setTheme = function (href) {
96
- document.getElementById('igTheme').setAttribute('href', href);
97
- };
98
- </script>
99
- ```
100
-
101
- ### Approach 2 - Preload both themes and toggle link disabled states
102
-
103
- ```html
104
- <link id="igLightTheme" href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
105
- <link id="igDarkTheme" href="_content/IgniteUI.Blazor/themes/dark/bootstrap.css" rel="stylesheet" disabled />
106
- ```
71
+ Preloading both stylesheets and toggling their `disabled` flags avoids the fetch flash:
107
72
 
108
73
  ```js
109
- window.toggleDarkMode = function (isDark) {
74
+ window.toggleDarkMode = isDark => {
110
75
  document.getElementById('igLightTheme').disabled = isDark;
111
76
  document.getElementById('igDarkTheme').disabled = !isDark;
112
77
  };
113
78
  ```
114
79
 
115
- ---
116
-
117
- ## CSS Custom Properties (Design Tokens)
118
-
119
- All visual attributes of Ignite UI components (colors, borders, shadows, fonts) are exposed as CSS custom properties. You override them by declaring the property in a CSS rule that matches the component's scope. Design tokens are the **primary** theming approach - prefer them over `::part()` selectors.
80
+ Remember to swap the grid stylesheet variant too when a full grid is on the page.
120
81
 
121
- **Workflow:**
82
+ ## CSS custom properties (design tokens)
122
83
 
123
- 1. Call `get_component_design_tokens` to get all available tokens for a component.
124
- 2. Pick the tokens you want to change.
125
- 3. Write a CSS rule that overrides those tokens.
84
+ Every visual attribute is a CSS custom property. Tokens are the **primary** customization layer — reach for `::part()` only when no token covers the property.
126
85
 
127
- **File context matters:**
128
-
129
- - **Global CSS file** (`app.css`) - write `igc-<tag> { --ig-<component>-<token>: value; }` directly.
130
- - **`.razor.css` isolation file** - add `::deep` before the `igc-<tag>` selector.
86
+ 1. Call `get_component_design_tokens("<component-or-variant>")` — never guess names.
87
+ 2. Override the ones you need in a rule matching the component's scope.
131
88
 
132
89
  ```css
133
- /* app.css - global, no ::deep needed */
90
+ /* app.css — global, no ::deep */
134
91
  :root {
135
92
  --ig-primary-500: #7b2fff;
136
93
  --ig-primary-600: #6200ee;
@@ -143,142 +100,94 @@ igc-chip {
143
100
  ```
144
101
 
145
102
  ```css
146
- /* MyView.razor.css - isolation file, ::deep required */
103
+ /* MyView.razor.css — isolation file, ::deep required on igc-* selectors */
147
104
  ::deep igc-chip {
148
105
  --ig-chip-background: var(--ig-primary-500);
149
- --ig-chip-text-color: var(--ig-primary-500-contrast);
150
106
  }
151
107
  ```
152
108
 
153
- > **AGENT INSTRUCTION:** Always call `get_component_design_tokens(component: "<component-or-variant>")` before styling a component. For variant-based components such as buttons, query the exact variant such as `contained-button` or `flat-button`. Do NOT guess token names from memory.
109
+ ## `::deep` — what it does and does not do
110
+
111
+ `::deep` is Blazor's CSS-isolation combinator, not a shadow-DOM piercer. It only applies in `.razor.css` files, and only when Blazor's scope attribute sits on a parent **above** the target.
154
112
 
155
- ---
113
+ | Do | Don't |
114
+ |---|---|
115
+ | `::deep igc-chip { … }` | `::deep .my-class { … }` — plain class selectors are already scoped |
116
+ | `::deep igc-dialog::part(footer) { … }` | `::deep :root { … }` — never scope a `:root` block |
117
+ | Plain `.layout { … }` for your own HTML | `::deep` on the component's own root element — no scoped parent exists above it |
156
118
 
157
- ## Scoped Component Theming
119
+ MCP output from `create_component_theme` is global CSS: drop it into `app.css` unchanged, or add `::deep` to each `igc-*` selector when it goes into an isolation file.
158
120
 
159
- Apply a custom theme to a specific component instance (without affecting all components):
121
+ ## Scoped overrides without `IgbThemeProvider`
122
+
123
+ Wrap the components and scope the selector to the wrapper — useful for one-off tweaks that are narrower than a whole theme.
160
124
 
161
125
  ```razor
162
- <div class="my-custom-button">
126
+ <div class="cta-area">
163
127
  <IgbButton>Custom Style</IgbButton>
164
128
  </div>
165
129
  ```
166
130
 
167
131
  ```css
168
- /* Scoped token override in your app's CSS (global file, no ::deep) */
169
- .my-custom-button igc-button {
132
+ /* global */
133
+ .cta-area igc-button {
170
134
  --ig-primary-500: #ff5722;
171
135
  --ig-primary-600: #e64a19;
172
136
  }
173
- ```
174
-
175
- When the scoped override is inside a `.razor.css` isolation file, add `::deep`:
176
137
 
177
- ```css
178
- /* MyComponent.razor.css - isolation file */
179
- ::deep .my-custom-button igc-button {
180
- --ig-primary-500: #ff5722;
181
- --ig-primary-600: #e64a19;
182
- }
138
+ /* isolation file */
139
+ ::deep .cta-area igc-button { --ig-primary-500: #ff5722; }
183
140
  ```
184
141
 
185
- Use `::part()` within a scoped selector only for properties not covered by tokens - verify via `get_component_design_tokens` first:
186
-
187
- ```css
188
- /* Global CSS */
189
- .my-custom-button igc-button::part(base) {
190
- border-radius: 20px;
191
- font-weight: 700;
192
- }
193
-
194
- /* Isolation file */
195
- ::deep .my-custom-button igc-button::part(base) {
196
- border-radius: 20px;
197
- font-weight: 700;
198
- }
199
- ```
200
-
201
- ---
202
-
203
- ## CSS Parts
204
-
205
- Some Ignite UI Blazor components expose shadow DOM parts via `::part()`. Use these for styling only after the Blazor component documentation confirms the exact part names. Prefer design token CSS custom properties (via `get_component_design_tokens` / `create_component_theme`) over `::part()` - tokens are the primary theming layer. Only reach for `::part()` when the property you need is not covered by any design token.
206
-
207
- **`::part()` is not a replacement for design tokens.** Setting a design token (e.g., `--ig-chip-background`) is different from using `::part(base) { background: ... }`. Use the token approach when a token exists; use `::part()` for properties the token system does not expose.
208
-
209
- **Workflow:**
142
+ ## CSS shadow parts
210
143
 
211
- 1. Call `get_component_design_tokens` to check whether the desired property has a token.
212
- 2. If a token exists, set it via `igc-<tag> { --ig-<component>-<token>: value; }` - no `::part()` needed.
213
- 3. If no token covers it, call `get_doc` to see the component's CSS parts list, then use `igc-<component-tag>::part(<part-name>)`.
144
+ Setting a design token and styling a part are different operations — a token flows through the component's own styling logic, a `::part()` rule overrides one element directly. Prefer the token.
214
145
 
215
- **File context:**
216
-
217
- - **Global CSS file** (`app.css`): use `igc-<tag>::part(<name>) { ... }` directly.
218
- - **`.razor.css` isolation file**: prefix with `::deep` → `::deep igc-<tag>::part(<name>) { ... }`.
219
-
220
- Example - styling the dialog footer area (global CSS):
146
+ 1. `get_component_design_tokens` — is there a token for this property? If yes, use it.
147
+ 2. If not, `get_doc` for the component to get the **exact** part names. Do not claim a component exposes parts without confirming.
148
+ 3. Write `igc-<tag>::part(<name>)`, adding `::deep` in an isolation file.
221
149
 
222
150
  ```css
223
- /* app.css - global, no ::deep needed */
151
+ /* app.css */
224
152
  igc-dialog::part(footer) {
225
- background-color: #f5f5f5;
226
- border-top: 1px solid #e0e0e0;
153
+ background-color: var(--ig-gray-100);
154
+ border-top: 1px solid var(--ig-gray-200);
227
155
  padding: 12px 16px;
228
156
  }
229
- ```
230
157
 
231
- Same override in a `.razor.css` isolation file:
232
-
233
- ```css
234
- /* MyView.razor.css - isolation file, ::deep required */
235
- ::deep igc-dialog::part(footer) {
236
- background-color: #f5f5f5;
237
- border-top: 1px solid #e0e0e0;
238
- padding: 12px 16px;
239
- }
158
+ /* MyView.razor.css */
159
+ ::deep igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
240
160
  ```
241
161
 
242
- > **AGENT INSTRUCTION:** Blazor renders Ignite UI components as web components with `igc-` tag names. The CSS selector uses the web component tag name (e.g., `igc-button`, `igc-dialog`) not the Razor component name (`IgbButton`). `::deep` is a Blazor CSS isolation combinator - it is only needed in `.razor.css` files, not in global stylesheets.
243
-
244
- ---
245
-
246
- ## Global Design Tokens
247
-
248
- Use the MCP theming tools to generate CSS for global design tokens:
162
+ ## Global layout tokens
249
163
 
250
- ### Roundness (border-radius)
251
-
252
- ```bash
253
- set_roundness(platform: "blazor", output: "css", radiusFactor: 0.5)
254
- # Returns CSS custom properties to add to :root
255
164
  ```
256
-
257
- `radiusFactor` is a value from 0 (square) to 1 (maximum roundness).
258
-
259
- ### Spacing
260
-
261
- ```bash
165
+ set_roundness(platform: "blazor", output: "css", radiusFactor: 0.5) # 0 = square, 1 = fully rounded
262
166
  set_spacing(platform: "blazor", output: "css", spacing: 1.25)
263
- # Returns spacing CSS custom properties to add to :root
167
+ set_size(platform: "blazor", output: "css", size: "small") # small | medium | large
264
168
  ```
265
169
 
266
- ### Size
170
+ Put the returned CSS in `:root` in your global stylesheet. `--ig-size` also drives grid density directly — see the grids skill's [`sizing.md`](../../igniteui-blazor-grids/references/sizing.md).
267
171
 
268
- ```bash
269
- set_size(platform: "blazor", output: "css", size: "small")
270
- # Returns size CSS custom properties; values: "small" | "medium" | "large"
271
- ```
172
+ ## Multiple surface depths in dark themes
272
173
 
273
- Add the returned CSS to your global `app.css` or `wwwroot/css/app.css` inside a `:root {}` selector.
174
+ A single generated surface color rarely covers a design with a darker sidebar and lighter cards. Define semantic variables layered on the palette and use those in layout CSS instead of hardcoding hex:
175
+
176
+ ```css
177
+ :root {
178
+ --surface-1: var(--ig-gray-900); /* sidebar, drawer */
179
+ --surface-2: var(--ig-gray-800); /* content area */
180
+ --surface-3: var(--ig-gray-700); /* elevated cards */
181
+ }
182
+ ```
274
183
 
275
- ---
184
+ `create_custom_palette` is the alternative when the extra depths belong in the palette itself.
276
185
 
277
- ## Key Rules
186
+ ## Rules
278
187
 
279
- 1. **Always use the MCP theming tools to get token names.** Do not hardcode CSS variable names without first calling `get_component_design_tokens`.
280
- 2. **Only one theme CSS file should be active at a time.** Loading multiple themes causes conflicts.
281
- 3. **CSS selectors use `igc-` tag names, not Razor component names.** `igc-button::part(base)`, not `IgbButton::part(base)`.
282
- 4. **Design token overrides go in a plain CSS file** - there is no Sass step for Blazor theming.
283
- 5. **Scoped theming works by wrapping the component in a container with a CSS class** and scoping the CSS selector to that container.
284
- 6. **`_content/IgniteUI.Blazor/themes/`** is the correct base path for all built-in theme CSS files.
188
+ 1. One built-in theme stylesheet at a time.
189
+ 2. Selectors use `igc-*` tag names, never Razor component names.
190
+ 3. Call `get_component_design_tokens` before writing any `--ig-<component>-*` name.
191
+ 4. Load your overrides after the built-in theme so the cascade favors them.
192
+ 5. Once a palette exists, use its tokens instead of raw hex — hardcoded colors break theme switching. Charts and other DV components are the exception; they need resolved color values.
193
+ 6. Blazor theming is plain CSS. There is no Sass pipeline.
@@ -1,98 +1,45 @@
1
- # LLM Agent Skills for Ignite UI for React
1
+ # Agent Skills for Ignite UI for React
2
2
 
3
- This directory contains skills for GitHub Copilot and other LLM agents to help developers use **Ignite UI for React** effectively in their applications.
3
+ Task-focused instructions that help AI coding agents use **Ignite UI for React** correctly — component selection, setup, theming, performance, and migration. Each skill is self-contained and framework-specific.
4
4
 
5
- ## What are Skills?
5
+ ## Available skills
6
6
 
7
- Skills are structured instructions that help AI agents understand and execute common tasks consistently. Each skill is a self-contained guide that provides step-by-step instructions, code examples, and best practices — all specific to React and the `igniteui-react` family of packages.
7
+ | Skill | Use when |
8
+ | --- | --- |
9
+ | [igniteui-react-components](./igniteui-react-components/SKILL.md) | Choosing an `Igr*` component, setting up `igniteui-react`, writing JSX, wiring events/refs/forms, or debugging components that render unstyled or invisible |
10
+ | [igniteui-react-customize-theme](./igniteui-react-customize-theme/SKILL.md) | Applying brand colors, switching light/dark, overriding component appearance |
11
+ | [igniteui-react-optimize-bundle-size](./igniteui-react-optimize-bundle-size/SKILL.md) | The bundle is too large, or grids/charts are in the initial chunk |
12
+ | [igniteui-react-generate-from-image-design](./igniteui-react-generate-from-image-design/SKILL.md) | Building a view from a screenshot, mockup, or wireframe |
13
+ | [grid-lite-to-igr-grid-migration](./grid-lite-to-igr-grid-migration/SKILL.md) | Grid Lite lacks a needed feature — editing, selection, paging, grouping, export |
8
14
 
9
- ## Available Skills
15
+ Agents pick a skill from the request, so ordinary questions are enough: *"add a data grid to my React app"*, *"build this dashboard screenshot"*, *"match our brand colors"*, *"my bundle is too large"*. Naming a skill directly also works: *"use the igniteui-react-customize-theme skill"*.
10
16
 
11
- | Skill | Description | Use When |
12
- | --- | --- | --- |
13
- | [igniteui-react-components](./igniteui-react-components/SKILL.md) | Identify the right React components (`Igr*`) for a UI pattern, then install, import, and use them - JSX patterns, events, refs, forms | Choosing components or setting up and using them in React |
14
- | [igniteui-react-customize-theme](./igniteui-react-customize-theme/SKILL.md) | Customize styling using CSS custom properties, Sass, and the theming system in a React context | Applying custom brand colors/styles |
15
- | [igniteui-react-optimize-bundle-size](./igniteui-react-optimize-bundle-size/SKILL.md) | Reduce bundle size with granular imports, tree-shaking, and lazy loading | Optimizing production performance |
16
- | [igniteui-react-generate-from-image-design](./igniteui-react-generate-from-image-design/SKILL.md) | Build a React view from a screenshot or mockup using Ignite UI components plus MCP-first theming and token mapping | Converting a design image into a working Ignite UI React page or dashboard |
17
+ ## MCP servers
17
18
 
18
- ## How to Use
19
+ Two optional MCP servers make the agent's answers authoritative rather than recalled:
19
20
 
20
- When working with an AI agent like GitHub Copilot, reference skills by name or ask questions naturally:
21
+ - **`igniteui-cli`** — component docs and API reference (`list_components`, `get_doc`, `get_api_reference`, `search_docs`, `search_api`)
22
+ - **`igniteui-theming`** — palette, typography, elevation, and per-component theme generation
21
23
 
22
- ### Natural Questions
24
+ Every skill works without them, falling back to the type declarations in `node_modules`. Setup instructions are in [igniteui-react-components/reference/MCP.md](./igniteui-react-components/reference/MCP.md) and the theming skill.
23
25
 
24
- - "How do I add a data grid to my React app?"
25
- - "What Ignite UI component should I use for a date picker?"
26
- - "Build this dashboard screenshot in Ignite UI React"
27
- - "Help me customize the button colors to match my brand"
28
- - "My bundle size is too large, how can I reduce it?"
29
- - "How do I handle events on IgrCombo?"
26
+ ## Installation
30
27
 
31
- ### Direct Skill Reference
28
+ Copy the skill folders into the directory your agent reads:
32
29
 
33
- - "Follow the igniteui-react-components skill for setting up my project"
34
- - "Use the igniteui-react-generate-from-image-design skill for this mockup"
35
- - "Use the igniteui-react-customize-theme skill to help me style components"
36
- - "Apply the igniteui-react-optimize-bundle-size skill to reduce my bundle"
30
+ | Agent | Directory |
31
+ | --- | --- |
32
+ | Claude Code | `.claude/skills/` |
33
+ | GitHub Copilot | `.agents/skills/` |
34
+ | Cursor, Windsurf, others | see the agent's documentation |
37
35
 
38
- ## Skill Structure
39
-
40
- Each skill contains:
41
-
42
- - **Example Usage**: Common questions or scenarios
43
- - **When to Use**: Situations where the skill applies
44
- - **Related Skills**: Other relevant skills to explore
45
- - **Step-by-Step Instructions**: Detailed guidance with code examples
46
- - **Common Issues & Solutions**: Troubleshooting guidance
47
- - **Best Practices**: Recommended approaches
48
- - **Additional Resources**: Further reading and documentation
49
-
50
- ## Editor / Agent Setup
51
-
52
- Most modern AI assistants (GitHub Copilot, Cursor, Windsurf, Claude Code, etc.) should auto-discover these skills from a specified location in the workspace or global profile.
53
-
54
- For example, you can copy them into the agent-specific skills folder for your editor:
55
-
56
- ### GitHub Copilot
57
-
58
- Copy the skill files into your project's `.agents/skills/` directory:
36
+ Keep each skill's `SKILL.md` alongside its `reference/` folder (when present) — the reference files are loaded on demand and the relative links between skills assume the layout is preserved.
59
37
 
60
38
  ```
61
- .agents/
62
- skills/
63
- igniteui-react-components/
64
- SKILL.md
65
- reference/
66
- igniteui-react-customize-theme/
67
- SKILL.md
68
- reference/
69
- igniteui-react-optimize-bundle-size/
70
- SKILL.md
71
- igniteui-react-generate-from-image-design/
72
- SKILL.md
73
- references/
39
+ .claude/skills/
40
+ igniteui-react-components/{SKILL.md,reference/}
41
+ igniteui-react-customize-theme/{SKILL.md,reference/}
42
+ igniteui-react-optimize-bundle-size/SKILL.md
43
+ igniteui-react-generate-from-image-design/{SKILL.md,reference/}
44
+ grid-lite-to-igr-grid-migration/SKILL.md
74
45
  ```
75
-
76
- ### Claude Code
77
-
78
- Copy the skill files into your project's `.claude/skills/` directory:
79
-
80
- ```
81
- .claude/
82
- skills/
83
- igniteui-react-components/
84
- SKILL.md
85
- reference/
86
- igniteui-react-customize-theme/
87
- SKILL.md
88
- reference/
89
- igniteui-react-optimize-bundle-size/
90
- SKILL.md
91
- igniteui-react-generate-from-image-design/
92
- SKILL.md
93
- references/
94
- ```
95
-
96
- ### Other Agents (Cursor, Windsurf, etc.)
97
-
98
- Consult your agent's documentation for the correct skills directory path and copy the skill files there. The skill structure is agent-agnostic — any assistant that supports skill files can use them directly.