igniteui-cli 15.5.0 → 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 (76) 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 +86 -0
  26. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +220 -0
  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/_base/files/src/main.tsx +1 -0
  30. package/templates/react/igr-ts/projects/_base_with_home/files/src/app/home/style.module.css +3 -3
  31. package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
  32. package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
  33. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
  34. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
  35. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
  36. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
  37. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
  38. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
  39. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
  40. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
  41. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
  42. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
  43. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
  44. package/templates/react/igr-ts/projects/side-nav/files/src/app/app.css +9 -9
  45. package/templates/react/igr-ts/projects/side-nav/files/src/app/home/style.module.css +7 -7
  46. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/app.css +8 -8
  47. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.module.css +1 -69
  48. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.tsx +5 -5
  49. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginBar.module.css +5 -26
  50. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginDialog.module.css +0 -1
  51. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.module.css +1 -56
  52. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.tsx +2 -2
  53. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/Profile.module.css +11 -11
  54. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectFacebook.tsx +1 -1
  55. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectGoogle.tsx +1 -1
  56. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectMicrosoft.tsx +1 -1
  57. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/app.css +9 -9
  58. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/home/style.module.css +7 -7
  59. package/templates/react/igr-ts/projects/side-nav-mini-auth/files/src/app/app.css +7 -7
  60. package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
  61. package/templates/webcomponents/igc-ts/constants.js +5 -5
  62. package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
  63. package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
  64. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
  65. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
  66. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
  67. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
  68. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
  69. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
  70. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
  71. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
  72. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
  73. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
  74. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
  75. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
  76. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
@@ -1,184 +1,132 @@
1
1
  ---
2
2
  name: igniteui-react-customize-theme
3
- 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
3
+ description: Theme Ignite UI for React with CSS custom properties — brand palette, dark mode, size/spacing/roundness, per-component tokens, and scoped themes, optionally via the igniteui-theming MCP server. Use when applying brand colors, switching light/dark, overriding a component's appearance (grid headers, buttons, avatars), or when theme overrides are not taking effect.
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # Ignite UI for React — Theming Skill
7
+ # Ignite UI for React — Theming
8
8
 
9
- ## Prerequisites
9
+ ## How the palette actually works
10
10
 
11
- - A React project with `igniteui-react` installed
12
- - A theme CSS file imported in your entry point (see [igniteui-react-components](../igniteui-react-components/SKILL.md))
13
- - The **Ignite UI Theming MCP server** (`igniteui-theming`)
11
+ Every palette role (`primary`, `secondary`, `surface`, `gray`, `info`, `success`, `warn`, `error`) exposes shades `50`–`900` plus a `-contrast` variant per shade. **Shades other than `500` are derived from `500` via relative color functions** — the theme CSS defines them as `hsl(from var(--ig-primary-500) h calc(s * …) calc(l * …))`.
14
12
 
15
- > **AGENT INSTRUCTION — MCP Server Setup (REQUIRED)**
16
- >
17
- > Before using any theming tools, you MUST verify the MCP server is available
18
- > by calling `detect_platform`. If the tool is not available or the call fails,
19
- > you MUST automatically configure it by following the setup process steps described below.
20
- >
21
- > After writing the file, inform the user that the MCP server has been
22
- > configured and they may need to reload the editor for the tools to activate.
23
- > Start the MCP server and wait for that MCP server to start before continuing the theming related work.
24
- > Do NOT skip this step or ask the user to do it manually.
13
+ So to rebrand, override the `500` shade and everything else follows:
25
14
 
