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,229 +1,100 @@
1
1
  ---
2
2
  name: igniteui-react-generate-from-image-design
3
- description: Implement React application views from design images using Ignite UI for React components. Uses MCP servers (igniteui-cli, igniteui-theming) and tools for component discovery, docs lookup, and theming to choose components, generate theme tokens, and follow React-specific best practices. Triggers when the user provides a design image (screenshot, mockup, wireframe) and wants it built as a working React view with Ignite UI for React. Also triggers when the user asks to "implement this design", "build this UI", "convert this mockup", or "create a page from this image" in an Ignite UI React project.
3
+ description: Build a React view from a design image (screenshot, mockup, wireframe) using Ignite UI for React components and generated theme tokens. Use when the user supplies an image and asks to implement this design, build this UI, convert this mockup, or create a page from this screenshot in an Ignite UI React project.
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # Implementing Ignite UI React Views from Design Images
7
+ # Implementing a React View from a Design Image
8
8
 
9
- ## MANDATORY AGENT PROTOCOL
9
+ React only — pass `platform: 'react'` / `framework: 'react'` to every MCP call.
10
10
 
11
- Before writing any implementation code, you must complete these steps in order:
11
+ ## Order of work
12
12
 
13
- 1. Analyze the image and identify all visible regions and UI patterns.
14
- 2. Read [reference/component-mapping.md](reference/component-mapping.md) and [reference/gotchas.md](reference/gotchas.md).
15
- 3. This skill is React-only. Check package routing, theme CSS imports, or licensing only when imports, packages, or theming depend on it.
16
- 4. To apply a theme, use the theming workflow from this skill and the dedicated `igniteui-react-customize-theme` skill; use the `igniteui-theming` MCP tools instead of styling from memory. This skill is React-only, so hardcode `platform: "react"` in theme-generation calls.
17
- 5. Call `get_doc` for every chosen component family before using it.
18
- 6. Only then start coding.
13
+ 1. **Read the image.** Identify every region, its component, and the layout structure.
14
+ 2. **Inspect the app.** Existing theme imports, design system, palette overrides, installed packages.
15
+ 3. **Look up the components you chose** before writing them — `get_doc`, `get_api_reference`.
16
+ 4. **Theme** — global layer only if the app has none, then per-component tokens.
17
+ 5. **Implement** the layout, mock data, and view.
18
+ 6. **Validate** — build, run, compare with the image, iterate.
19
19
 
20
- ## Workflow
20
+ Steps 3 and 4 use MCP servers where available; both are optional. Without them, read the installed `.d.ts` files (`node_modules/igniteui-webcomponents/components/<name>/`) for props, `@slot`, `@csspart`, and `@cssproperty` names, and theme with the palette shades documented in [igniteui-react-customize-theme](../igniteui-react-customize-theme/SKILL.md).
21
21
 
22
- 1. **Analyze the design image** - Read the image, identify every UI section, component, and layout structure.
23
- 2. **Confirm package routing or theme setup if needed** - this skill is React-only; check package routing, theme CSS imports, or licensing only when imports, packages, or theming depend on it.
24
- 3. **Discover components** - Call `list_components` with targeted filters to find matching components for each UI pattern.
25
- 4. **Look up component docs** - Call `get_doc` for every chosen component family before coding.
26
- 5. **Generate theme** - (a) To generate a theme, first extract colors and create a color palette using `create_palette` or `create_custom_palette` depending on the scenario. Then extract elevations and call `create_elevations`. Then extract typography and call `create_typography`. Then call `create_theme` with the palette, elevations, and typography. (b) After a theme exists, prefer design tokens, or scoped semantic CSS variables over raw literals. (c) For every Ignite UI component, call `get_component_design_tokens`, map extracted image tokens to token roles, then call `create_component_theme` with the tokens differing from the global theme for the specific component.
27
- 6. **Implement** - Build the screenshot-first layout, data, and view components.
28
- 7. **Refine** - Use the `set_size`, `set_spacing`, and `set_roundness` tools to refine the view's visual fidelity against the image, then iterate on implementation and theming until the view matches the design closely.
29
- 8. **Validate** - Build, test, run, compare against the image, and fix differences.
22
+ ## 1. Read the image
30
23
 
31
- ## Step 1: Analyze the Design Image
24
+ Record, per region: layout role and proportions, component type, colors, type scale, borders/radius/shadow, data shape, and spacing rhythm.
32
25
 
33
- Read the input image carefully. For each visual section, identify:
26
+ Resolve layout as CSS Grid rows and columns that preserve the observed *proportions* — do not reverse-engineer exact pixel values or invent breakpoints yet. Get desktop proportions right first, then add stacking rules.
34
27
 
