igniteui-webcomponents 7.4.0 → 7.4.1

package/skills/igniteui-wc-figma-to-app/references/figma-component-map.md

@@ -1,39 +1,87 @@
-# Indigo.Design UI Kit → Ignite UI Web Components Map
+# Figma Components → Ignite UI Web Components Map
 
 > **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
 >
-> The **Indigo.Design UI Kits** are Figma component libraries (Material, Fluent, Bootstrap,
-> Indigo variants) that designers use to build their app screens. Every component instance
-> in a design file is drawn from one of these libraries and maps to an Ignite UI Web
-> Components control.
+> Use this file in Phase 2a to resolve every row of the Phase 1g Table A to a tag, component class, package, and `get_doc` name. It has two entry points:
 >
-> Use this file in Phase 2a to map Figma layer names — as they appear in the kit library —
-> to tags, component classes, packages, and `get_doc` names. When a layer name is not in
-> this table, call `list_components` then `get_doc` on the closest match.
+> - **Canonical Role Index** (next section). Use it for **Tier B and Tier C** layers: components from any other UI kit, or un-componentized frames, after they are normalized with [design-provenance.md](design-provenance.md).
+> - **Kit Component Name** tables (the sections after it). Use them for **Tier A** layers from the Infragistics **Indigo.Design UI Kits** (Material, Fluent, Bootstrap, Indigo variants), whose layer names map to Ignite UI directly.
+>
+> When a role or layer name is in neither, call `list_components` then `get_doc` on the closest match.
+
+---
+
+## Canonical Role Index
+
+Normalized roles from `design-provenance.md` → the Ignite UI tag, and the section below that holds its full row (class, package, doc name, key attributes).
+
+| Canonical role (+ normalized props) | Ignite UI Web Components | Section |
+| --- | --- | --- |
+| `button` · high | `<igc-button variant="contained">` | Button Components |
+| `button` · medium (outlined) | `<igc-button variant="outlined">` | Button Components |
+| `button` · medium (tonal / secondary fill) | `<igc-button variant="contained">` + `contained-button` tokens set to the **measured** tonal fill and text colors (usually a light shade such as `var(--ig-primary-100)`). Do not use the plain `secondary` palette: on a `material` baseline it holds the brand color, so tonal buttons would look like high-emphasis ones | Button Components |
+| `button` · low | `<igc-button variant="flat">` | Button Components |
+| `button` · link | `<igc-button variant="flat" href="…">`, or a plain `<a>` styled as a link | Button Components |
+| `button` · elevated | `<igc-button variant="contained">` + elevation via tokens | Button Components |
+| `button` · danger | Same variant + tokens bound to `--ig-error-*` | Button Components |
+| `icon-button` | `<igc-icon-button variant="flat\|outlined\|contained">` | Button Components |
+| `fab` | `<igc-button variant="fab">` | Button Components |
+| `toggle-group` | `<igc-button-group>` + `<igc-toggle-button>` | Button Components |
+| `text-field` · outlined | `<igc-input outlined>` | Form Controls |
+| `text-field` · filled / underlined | `<igc-input>` (close the look with `input-group` tokens) | Form Controls |
+| `textarea` | `<igc-textarea>` | Form Controls |
+| `select` | `<igc-select>` | Form Controls |
+| `combobox` (single, searchable) | `<igc-combo single-select>` | Form Controls |
+| `combobox` (multi / tags) | `<igc-combo>` | Form Controls |
+| `checkbox` / `radio` / `switch` | `<igc-checkbox>` / `<igc-radio-group>`+`<igc-radio>` / `<igc-switch>` | Form Controls |
+| `slider` / `range-slider` | `<igc-slider>` / `<igc-range-slider>` | Form Controls |
+| `rating` | `<igc-rating>` | Form Controls |
+| `file-upload` | `<igc-file-input>` | Form Controls |
+| `color-picker` | `<igc-color-picker>` | Form Controls |
+| `date-picker` / `date-range-picker` / `calendar` | `<igc-date-picker>` / `<igc-date-range-picker>` / `<igc-calendar>` | Date & Time |
+| `time-picker` | `<igc-date-time-input>` with a time format | Date & Time |
+| `app-bar` | `<igc-navbar>` | Navigation |
+| `side-nav` (expanded, always visible) | `<igc-nav-drawer position="relative" open>` | Navigation |
+| navigation rail (icon-only) | `<igc-nav-drawer position="relative">` (**not** `open`) with the rail items in the `mini` slot. The mini rail is hidden while the drawer is open | Navigation |
+| `tabs` | `<igc-tabs>` | Navigation |
+| `breadcrumbs` | `<igc-breadcrumbs>` + `<igc-breadcrumb>` | Navigation |
+| `stepper` | `<igc-stepper>` | Navigation |
+| `menu` | `<igc-dropdown>` | Form Controls |
+| `accordion` / `expansion-panel` | `<igc-accordion>` / `<igc-expansion-panel>` | Layout |
+| `card` | `<igc-card>` (only when header/media/content/actions anatomy fits) | Data Display |
+| `list` | `<igc-list>` | Data Display |
+| `tree` | `<igc-tree>` | Data Display |
+| `data-table` (simple, read-only) | `<igc-grid-lite>` | Grids |
+| `data-table` (editing, grouping, paging, summaries…) | `<igc-grid>` and family | Grids |
+| `avatar` | `<igc-avatar>` | Data Display |
+| `tag` / `count-badge` | `<igc-badge>` | Data Display |
+| `chip` | `<igc-chip>` | Data Display |
+| `progress-linear` / `progress-circular` | `<igc-linear-progress>` / `<igc-circular-progress>` | Data Display |
+| `divider` | `<igc-divider>` | Data Display |
+| `carousel` | `<igc-carousel>` | Data Display |
+| `dialog` | `<igc-dialog>` | Feedback / Overlay |
+| `toast` (text only) / (with action) | `<igc-toast>` / `<igc-snackbar>` | Feedback / Overlay |
+| `inline-alert` | `<igc-banner>` | Feedback / Overlay |
+| `tooltip` | `<igc-tooltip>` | Feedback / Overlay |
+| `qr-code` | `<igc-qr-code>` | Data Display |
+| `chart-*` / `gauge-*` / `map` | See the DV table | Charts, Gauges, and Maps |
+| `bottom-nav`, `sheet`, `skeleton`, `pagination` (standalone) | No direct component | Components With No Web Components Equivalent |
 
 ---
 