26
- ## Description
27
-
28
- This skill teaches AI agents how to theme Ignite UI for React applications. One approach is supported:
29
-
30
- - **CSS custom properties** — works in any project without additional build tooling
31
-
32
- 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.
33
-
34
- ## Example Usage
35
-
36
- - "How do I change the primary color in my Ignite UI React app?"
37
- - "Apply a dark theme to my React app"
38
- - "Customize the grid header colors"
39
- - "How do I scope a theme to a specific section of my React app?"
40
- - "Set up Material Design theming for Ignite UI components"
41
-
42
- ## Setting Up the Theming MCP Server
43
-
44
- > **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.
45
-
46
- ## Related Skills
47
-
48
- - [igniteui-react-components](../igniteui-react-components/SKILL.md) — Choose the right components and set up your React project
49
- - [igniteui-react-optimize-bundle-size](../igniteui-react-optimize-bundle-size/SKILL.md) — Optimize after theming
50
-
51
- ## When to Use
52
-
53
- - Applying custom brand colors or a dark theme to an Ignite UI React app
54
- - Overriding individual component styles (e.g., grid header color, button appearance)
55
- - Switching between light and dark mode in a React app
56
- - Scoping different themes to different sections of a React app
57
- - Setting up the Ignite UI Theming MCP server for AI-assisted theming
58
-
59
- ---
60
-
61
- ## Content Guide
62
-
63
- This skill is organized into focused sections. Refer to the appropriate file for detailed instructions:
64
-
65
- | Topic | File | When to Use |
66
- |---|---|---|
67
- | CSS Theming | [CSS-THEMING.md](./reference/CSS-THEMING.md) | Pre-built themes, CSS custom properties, scoped overrides, layout controls, light/dark switching |
68
- | MCP Server | [MCP-SERVER.md](./reference/MCP-SERVER.md) | AI-assisted theming code generation |
69
- | Troubleshooting | [TROUBLESHOOTING.md](./reference/TROUBLESHOOTING.md) | Common issues and solutions |
15
+ ```css
16
+ /* src/index.css — imported AFTER the theme CSS */
17
+ :root {
18
+ --ig-primary-500: #0d6efd;
19
+ --ig-secondary-500: #ff9800;
20
+ }
21
+ ```
70
22
 
71
- ---
23
+ **There are no `--ig-primary-h` / `-s` / `-l` tokens.** Writing them is a silent no-op — a common and hard-to-spot mistake. The same applies to `--ig-surface-h`, `--ig-gray-h`, and every other `-h`/`-s`/`-l` name.
72
24
 
73
- ## Quick Start
25
+ Always reference palette tokens rather than literals in your own CSS: `var(--ig-primary-500)`, `var(--ig-primary-500-contrast)` for text on top of it. `50` is lightest, `900` darkest.
74
26
 
75
- ### 1. Import a Pre-built Theme (REQUIRED)
27
+ ## Order matters
76
28
 
77
29
  ```tsx
78
30
  // main.tsx
79
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
31
+ import 'igniteui-webcomponents/themes/light/bootstrap.css'; // theme
32
+ import 'igniteui-react-grids/grids/themes/light/bootstrap.css'; // grid theme, if using grids
33
+ import './index.css'; // your overrides — last
80
34
  ```
81
35
 
82
- **For grids**, also import:
83
-
84
- ```tsx
85
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
86
- ```
36
+ Design systems: `bootstrap` (default), `material`, `fluent`, `indigo`; each in `light` and `dark`.
87
37
 
88
- ### 2. Override with CSS Custom Properties
38
+ ## Global layout knobs
89
39
 
90
40
  ```css
91
- /* src/index.css */
92
41
  :root {
93
- --ig-primary-h: 211deg;
94
- --ig-primary-s: 100%;
95
- --ig-primary-l: 50%;
42
+ --ig-size: 2; /* 1 small, 2 medium, 3 large */
43
+ --ig-spacing: 1; /* 0.5 compact … 2 spacious; also -inline / -block variants */
44
+ --ig-radius-factor: 1; /* 0 square … 1 fully rounded */
96
45
  }
97
46
  ```
98
47
 
99
- ```tsx
100
- // main.tsx
101
- import 'igniteui-webcomponents/themes/light/bootstrap.css'; // Theme first
102
- import './index.css'; // Overrides second
103
- ```
48
+ All three cascade, so they scope to a subtree or a single element: `igc-button { --ig-size: 1; }`.
104
49
 
105
- ---
50
+ ## Component-level overrides
51
+
52
+ Selectors target the **rendered element**, never the React name:
106
53
 
107
- ## Theming Architecture
54
+ ```css
55
+ igc-avatar {
56
+ --ig-avatar-background: var(--ig-primary-500);
57
+ --ig-avatar-color: var(--ig-primary-500-contrast);
58
+ }
108
59
 
109
- The Ignite UI theming system is built on **palette**, **typography**, **elevations**, and per-component **schemas**. Use the MCP theming tools at the right stage:
60
+ igc-input::part(input) { font-size: 1.1rem; } /* ::part() reaches shadow DOM internals */
61
+ ```
110
62
 