35
- - **Layout structure**: grid rows/columns, sidebar, navbar, content area proportions, and estimated fixed widths or percentages for major regions.
36
- > Note: Do not guess the exact CSS properties at this stage; just identify the high-level structure and relative proportions. Do not try to fit the view into exact breakpoints or pixel values. Try to generate a flexible layout that preserves the observed proportions and can adapt to different screen sizes. You will refine the exact CSS rules in Step 8 after building a first version of the view.
37
- - **Component type**: chart, list, card, map, gauge, table, form, etc.
38
- - **Color palette**: primary, secondary, surface/background, accent, text colors
39
- - **Typography**: font sizes, weights, letter-spacing patterns
40
- - **Surface styling**: borders, border-radius, shadows, elevation, divider treatments
41
- - **Data patterns**: what mock data is needed (time series, lists, KPIs, geographic)
42
- - **Spacing system**: translate observed padding and gaps into a small reusable scale derived from the design
28
+ Before coding, state briefly: chosen component per region, any region falling back to plain HTML and why, theme strategy, packages needed, and assumptions you made where the image is ambiguous.
43
29
 
44
- Before writing code, create a decomposition table with one row per visible region containing:
30
+ **Start every region from an Ignite UI component.** Fall back to semantic HTML only when the component's DOM structure stays incompatible after CSS overrides and `::part()` are considered, and say so in a comment. Component picks live in [COMPONENTS.md](../igniteui-react-components/reference/COMPONENTS.md); use `list_components({ framework: 'react', filter: '<narrow term>' })` to discover more. Narrow filters work better — `'list view'`, not `'list'`.
45
31
 
46
- | Region | Visual role | Candidate component | Custom CSS required | Data type |
47
- |---|---|---|---|---|
48
- | Example: sidebar item list | repeated rows with icon + label | `IgrList` | yes - item height, icon size | domain-appropriate mock data |
49
- | Example: top bar | brand + tabs + search | `IgrNavbar` | yes - multi-zone flex layout | n/a |
50
- | Example: side panel | always-visible navigation | `IgrNavDrawer` | yes - width, item styling | n/a |
32
+ Judgement calls that recur:
51
33
 
52
- Start every region with the most appropriate Ignite UI component from [reference/component-mapping.md](reference/component-mapping.md). Only fall back to plain semantic HTML when the component DOM structure is fundamentally incompatible with the design after CSS overrides are considered. Document the reason for any plain-HTML fallback in a code comment.
34
+ - `IgrNavbar` for a top bar; plain `<header>` if the design's zones fight the slot structure.
35
+ - `IgrNavDrawer` for a sidebar — set open/mini to match fixed, collapsible, or icon-only navigation; plain `<aside>` for a purely static rail.
36
+ - `IgrGridLite` or `IgrGrid` **only** when the region is genuinely tabular. Repeated cards or rows with mixed content are `IgrList` or custom markup.
37
+ - `IgrChip` for tags and status pills when the chip anatomy matches; otherwise simple custom markup.
38
+ - `IgrFinancialChart` for OHLC; `IgrCategoryChart` for ordinary trends; `IgrDataChart` only when you need per-series or per-axis control.
53
39
 
54
- Before writing code, produce a compact implementation brief that captures:
40
+ ## 2. Inspect the app first
55
41
 
56
- - chosen components per region
57
- - fallback HTML regions
58
- - theme strategy
59
- - package needs
60
- - major assumptions
42
+ Check `main.tsx`, `index.tsx`, `App.tsx`, `app/layout.tsx`, and shared CSS for theme CSS imports, grid theme imports, and existing palette or semantic-variable overrides. A bare stock theme import is required baseline setup — not evidence of a customized design system.
61
43
 
62
- After the table, translate the image into CSS Grid rows and columns first. Preserve desktop proportions before adding responsive behavior, then define explicit breakpoint stacking rules for smaller screens.
44
+ - **Customized theme already present** → do not generate a global theme or palette unless the user explicitly wants one. Reuse the existing design system, variant, and tokens; go straight to per-component overrides.
45
+ - **Stock theme import only** → keep it and add the minimal override layer.
46
+ - **No theme import** → add one first (see [igniteui-react-components](../igniteui-react-components/SKILL.md)).
63
47
 
64
- ## Step 2-3: Use MCP Tools for Discovery
48
+ ## 3. Packages
65
49
 
66
- This skill is React-only. Check package routing, theme CSS imports, or licensing only when imports, packages, or theming depend on it.
50
+ Core components ship in `igniteui-react`. Grid Lite additionally needs `igniteui-grid-lite`; advanced grids, charts, maps, and gauges are separate packages that may be scoped `@infragistics/…` in licensed workspaces. Resolve versions against the installed Ignite UI version, install only what the selected components require, and **ask before modifying dependencies**. Charts, gauges, and maps need `.register()`; nothing else does.
67
51
 
68
- Then call `list_components('react')` and relevant filters to find components matching each UI pattern. Common filters:
52
+ ## 4. Theme
69
53
 
