refactor(blazor): update layout and navigation documentation for clarity and accuracy

Author: Marina-L-Stoyanova

packages/cli/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md

@@ -23,18 +23,7 @@ This reference gives high-level guidance on layout and navigation components, th
 > **Docs:** [Tabs](https://www.infragistics.com/products/ignite-ui-blazor/blazor/components/layouts/tabs)
 
 ```csharp
-builder.Services.AddIgniteUIBlazor(typeof(IgbTabsModule), typeof(IgbTabModule));
-```
-
-```razor
-<IgbTabs>
-    <IgbTab Panel="home">Home</IgbTab>
-    <IgbTab Panel="search">Search</IgbTab>
-    <IgbTab Panel="favorites" Disabled="true">Favorites</IgbTab>
-    <IgbTabPanel Id="home">Home panel content</IgbTabPanel>
-    <IgbTabPanel Id="search">Search panel content</IgbTabPanel>
-    <IgbTabPanel Id="favorites">Favorites panel content</IgbTabPanel>
-</IgbTabs>
+builder.Services.AddIgniteUIBlazor(typeof(IgbTabsModule));
 ```
 
 For icon tabs, use the `label` slot inside `IgbTab`:
@@ -46,7 +35,7 @@ For icon tabs, use the `label` slot inside `IgbTab`:
 </IgbTab>
 ```
 
-Key attributes on `IgbTabs`: `Alignment` (`TabsAlignment.Start` / `End` / `Center` / `Justify`), `Activation` (`TabsActivation.Auto` / `Manual`). On `IgbTab`: `Panel` (must match `IgbTabPanel.Id`), `Disabled`, `Selected`.
+Key attributes on `IgbTabs`: `Alignment` (`TabsAlignment.Start` / `End` / `Center` / `Justify`), `Activation` (`TabsActivation.Auto` / `Manual`). On `IgbTab`: `Label`, `Disabled`, `Selected`.
 
 Events on `IgbTabs`: `Change` - fires when the selected tab changes.
 
@@ -311,8 +300,7 @@ Events on `IgbTree`: `NodeSelectionChanging` (cancellable), `NodeSelectionChange
 
 ## Key Rules
 
-1. **`IgbTab.Panel` must match `IgbTabPanel.Id`** - mismatched IDs cause the panel to never display.
-2. **Stepper with `Linear="true"` prevents users from skipping steps.** Do not set `Linear` if free navigation is intended.
-3. **Activate/deactivate `IgbNavDrawerItem` programmatically** by setting `item.Active` - there is no automatic selection tracking.
-4. **Register icons via `RegisterIconFromTextAsync` in `OnAfterRenderAsync(bool firstRender)`**, and always call `await component.EnsureReady()` first.
-5. **`IgbAccordion` with `SingleExpand="true"` closes other panels when one is opened.** This is the most common use case for accordions.
+1. **Stepper with `Linear="true"` prevents users from skipping steps.** Do not set `Linear` if free navigation is intended.
+2. **Activate/deactivate `IgbNavDrawerItem` programmatically** by setting `item.Active` - there is no automatic selection tracking.
+3. **Register icons via `RegisterIconFromTextAsync` in `OnAfterRenderAsync(bool firstRender)`**, and always call `await component.EnsureReady()` first.
+4. **`IgbAccordion` with `SingleExpand="true"` closes other panels when one is opened.** This is the most common use case for accordions.

packages/cli/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md

@@ -11,11 +11,12 @@ user-invocable: true
 Before writing any implementation code, you must complete these steps in order:
 
 1. Analyze the image and identify all visible regions and UI patterns.
-2. Read [references/component-mapping.md](references/component-mapping.md) and [references/gotchas.md](references/gotchas.md).
+2. Read [references/component-mapping.md](references/component-mapping.md).
 3. This skill is Blazor-only. Check NuGet package (`IgniteUI.Blazor.Lite`, `IgniteUI.Blazor.GridLite` for general purpose components and light-weight grid, or `IgniteUI.Blazor` / `IgniteUI.Blazor.Trial` for specialized feature-rich grids and charts) only when theming or component availability depends on it.
 4. To apply a theme, use the theming workflow from this skill and the dedicated `igniteui-blazor-theming` skill; use the `igniteui-theming` MCP tools instead of styling from memory.
 5. Call `get_doc` for every chosen component family before using it.
-6. Only then start coding.
+6. **Read [references/gotchas.md](references/gotchas.md) now — after docs, before writing any code.** Read the file in full. Some entries are component-specific; others apply broadly to any chart, any themed component, or any scoped CSS. Apply every entry that is relevant to what you are building. This is a blocking step: do not start implementation until you have read the whole file and checked it against your component list.
+7. Only then start coding.
 
 ---
 
@@ -25,7 +26,7 @@ Before writing any implementation code, you must complete these steps in order:
 2. **Confirm NuGet package if needed** - this skill is Blazor-only; use `IgniteUI.Blazor.Lite`, `IgniteUI.Blazor.GridLite` for general purpose components and the light-weight grid, and `IgniteUI.Blazor` (trial version available publicly as `IgniteUI.Blazor.Trial`) for specialized feature-rich grids and charts.
 3. **Discover components** - Call `list_components` with targeted filters and `framework: "blazor"` to find matching components for each UI pattern.
 4. **Look up component docs** - Call `get_doc` for every chosen component family before coding.
-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 with `platform: "blazor"`. (b) After a palette exists, prefer using 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.
+5. **Generate theme** - (a) Extract colors and call `create_palette` or `create_custom_palette` with `platform: "blazor"` and `output: "css"` — do **not** use `create_theme` for Blazor, it produces Sass requiring compilation. Optionally call `create_elevations` and `create_typography` for elevation and font overrides. (b) After a palette exists, prefer using 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.
 6. **Implement** - Build the screenshot-first layout, data, and view components.
 7. **Refine** - Use the `set_size`, `set_spacing`, `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.
 8. **Validate** - Build, test, run, compare against the image, and fix differences.
@@ -236,7 +237,7 @@ If the required NuGet package is not referenced in the project, identify the cor
 ### Implementation Checks
 
 - Use [references/component-mapping.md](references/component-mapping.md) for component-choice and semantic-fallback rules
-- Use [references/gotchas.md](references/gotchas.md) for components, theming, and API edge cases instead of re-encoding those rules inline
+- When unsure about an API parameter, CSS scoping rule, or component choice, re-check [references/gotchas.md](references/gotchas.md) — do not guess or re-encode its rules inline
 - Favor Ignite UI components over custom HTML when both approaches can reach similar visual fidelity
 - Preserve spacing, hierarchy, and data density before adding extra interactivity
 - Avoid generic placeholders when the image shows domain-specific content

packages/cli/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md

@@ -94,6 +94,27 @@ Brushes="#FF6B6B #4ECDC4 #45B7D1"
 ### `AreaFillOpacity` exists on `IgbCategoryChart`
 It does **NOT** exist on `IgbSparkline`. For sparkline fill, use the `Brush` parameter.
 
+### `IgbSparkline` has no SplineArea type — use `IgbCategoryChart` for smooth area sparklines
+`IgbSparkline` supports only `Line`, `Area`, `Column`, and `WinLoss` display types. `Area` renders as angular polygon fills, not smooth curves. If the design shows smooth mountain-shaped area sparklines, use a small `IgbCategoryChart` with `ChartType="CategoryChartType.SplineArea"`:
+
+```razor
+<!-- ❌ Angular fill — no smooth curves available on IgbSparkline -->
+<IgbSparkline DisplayType="SparklineDisplayType.Area" Brush="#5B57E8" ... />
+
+<!-- ✅ Smooth spline area sparkline -->
+<IgbCategoryChart @ref="splineChart"
+                  ChartType="@CategoryChartType.SplineArea"
+                  Brushes="#5B57E8"
+                  Outlines="#5B57E8"
+                  AreaFillOpacity="0.35"
+                  XAxisLabelTextColor="transparent"
+                  YAxisLabelTextColor="transparent"
+                  Height="70px"
+                  Width="100%"
+                  DataSource="@SparkData" />
+```
+
+
 ### `IncludedProperties` and `ExcludedProperties` are string arrays
 Pass them as bound parameters:
 ```razor
@@ -132,7 +153,38 @@ jobSeries.Brushes = "#CF6E7A #6C74DC #D4A84B";
 ```
 
 ### Smooth area/line charts
-Set `ChartType` to `Spline`, `SplineArea`, or `StepLine` / `StepArea` depending on the visual in the screenshot.
+Match `ChartType` to the curve shape in the screenshot:
+- Smooth flowing curves → `Spline` (lines) or `SplineArea` (filled)
+- Angular/jagged lines → `Line` or `Area`
+- Step-shaped → `StepLine` or `StepArea`
+
+Do not default to `Line` or `Area` when the screenshot shows smooth curves. The difference is immediately visible and is the most common chart fidelity mistake.
+
+### Circular ring with centered percentage — choosing the right component
+- **Thick static ring with a centred label and no needle** → `IgbDoughnutChart` + `IgbRingSeries`. Place `InnerExtent` on the chart, not the series. Overlay the label with `position: absolute` inside a `position: relative` wrapper.
+- **Thin animated spinner / loading progress** → `IgbCircularProgress`. Not a data visualisation.
+- **Needle pointer on a scale arc** → `IgbRadialGauge`.
+
+`IgbRadialGauge` and `IgbCircularProgress` will never produce a clean static ring. Use `IgbDoughnutChart` whenever the design shows a coloured arc ring with a centred value and no needle.
+
+```razor
+<div class="gauge-wrapper">
+    <IgbDoughnutChart InnerExtent="0.62" Height="160px" Width="160px" AllowSliceExplosion="false">
+        <IgbRingSeries ValueMemberPath="Value" LabelMemberPath="Category"
+                       LabelsPosition="@LabelsPosition.None"
+                       DataSource="@GaugeData"
+                       Brushes="#5B57E8 #e8e8f5"
+                       Outlines="transparent transparent"
+                       RadiusFactor="0.95" />
+    </IgbDoughnutChart>
+    <div class="gauge-label">75%</div>
+</div>
+```
+
+```css
+.gauge-wrapper { position: relative; display: inline-flex; align-items: center; justify-content: center; }
+.gauge-label   { position: absolute; font-size: 1.9rem; font-weight: 700; }
+```
 
 ### Charts inside CSS Grid can collapse
 Charts may render with zero height inside a CSS Grid container. Set `min-height: 0` on the grid cell and `Height="100%"` on the chart component so the chart fills its container without requiring a fixed pixel value:
@@ -184,15 +236,6 @@ The component's `::part(base)` is always `position: fixed; transform: translateX
 
 To make the drawer occupy real layout space (pinned sidebar), override the parts in **global CSS**: set explicit width on the host, `position: relative; transform: none` on `::part(base)`, hide `::part(overlay)`, and strip `inert` from `::part(base)` via JS in `OnAfterRenderAsync`. See `layout.md` for the full pattern.
 
-### IgbTabs: Panel and Id pairing
-Each `IgbTab` must reference an `IgbTabPanel` via the `Panel` property matching the panel's `Id`:
-```razor
-<IgbTabs>
-    <IgbTab Panel="panel-1">Tab A</IgbTab>
-    <IgbTabPanel Id="panel-1">Content A</IgbTabPanel>
-</IgbTabs>
-```
-
 ### IgbTileManager: drag and resize modes
 Set `DragMode` and `ResizeMode` for interactive dashboards:
 ```razor