111
- - **`create_palette`** — when the user provides brand colors; generates luminance-safe shades for all palette roles
112
- - **`create_theme`** — generates the complete global theme CSS; call after `create_palette`
113
- - **`create_typography`** — when the user wants to change fonts, type scale, or weights
114
- - **`create_elevations`** — when the user wants to adjust shadow depth
115
- - **`get_component_design_tokens`** - before writing any component-level CSS; retrieves the current token names for a specific component
116
- - **`set_size`**, **`set_spacing`**, or **`set_roundness`** - adjust component size, content spacing, and roundness.
63
+ **Component token names are per-component and not guessable.** `igc-avatar` has `--ig-avatar-background`, but `igc-button` exposes only typographic tokens (`--ig-button-font-size`, …) and has no `--ig-button-foreground`. Before writing any component token, get the real list: `get_component_design_tokens({ component: 'button' })`, or read the `@cssproperty` annotations in `node_modules/igniteui-webcomponents/components/<name>/*.d.ts`. If a component exposes no token for what you need, use `::part()`.
117
64
 
118
- ### Design Systems
65
+ ## Scoping
119
66
 
120
- - **Bootstrap** (default), **Material**, **Fluent**, **Indigo**
121
- - Each has light and dark variants
67
+ Palette tokens cascade, so a scoped theme is just custom properties on a container:
122
68
 
123
- ---
69
+ ```css
70
+ .admin { --ig-primary-500: #7c4dff; }
71
+ ```
124
72
 
125
- ## Key Concepts
73
+ ## Dark mode
126
74
 
127
- ### CSS Custom Properties
75
+ The theme CSS also declares `--ig-theme` and `--ig-theme-variant` on `:root`. Components read those **once, globally**, from `document.documentElement` to pick their shadow-DOM styles. Two consequences:
128
76
 
129
- Override tokens in your CSS:
77
+ - **The variant cannot be scoped to a subtree.** Overriding `--ig-theme-variant` on a wrapper does nothing. Dark mode is an app-wide switch.
78
+ - **Swapping the stylesheet is not enough at runtime** — the value is cached. Call `configureTheme`, which is re-exported from `igniteui-react`, to update it and notify mounted components:
130
79
 
131
- ```css
132
- :root { --ig-primary-h: 211deg; }
133
- .admin-panel { --ig-primary-h: 260deg; }
80
+ ```tsx
81
+ import { configureTheme } from 'igniteui-react';
82
+
83
+ configureTheme('bootstrap', 'dark'); // design system, variant
134
84
  ```
135
85
 
136
- ### Component-Level Theming
86
+ Prefer a real dark theme file (`themes/dark/bootstrap.css`) over hand-overriding palette tokens: it re-tunes surface, gray, elevations, and every component schema. See [CSS-THEMING.md](./reference/CSS-THEMING.md) for the switching patterns.
137
87
 
138
- Target web component tag names in CSS:
88
+ When choosing colors for a dark palette, `surface` must be dark (luminance ≤ 0.5) and the `gray` base must be **light**. Gray shades are generated to contrast *against* the surface, so the gray base is always inverted relative to the variant — reversing it produces unreadable text.
139
89
 
140
- ```css
141
- igc-button { --ig-button-foreground: var(--ig-secondary-500); }
142
- ```
90
+ ## Using the `igniteui-theming` MCP server
143
91
 
144
- ### CSS `::part()` Selectors
92
+ Optional but preferred when available — it generates palettes with luminance-safe shades and correct contrast. Verify with `detect_platform`; if missing, add the config below and tell the user to reload the editor. Pass `platform: 'react'`.
145
93
 
146
- ```css
147
- igc-input::part(input) { font-size: 1.1rem; }
148
- ```
94
+ | Stage | Tool |
95
+ |---|---|
96
+ | Brand colors → palette | `create_palette` (`primary`, `secondary`, `surface`, `gray`, `info`, `success`, `warn`, `error`, `variant`) |
97
+ | Multiple surface depths or several accent families | `create_custom_palette` |
98
+ | Fonts, type scale | `create_typography` |
99
+ | Shadow depth | `create_elevations` |
100
+ | Full global theme | `create_theme` (`primaryColor`, `secondaryColor`, `surfaceColor`, `variant`, `designSystem`, `fontFamily`) |
101
+ | Discover a component's tokens | `get_component_design_tokens` (`component`) |
102
+ | Component override block | `create_component_theme` (`component`, `tokens`, `selector`, `variant`, `designSystem`) |
103
+ | Resolve a palette color | `get_color` (`color`, `variant`, `contrast`, `opacity`) |
104
+ | Size / spacing / roundness | `set_size`, `set_spacing`, `set_roundness` |
105
+ | Guidance documents | `read_resource` (`uri`), e.g. `theming://guidance/colors/rules` |
149
106
 