-## How to Use This File
+## How to Use the Kit Tables
 
-1. Find the kit component name (as it appears in the Figma layers panel or the
-   Indigo.Design kit library) in the **Kit Component Name** column.
+1. Find the kit component name (as it appears in the Figma layers panel or the Indigo.Design kit library) in the **Kit Component Name** column.
 2. Read the **Tag**, **Class**, and **Package** columns for the markup and imports.
-3. Call `get_doc({ framework: "webcomponents", name: "<doc name>" })` for usage patterns
-   and slots, then `get_api_reference({ platform: "webcomponents", component: "<Class>" })`
-   for the full property/method/event API.
-4. Consult **Key attributes / slots** for the properties most commonly configured from
-   Figma variants. These are starting points, not a substitute for the docs.
+3. Call `get_doc({ framework: "webcomponents", name: "<doc name>" })` for usage patterns and slots, then `get_api_reference({ platform: "webcomponents", component: "<Class>" })` for the full property/method/event API.
+4. Consult **Key attributes / slots** for the properties most commonly configured from Figma variants. These are starting points, not a substitute for the docs.
 
-> The kit component names are identical across all four kit variants (Material, Fluent,
-> Bootstrap, Indigo). The kit variant determines the theme, not the component name.
+> The kit component names are identical across all four kit variants (Material, Fluent, Bootstrap, Indigo). The kit variant determines the theme, not the component name.
 
 ### Doc-name rules you will hit immediately
 
-- **Doc names are topic-page names, not tag names.** `navigation-drawer`, `text-area`,
-  `data-grid`, `circular-progress`.
-- **`get_doc` normalizes and aliases input.** It strips the `Igc` prefix and the
-  `Component` suffix, so `IgcCarouselComponent` resolves to `carousel`. It also aliases
-  these Web Components names:
+- **Doc names are topic-page names, not tag names.** `navigation-drawer`, `text-area`, `data-grid`, `circular-progress`.
+- **`get_doc` normalizes and aliases input.** It strips the `Igc` prefix and the `Component` suffix, so `IgcCarouselComponent` resolves to `carousel`. It also aliases these Web Components names:
 
   | You pass | Resolves to |
   | --- | --- |
@@ -48,10 +96,8 @@
   | `range-slider` | `slider` |
   | `geographic-map` | `geo-map` |
 
-- Combo has several topic pages (`overview`, `features`, `single-selection`, `templates`);
-  read `overview` first, then the specific one the design needs.
-- Always confirm against a live `list_components({ framework: "webcomponents" })` — the
-  catalog is the source of truth, this table is a shortcut.
+- Combo has several topic pages (`overview`, `features`, `single-selection`, `templates`); read `overview` first, then the specific one the design needs.
+- Always confirm against a live `list_components({ framework: "webcomponents" })` — the catalog is the source of truth, this table is a shortcut.
 
 ### Registration cheat sheet
 
@@ -59,13 +105,11 @@
 | --- | --- |
 | `igniteui-webcomponents` | `defineComponents(IgcNavbarComponent, IgcCardComponent, …)` |
 | `igniteui-webcomponents-grids` | `IgcGridComponent.register()` (per grid type) |
-| `igniteui-grid-lite` | per the Grid Lite docs — confirm with `get_doc` |
+| `igniteui-grid-lite` | `IgcGridLite.register()`, or `import 'igniteui-grid-lite/define'`; the column tag is `igc-grid-lite-column` |
 | `igniteui-webcomponents-charts` / `-gauges` / `-maps` | `ModuleManager.register(IgcCategoryChartModule, …)` from `igniteui-webcomponents-core` |
-| `igniteui-dockmanager` | `defineCustomElements()` per the dock-manager docs |
+| `igniteui-dockmanager` | `defineComponents(IgcDockManagerComponent)` from `igniteui-dockmanager` (`defineCustomElements()` is deprecated since 2.0.0) |
 
-Licensed projects use the same names prefixed with `@infragistics/` (e.g.
-`@infragistics/igniteui-webcomponents-grids`). Resolve the layout once in Phase 0b and keep
-it consistent.
+Licensed projects use the same names prefixed with `@infragistics/` (e.g. `@infragistics/igniteui-webcomponents-grids`, `@infragistics/igniteui-dockmanager`). `igniteui-webcomponents` itself is MIT and has no licensed variant. Resolve the layout once in Phase 0b and keep it consistent.
 
 ---
 
@@ -80,21 +124,13 @@ it consistent.
 | `_Icon Button/*`                       | `<igc-icon-button variant="flat">`     | `IgcIconButtonComponent` | `igniteui-webcomponents` | `icon-button` | `variant` (`flat\|contained\|outlined`), `name`, `collection` |
 | `_Button Group`                        | `<igc-button-group>`                   | `IgcButtonGroupComponent` | `igniteui-webcomponents` | `button-group` | `selection`, `alignment`; `<igc-toggle-button>` children |
 
-> `variant` is an **attribute** on the element itself — there is no directive equivalent of
-> Angular's `igxButton`. Icon-only buttons need an `aria-label` for the Phase 5g check.
+> `variant` is an **attribute** on the element itself — there is no directive equivalent of Angular's `igxButton`. Icon-only buttons need an `aria-label` for the Phase 5g check.
 
 ---
 
 ## Form Controls
 
