igniteui-cli 15.5.1 → 15.6.1
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.
- package/package.json +4 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/AGENTS.md +6 -3
- package/templates/blazor/igb/projects/ai-config/files/skills/README.md +30 -45
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/SKILL.md +48 -96
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/charts.md +61 -238
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/data-display.md +60 -193
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/feedback.md +36 -92
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +66 -224
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout-manager.md +39 -88
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md +75 -152
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +40 -149
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md +58 -243
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +89 -280
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +143 -431
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/SKILL.md +91 -157
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/data-operations.md +50 -228
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +61 -222
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/features.md +67 -360
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/grid-migration.md +55 -236
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md +53 -202
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md +31 -232
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/state.md +27 -119
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/structure.md +88 -363
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/types.md +87 -415
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/SKILL.md +8 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +42 -6
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/SKILL.md +83 -211
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/common-patterns.md +93 -184
- package/templates/react/igr-ts/avatar/default/files/src/app/__path__/__filePrefix__.tsx +3 -3
- package/templates/react/igr-ts/avatar/default/files/src/app/__path__/style.module.css +9 -0
- package/templates/react/igr-ts/button/default/files/src/app/__path__/__filePrefix__.tsx +1 -1
- package/templates/react/igr-ts/button/default/files/src/app/__path__/style.module.css +3 -0
- package/templates/react/igr-ts/icon/default/files/src/app/__path__/__filePrefix__.tsx +2 -2
- package/templates/react/igr-ts/icon/default/files/src/app/__path__/style.module.css +3 -0
- package/templates/react/igr-ts/icon-button/default/files/src/app/__path__/__filePrefix__.tsx +1 -1
- package/templates/react/igr-ts/icon-button/default/files/src/app/__path__/style.module.css +3 -0
- package/templates/react/igr-ts/pivot-grid/basic/files/src/app/__path__/__filePrefix__.tsx +3 -4
- package/templates/react/igr-ts/projects/_base/files/package.json +1 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
- package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
- package/templates/webcomponents/igc-ts/avatar/default/files/src/app/__path__/__filePrefix__.ts +7 -2
- package/templates/webcomponents/igc-ts/button/default/files/src/app/__path__/__filePrefix__.ts +8 -3
- package/templates/webcomponents/igc-ts/card/default/files/src/app/__path__/__filePrefix__.ts +3 -1
- package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
- package/templates/webcomponents/igc-ts/constants.js +5 -5
- package/templates/webcomponents/igc-ts/date-time-input/default/files/src/app/__path__/__filePrefix__.ts +8 -2
- package/templates/webcomponents/igc-ts/icon/default/files/src/app/__path__/__filePrefix__.ts +7 -3
- package/templates/webcomponents/igc-ts/icon-button/default/files/src/app/__path__/__filePrefix__.ts +8 -2
- package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
- package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/README.md +1 -0
- package/templates/webcomponents/igc-ts/projects/side-nav-auth/files/src/app/authentication/login-bar/login-bar.ts +1 -1
- package/templates/webcomponents/igc-ts/tabs/default/files/src/app/__path__/__filePrefix__.ts +21 -15
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
- /package/templates/webcomponents/igc-ts/tabs/default/files/src/app/__path__/{__filePrefix__.test → __filePrefix__.test.ts} +0 -0
|
@@ -1,184 +1,132 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: igniteui-react-customize-theme
|
|
3
|
-
description:
|
|
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
|
|
7
|
+
# Ignite UI for React — Theming
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## How the palette actually works
|
|
10
10
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
38
|
+
## Global layout knobs
|
|
89
39
|
|
|
90
40
|
```css
|
|
91
|
-
/* src/index.css */
|
|
92
41
|
:root {
|
|
93
|
-
--ig-
|
|
94
|
-
--ig-
|
|
95
|
-
--ig-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
+
igc-input::part(input) { font-size: 1.1rem; } /* ::part() reaches shadow DOM internals */
|
|
61
|
+
```
|
|
110
62
|
|
|
111
|
-
-
|
|
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
|
-
|
|
65
|
+
## Scoping
|
|
119
66
|
|
|
120
|
-
|
|
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
|
-
##
|
|
73
|
+
## Dark mode
|
|
126
74
|
|
|
127
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
132
|
-
|
|
133
|
-
|
|
80
|
+
```tsx
|
|
81
|
+
import { configureTheme } from 'igniteui-react';
|
|
82
|
+
|
|
83
|
+
configureTheme('bootstrap', 'dark'); // design system, variant
|
|
134
84
|
```
|
|
135
85
|
|
|
136
|
-
|
|
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
|
-
|
|
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
|
-
|
|
141
|
-
igc-button { --ig-button-foreground: var(--ig-secondary-500); }
|
|
142
|
-
```
|
|
90
|
+
## Using the `igniteui-theming` MCP server
|
|
143
91
|
|
|
144
|
-
|
|
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
|
-
|
|
147
|
-
|
|
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
|
-
|
|
107
|
+
All tools take named arguments. There is no `get_theming_guidance` tool — guidance is read through `read_resource`.
|
|
151
108
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
126
|
+
## Reference
|
|
161
127
|
|
|
162
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
5
|
+
## Scoping overrides
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
/*
|
|
64
|
-
:
|
|
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
|
-
/*
|
|
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
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
<IgrButton>Save</IgrButton>
|
|
130
|
-
</div>
|
|
131
|
-
);
|
|
132
|
-
}
|
|
22
|
+
<div className={styles.panel}>
|
|
23
|
+
<IgrButton>Save</IgrButton>
|
|
24
|
+
</div>
|
|
133
25
|
```
|
|
134
26
|
|
|
135
|
-
|
|
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-
|
|
141
|
-
<
|
|
30
|
+
<div style={{ '--ig-primary-500': brandColor } as React.CSSProperties}>
|
|
31
|
+
<IgrAvatar />
|
|
142
32
|
</div>
|
|
143
33
|
```
|
|
144
34
|
|
|
145
|
-
|
|
35
|
+
## Light / dark switching
|
|
146
36
|
|
|
147
|
-
|
|
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
|
-
|
|
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
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
+
```tsx
|
|
49
|
+
import { useEffect, useState } from 'react';
|
|
50
|
+
import { configureTheme, type Theme, type ThemeVariant } from 'igniteui-react';
|
|
171
51
|
|
|
172
|
-
|
|
52
|
+
export function useIgTheme(design: Theme = 'bootstrap') {
|
|
53
|
+
const [variant, setVariant] = useState<ThemeVariant>('light');
|
|
173
54
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
-
|
|
180
|
-
padding: 1rem;
|
|
61
|
+
return [variant, setVariant] as const;
|
|
181
62
|
}
|
|
182
63
|
```
|
|
183
64
|
|
|
184
|
-
|
|
65
|
+
`Theme` is `'bootstrap' | 'material' | 'fluent' | 'indigo'` and `ThemeVariant` is `'light' | 'dark'`; both are re-exported from `igniteui-react`.
|
|
185
66
|
|
|
186
|
-
|
|
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
|
-
|
|
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
|
-
|
|
192
|
-
|
|
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
|
-
|
|
80
|
+
## Component internals
|
|
196
81
|
|
|
197
|
-
|
|
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
|
-
|
|
206
|
-
igc-
|
|
85
|
+
igc-input::part(input) { font-size: 1.1rem; }
|
|
86
|
+
igc-card::part(header) { padding: 1rem; }
|
|
207
87
|
```
|
|
208
88
|
|
|
209
|
-
|
|
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
|
-
|
|
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 '
|
|
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
|
-
|
|
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.
|