70
- - `chart`, `sparkline` - for data visualization
71
- - `list view`, `card`, `avatar`, `badge` - for data display
72
- - `nav`, `navbar`, `drawer` - for navigation
73
- - `progress`, `gauge` - for metrics
74
- - `map` - for geographic displays
75
- - `grid`, `grid lite` - for tabular data
54
+ ### Global layer (only when the app has no customized theme)
76
55
 
77
- Use narrow search terms to reduce noisy MCP results. Search for the specific UI pattern you need, such as `list view` instead of `list`.
78
-
79
- For component-to-Ignite-UI mapping, see [reference/component-mapping.md](reference/component-mapping.md).
80
-
81
- ## Step 4: Look Up Component API
82
-
83
- For every chosen component category, call `get_doc('react', '<name>')` using the doc `name` field from `list_components` results (e.g., `get_doc('react', 'card')`), not the result title shown in the list. This is mandatory before coding and gives exact React usage patterns, prop names, slot structure, event signatures, and any required module registration.
84
-
85
- Call `search_docs` for feature-based questions (e.g., "how to configure [component] for [specific behavior or styling need]").
86
-
87
- ## Step 5: Generate Theme with MCP
88
-
89
- Use this skill for the image-to-view theming workflow only. The dedicated [`igniteui-react-customize-theme`](../igniteui-react-customize-theme/SKILL.md) skill remains the source of truth for palette-token behavior, global theme rules, and broader theming-system guidance.
90
-
91
- ### 5a - Existing app guard (always run first)
92
-
93
- Before generating any theme code, inspect the app entry points and shared global styles. Typical files include `main.tsx`, `index.tsx`, `App.tsx`, `app/layout.tsx`, `src/index.css`, and other shared CSS files. Look for:
94
-
95
- - existing theme CSS imports such as `igniteui-webcomponents/themes/...`
96
- - grid theme imports such as `igniteui-react-grids/grids/themes/...`
97
- - existing palette-token overrides or semantic CSS variables already used by the app
98
-
99
- Treat a plain stock theme CSS import as required baseline setup, not as evidence of an already customized design system.
100
-
101
- - **Existing customized theme found** -> the app already has meaningful palette or token overrides. Do **not** call `create_theme` or `create_palette` unless the user explicitly wants a global theme change. Instead:
102
- 1. Inspect the existing theme definition and any exposed palette tokens or semantic CSS variables
103
- 2. Reuse the current design system, variant, and palette tokens wherever they already match the design image
104
- 3. Skip to **5c** and apply only minimal scoped overrides for the new view's components
105
- - **Only stock theme CSS import found** -> keep the import in place and proceed with **5b** to generate the minimal override layer needed for the design
106
- - **No theme import found** -> add the required theme CSS import first, then proceed with **5b**
107
-
108
- ### 5b - Global theme generation (new projects)
109
-
110
- Follow this order - MCP guidance first, image extraction second:
111
-
112
- 1. **Read MCP guidance first** - call `theming://guidance/colors/rules` (or `get_theming_guidance`) before looking at the image. This tells you the available theme inputs and any luminance or variant constraints.
113
- 2. **Resolve the design system** - infer it from the existing workspace, explicit user request, or the closest visual match in the design. Do not assume one if a stronger signal exists.
114
- 3. **Extract from the image** - now that you know the available slots, extract values only for the inputs you actually need.
115
- 4. **Call `create_theme` or `create_palette`** with the extracted seed values.
56
+ Read `read_resource({ uri: 'theming://guidance/colors/rules' })` *before* extracting colors, so you know the available slots and the luminance constraints. Resolve the design system from the workspace, the user's request, or the closest visual match — in that order. Then extract only the values you need and generate:
116
57
 
117
58
  ```
118
59
  create_theme({
119
- primaryColor: "<color extracted from image for primary slot>",
120
- secondaryColor: "<color extracted from image for secondary slot>",
121
- surfaceColor: "<color extracted from image for surface/background slot>",
122
- variant: "<resolved theme variant>",
123
- platform: "react",
124
- fontFamily: "<font extracted from image or existing app>",
125
- designSystem: "<resolved design system>"
60
+ primaryColor: '<from image>',
61
+ secondaryColor: '<from image>',
62
+ surfaceColor: '<from image>',
63
+ variant: 'light' | 'dark',
64
+ designSystem: '<resolved>',
65
+ fontFamily: '<from image or app>',
66
+ platform: 'react'
126
67
  })
127
68
  ```
128
69
 