-> **Input variants.** The kits express `line` / `box` / `border` input types. Web Components
-> expose a single boolean **`outlined`** attribute (inherited from the shared input base) on
-> `igc-input`, `igc-textarea`, `igc-mask-input`, `igc-date-time-input`, `igc-file-input`,
-> `igc-select`, `igc-combo`, `igc-date-picker`, and `igc-date-range-picker`.
-> Map `_Input/Border` → `outlined`; `_Input/Line` and `_Input/Box` → default.
-> There is **no** global injection-token equivalent of Angular's `IGX_INPUT_GROUP_TYPE` —
-> set the attribute per control, and close residual differences with `input-group`
-> component tokens (Phase 3d), never with internal class selectors.
+> **Input variants.** The kits express `line` / `box` / `border` input types. Web Components expose a single boolean **`outlined`** attribute on `igc-input`, `igc-textarea`, `igc-mask-input`, `igc-date-time-input`, `igc-file-input`, `igc-select`, `igc-combo`, `igc-date-picker`, and `igc-date-range-picker`. Map `_Input/Border` → `outlined`; `_Input/Line` and `_Input/Box` → default. There is **no** global injection-token equivalent of Angular's `IGX_INPUT_GROUP_TYPE` — set the attribute per control, and close residual differences with `input-group` component tokens (Phase 3d), never with internal class selectors.
 
 | Kit Component Name             | Tag                       | Class                           | Package                  | Doc                 | Key attributes / slots                                                     |
 | ------------------------------ | ------------------------- | ------------------------------- | ------------------------ | ------------------- | --------------------------------------------------------------------------- |
@@ -102,7 +138,7 @@ it consistent.
 | `_Input/Border`                | `<igc-input outlined>`    | `IgcInputComponent`             | `igniteui-webcomponents` | `input`             | `outlined`                                                                  |
 | `_Input/Search`                | `<igc-input type="search">` | `IgcInputComponent`           | `igniteui-webcomponents` | `input`             | Add a search `igc-icon` in the `prefix` slot                                |
 | `_Text Area`                   | `<igc-textarea>`          | `IgcTextareaComponent`          | `igniteui-webcomponents` | `text-area`         | `label`, `rows`, `resize`, `outlined`                                       |
-| `_Masked Input`                | `<igc-mask-input>`        | `IgcMaskInputComponent`         | `igniteui-webcomponents` | `mask-input`        | `mask`, `prompt-char`, `value-mode`                                         |
+| `_Masked Input`                | `<igc-mask-input>`        | `IgcMaskInputComponent`         | `igniteui-webcomponents` | `mask-input`        | `mask`, `prompt`, `value-mode`                                         |
 | `_File Upload`                 | `<igc-file-input>`        | `IgcFileInputComponent`         | `igniteui-webcomponents` | `file-input`        | `multiple`, `accept`, `label`                                               |
 | `_Combo` / `_ComboBox`         | `<igc-combo>`             | `IgcComboComponent`             | `igniteui-webcomponents` | `combo` → `overview` | `.data`, `display-key`, `value-key`, `group-key`, `single-select`, `outlined` |
 | `_Simple Combo`                | `<igc-combo single-select>` | `IgcComboComponent`           | `igniteui-webcomponents` | `single-selection`  | `single-select` — theme key is `simple-combo`                               |
@@ -114,6 +150,7 @@ it consistent.
 | `_Slider`                      | `<igc-slider>`            | `IgcSliderComponent`            | `igniteui-webcomponents` | `slider`            | `min`, `max`, `step`, `value`, `discrete-track`                              |
 | `_Range Slider`                | `<igc-range-slider>`      | `IgcRangeSliderComponent`       | `igniteui-webcomponents` | `slider`            | `lower`, `upper`                                                            |
 | `_Rating`                      | `<igc-rating>`            | `IgcRatingComponent`            | `igniteui-webcomponents` | `rating`            | `value`, `max`, `step`, `single`, `allow-reset`, `hover-preview`, `readonly`; slots `symbol`, `value-label`; `igcChange` event                          |
+| `_Color Picker`                | `<igc-color-picker>`      | `IgcColorPickerComponent`       | `igniteui-webcomponents` | confirm via `list_components` | `value`, `format`, `label`, `mode`, `show-alpha`, `hide-formats`             |
 
 ---
 
@@ -126,8 +163,7 @@ it consistent.
 | `_Time Picker`       | `<igc-date-time-input>`     | `IgcDateTimeInputComponent`     | `igniteui-webcomponents` | `date-time-input`   | **No dedicated time picker in Web Components** — use a time `input-format` |
 | `_Calendar`          | `<igc-calendar>`            | `IgcCalendarComponent`          | `igniteui-webcomponents` | `calendar`          | `selection` (`single\|multiple\|range`), `value`, `values`, `visible-months`, `week-start`, `show-week-numbers`, `header-orientation` |
 
-> Date pickers and the calendar are **compound** — their dropdown/calendar surface is a
-> separate theme. Follow the related-theme chain from `get_component_design_tokens`.
+> The date pickers are **compound** — their dropdown and calendar surfaces are separate themes. Follow the related-theme chain from `get_component_design_tokens`.
 
 ---
 
@@ -140,11 +176,10 @@ it consistent.
 | `_Tabs`                            | `<igc-tabs>`              | `IgcTabsComponent`             | `igniteui-webcomponents` | `tabs`                | `alignment`, `activation`; `<igc-tab label="…">` children with `prefix`/`suffix` slots |
 | `_Bottom Navigation`               | —                         | —                              | —                        | —                     | **Not available in Web Components.** Use `igc-tabs` or custom markup; document the substitution. |
 | `_Stepper`                         | `<igc-stepper>`           | `IgcStepperComponent`          | `igniteui-webcomponents` | `stepper`             | `orientation`, `step-type`, `linear`, `title-position`; `<igc-step>` children     |
+| `_Breadcrumbs`                     | `<igc-breadcrumbs>` | `IgcBreadcrumbsComponent` | `igniteui-webcomponents` | confirm via `list_components` | `separator`; default slot contains `<igc-breadcrumb>` children; wrap in `<nav aria-label="…">` |
+| `_Breadcrumb`                      | `<igc-breadcrumb>`  | `IgcBreadcrumbComponent`  | `igniteui-webcomponents` | confirm via `list_components` | `current`, `disabled`; slots `prefix`, `suffix`, `separator` |
 