150
- ### Layout Controls
107
+ All tools take named arguments. There is no `get_theming_guidance` tool — guidance is read through `read_resource`.
151
108
 
152
- ```css
153
- :root {
154
- --ig-size: 2; /* 1=small, 2=medium, 3=large */
155
- --ig-spacing: 1; /* 0.5=compact, 1=default, 2=spacious */
156
- --ig-radius-factor: 1; /* 0=square, 1=max radius */
109
+ Sequence: `create_palette` → `create_typography` / `create_elevations` → `create_theme` → per component `get_component_design_tokens` → `create_component_theme` with only the tokens that differ from the global theme. Read any luminance warning the tools return instead of ignoring it; if one generated surface color cannot express every depth in the design, use `create_custom_palette` or define your own `--surface-1` / `--surface-2` semantic variables.
110
+
111
+ **Never overwrite an existing stylesheet.** Propose generated theme code as an edit the user reviews.
112
+
113
+ VS Code — `.vscode/mcp.json` (Cursor and Claude Desktop use the same entry under `mcpServers`):
114
+
115
+ ```json
116
+ {
117
+ "servers": {
118
+ "igniteui-theming": {
119
+ "command": "npx",
120
+ "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
121
+ }
122
+ }
157
123
  }
158
124
  ```
159
125
 
160
- ### Light/Dark Switching
126
+ ## Reference
161
127
 
162
- See [CSS-THEMING.md](./reference/CSS-THEMING.md) for approaches: class toggle, media query, or stylesheet swap.
128
+ - [CSS-THEMING.md](./reference/CSS-THEMING.md) — scoping patterns, CSS Modules, light/dark switching, inline overrides
163
129
 
164
- ---
130
+ ## Related skills
165
131
 
166
- ## Best Practices
167
-
168
- 1. **Import theme CSS first**, then your custom overrides
169
- 2. **Use palette tokens** (`var(--ig-primary-500)`) for all colors — never hardcode hex values
170
- 3. **Use CSS custom properties on `:root`** for global theme adjustments
171
- 4. **Scope overrides with CSS classes** for different sections
172
- 5. **Use `::part()` selectors** to style shadow DOM internals
173
- 6. **In CSS selectors, use web component tag names** (`igc-button`), not React names (`IgrButton`)
174
- 7. **Test both light and dark themes**
175
- 8. **Use the MCP server** for AI-assisted theme generation when available
176
-
177
- ## Key Rules
178
-
179
- 1. **Never overwrite existing files directly** — propose theme code as an update for user review
180
- 2. **Always call `detect_platform` first** when using MCP tools
181
- 3. **Always call `get_component_design_tokens` before `create_component_theme`**
182
- 4. **Palette shades**: 50 = lightest, 900 = darkest
183
- 5. **Surface color must match variant** — light color for `light`, dark for `dark`
184
- 6. **Never hardcode colors after palette generation**
132
+ - [igniteui-react-components](../igniteui-react-components/SKILL.md) — components, theme CSS setup, slots and events
@@ -1,267 +1,100 @@
1
- # CSS Theming
1
+ # CSS Theming Patterns
2
2
 
3
- This guide covers theming Ignite UI for React using CSS custom properties — works in any project without additional build tooling.
3
+ Read [../SKILL.md](../SKILL.md) first — it covers the token model (`--ig-primary-500` and derived shades), import order, and why `-h`/`-s`/`-l` tokens do not exist.
4
4
 
5
- ## Pre-built Themes
5
+ ## Scoping overrides
6
6
 
7
- Import a pre-built CSS file in your React entry point:
8
-
9
- ```tsx
10
- // main.tsx or index.tsx
11
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
12
- ```
13
-
14
- > **CRITICAL:** Theme CSS imports are **required** for components to render correctly.
15
-
16
- **For grids**, you **must also** import the grid theme CSS:
17
-
18
- ```tsx
19
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
20
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
21
- ```
22
-
23
- ### Available Pre-built CSS Files
24
-
25
- | Import path | Theme |
26
- |---|---|
27
- | `igniteui-webcomponents/themes/light/bootstrap.css` | Bootstrap Light |
28
- | `igniteui-webcomponents/themes/dark/bootstrap.css` | Bootstrap Dark |
29
- | `igniteui-webcomponents/themes/light/material.css` | Material Light |
30
- | `igniteui-webcomponents/themes/dark/material.css` | Material Dark |
31
- | `igniteui-webcomponents/themes/light/fluent.css` | Fluent Light |
32
- | `igniteui-webcomponents/themes/dark/fluent.css` | Fluent Dark |
33
- | `igniteui-webcomponents/themes/light/indigo.css` | Indigo Light |
34
- | `igniteui-webcomponents/themes/dark/indigo.css` | Indigo Dark |
35
-
36
- Grid theme CSS files follow the same pattern under `igniteui-react-grids/grids/themes/`.
37
-
38
- ### Next.js
39
-
40
- In Next.js, import the theme CSS in each client component file or in a shared root layout:
41
-
42
- ```tsx
43
- // app/layout.tsx
44
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
45
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
46
-
47
- export default function RootLayout({ children }: { children: React.ReactNode }) {
48
- return (
49
- <html lang="en">
50
- <body>{children}</body>
51
- </html>
52
- );
53
- }
54
- ```
55
-
56
- ## Custom Theme via CSS Custom Properties
57
-
58
- After importing a pre-built theme, override individual design tokens with CSS custom properties.
59
-
60
- ### Global Overrides (in your CSS file)
7
+ Palette tokens are ordinary custom properties, so any of these work. Prefer a class over inline styles.
61
8
 
62
9
  ```css