129
- Read and act on any luminance warnings returned. If the design needs multiple surface depths that a single generated surface color does not cover, use `create_custom_palette` or define semantic CSS variables for the additional depths in the app's global stylesheet.
130
-
131
- Use `create_palette` for straightforward designs with a small, coherent color system. Use `create_custom_palette` when the design has multiple distinct surface depths, several accent families, or when the generated palette cannot reliably match the screenshot.
132
-
133
- ### 5c - Per-component token discovery and mapping (always run)
134
-
135
- > **Scope:** this step applies only to **core Ignite UI React components** (grid, grid lite, list, navbar, nav drawer, card, inputs, chips, avatar, etc.). DV components - charts, maps, gauges, and sparklines - do not use the component-token theme generation flow in this skill. Skip this step for them and set their visual properties exclusively via component props as described in [reference/gotchas.md](reference/gotchas.md) and in Step 7.
136
-
137
- For **every** core Ignite UI component chosen in Steps 3-4, follow this MCP-first loop - query MCP before touching the image:
138
-
139
- 1. **Discover (MCP first)** - call `get_component_design_tokens(component)` before looking at the image for that component. Read the full token list with names, types, and descriptions. Identify which tokens correspond to visible surfaces, text, borders, icons, and interaction states.
140
- 2. **Extract (image second)** - now that you know the exact token names, go to the image region for that component and read the exact token value for each relevant token slot. Do not guess; zoom into the component region.
141
- 3. **Generate** - call `create_component_theme(component, platform, licensed, tokens)` passing only the tokens whose resolved value differs from the global theme. This produces scoped CSS or SCSS with the minimal override set.
142
-
143
- **Example - theming a grid:**
144
- - `get_component_design_tokens("grid")` returns `header-background`, `content-background`, `row-hover-background` among many others
145
- - Look at the grid region in the image -> extract the color intent for header, row background, and hover state
146
- - Resolve each value to a palette token or local semantic CSS variable
147
- - Call `create_component_theme("grid", ...)` with only `{ "header-background": "<resolved token>", "content-background": "<resolved token>", "row-hover-background": "<resolved token>" }`
148
-
149
- Apply the generated theme blocks in CSS using a scoped wrapper and the underlying web component selectors shown in the MCP output. In selectors, use the rendered `igc-*` tags or `::part()` hooks where applicable.
150
-
151
- Do not run `create_component_theme` for regions built with custom HTML/CSS only.
152
-
153
- ### 5d - Theming sequence summary
154
-
155
- Apply in this exact order:
156
-
157
- 1. Inspect the entry point and shared styles -> customized theme, stock theme only, or missing import?
158
- 2. Create or update the global theme layer: add the required theme CSS import if missing, then `create_theme` or `create_palette` as needed (Step 5b)
159
- 3. For each Ignite UI component: `get_component_design_tokens` -> map image design tokens -> resolve values to design tokens or semantic CSS variables -> `create_component_theme` (Step 5c)
160
- 4. Use `get_color` after palette generation whenever a palette token can represent the final color intent
161
-
162
- ## Step 6: Install Additional Packages
163
-
164
- Core UI components ship with `igniteui-react`. Grid Lite requires both `igniteui-react` and `igniteui-grid-lite`. Advanced grids, charts, maps, and gauges use separate React package families and may also appear under `@infragistics/igniteui-react-*` in licensed workspaces. These packages are version-sensitive: determine the installed Ignite UI version, resolve the compatible published package version, and install only the package set required by the selected components. See [reference/component-mapping.md](reference/component-mapping.md) for package names and import patterns.
165
-
166
- Theme CSS imports are also required:
167
-
168
- - core components -> `igniteui-webcomponents/themes/<variant>/<design-system>.css`
169
- - grids -> `igniteui-react-grids/grids/themes/<variant>/<design-system>.css`
170
-
171
- If packages are missing, identify the exact packages and versions required first, then ask for approval before installing packages or changing dependency manifests.
172
-
173
- Charts, maps, and gauges also require explicit `*.register()` calls at module level in React files. Grid Lite does **not** require registration.
174
-
175
- ## Step 7: Implement
176
-
177
- ### Structure
178
-
179
- - **Layout**: use Ignite UI layout and data-display components as the starting point for standard regions, then apply CSS Grid/Flexbox and component overrides to match the screenshot. Only substitute plain semantic HTML when an Ignite UI component remains structurally incompatible after a genuine attempt.
180
- - **Data**: use typed mock data that matches the design's density and domain; add models, helpers, or hooks only when they help the implementation.
181
- - **View**: keep layout, spacing, typography, and surface styling in CSS modules or shared CSS rather than inline styles wherever practical.
182
- - **Theming**: apply the resolved design system and theme variant from Step 5, and keep color usage aligned with palette tokens, or local semantic CSS variables.
183
-
184
- ### Implementation Checks
70
+ Act on any luminance warning returned. Use `create_palette` for a small coherent color system, `create_custom_palette` when the design has several distinct surface depths or accent families that one generated surface cannot express.
185
71
 