-> A design showing a persistent, always-visible sidebar maps to
-> `<igc-nav-drawer position="relative" open>` — not the modal default. The drawer's width is
-> controlled by the `--menu-full-width` / `--menu-mini-width` custom properties on the host,
-> which are **not** design tokens and will not appear in `get_component_design_tokens`.
+> A design showing a persistent, always-visible sidebar maps to `<igc-nav-drawer position="relative" open>` — not the modal default. The drawer's width comes from the `navdrawer` design tokens `size` and `size--mini`, exposed as `--ig-nav-drawer-size` (default 15rem) and `--ig-nav-drawer-size--mini`. Set them through `create_component_theme` like any other token.
 
 ---
 
@@ -176,6 +211,7 @@ it consistent.
 | `_Circular Progress`                 | `<igc-circular-progress>`  | `IgcCircularProgressComponent`    | `igniteui-webcomponents` | `circular-progress`  | `value`, `max`, `indeterminate` — theme key `progress-circular`           |
 | `_Divider`                           | `<igc-divider>`            | `IgcDividerComponent`             | `igniteui-webcomponents` | `divider`            | `type` (`solid\|dashed`), `vertical`, `middle`                            |
 | `_Chat`                              | `<igc-chat>`               | `IgcChatComponent`                | `igniteui-webcomponents` | `chat`               | `.messages`, `.options` assigned as properties                            |
+| `_QR Code`                          | `<igc-qr-code>`            | `IgcQrCodeComponent`              | `igniteui-webcomponents` | confirm via `list_components` | `value`, `size`, `error-level`, `logo-src`, `dot-style`, `square-style` |
 | `_Paginator`                         | `<igc-paginator>`          | grid package                      | `igniteui-webcomponents-grids` | search `grid-paging` | Part of the grid packages, not a standalone core component           |
 
 ---
@@ -205,27 +241,18 @@ it consistent.
 Grid rules that differ from Angular:
 
 - Register per grid type: `IgcGridComponent.register()`.
-- The grid packages ship their **own theme CSS** —
-  `igniteui-webcomponents-grids/grids/themes/<variant>/<design-system>.css` — in addition to
-  the core theme. Inside a Lit component, import it `?inline` and inject it into the shadow
-  root; at app level, import it normally.
+- The grid packages ship their **own theme CSS** — `igniteui-webcomponents-grids/grids/themes/<variant>/<design-system>.css` — in addition to the core theme. Inside a Lit component, import it `?inline` and inject it into the shadow root; at app level, import it normally.
 - `data` is a property, not an attribute: `.data=${rows}` / `grid.data = rows`.
 - Leave at least one `<igc-column>` without a `width` so it fills the remaining space.
-- Feature docs are separate pages (`grid-editing`, `grid-filtering`, `grid-paging`, …) —
-  fetch the ones the artboard actually shows.
+- Feature docs are separate pages (`grid-editing`, `grid-filtering`, `grid-paging`, …) — fetch the ones the artboard actually shows.
 
 ---
 
 ## Charts, Gauges, and Maps
 
-> These are DV components. They have **no design tokens** — do not call
-> `get_component_design_tokens` for them. Configure everything through properties, and take
-> series colors from `theming_get_chart_series_colors` plus the Figma values captured in
-> Phase 1d.
+> These are DV components. They have **no design tokens** — do not call `get_component_design_tokens` for them. Configure everything through properties, and take series colors from `theming_get_chart_series_colors` plus the Figma values captured in Phase 1d.
 >
-> Registration for all three packages goes through
-> `ModuleManager.register(IgcXxxModule, …)` imported from `igniteui-webcomponents-core`.
-> Array and function values must be **assigned as properties**, never as attributes.
+> Registration for all three packages goes through `ModuleManager.register(IgcXxxModule, …)` imported from `igniteui-webcomponents-core`. Array and function values must be **assigned as properties**, never as attributes.
 
 | Kit Component Name                                        | Tag                       | Class                        | Package                          | Doc                                          |
 | --------------------------------------------------------- | ------------------------- | ---------------------------- | -------------------------------- | --------------------------------------------- |
@@ -244,12 +271,9 @@ Grid rules that differ from Angular:
 
 DV specifics worth knowing before Phase 4:
 
-- Gauge and chart **attributes are kebab-case** (`minimum-value`, `maximum-value`,
-  `chart-type`, `data-source`), while collection-valued members are properties.
-- `plotAreaBackground` and `areaFillOpacity` are inherited from parent classes and will not
-  appear in `get_api_reference` for `IgcCategoryChartComponent` — find them with `search_api`.
-- Category charts show markers by default; if the design has none, set the documented
-  no-marker value.
+- Gauge and chart **attributes are kebab-case** (`minimum-value`, `maximum-value`, `chart-type`), while collection-valued members such as `dataSource` are properties.
+- `plotAreaBackground` and `areaFillOpacity` are inherited from parent classes and will not appear in `get_api_reference` for `IgcCategoryChartComponent` — find them with `search_api`.
+- Category charts show markers by default; if the design has none, set the documented no-marker value.
 - Give charts an explicit height (and their grid track a `min-height`) or they collapse.
 
 ---
@@ -268,8 +292,7 @@ registerIconFromText('home', '<svg …></svg>', 'material');
 await registerIcon('search', 'https://example.com/icons/search.svg');
 ```
 
-For the Material Icons Extended set used by the Indigo.Design UI Kit for Material — Figma
-component descriptions carry the suffix **"material extended"**:
+For the Material Icons Extended set used by the Indigo.Design UI Kit for Material — Figma component descriptions carry the suffix **"material extended"**:
 
 ```bash
 npm install @igniteui/material-icons-extended