63
- /* src/index.css */
64
- :root {
65
- --ig-primary-h: 211deg;
66
- --ig-primary-s: 100%;
67
- --ig-primary-l: 50%;
68
-
69
- --ig-secondary-h: 33deg;
70
- --ig-secondary-s: 100%;
71
- --ig-secondary-l: 50%;
72
- }
73
- ```
74
-
75
- Import it in your entry point:
76
-
77
- ```tsx
78
- // main.tsx
79
- import 'igniteui-webcomponents/themes/light/bootstrap.css'; // Theme first
80
- import './index.css'; // Overrides — must come after the theme import
81
- ```
82
-
83
- ### Scoped Overrides
84
-
85
- Use a CSS class to scope theme overrides to a specific container:
86
-
87
- ```css
88
- /* src/AdminPanel.css */
89
- .admin-panel {
90
- --ig-primary-h: 260deg;
91
- --ig-primary-s: 60%;
92
- --ig-primary-l: 45%;
93
- }
94
- ```
95
-
96
- ```tsx
97
- // AdminPanel.tsx
98
- import './AdminPanel.css';
99
- import { IgrButton, IgrInput } from 'igniteui-react';
100
-
101
- function AdminPanel() {
102
- return (
103
- <div className="admin-panel">
104
- <IgrInput label="Admin Search" />
105
- <IgrButton>Save</IgrButton>
106
- </div>
107
- );
108
- }
10
+ /* plain class */
11
+ .admin-panel { --ig-primary-500: #7c4dff; }
109
12
  ```
110
13
 
111
- ### CSS Modules
112
-
113
14
  ```css
114
- /* AdminPanel.module.css */
115
- .panel {
116
- --ig-primary-h: 260deg;
117
- --ig-primary-s: 60%;
118
- --ig-primary-l: 45%;
119
- }
15
+ /* CSS Modules */
16
+ .panel { --ig-primary-500: #7c4dff; }
120
17
  ```
121
18
 
122
19
  ```tsx
123
20
  import styles from './AdminPanel.module.css';
124
- import { IgrButton } from 'igniteui-react';
125
21
 
126
- function AdminPanel() {
127
- return (
128
- <div className={styles.panel}>
129
- <IgrButton>Save</IgrButton>
130
- </div>
131
- );
132
- }
22
+ <div className={styles.panel}>
23
+ <IgrButton>Save</IgrButton>
24
+ </div>
133
25
  ```
134
26
 
135
- ### Inline Styles on a Wrapper
136
-
137
- For truly dynamic one-off overrides:
27
+ Inline styles need a cast, since TypeScript's `CSSProperties` does not accept custom property names:
138
28
 
139
29
  ```tsx
140
- <div style={{ '--ig-primary-h': '260deg', '--ig-primary-s': '60%', '--ig-primary-l': '45%' } as React.CSSProperties}>
141
- <IgrButton>Custom Color Button</IgrButton>
30
+ <div style={{ '--ig-primary-500': brandColor } as React.CSSProperties}>
31
+ <IgrAvatar />
142
32
  </div>
143
33
  ```
144
34
 
145
- > **Note:** TypeScript requires the `as React.CSSProperties` cast. Prefer CSS classes when possible.
35
+ ## Light / dark switching
146
36
 
147
- ## Component-Level Theming
37
+ Both `themes/light/*.css` and `themes/dark/*.css` define their tokens on `:root`, so importing both means the later import wins globally — you cannot scope one to a subtree. Pick one of these instead.
148
38
 
149
- Override individual component appearance using CSS custom properties.
39
+ **Static, follow the OS.** No JavaScript, but the variant is fixed at load, so components that read `--ig-theme-variant` see whatever matched first.
150
40
 
151
- > **AGENT INSTRUCTION**: Before writing component-level token overrides, call `get_component_design_tokens` with the component name (e.g., `"avatar"`, `"button"`, `"grid"`) to retrieve the current, correct token names. Token names vary by component and can change between versions. Use only tokens returned by that call — do not guess or reuse tokens from other components.
152
-
153
- ```css
154
- /* Target the Ignite UI web component tag name */
155
- igc-avatar {
156
- --ig-avatar-background: var(--ig-primary-500);
157
- --ig-avatar-color: var(--ig-primary-500-contrast);
158
- }
159
-
160
- igc-button {
161
- --ig-button-foreground: var(--ig-secondary-500);
162
- }
41
+ ```html
42
+ <link rel="stylesheet" href="/themes/light/bootstrap.css" media="(prefers-color-scheme: light)">
43
+ <link rel="stylesheet" href="/themes/dark/bootstrap.css" media="(prefers-color-scheme: dark)">
163
44
  ```
164
45
 
165
- > **IMPORTANT — No Hardcoded Colors**
166
- >
167
- > ✅ **Right:** `--ig-avatar-background: var(--ig-primary-500);`
168
- > ❌ **Wrong:** `--ig-avatar-background: #E91E63;`
46
+ **Runtime toggle.** Swap the active stylesheet *and* call `configureTheme` so mounted components restyle:
169
47
 
170
- ### CSS `::part()` Selectors
48
+ ```tsx
49
+ import { useEffect, useState } from 'react';
50
+ import { configureTheme, type Theme, type ThemeVariant } from 'igniteui-react';
171
51
 
172
- Use `::part()` selectors to style shadow DOM internal elements:
52
+ export function useIgTheme(design: Theme = 'bootstrap') {
53
+ const [variant, setVariant] = useState<ThemeVariant>('light');
173
54
 
174
- ```css
175
- igc-input::part(input) {
176
- font-size: 1.1rem;
177
- }
55
+ useEffect(() => {
56
+ const link = document.getElementById('ig-theme') as HTMLLinkElement | null;
57
+ if (link) link.href = `/themes/${variant}/${design}.css`;
58
+ configureTheme(design, variant);
59
+ }, [variant, design]);
178
60
 
179
- igc-card::part(header) {
180
- padding: 1rem;
61
+ return [variant, setVariant] as const;
181
62
  }
182
63
  ```
183
64
 
184
- > **Note:** In CSS, use web component tag names (`igc-input`), not React component names (`IgrInput`).
65
+ `Theme` is `'bootstrap' | 'material' | 'fluent' | 'indigo'` and `ThemeVariant` is `'light' | 'dark'`; both are re-exported from `igniteui-react`.
185
66
 
186
- ## Layout Controls
67
+ Serve the CSS from your own build output or public directory — do not point a `<link>` at `node_modules`, which is not deployed.
187
68
 
188
- ### Sizing
69
+ **Partial dark surfaces.** If only one panel must look dark, do not fight the global variant. Define semantic variables for the depths you need and use them in your own CSS, leaving Ignite UI components on the app-wide variant:
189
70
 
190
71
  ```css
191
- :root { --ig-size: 2; } /* 1 = small, 2 = medium, 3 = large */
192
- igc-button { --ig-size: 1; }
72
+ .dark-panel {
73
+ --surface-1: var(--ig-gray-900);
74
+ --surface-2: var(--ig-gray-800);
75
+ background: var(--surface-1);
76
+ color: var(--ig-gray-50);
77
+ }
193
78
  ```
194
79
 
195
- ### Spacing
80
+ ## Component internals
196
81
 
197
- ```css
198
- :root { --ig-spacing: 1; } /* 0.5 = compact, 1 = default, 2 = spacious */
199
- .compact-section { --ig-spacing: 0.75; }
200
- ```
201
-
202
- ### Roundness
82
+ When a component exposes no custom property for what you need, reach for `::part()`:
203
83
 
204
84
  ```css
205
- :root { --ig-radius-factor: 1; } /* 0 = square, 1 = maximum radius */
206
- igc-avatar { --ig-radius-factor: 0.5; }
85
+ igc-input::part(input) { font-size: 1.1rem; }
86
+ igc-card::part(header) { padding: 1rem; }
207
87
  ```
208
88
 
209
- ## Switching Between Light and Dark Themes
89
+ Available parts are listed as `@csspart` annotations in `node_modules/igniteui-webcomponents/components/<name>/*.d.ts`. Parts are stable API; descendant selectors into the shadow DOM are not available at all.
90
+
91
+ ## Grid themes
210
92
 
211
- ### Approach 1: CSS class toggle
93
+ Grids need a second stylesheet alongside the base theme, matched on both variant and design system:
212
94
 
213
95
  ```tsx
214
- import { useState } from 'react';
215
96
  import 'igniteui-webcomponents/themes/light/bootstrap.css';
216
- import './theme-overrides.css';
217
-
218
- function App() {
219
- const [isDark, setIsDark] = useState(false);
220
-
221
- return (
222
- <div className={isDark ? 'dark-theme' : ''}>
223
- <button onClick={() => setIsDark(!isDark)}>Toggle Theme</button>
224
- </div>
225
- );
226
- }
227
- ```
228
-
229
- ```css
230
- /* theme-overrides.css */
231
- .dark-theme {
232
- --ig-surface-h: 0deg;
233
- --ig-surface-s: 0%;
234
- --ig-surface-l: 7%;
235
-
236
- --ig-gray-h: 0deg;
237
- --ig-gray-s: 0%;
238
- --ig-gray-l: 100%;
239
- }
240
- ```
241
-
242
- ### Approach 2: CSS media query
243
-
244
- ```css
245
- @media (prefers-color-scheme: dark) {
246
- :root {
247
- --ig-surface-h: 0deg;
248
- --ig-surface-s: 0%;
249
- --ig-surface-l: 7%;
250
- }
251
- }
97
+ import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
252
98
  ```
253
99
 
254
- ### Approach 3: Dynamically swap theme stylesheet
255
-
256
- ```tsx
257
- import { useEffect } from 'react';
258
-
259
- function useTheme(variant: 'light' | 'dark', design = 'bootstrap') {
260
- useEffect(() => {
261
- const link = document.getElementById('igc-theme') as HTMLLinkElement;
262
- if (link) {
263
- link.href = `node_modules/igniteui-webcomponents/themes/${variant}/${design}.css`;
264
- }
265
- }, [variant, design]);
266
- }
267
- ```
100
+ Grid tokens are prefixed per component, e.g. `--ig-grid-header-background`, `--ig-grid-content-background`, `--ig-grid-row-even-background`. Confirm names with `get_component_design_tokens({ component: 'grid' })` rather than guessing.