186
- - Follow the surrounding repo conventions and the existing React skills in this repo, especially [`igniteui-react-components`](../igniteui-react-components/SKILL.md) and [`igniteui-react-customize-theme`](../igniteui-react-customize-theme/SKILL.md)
187
- - Use [reference/component-mapping.md](reference/component-mapping.md) for component-choice and semantic-fallback rules
188
- - Use [reference/gotchas.md](reference/gotchas.md) for components, theming, and API edge cases instead of re-encoding those rules inline
189
- - Favor Ignite UI components over custom HTML when both approaches can reach similar visual fidelity
190
- - Ensure the required theme CSS imports are present before component usage
191
- - Preserve spacing, hierarchy, and data density before adding extra interactivity
192
- - Avoid generic placeholders when the image shows domain-specific content
193
- - Document brief assumptions when the image is ambiguous instead of silently guessing
72
+ ### Per-component tokens (always)
194
73
 
195
- ## Step 8: Refine
74
+ For each **core** Ignite UI component in the design, in this order:
196
75
 
197
- After the first implementation pass, use the `set_size`, `set_spacing`, and `set_roundness` tools to adjust the view's visual properties and close the gap with the image. Focus on the most visually distinctive elements first (e.g., panel proportions, chart shape, button prominence) before tuning smaller details (e.g., row heights, spacing between regions).
76
+ 1. `get_component_design_tokens({ component })` — read the real token names first.
77
+ 2. Now look at that region in the image and read a value for each relevant token.
78
+ 3. `create_component_theme({ component, tokens, selector, platform: 'react' })` with **only** the tokens whose value differs from the global theme.
198
79
 
199
- ## Step 9: Validate
80
+ Querying tokens before reading the image matters: it stops you inventing token names, which is the most common failure here. Apply the generated block with a scoped wrapper plus `igc-*` selectors or `::part()`.
200
81
 
201
- Use this validation loop explicitly:
82
+ Charts, maps, gauges, and sparklines are **excluded** — they are not `igc-*` elements and have no design tokens. Style them through props (see [gotchas.md](reference/gotchas.md)). Skip regions built from custom HTML too.
202
83
 
203
- 1. Build
204
- 2. Test
205
- 3. Run the app
206
- 4. Visually compare against the image
207
- 5. Adjust and repeat
84
+ Once a palette exists, resolve colors to palette tokens (`var(--ig-primary-500)`) or your own semantic variables rather than leaving hex literals in JSX and CSS. `get_color` resolves a palette token to a concrete value when you need one.
208
85
 
209
- In terminal-only environments, the user performs the visual comparison and provides feedback on any mismatches. Only perform the visual check directly when the environment has browser and screenshot capabilities available to the agent.
86
+ ## 5. Implement
210
87
 
211
- Use this checklist during the first visual comparison:
88
+ - **Layout** — Ignite UI components for standard regions, CSS Grid/Flexbox plus overrides for the composition.
89
+ - **Styles** — CSS Modules or shared CSS, not inline styles.
90
+ - **Data** — typed mock data matching the design's domain and density. Domain-appropriate content, never `Lorem ipsum` or `Item 1` when the image shows real subject matter.
91
+ - Preserve spacing, hierarchy, and data density before adding interactivity.
92
+ - Read [gotchas.md](reference/gotchas.md) before writing charts, maps, avatars, grids, or dark surfaces — it lists the props that do not exist and the ones that must be arrays or function references.
212
93
 
213
- - panel proportions
214
- - control density
215
- - chart shape
216
- - legend placement
217
- - button prominence
218
- - row heights
219
- - spacing between regions
94
+ ## 6. Validate
220
95
 
221
- Fix TypeScript, JSX, styling, or runtime errors immediately during the build/test steps. Use the build output, component docs, [reference/gotchas.md](reference/gotchas.md), and the user's visual feedback to close the remaining gaps. Typical adjustments include:
96
+ Build → test → run → compare against the image → fix. Fix TypeScript and runtime errors as they appear rather than at the end.
222
97
 
223
- - revisiting chart data density, smoothing, marker visibility, or missing module registration
224
- - adjusting layout ratios, region spacing, or row heights
225
- - correcting navigation mode, panel chrome, or component choice
226
- - tuning map/filter treatment and dark-surface hierarchy
227
- - re-examining the original design for overlooked sections, missing theme imports, or missing packages
98
+ Compare in this order, coarse to fine: panel proportions, control density, chart shape, legend placement, button prominence, row heights, inter-region spacing. Use `set_size`, `set_spacing`, and `set_roundness` to close density and roundness gaps instead of hand-writing padding.
228
99
 