@@ -288,28 +311,52 @@ for (const icon of all) {
 <igc-icon name="credit-cards"></igc-icon>
 ```
 
-**Detection in Phase 1d:** scan `data-name` values and component descriptions for
-"material extended". If found, add the package to the required list and get approval before
-Phase 4. `setIconRef(name, collection, meta)` lets you alias one registered icon to another
-name when the design reuses a glyph under a different label.
+**Detection in Phase 1d:** scan `data-name` values and component descriptions for "material extended". If found, add the package to the required list and get approval before Phase 4. `setIconRef(name, collection, meta)` lets you alias one registered icon to another name when the design reuses a glyph under a different label.
 
 Registered icons are never extracted as image assets — see `asset-extraction.md`.
 
+### Icons from other kits
+
+Third-party kits come with their own icon sets. Identify the set from the icon instance names (`lucide/chevron-down`, `ic_fluent_…`, `Icon / arrow-right`, `Symbols/…`), from the component descriptions, or from the kit fingerprint in `design-provenance.md`. Then register glyphs **from that set's SVG package**, so names, weights, and stroke widths match the design:
+
+| Icon set | SVG source package (confirm name, version, and license before installing) |
+| --- | --- |
+| Material Symbols | `@material-symbols/svg-400` (pick the weight/fill the design uses) |
+| Fluent System Icons | `@fluentui/svg-icons` |
+| Lucide (shadcn/ui kits) | `lucide-static` |
+| Bootstrap Icons | `bootstrap-icons` |
+| Heroicons | `heroicons` |
+| Phosphor | `@phosphor-icons/core` |
+| Ant Design Icons | `@ant-design/icons-svg` |
+
+```typescript
+import chevronDown from 'lucide-static/icons/chevron-down.svg?raw';
+registerIconFromText('chevron-down', chevronDown, 'lucide');
+```
+
+```html
+<igc-icon name="chevron-down" collection="lucide"></igc-icon>
+```
+
+Register only the glyphs the design uses: importing a whole set inflates the bundle. When the set is paid (for example Untitled UI Icons Pro) or unknown, or is not licensed for the web (SF Symbols), extract the used glyphs as SVG with Tier 1 Method B from `asset-extraction.md` and register those instead. Tell the user which icons came from a licensed set.
+
 ---
 
-## Components in the Kit With No Web Components Equivalent
+## Components With No Web Components Equivalent
 
-Check this list before assuming a 1:1 mapping exists. When you hit one, substitute and
-document the substitution in a code comment and in the Phase 2d plan.
+Check this list before assuming a 1:1 mapping exists. When you hit one, substitute and document the substitution in a code comment and in the Phase 2d plan.
 
-| Kit component     | Status in Web Components | Substitute                                                        |
+| Kit component / role | Status in Web Components | Substitute                                                      |
 | ----------------- | ------------------------- | ------------------------------------------------------------------ |
 | `_Bottom Navigation` | Not available          | `igc-tabs`, or custom markup styled from the design                |
 | `_Time Picker`    | Not available as a picker | `igc-date-time-input` with a time input format                     |
 | `_Autocomplete`   | Not available             | `igc-combo` with filtering, or `igc-input` + `igc-dropdown`         |
-| `_Action Strip`   | Not available             | Slotted icon buttons positioned over the row/card                   |
+| `_Action Strip`   | Grid packages only (`igc-action-strip`) | Inside grids, use `igc-action-strip`; elsewhere, slotted icon buttons positioned over the row/card |
 | `_Chips Area`     | Not a component           | A flex container around `igc-chip` elements                         |
 | `_Query Builder`  | Grid packages only        | `query-builder` doc — confirm availability for the installed package |
+| Sheet / side sheet (other kits) | Not available           | `igc-nav-drawer` for navigation; `igc-dialog` or custom markup for content panels |
+| Skeleton loader (other kits) | Not available             | Custom markup with a CSS shimmer bound to palette variables          |
+| Standalone pagination (other kits) | Grid packages only (`igc-paginator`) | `igc-paginator` when paging a grid; otherwise custom markup with `igc-icon-button`s |
 
 ---
 
@@ -317,9 +364,7 @@ document the substitution in a code comment and in the Phase 2d plan.
 
 When you encounter a Figma layer that is **not in this file**:
 
-1. Extract the visual pattern (is it a list? a form field? a card?).
-2. Call `list_components({ framework: "webcomponents", filter: "<keyword>" })` and scan for
-   the closest match.
+1. Normalize it with [design-provenance.md](design-provenance.md) (Tier B variant properties, or Tier C structure) and retry the Canonical Role Index. Otherwise, extract the visual pattern (is it a list? a form field? a card?).
+2. Call `list_components({ framework: "webcomponents", filter: "<keyword>" })` and scan for the closest match.
 3. Call `get_doc` (and `get_api_reference` when you need the full API) before writing code.
-4. If no Ignite UI component matches after a genuine attempt, use plain semantic HTML and
-   document the reason in a code comment.
+4. If no Ignite UI component matches after a genuine attempt, use plain semantic HTML and document the reason in a code comment.

package/skills/igniteui-wc-figma-to-app/references/figma-exploration.md

@@ -0,0 +1,222 @@
+# Figma Design Exploration
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 1 to explore the Figma design and capture everything needed for implementation and validation. Read in full before the first Figma MCP call.
+
+**Goal:** understand the full design structure and capture all data needed for implementation and validation before writing any code.
+
+> **Rate-limit awareness:** Figma MCP limits depend on the **seat**, not only the plan (as published in September 2026; verify at https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/): **View/Collab seats** get up to 6 calls/month (20 on Starter). **Dev/Full seats** get 200/day (Starter, Professional) or 600/day (Organization, Enterprise), with 10–20/min.
+>
+> Estimated call budget for a 5-artboard design: `figma_get_metadata` ×2 + `figma_get_screenshot` ×5 + `figma_get_design_context` ×5 + `figma_get_variable_defs` ×1 per target page + `figma_get_code_connect_map` ×5 + `figma_get_libraries` ×1 = **~19 calls**. Retries and sparse-response follow-ups add to this. **Compare the estimate with the user's remaining quota before starting.** On a View/Collab seat (6/month on Professional and above) even one artboard may not fit. The Starter View/Collab limit (20/month) covers a small design with no retries. When the estimate does not fit, say so and suggest a Dev/Full seat, or the REST API with a personal access token for metadata and assets. Strategies:
+> 1. Call `figma_get_variable_defs` once per **target page**, not once per artboard. It returns the variables used inside the node you pass, so one page-level call covers every artboard on that page.
+> 2. Prioritize `figma_get_design_context` over additional screenshots if quota is tight.
+> 3. For large files, consider implementing one artboard per monthly budget cycle.
+>
+> Use `figma_get_metadata` first to discover structure cheaply, then call `figma_get_design_context` only for the artboards you will implement.
+
+## Before the First Call: Determine the Figma MCP Variant
+
+Figma has two official MCP servers (setup: `mcp-setup.md § 1. Figma MCP`). Establish which one is connected **before** Phase 1, because it decides how you address artboards.
+
+| Variant | How to recognize it | How you drive it |
+| --- | --- | --- |
+| **Remote** | Configured URL `https://mcp.figma.com/mcp`; the tools take `fileKey` | Pass `fileKey` and a `nodeId` (page or artboard) on **every** call. You can iterate artboards without the user. |
+| **Desktop** | Configured URL `http://127.0.0.1:3845/mcp`; the tools take no `fileKey` | Works only on the file **open in the Figma desktop app**. Pass the `nodeId` from a frame link, or act on the current selection. |
+
+Prefer the remote variant, and ask the user once for the file URL:
+
+```
+https://figma.com/design/:fileKey/:fileName?node-id=1-2   →   fileKey = ":fileKey", nodeId = "1:2"
+```
+
+On the remote variant, treat both `fileKey` and `nodeId` as required, even if the schema marks `nodeId` optional. Calls without a node are not reliably supported.
+
+On the desktop variant:
+
+1. Make sure the user has the design file **open** in the desktop app.
+2. When the user can share frame links (right-click → **Copy link to selection**), pass each frame's `nodeId` and **check that the response describes the requested frame** (same name and size as in the Phase 1a metadata).
+3. If the response describes a different node, or the user cannot share links, fall back to selection: ask *"In Figma, please click the **[Artboard Name]** frame to select it, then confirm."*, wait for confirmation, and call the tool with no node. Never batch selection-based calls: each one depends on what the user has selected at that moment.
+
+## 1a: Discover Pages and Artboards
+
+The goal is to list the pages, then get each relevant page's artboard tree. The calls differ by variant:
+
+```
+// Remote variant: fileKey and nodeId are both required
+figma_get_metadata({ fileKey: "<fileKey>", nodeId: "<pageId>" })
+
+// Desktop variant: a nodeId from a page or frame link, or no arguments to use the current selection
+figma_get_metadata({ nodeId: "<pageId>" })
+figma_get_metadata({})
+```
+
+**Remote variant.** Choose the starting `nodeId` like this:
+
+1. If the shared URL has a `node-id`, use it (replace `-` with `:`, e.g. `1-2` → `1:2`). URL format: `https://figma.com/design/:fileKey/:name?node-id=1-2`.
+2. Otherwise, list the pages with the REST API when a token is available. It costs no MCP quota: `GET https://api.figma.com/v1/files/:fileKey?depth=1` returns `document.children[]` with each page's `id` and `name`.
+3. Otherwise, ask the user to copy the link to the page or a frame (right-click → **Copy link to selection**) and take its `node-id`.
+
+If that node is a single frame rather than a page, the response covers only that frame's subtree. To see its sibling artboards, get the page's `id` (step 2 or 3) and call `figma_get_metadata` again with it. Repeat for every page that looks relevant.
+
+**Desktop variant.** The user must have the file open in the desktop app. With a link to the page or a frame, pass its `nodeId` and check the response. Otherwise ask the user to open the relevant page and select its top-level frames (or the page in the Layers panel), then call `figma_get_metadata({})`. Repeat for each relevant page, waiting for confirmation each time.
+
+## 1b: Select Target Artboards
+
+If there are multiple pages or artboards, show the user a list:
+
+> "I found these artboards in your Figma file:
+>
+> - Page 1: [list artboard names + node IDs]
+> - Page 2: [list artboard names + node IDs]
+>
+> Which artboards should I implement? (You can say 'all' or list specific names.)"
+
+Wait for confirmation before proceeding.
+
+## 1c: Capture Reference Screenshots
+
+For each target artboard:
+
+1. **Remote variant:** call `figma_get_screenshot({ fileKey: "<fileKey>", nodeId: "<artboardId>", maxDimension: 2048 })`. **Desktop variant:** call `figma_get_screenshot({ nodeId: "<artboardId>" })` and check that the image shows the requested artboard. If it does not, or you have no node ID, ask the user to select the artboard, wait for confirmation, then call `figma_get_screenshot({})`. Do **not** batch selection-based calls.
+2. **Save each screenshot to disk** (e.g. `.figma-reference/<artboard-name>.png`). Phase 5 compares against these files. If the tool returns a URL, download it right away (it is short-lived). If it returns the image inline and you cannot write it to disk, export the node through the REST API instead (`GET /v1/images/:fileKey?ids=<nodeId>&format=png&scale=2`, see `asset-extraction.md`) when a token is available. Otherwise keep the image in context for Phase 5. Record `{ artboardName, nodeId, file, width, height }`.
+
+After all artboards are captured, confirm the count:
+
+> *"I have N reference screenshots: [list artboard names]. Proceeding to design context extraction."*
+
+If any are missing, recapture them: by `nodeId` on the remote server, or by asking the user to select the artboard on the desktop server.
+
+> Never skip this step. The screenshots are your ground truth for Phase 5 validation.
+
+## 1d: Extract Design Context
+
+> **Output format:** `figma_get_design_context` returns **React + Tailwind CSS reference code**, not structured Web Components metadata. Do **not** copy that code into the project. Read the JSX to extract the information below. Asset URLs in the output (localhost on the desktop server, https on the remote server) are short-lived previews — do **not** use them as final assets (see Phase 1h and `references/asset-extraction.md`).
+
+For **each** target artboard:
+
+1. On the remote variant, pass `fileKey` and `nodeId`. On the desktop variant, pass the `nodeId` and check the response, or fall back to selection (see [Before the First Call](#before-the-first-call-determine-the-figma-mcp-variant)).
+2. Call:
+   ```
+   figma_get_design_context({
+     fileKey: "<fileKey>",     // remote variant only
+     nodeId: "<artboardId>",   // both variants (desktop: check the response)
+   })
+   ```
+3. From the React+Tailwind output, extract:
+
+   - **Component layer names and props** — the `data-name` attributes and any component props or variant values in the JSX. Phase 1f classifies and normalizes them.
+   - **Layout structure** — `flex`, `grid`, `gap-*`, `p-*`, `w-*`, `h-*` Tailwind classes on container divs
+   - **Typography** — `font-['...']`, `text-[...]`, `font-weight` classes
+   - **Surface colors** — `bg-[#XXXXXX]` classes on container `<div>` elements that wrap major sections (these become plain `<div>` wrappers in the view, not Ignite UI components)
+   - **Border/roundness** — `rounded-[...]`, `border`, `border-[...]` classes on containers and cards
+   - **Input type variants** *(Tier A only)* — look for hidden zero-size nodes (`size-[0.5px]`) whose `data-name` contains a component type (e.g. `"Date Picker Type"`, `"Combo Input"`). These are the Indigo.Design kit's **variant indicator nodes**, and their name encodes which input variant (border/line/box) is active for that component. For other kits, read the field style from its variant property or visuals (outlined / filled / underlined, label floating or above). Web Components expose this as the boolean `outlined` attribute, not a three-way type (SKILL.md Phase 4, rule 12).
+   - **Chart series colors** — for any chart layer, note the fill colors on its series paths
+   - **Color census** — which colors appear on which kinds of element: high-emphasis button fills, page and card backgrounds, borders, primary and secondary text, error states. For Tier B/C designs, Phase 3 seeds the palette from this (see `design-token-bridge.md § B2`), not from variable names.
+   - **Measured control heights** — button, input, and list-row heights. Phase 3 uses them to pick `--ig-size`.
+   - **Action controls** — list every button, icon button, and toolbar action visible in the artboard; this is your authoritative inventory — do not add actions not present in the design
+   - **Provenance signals** — library/source file names (e.g. `Indigo.Design UI Kit for Material`, `Material 3 Design Kit`, `shadcn/ui`), naming conventions (`_Button/…` vs `Button` with `Variant=…`), and un-componentized frames. Phase 1f turns them into a tier for each instance.
+
+4. Record all surface containers for **Table B — Layout Surfaces** (Phase 1g).
+
+## 1e: Extract Design Tokens
+
+> `figma_get_variable_defs` returns the variables and styles **used inside the node you pass** (or the current selection), not every variable in the file. Call it **once per target page**, with the page's node ID. That covers every target artboard on the page without spending a call per artboard. If the targets span two pages, call it twice.
+
+```
+// Remote variant
+figma_get_variable_defs({ fileKey: "<fileKey>", nodeId: "<pageId>" })
+
+// Desktop variant: the page's nodeId (check the response), or select the page and pass nothing
+figma_get_variable_defs({ nodeId: "<pageId>" })
+figma_get_variable_defs({})
+```
+
+The response contains a map of variable names to values, e.g.:
+
+```
+"color/primary/500": "#6200EE"
+"color/surface": "#FFFFFF"
+"typography/body/font-family": "Roboto"
+```
+
+Use `references/design-token-bridge.md` to map color and typography variables to Ignite UI theming inputs in Phase 3. Third-party kits name variables differently (`md.sys.color.primary`, `Colors/Brand/600`, `colorBrandBackground`, `primary-foreground`, …). Record them as-is. Phase 3 matches them to roles by **usage** (the Phase 1d color census), not by name. Files without variables are normal for Tier C designs. The color census then provides every seed. Do **not** attempt to map Figma spacing or sizing values — see `references/design-token-bridge.md § Spacing, Sizing, and Roundness` for why.
+
+## 1f: Classify Provenance and Normalize Components
+
+Read [design-provenance.md](design-provenance.md) in full.
+
+1. Call `figma_get_libraries` **once per file**, if the connected server exposes it. The subscribed library names (`Indigo.Design UI Kit for Material`, `Material 3 Design Kit`, `shadcn/ui`, an in-house library) are the fastest provenance signal.
+2. Check for Code Connect mappings:
+
+   ```
+   figma_get_code_connect_map({ fileKey: "<fileKey>", nodeId: "<artboardId>" })      // remote variant
+   figma_get_code_connect_map({ nodeId: "<artboardId>" })                            // desktop variant
+   ```
+
+   Mappings are strong evidence of a component's **role and props**. They may point at **another library** (e.g. a shadcn kit connected to `@/components/ui/button`). Never copy their imports or tags: the target is always Ignite UI for Web Components.
+
+3. Classify **every** component-like layer as **Tier A** (Indigo.Design kit), **Tier B** (any other component library), or **Tier C** (un-componentized). Classify per instance, not per file.
+4. Normalize Tier B instances to a canonical role + emphasis/style + measured height, using their variant properties. When names are ambiguous and a file key and token are available, read exact `componentProperties` from the REST API (`design-provenance.md § Step 1`).
+5. Infer Tier C roles from structure and visuals. Mark them **low confidence**.
+6. Record the dominant tier. It selects the Phase 3 theming path (A or B).
+
+## 1g: Build the Decomposition Table
+
+Before writing any code, produce **two tables** for **each artboard**.
+
+### Table A — Ignite UI Components
+
+| Figma Layer Name | Tier | Kit / Source | Canonical Role + Props | Ignite UI Tag | Package | Confidence | Token Work | Suspected Anatomy Deltas | Data Type |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| _e.g._ `_NavBar` | A | Indigo.Design (Material) | `app-bar` | `<igc-navbar>` | `igniteui-webcomponents` | high | — | — | n/a |
+| _e.g._ `_Grid/Default` | A | Indigo.Design (Material) | `data-table` | `<igc-grid>` | `igniteui-webcomponents-grids` | high | — | — | Tabular records |
+| _e.g._ `Button` (`Variant=outline, Size=sm`) | B | shadcn/ui | `button` · medium · 32px | `<igc-button variant="outlined">` | `igniteui-webcomponents` | high | radius, casing, size | — | n/a |
+| _e.g._ `Text field` (`Style=Filled`) | B | M3 Design Kit | `text-field` · filled · label-floating · 56px | `<igc-input>` | `igniteui-webcomponents` | high | height, fill color | — | n/a |
+| _e.g._ `Segmented button` | B | M3 Design Kit | `toggle-group` · 40px | `<igc-button-group>` | `igniteui-webcomponents` | high | radius, colors | check icon on the selected segment | n/a |
+| _e.g._ `Frame 427` | C | — | `tag` · pill · 24px | `<igc-badge>` | `igniteui-webcomponents` | low | radius, colors | — (confirm the role) | n/a |
+
+The **Package** column is not optional in Web Components: general UI (`igniteui-webcomponents`, MIT), grids, charts, and dock manager ship as separate packages, and the commercial ones come in trial and `@infragistics` licensed variants.
+
+- **Token Work** lists what Phase 3 must set: colors, radius, borders, casing, size. These are implementation work. They are **never** anatomy deltas and never become Accepted.
+- **Suspected Anatomy Deltas** lists only structural differences that tokens, documented `::part(...)` selectors, and slotted content cannot close. They are suspicions at this point: you only know what Ignite UI renders after reading its doc in Phase 2b. Confirm them in the Phase 2d ledger.
+
+Fallback to plain semantic HTML only when no Ignite UI component can match the layer after consulting `references/figma-component-map.md`. Document the reason inline.
+
+### Table B — Layout Surfaces
+
+Record every **non-`igc-*` container** that carries visual properties (background color, border, padding, shadow). These are plain `<div>` wrappers in the view — not Ignite UI components — but they are critical to visual fidelity. Populate this table from the `bg-[...]`, `rounded-[...]`, `border`, `p-[...]`, and `shadow-[...]` Tailwind classes observed on container divs in the Phase 1d design context output.
+
+| Figma Frame / Container Name | Background | Border-Radius | Padding | Border | Shadow | Encloses (child sections) |
+| ---------------------------- | ---------- | ------------- | ------- | ------ | ------ | ------------------------- |
+| _e.g._ `Budget Categories`  | `#222222`  | `4px`         | `24px`  | none   | none   | Categories list, Add button |
+| _e.g._ `Friend Card`        | `#222222`  | `8px`         | `24px 16px` | `1px solid #333` | none | Avatar, name, phone, email, buttons |
+
+> **Rule:** if a section appears on a surface in Figma (i.e. its container has a non-transparent background), it **must** have that background in the implementation. If a section floats on the page background (transparent), do **not** add a surface wrapper. Never infer surface structure from another page — always derive it from the design context for the specific artboard being implemented.
+
+Present both tables to the user for review before proceeding. List **low-confidence** mappings first and ask the user to confirm or correct them. A wrong role is the most expensive mistake to fix after Phase 4.
+
+## 1h: Extract Image Assets
+
+Read [references/asset-extraction.md](asset-extraction.md) in full before running any extraction.
+
+**Zero-placeholder policy:** every image visible in the Figma design must be extracted and committed to the project's assets directory before Phase 4. Gradient placeholders are not acceptable.
+
+**Step 0 — File key and token.** Reuse the file key from Phase 1 (the remote server always has one). On the desktop server without one, ask the user for the file URL (Figma desktop: right-click the file tab → **Copy link**). Tier 1 also needs a REST API token (`mcp-setup.md § Personal access token`). Without both you fall back to Tier 2 or 3.
+
+From the decomposition tables, identify every layer that is a **static image asset** (photo, background, logo, custom icon, illustration) rather than an Ignite UI component. Do **not** extract component instances that Table A maps to a component, whatever kit they come from, or icons available from a registerable icon package (`figma-component-map.md § Icons`, which also covers third-party kit icon sets).
+
+**Use the four-tier decision tree from `asset-extraction.md`** (these asset tiers 1–4 are unrelated to the provenance Tiers A–C):
+
+| Tier | Method | When to use |
+| ---- | ------ | ----------- |
+| **1** | REST API `/v1/files/:key/images` (Method A) or `/v1/images/:key` (Method B) | `FILE_KEY` **and** `FIGMA_TOKEN` available — always the highest fidelity |
+| **2** | Download the asset URLs from `figma_get_design_context` (localhost on desktop, https on remote), or `figma_download_assets` on remote | No REST access; the design context returned asset URLs |
+| **3** | `figma_get_screenshot` per node (`nodeId`, or the selection on desktop) | No REST access and no asset URL for this node |
+| **4** | CSS gradient/color placeholder with `// TODO` comment | Only for confirmed pure-color fills — never as a shortcut |
+
+Save assets under the project's static directory — `src/assets/images/` and `src/assets/icons/` in a CLI-scaffolded Vite project (copied to the build output by `vite-plugin-static-copy`); `public/` in a stock Vite app. Match whatever the project already uses.
+
+Build a concise asset manifest (see `asset-extraction.md § Build an Asset Manifest`) so the implementation phase uses consistent paths.
+
+If you used Tier 2 or Tier 3 for any asset, tell the user which ones need re-export once the file key and a REST API token are available.