229
- After the build succeeds with zero errors, refine layout proportions, color values, missing sections, and typography until the view matches closely.
100
+ Only perform the visual check yourself if you can screenshot the running app; otherwise ask the user to compare and report mismatches. Recurring causes of a mismatch: missing chart module registration, chart data too sparse to read as continuous, markers visible when the design has none, a chart collapsed in a flexible grid track, wrong nav drawer mode, a missing theme import, or a section of the image overlooked entirely.
@@ -1,204 +1,105 @@
1
- # Ignite UI React Gotchas & Pitfalls
1
+ # Gotchas When Matching a Design
2
2
 
3
- ## Table of Contents
4
- - [React Wrappers & CSS Selectors](#react-wrappers--css-selectors)
5
- - [Chart Properties](#chart-properties)
6
- - [Component Properties](#component-properties)
7
- - [Theming Pitfalls](#theming-pitfalls)
8
- - [Map Component](#map-component)
9
- - [Dark Theme Specifics](#dark-theme-specifics)
3
+ Props and CSS names that do not exist, or that behave unlike their obvious form. Verified against current packages.
10
4
 
11
- ## React Wrappers & CSS Selectors
5
+ ## Props that do not exist
12
6
 
13
- ### Use JSX props and children
14
- Pass dynamic values as JSX expressions and use children with `slot` attributes for named regions:
7
+ | Written | Reality |
8
+ |---|---|
9
+ | `plotAreaBackground` on `IgrCategoryChart` | Not a prop. Style the container's background in CSS. |
10
+ | `areaFillOpacity` on `IgrSparkline` | Exists on `IgrCategoryChart` / `IgrDataChart` only. |
11
+ | `roundShape` on `IgrAvatar` | Use `shape` alone. |
12
+ | `--ig-button-foreground` | Button exposes only `--ig-button-font-*`. Use `::part()` or the tokens `get_component_design_tokens({ component: 'button' })` returns. |
13
+ | `--ig-primary-h` / `-s` / `-l` | No such tokens. Override the shade: `--ig-primary-500`. |
15
14
 
16
- ```tsx
17
- <IgrCard>
18
- <IgrCardHeader>
19
- <h3 slot="title">{'<resolved-card-title>'}</h3>
20
- <p slot="subtitle">{'<resolved-card-subtitle>'}</p>
21
- </IgrCardHeader>
22
- <IgrCardContent>{'<resolved-card-content>'}</IgrCardContent>
23
- </IgrCard>
24
- ```
15
+ ## Chart props
25
16
 
26
- ### CSS selectors must target rendered `igc-*` tags
27
- When applying CSS custom properties, `::part()` selectors, or MCP-generated component theme blocks, target the underlying web component selectors:
17
+ **Array props need array expressions**, not comma-joined strings:
28
18
 
29
- ```css
30
- .dashboard-panel igc-card::part(header) {
31
- padding: <resolved-header-padding>;
32
- }
19
+ ```tsx
20
+ <IgrCategoryChart includedProperties={['revenue', 'cost']} />
33
21
  ```
34
22
 
35
- Do not write selectors against React wrapper names.
23
+ **`markerTypes` takes documented marker-type values** (an `IgrMarkerTypeCollection`), not lowercase string arrays. Category charts show a marker at every point by default — if the design shows a bare line or area, you must turn markers off explicitly.
36
24
 
37
- ## Chart Properties
25
+ **Function-valued props take a reference**, not a call: `xAxisFormatLabel={labelFormatter}`.
38
26
 
39
- ### Charts, gauges, and maps require module registration
40
- The React wrappers for charts, gauges, and maps must register their modules once at module level before use:
27
+ **Smooth, continuous area charts** come from data density first: add points until the shape reads continuous at the rendered size, hide markers, then tune fill opacity and label density. Apply smoothing only if the design itself looks smoothed rather than point-to-point.
41
28
 
42
- ```tsx
43
- import { IgrCategoryChartModule } from 'igniteui-react-charts';
29
+ **Charts collapse inside a flexible CSS Grid track.** Set `min-height: 0` on the cell and make the chart fill it:
44
30
 
45
- IgrCategoryChartModule.register();
46
- ```
47
-
48
- `IgrGridLite` does **not** require registration.
49
-
50
- ### Markers shown by default
51
- Category charts show markers at every data point by default. If the screenshot does not show markers, set `markerTypes` to the matching no-marker option documented for the component:
52
- ```tsx
53
- <IgrCategoryChart markerTypes="<resolved-marker-types>" />
31
+ ```css
32
+ .chart-panel { min-height: 0; }
33
+ .chart-panel > * { width: 100%; height: 100%; }
54
34
  ```
55
35
 
56
- `markerTypes` must use the documented marker type values for the chosen chart. Do not pass an array of lowercase strings.
36
+ Charts, gauges, and maps also need `.register()` at module scope. Grid Lite and the `igc-*`-based components do not.
57
37
 
58
- ### `plotAreaBackground` does NOT exist on `IgrCategoryChart`
59
- Use CSS to style the chart container background instead.
38
+ ## Styling DV components
60
39
 
61
- ### `areaFillOpacity` exists on `IgrCategoryChart`
62
- It does NOT exist on the sparkline component.
40
+ Charts, maps, gauges, and sparklines are not `igc-*` elements — they have **no design tokens and no `::part()`**. Set their appearance through props, resolving values to palette tokens or semantic variables rather than raw hex:
63
41
 
64
- ### `includedProperties` must be an array prop
65
- Use a JSX array expression, not a plain string:
66
42
  ```tsx
67
- <IgrCategoryChart includedProperties={['fieldOne', 'fieldTwo', 'fieldThree']} />
43
+ <IgrCategoryChart
44
+ brushes={seriesBrushes}
45
+ outlines={seriesOutlines}
46
+ xAxisLabelTextColor="var(--ig-gray-600)"
47
+ yAxisMajorStroke="var(--ig-gray-200)"
48
+ />
68
49
  ```
69
- Replace `'fieldOne'`, `'fieldTwo'`, etc. with the actual data property names from your mock data.
70
50
 
71
- ### Chart callback props must receive function references
72
- Function-valued chart props must receive a function reference:
73
- ```tsx
74
- <IgrCategoryChart xAxisFormatLabel={labelFormatter} />
75
- ```
51
+ ## Component specifics
76
52
 
77
- ### Smooth area charts
78
- For smooth-looking area charts where the data should appear continuous rather than spiky:
79
- - Increase data density until the line or area reads as continuous at the rendered size
80
- - Apply smoothing only when the source shape in the design looks smoothed rather than point-to-point
81
- - Hide markers unless the screenshot clearly shows visible data points
82
- - Tune fill opacity and label density to match the screenshot instead of relying on a fixed default
53
+ **CSS targets the rendered element.** `igc-card::part(header)`, never `IgrCard`.
83
54
 
84
- ### Charts inside CSS Grid can collapse
85
- In a flexible CSS Grid track, set `min-height: 0` on the grid cell and make the chart fill its container:
86
- ```css
87
- .chart-panel {
88
- min-height: 0;
89
- }
55
+ **Nav drawer width** comes from two custom properties, both measurable from the image:
90
56
 
91
- .chart-panel > * {
92
- height: <resolved-chart-height>;
93
- width: <resolved-chart-width>;
57
+ ```css
58
+ igc-nav-drawer {
59
+ --menu-full-width: 15rem;
60
+ --menu-mini-width: 5.5rem;
94
61
  }
95
62
  ```
96
63
 
97
- ## Component Properties
98
-
99
- ### `roundShape` does NOT exist on `IgrAvatar`
100
- Use the supported `shape` input alone. Do not add `roundShape`.
101
-
102
- ### Omit column `width` — both grid types are fluid by default
103
-
104
- Do not add `width` to `IgrGridLiteColumn` or `IgrColumn` — columns are responsive by default. Fixed pixel widths leave empty space on the right side of the grid. Only set `width` if the user explicitly asks for it. If some columns need explicit widths, leave at least one column without a `width` to fill the remaining space.
64
+ **Avatar background** is a custom property, so set it on a wrapper for per-instance colors:
105
65
 
106
- ### Tabs used for navigation should be label-only
107
- When a screenshot shows tabs that drive routed page content, use label-only `IgrTab` items and keep the routed content outside the `IgrTabs` component. Do not place inline tab panel content inside router-driven tabs.
108
-
109
- ### Avatar background color via CSS variable
110
66
  ```tsx
111
67
  <div style={{ '--ig-avatar-background': color } as React.CSSProperties}>
112
- <IgrAvatar />
68
+ <IgrAvatar initials="KD" />
113
69
  </div>
114
70
  ```
115
71
 
116
- ## Theming Pitfalls
72
+ **Grid columns are fluid — do not add `width`.** Both `IgrGridLiteColumn` and `IgrColumn` size themselves; fixed widths leave dead space right of the last column. If some column truly needs a fixed width, leave at least one without one.
117
73
 
118
- ### Theme CSS imports are required
119
- Core components need a base theme import, and grids need an additional grid theme import:
74
+ **Router-driven tabs are label-only.** Inline content inside a routed `IgrTab` renders in addition to the routed view and pushes it off screen. Keep the outlet outside `IgrTabs`.
120
75
 
121
- ```tsx
122
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
123
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
124
- ```
76
+ ## Theming
125
77
 
126
- Do not remove or replace those imports unless the user explicitly wants a theme variant change.
78
+ **Theme CSS imports are required** — the base theme for core components, plus the grid theme for grids. Do not remove or swap them unless the user wants a variant change.
127
79
 
128
- ### DV components require explicit visual props
129
- Charts, maps, gauges, and sparklines do not use the component-token theme generation flow from this skill. Set their visual properties explicitly via component props. After a palette exists, prefer palette tokens or local semantic CSS variables over leaving raw color literals in the final JSX:
130
- ```tsx
131
- <IgrCategoryChart
132
- brushes="<resolved-series-brush>"
133
- outlines="<resolved-series-outline>"
134
- xAxisLabelTextColor="<resolved-axis-label-color>"
135
- yAxisMajorStroke="<resolved-grid-line-color>"
136
- />
137
- ```
138
-
139
- ### Component theme functions
140
- For core UI component theming, prefer `create_component_theme` and apply the returned theme block as generated by the MCP server.
80
+ **Dark mode is global.** Components read `--ig-theme-variant` once from `:root`, so a dark wrapper class cannot make Ignite UI components dark. For one dark panel in a light app, define your own `--surface-1` / `--surface-2` semantic variables and style your own markup; do not swap the app's theme import. To switch the whole app at runtime, call `configureTheme(design, variant)` from `igniteui-react` in addition to swapping the stylesheet.
141
81
 
142
- ### Nav drawer width
143
- Override the drawer width using the nav drawer CSS custom properties measured from the design image:
144
- ```css
145
- igc-nav-drawer {
146
- --menu-full-width: <extracted-sidebar-width>;
147
- --menu-mini-width: <extracted-mini-drawer-width>;
148
- }
149
- ```
82
+ **Multiple dark surface depths** rarely come from one generated surface color. Define the depths you need as semantic variables in shared CSS, and read any luminance warning `create_theme` returns instead of ignoring it.
150
83
 
151
- ### Read luminance warnings from theme generation
152
- If `create_theme` returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use `create_custom_palette` or define semantic CSS variables such as `--surface-1` and `--surface-2` in a shared CSS file instead of relying on a single generated surface color.
84
+ ## Maps
153
85
 
154
- ## Map Component
86
+ Series often have to be added programmatically once the ref exists:
155
87
 
156
- ### Adding markers programmatically
157
- The geographic map often requires programmatic series setup once the map ref is available:
158
88
  ```tsx
159
- const mapRef = useRef<IgrGeographicMap>(null);
160
-
161
89
  useEffect(() => {
162
90
  const map = mapRef.current;
163
91
  if (!map) return;
164
-
165
- const symbolSeries = new IgrGeographicSymbolSeries();
166
- symbolSeries.dataSource = locations;
167
- symbolSeries.latitudeMemberPath = '<latitude-field>';
168
- symbolSeries.longitudeMemberPath = '<longitude-field>';
169
- symbolSeries.markerType = <resolvedMarkerType>;
170
- symbolSeries.markerBrush = '<resolved-accent-color>';
171
- symbolSeries.markerOutline = '<resolved-accent-color>';
172
- map.series.add(symbolSeries);
173
- map.zoomToGeographic({ left: <min-longitude>, top: <top-latitude>, width: <longitude-span>, height: <latitude-span> });
92
+ const series = new IgrGeographicSymbolSeries();
93
+ series.dataSource = locations;
94
+ series.latitudeMemberPath = 'lat';
95
+ series.longitudeMemberPath = 'lon';
96
+ map.series.add(series);
97
+ map.zoomToGeographic({ left, top, width, height });
174
98
  }, []);
175
99
  ```
176
100
 
177
- ### Dark map styling
178
- OpenStreetMap tiles are light by default. For dark themes, apply a CSS filter to the container. Adjust the values to match the map tone in the design image:
179
- ```css
180
- .map-container {
181
- /* tune grayscale (0-1) and brightness (0-1) to match the design */
182
- filter: grayscale(<0-1>) brightness(<0-1>);
183
- }
184
- ```
185
-
186
- ## Dark Theme Specifics
187
-
188
- ### CSS custom properties for dark panels
189
- When the design uses multiple dark surface depths (panels, sidebars, cards on a dark background), define reusable semantic tokens using palette references or values derived from the design intent:
101
+ OpenStreetMap tiles are light. For a dark design, filter the container and tune the values to match the image's map tone:
190
102
 
191
103
  ```css
192
- :root {
193
- --surface-primary: <resolved-surface-token>;
194
- --surface-secondary: <resolved-surface-token>;
195
- --accent-strong: <resolved-accent-token>;
196
- --text-primary: <resolved-text-token>;
197
- --text-secondary: <resolved-text-token>;
198
- }
104
+ .map-container { filter: grayscale(0.9) brightness(0.6); }
199
105
  ```
200
-
201
- If `create_theme` returns a single surface color that doesn't cover all depth levels visible in the design, define additional surface tokens (`--surface-1`, `--surface-2`, etc.) for each distinct depth.
202
-
203
- ### Scope dark overrides on a wrapper before reaching for file-wide theme swaps
204
- When only one view or panel should match a dark screenshot, prefer a scoped wrapper class with semantic CSS variables over replacing the app's global theme import.