igniteui-angular 22.2.0-rc.0 → 22.2.0-rc.2

package/skills/igniteui-angular-figma-to-app/references/asset-extraction.md

@@ -2,35 +2,25 @@
 
 > **Part of the [`igniteui-angular-figma-to-app`](../SKILL.md) skill.**
 >
-> Use this file in Phase 1h to identify and extract image assets from Figma artboards
-> before implementation. Read in full before calling any extraction tool.
+> Use this file in Phase 1h to identify and extract image assets from Figma artboards before implementation. Read in full before calling any extraction tool.
 >
-> **Zero-placeholder policy:** every image asset visible in the Figma design must be
-> extracted and committed to `src/assets/` before Phase 4 begins. Gradient placeholders
-> and empty `<div>` boxes are not acceptable. If the highest-fidelity method is
-> unavailable, use the next tier — but always extract something real.
+> **Zero-placeholder policy:** every image asset visible in the Figma design must be extracted and committed to `src/assets/` before Phase 4 begins. Gradient placeholders and empty `<div>` boxes are not acceptable. If the highest-fidelity method is unavailable, use the next tier — but always extract something real.
 
 ---
 
 ## Step 0 — Acquire the Figma File Key (Required for REST API)
 
-The Figma REST API requires a **file key** — the identifier embedded in every Figma
-file URL. Without it, you can still extract assets using Tier 2 and Tier 3 methods
-below, but the REST API (Tier 1) produces the highest quality output and should always
-be the first attempt.
+The Figma REST API requires a **file key** — the identifier embedded in every Figma file URL. Without it, you can still extract assets using Tier 2 and Tier 3 methods below, but the REST API (Tier 1) produces the highest quality output and should always be the first attempt.
 
-**Ask the user for the file key at the start of Phase 1h:**
+**Reuse the file key from Phase 1** when you already have it (the remote Figma server always has one). Otherwise, ask the user for it at the start of Phase 1h:
 
-> "To extract image assets at the highest quality, I need the Figma file key.
-> In the Figma desktop app:
+> "To extract image assets at the highest quality, I need the Figma file key. In the Figma desktop app:
 >
 > 1. Right-click the file tab at the top → **Copy link** (or go to **File → Share** and copy the URL)
 > 2. The URL looks like: `https://www.figma.com/design/ABCDEF1234567890/My-File-Name`
 > 3. The file key is the segment after `/design/`: **`ABCDEF1234567890`**
 >
-> Please share that key (or the full URL). If you cannot access it right now, I will
-> proceed with the desktop-app extraction methods and note which assets need to be
-> re-exported at higher quality."
+> Please share that key (or the full URL). If you cannot access it right now, I will proceed with the desktop-app extraction methods and note which assets need to be re-exported at higher quality."
 
 **Extracting the key from a URL (if the user pastes it):**
 
@@ -43,7 +33,7 @@ echo "https://www.figma.com/design/ABCDEF1234567890/My-App" \
 export FILE_KEY="ABCDEF1234567890"
 ```
 
-**Your Figma personal access token** (same one used for the MCP server) is needed for REST calls. Store it as an environment variable:
+**A Figma personal access token** is needed for REST calls. The Figma MCP servers do not use one, so this is a separate token (see `mcp-setup.md § Personal access token`). Ask the user to export it in the agent's shell, and never write it into a project file:
 
 ```bash
 export FIGMA_TOKEN="your-personal-access-token"
@@ -82,52 +72,48 @@ Scan the XML returned by `figma_get_metadata` for layer names matching:
 
 > **Ignore these** — do NOT extract them as image assets:
 >
-> - Any layer whose name starts with `_Button`, `_Input`, `_Grid`, `_Card`, etc.
->   (Indigo.Design UI Kit component instances → implement as IgxXxx components)
-> - `igx-icon` glyph nodes (use `<igx-icon>` in Angular instead)
+> - Any layer whose name starts with `_Button`, `_Input`, `_Grid`, `_Card`, etc. (Indigo.Design UI Kit component instances → implement as IgxXxx components), and any other layer that Table A maps to a component — `Button`, `Text field`, … from any kit
+> - Icon glyphs available from a registerable package (Material Icons Extended, Material Symbols, Lucide, Fluent, …; see `figma-component-map.md § Icons from other kits`) — register them with `IgxIconService` and render `<igx-icon>` instead
 > - Artboard/frame boundaries themselves
 
 ### Size heuristic
 
-Large rectangles (width > 200px or height > 200px) at key layout positions (hero area,
-sidebar background, card thumbnail slot) are almost always image fills.
+Large rectangles (width > 200px or height > 200px) at key layout positions (hero area, sidebar background, card thumbnail slot) are almost always image fills.
 
 Small nodes (< 48×48px) named with icon-like names are usually SVG icons.
 
 ### Confirm with design context
 
-For ambiguous nodes, look at the `figma_get_design_context` output for the artboard.
-Each image asset appears as either:
+For ambiguous nodes, look at the `figma_get_design_context` output for the artboard. Each image asset appears as either:
 
-- An `<img src="http://localhost:3845/assets/...">` — confirms it is a raster fill; note the node ID
+- An `<img>` with an asset URL (`http://localhost:3845/assets/...` on desktop, an https URL on remote) — confirms it is a raster fill; note the node ID
 - Inline SVG or an `<img>` with `.svg` extension — confirms it is a vector; note the node ID
 
-Note all localhost image URLs from the design context — these are needed for Tier 2
-extraction if the REST API is unavailable.
+Note all asset URLs from the design context — these are needed for Tier 2 extraction if the REST API is unavailable.
 
 ---
 
 ## Step 2 — Extract at the Highest Available Fidelity
 
-Use this **four-tier decision tree**. Start at Tier 1. Move to the next tier only if
-the previous one is unavailable for this specific asset.
+Use this **four-tier decision tree**. Start at Tier 1. Move to the next tier only if the previous one is unavailable for this specific asset.
 
 ```
-Do you have the FILE_KEY?
+Do you have BOTH the FILE_KEY and a FIGMA_TOKEN (REST API personal access token)?
 ├─ YES → Use Tier 1 (REST API). Always the best.
-└─ NO  → Did figma_get_design_context include a localhost URL for this asset?
-          ├─ YES → Use Tier 2 (download localhost URL to disk).
-          └─ NO  → Can you get a clean node screenshot?
+└─ NO  → Did figma_get_design_context return a download URL for this asset?
+          (desktop server: http://localhost:3845/assets/…; remote server: short-lived https URLs)
+          ├─ YES → Use Tier 2 (download that URL to disk now).
+          └─ NO  → Can you render the node on its own?
                     ├─ YES → Use Tier 3 (figma_get_screenshot per node).
                     └─ NO  → Use Tier 4 (CSS gradient/color placeholder as last resort,
                               with a TODO comment to replace later).
 ```
 
-**After completing Phase 4, if you used Tier 2 or Tier 3 for any asset:**
+The remote server also offers `figma_download_assets` (up to 20 nodes per call, exports and original images). If it is in the tool list, use it for Tier 2 when there is no FIGMA_TOKEN.
 
-> Tell the user: "The following assets were extracted at reduced quality because the
-> Figma file key was not available: [list]. To replace them with the original
-> source files, run the Tier 1 REST API commands in Step 2a once you have the file key."
+**At the end of Phase 1h, if you used Tier 2 or Tier 3 for any asset:**
+
+> Tell the user: "The following assets were extracted at reduced quality because the Figma REST API was not available (no file key or no personal access token): [list]. To replace them with the original source files, run the Tier 1 REST API commands once you have both."
 
 ---
 
@@ -137,9 +123,7 @@ Do you have the FILE_KEY?
 
 #### Method A — Original Image Fills
 
-Use this to download **photos, textures, and raster images** that were uploaded to
-Figma (identified by `imageRef` in node fill data). Returns the original source file
-at its native resolution — never a re-render.
+Use this to download **photos, textures, and raster images** that were uploaded to Figma (identified by `imageRef` in node fill data). Returns the original source file at its native resolution — never a re-render.
 
 ```bash
 # Step A.1 — Get all image fill URLs in the file
@@ -168,8 +152,7 @@ curl -sL "$IMAGE_URL" -o src/assets/images/hero-background.jpg
 
 #### Method B — Node Export (SVG, PNG, JPG)
 
-Use this to export **any node** as SVG, PNG, or JPG. Best for logos, custom icons,
-vector illustrations, and raster compositions.
+Use this to export **any node** as SVG, PNG, or JPG. Best for logos, custom icons, vector illustrations, and raster compositions.
 
 ```bash
 mkdir -p src/assets/images src/assets/icons
@@ -215,46 +198,41 @@ done
 
 ---
 
-### Tier 2 — Localhost URL Download (Desktop MCP Fallback)
+### Tier 2 — Design-Context Asset URLs
 
-**Use when:** the file key is unavailable and `figma_get_design_context` returned
-localhost URLs (e.g. `http://localhost:3845/assets/abc123.png`).
+**Use when:** Tier 1 is unavailable and `figma_get_design_context` returned download URLs. The desktop server returns localhost URLs (e.g. `http://localhost:3845/assets/abc123.png`); the remote server returns short-lived https URLs. The steps below are the same for both.
 
-These URLs are served by the Figma desktop app's in-memory renderer and are accessible
-via `curl` during the active Figma session. They are **not** the original source file
-(they are a renderer output), but they are substantially better than placeholders and
-can be committed to the repository.
+On the desktop server these URLs are served by the Figma desktop app's in-memory renderer and work only during the active Figma session. On the remote server they are https URLs that expire after a short time. Either way they are **not** the original source file (they are a renderer output), but they are substantially better than placeholders and can be committed to the repository.
 
 ```bash
 mkdir -p src/assets/images src/assets/icons
 
-# Extract localhost URLs from a design context output and download them
-# Replace <localhost-url> with the actual URL found in figma_get_design_context output
+# Download the asset URLs found in the figma_get_design_context output
+# (desktop: localhost URLs as below; remote: the https URLs, downloaded the same way)
 curl -sL "http://localhost:3845/assets/<hash>.png" -o src/assets/images/hero-background.png
 curl -sL "http://localhost:3845/assets/<hash>.svg" -o src/assets/icons/logo.svg
 ```
 
-**Finding localhost URLs in design context output:**
+**Finding asset URLs in design context output** (desktop examples; remote URLs are https):
 
 In the React+Tailwind code returned by `figma_get_design_context`, look for:
 
 - `const imgXxx = "http://localhost:3845/assets/<hash>.<ext>";` at the top of the output
 - `<img src={imgXxx} />` or `background-image` references inline
 
-Each `const` at the top is an image asset. Note its variable name, the URL, and which
-Figma node it belongs to (from context around the `<img>` tag).
+Each `const` at the top is an image asset. Note its variable name, the URL, and which Figma node it belongs to (from context around the `<img>` tag).
 
 **Limitations of Tier 2 assets:**
 
-- Raster renders — vectors become PNGs, not SVGs
+- Usually raster renders. When the context offers an SVG URL for a vector, download it as SVG
 - Renderer resolution (typically 2×) — adequate for most uses
-- Expire when the Figma desktop app closes — **must be downloaded before closing Figma**
+- Short-lived — desktop URLs die when the Figma desktop app closes, remote URLs expire after a while. **Download them immediately**
 - Must be renamed from `<hash>.png` to descriptive names before committing
 
 **Commit as-is** — they are real assets. Add a comment in the asset manifest:
 
 ```typescript
-// TODO: Replace with Tier 1 REST API export once FILE_KEY is available
+// TODO: Replace with Tier 1 REST API export once FILE_KEY and FIGMA_TOKEN are available
 heroBg: 'assets/images/hero-background.png', // extracted from Figma session
 ```
 
@@ -262,16 +240,17 @@ heroBg: 'assets/images/hero-background.png', // extracted from Figma session
 
 ### Tier 3 — `figma_get_screenshot` per Node
 
-**Use when:** no file key AND no localhost URLs were produced for a specific node.
+**Use when:** neither Tier 1 nor Tier 2 produced the asset.
 
-`figma_get_screenshot` renders any currently-selected Figma node as a PNG screenshot.
-Ask the user to select each image node in Figma, then call the tool.
+`figma_get_screenshot` renders a single node. Address the node the same way as in Phase 1 (`figma-exploration.md § Before the First Call`):
 
 ```
-// 1. Ask: "In Figma, please click the [Hero Background] layer to select it."
-// 2. After confirmation:
+// Remote server
+figma_get_screenshot({ fileKey: "<fileKey>", nodeId: "<imageNodeId>" })
+// Desktop server: the node ID (check the image), or ask the user to select the layer
+figma_get_screenshot({ nodeId: "<imageNodeId>" })
 figma_get_screenshot({})
-// 3. The returned image is a 1× screen-capture PNG. Save it to src/assets/images/.
+// The returned image is a screen-capture PNG. Save it to src/assets/images/.
 ```
 
 **Limitations:**
@@ -291,20 +270,17 @@ heroBg: 'assets/images/hero-background.png',
 
 ### Tier 4 — CSS Fallback (Last Resort Only)
 
-**Use only when** an asset is confirmed to be a pure color fill or a gradient — not when
-an image exists in Figma but extraction failed. Never use Tier 4 because extraction
-feels difficult.
+**Use only when** an asset is confirmed to be a pure color fill or a gradient — not when an image exists in Figma but extraction failed. Never use Tier 4 because extraction feels difficult.
 
 ```scss
 // Only acceptable when the Figma layer is genuinely a gradient, not a photo
 .hero-banner {
-  // TODO: Replace with real asset — extraction blocked (no file key, no session URL)
+  // TODO: Replace with real asset — extraction blocked (no REST token and no design-context asset URL)
   background: linear-gradient(135deg, #0d1b3e 0%, #1a0533 100%);
 }
 ```
 
-If you use Tier 4, add the `TODO` comment and include it in the post-session handoff
-notes to the user.
+If you use Tier 4, add the `TODO` comment and include it in the post-session handoff notes to the user.
 
 ---
 
@@ -325,7 +301,7 @@ export const PAGE_ASSETS = {
   logo: 'assets/icons/logo.svg',
 
   // Figma node 345:678 — "Card/Thumbnail" layer
-  // Tier 2: localhost URL download (TODO: re-export via REST API)
+  // Tier 2: design-context asset URL (TODO: re-export via REST API)
   cardThumbnail: 'assets/images/card-thumbnail.png',
 } as const;
 ```
@@ -343,8 +319,7 @@ Name files by layer purpose, not by node ID.
 <img ngSrc="assets/images/hero-background.jpg" width="1440" height="600" alt="Dashboard hero background" priority />
 ```
 
-Import `NgOptimizedImage` in the component's `imports` array. Note: `NgOptimizedImage`
-does **not** work for inline base64 images.
+Import `NgOptimizedImage` in the component's `imports` array. Note: `NgOptimizedImage` does **not** work for inline base64 images.
 
 ### Background images via SCSS
 
@@ -364,8 +339,7 @@ does **not** work for inline base64 images.
 
 ### Igx-icon for kit icons (do NOT extract as assets)
 
-Standard Material icons and `imx-icons` (Material Icons Extended) are registered at
-runtime — never extract them as image files:
+Standard Material icons and `imx-icons` (Material Icons Extended) are registered at runtime — never extract them as image files:
 
 ```html
 <igx-icon>settings</igx-icon> <igx-icon family="imx-icons" name="credit-cards"></igx-icon>
@@ -381,7 +355,7 @@ See `figma-component-map.md § Material Icons Extended` for setup.
 | ------------------------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Skipping asset extraction entirely (gradient placeholders)   | Implementation looks nothing like the design; Phase 5 fails      | Always use at least Tier 2 or Tier 3 — never skip                                      |
 | Not asking for the file key before starting extraction       | Defaults to Tier 2/3 when Tier 1 was actually possible           | Ask for the file key at the start of Phase 1h (see Step 0)                             |
-| Using localhost URLs without downloading them in the session | URLs expire when Figma closes; assets become broken              | Download with `curl` immediately; commit the files                                     |
+| Using design-context asset URLs without downloading them in the session | The URLs are short-lived; assets become broken              | Download with `curl` immediately; commit the files                                     |
 | Naming assets by node ID ("node-123-456.png")                | Unmaintainable; breaks if Figma is reorganized                   | Name by layer purpose: `hero-background.jpg`, `company-logo.svg`                       |
 | Using `figma_get_screenshot` for SVG logos                   | Logo is rasterized to PNG; loses vector scalability              | Use Tier 1 Method B with `format=svg` instead; fall back to Tier 2 only if unavailable |
 | Exporting PNG at `scale=1`                                   | Blurry on HiDPI/retina screens                                   | Always use `scale=2`                                                                   |

package/skills/igniteui-angular-figma-to-app/references/design-provenance.md

@@ -0,0 +1,201 @@
+# Design Provenance — Recognizing Components From Any UI Kit
+
+> **Part of the [`igniteui-angular-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 1f to decide **where every component in the design came from** and to normalize it into a **canonical role** that [figma-component-map.md](figma-component-map.md) resolves to an Ignite UI Angular selector. Read it in full before building the Phase 1g decomposition table.
+
+---
+
+## Why This Step Exists
+
+Designers build Figma screens from many sources: the Infragistics **Indigo.Design UI Kits**, public kits (Material 3 Design Kit, Fluent 2, Bootstrap, shadcn/ui, Untitled UI, Ant Design, iOS/Apple kits), an in-house design system, or plain frames with no components at all. The Ignite UI kits map to Ignite UI one-to-one by layer name. Other kits do not, but they describe the same **roles** (a high-emphasis button, an outlined text field, a tab strip), using different names and variant properties.
+
+Translating any kit directly into Ignite UI tags would need one mapping table per kit. Instead, this skill uses two steps: **kit → canonical role** (a small vocabulary, normalized here) and **canonical role → Ignite UI** (one table, in `figma-component-map.md`). A kit you have never seen still works if its variant names can be normalized.
+
+---
+
+## Step 1 — Collect the Evidence for Each Instance
+
+For every component-like layer in the target artboard, gather what the design data exposes. Use the cheapest source first.
+
+| Evidence | Where it comes from | Strength |
+| --- | --- | --- |
+| **Layer / main-component name** | `data-name` in `figma_get_design_context`; instance names in `figma_get_metadata` XML | Medium. Designers rename layers, and detached instances keep the old name. |
+| **Variant properties** (`Variant=Primary`, `Size=md`, `State=Hover`) | The design-context code (component props), or the REST API (below) | Strong. This is the kit's own statement of role and variant. |
+| **Component description** | REST `components` map, or design-context annotations | Strong when present. Kits often document intent here. |
+| **Code Connect mapping** | `figma_get_code_connect_map` | Strong for **role**, but it may point at a *different* library. See the caveat below. |
+| **Library / source file name** | `figma_get_libraries` (the libraries the file subscribes to: name, key, description) and `figma_search_design_system` (returns `libraryName` for a component name). Check the connected server's tool list, because availability varies by Figma MCP version. | Strong for kit identity. Call `get_libraries` **once per file**: it names the kits in play before you look at a single instance. |
+| **Structure + visuals** | Auto-layout, children, fills, size, the screenshot | Weak alone. It is the only evidence for un-componentized frames. |
+
+**Reading exact variant properties via the REST API** (use when names are ambiguous and `FIGMA_TOKEN` + `FILE_KEY` are available. This is the REST API token from `mcp-setup.md § Personal access token`, not an MCP credential):
+
+```bash
+curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=$ARTBOARD_ID" -o /tmp/figma_nodes.json
+
+# Every instance with its variant properties
+jq '[.. | objects | select(.type? == "INSTANCE")
+     | {id, name, componentId, props: (.componentProperties // {} | with_entries(.value |= .value))}]' \
+  /tmp/figma_nodes.json
+
+# Main-component and component-set names/descriptions (remote == came from a library)
+jq '.nodes[].components, .nodes[].componentSets' /tmp/figma_nodes.json
+```
+
+**Design-context quirks that matter here:**
+
+- `data-name` preserves the main-component name, for example `.Status badge`. Components can also appear as local functions with typed props (`Button({ variant = "outline" })`), which carry the variant values.
+- Nodes inside an instance have IDs like `I9:12;6:3`. Treat those as parts of the parent component, not as components of their own.
+- If the response is flagged **sparse** (large frames), fetch the visible child nodes in one parallel batch instead of guessing from the partial output.
+- When Code Connect maps components to a non-Ignite library, pass `disableCodeConnect: true` (where the server supports it) to keep the reference output free of foreign imports. Read the mapping separately with `figma_get_code_connect_map`.
+
+`remote: true` on a component means it came from a published library. `componentSetId` groups the variants of one component. Use the **component-set name** as the main-component name, because instance layer names are often edited.
+
+---
+
+## Step 2 — Classify Provenance (Per Instance)
+
+Classify **per instance**, not per file. Real files mix sources: an Ignite UI kit navbar next to a hand-drawn KPI tile and a third-party date picker.
+
+| Tier | What it is | Recognized by | Resolution path |
+| --- | --- | --- | --- |
+| **A — Ignite UI kit** | Instance of an Indigo.Design UI Kit component | Leading-underscore names (`_Button/Contained`, `_Input/Border`), `Indigo.Design` library names, hidden `size-[0.5px]` variant-indicator nodes, the kit variable collections | Direct lookup in `figma-component-map.md` by kit name. Highest confidence. |
+| **B — Other component library** | Instance of any other published or local component (public kit or in-house) | A main component / component set with variant properties, without Tier A fingerprints | **Normalize** (Step 3) to a canonical role, then look it up in the canonical role index of `figma-component-map.md`. |
+| **C — Un-componentized** | Plain frames, groups, or detached instances | No main component. Type is `FRAME` / `GROUP`, or a detached copy that still carries a component-like name | **Infer** the role from structure and visuals (Step 4). Lowest confidence. Confirm with the user. |
+
+Record the tier and a confidence (**high / medium / low**) in the Phase 1g Table A.
+
+### Recognizing common public kits (confirmation only)
+
+These fingerprints help name the kit in the plan and choose the theme baseline (Phase 3b). Normalization does **not** depend on them. Kit files change between versions, so treat every row as a hint, not a rule.
+
+| Kit | Typical fingerprints | Default icon set |
+| --- | --- | --- |
+| Material 3 Design Kit (Google) | Variables/styles under `M3/…` or `md.sys.…` / `md.ref.…`; tonal roles (`primary`, `on-primary`, `primary-container`, `surface-container-*`); button styles *Filled / Tonal / Outlined / Text / Elevated*; text fields *Filled / Outlined* | Material Symbols |
+| Fluent 2 (Microsoft) | Token names like `colorBrandBackground`, `colorNeutralForeground1`, `borderRadiusMedium`; button appearance *Primary / Secondary / Outline / Subtle / Transparent* | Fluent System Icons |
+| Bootstrap kits | Variant names `primary / secondary / success / danger / warning / info / light / dark`; `btn-outline-*`; `form-control` / `form-select` | Bootstrap Icons |
+| shadcn/ui kits | Semantic variables `background`, `foreground`, `primary`, `primary-foreground`, `muted`, `accent`, `border`, `input`, `ring`, `radius`; button variants *default / secondary / outline / ghost / link / destructive* | Lucide |
+| Untitled UI | `Colors/Brand/600`, `Colors/Gray (light mode)/…`, `bg-primary`, `text-secondary`; button hierarchy *Primary / Secondary / Tertiary / Link* (+ *color / gray*) | Untitled UI Icons (paid Pro tier; check the license) |
+| Ant Design kits | Button type *Primary / Default / Dashed / Text / Link*; `colorPrimary`, `colorBgContainer` tokens | Ant Design Icons |
+| iOS / Apple kits | SF Pro type, *Filled / Tinted / Gray / Plain* buttons, grouped inset lists, tab bars at the bottom | SF Symbols (not licensed for web; substitute) |
+
+---
+
+## Step 3 — Normalize Tier B Instances Into Canonical Roles
+
+Normalize **role**, **emphasis**, **style**, **size**, and **state** separately. Match property values case-insensitively and by meaning, not exact spelling.
+
+### Role (from the component or component-set name)
+
+Strip prefixes, sigils, status emoji, numbering, and platform tags (`.Button`, `Button / Base`, `❖ Button`, `✅ Button`, `[Web] Button`, `Buttons`). A leading `.` usually marks a private or base component. A leading `_` with a `/` path (`_Button/Contained`) is the Tier A Indigo.Design fingerprint. Classify it before stripping anything. Ignore the order of variant axes: `Button (M, Accent)` is the same as `Button (Accent, M)`. Then match against the canonical roles in `figma-component-map.md § Canonical Role Index`. Common synonyms:
+
+| Canonical role | Also called |
+| --- | --- |
+| `button` | Btn, CTA, Action |
+| `icon-button` | Button with `Icon only=true`, Icon Btn, Square button |
+| `fab` | Floating action button, Extended FAB |
+| `toggle-group` | Segmented button, Segmented control, Button group (selectable), Radio buttons (button style) |
+| `text-field` | Input, Text input, Field, Form control, Textbox |
+| `textarea` | Text area, Multiline input |
+| `select` | Dropdown (as a form field), Picker, Listbox trigger |
+| `combobox` | Autocomplete, Searchable select, Typeahead, Multi-select, Tag input |
+| `menu` | Dropdown menu, Context menu, Overflow menu, Action sheet (desktop) |
+| `app-bar` | Navbar, Top bar, Header, Toolbar (page-level) |
+| `side-nav` | Sidebar, Drawer, Navigation rail, Rail |
+| `tabs` | Tab bar, Tab list, Segmented tabs |
+| `breadcrumbs` | Breadcrumb, Path |
+| `dialog` | Modal, Alert dialog |
+| `sheet` | Side sheet, Drawer (overlay), Bottom sheet |
+| `toast` | Snackbar, Notification, Sonner |
+| `inline-alert` | Alert, Banner, Callout, Message bar |
+| `tag` | Badge (text pill), Label, Pill, Status |
+| `count-badge` | Badge (dot or number on another element), Indicator |
+| `chip` | Filter chip, Input chip, Assist chip, Removable tag |
+| `data-table` | Table, Data grid, Grid |
+| `list` | List, List group, Menu list (non-overlay) |
+| `progress-linear` / `progress-circular` | Progress bar, Loader / Spinner (determinate or not) |
+
+### Emphasis (buttons, icon buttons, links)
+
+| Normalized | Kit values that mean it |
+| --- | --- |
+| **high** | Primary, Filled, Solid, Contained, Default (shadcn), Brand, Accent, Hierarchy=Primary |
+| **medium** | Secondary, Tonal, Soft, Outline(d), Stroke, Bordered, Default (Ant/Fluent), Gray |
+| **low** | Tertiary, Ghost, Subtle, Text, Plain, Transparent, Flat, Borderless |
+| **link** | Link, Hyperlink, Link color / Link gray |
+| **elevated** | Elevated, Raised |
+| **danger** (modifier) | Destructive, Danger, Error, Critical |
+
+"Secondary" means *outlined* in some kits and *a filled button in the secondary color* in others. Read the visuals of that instance (fill vs stroke) before choosing.
+
+### Style (form fields)
+
+| Normalized | Kit values / visuals |
+| --- | --- |
+| **outlined** | Outlined, Bordered, Border, Default with a full 1px stroke |
+| **filled** | Filled, Box, Solid, Flushed-with-background, Tonal |
+| **underlined** | Line, Underline, Flushed, Standard |
+| **label-floating** | Label inside the field that moves to the top edge |
+| **label-above** | Label as separate text above the field |
+
+### Size and state
+
+- **Size:** record the measured control **height** in px (from the design context), not the kit's size name. Kits disagree on what `md` means. Phase 3d turns heights into `--ig-size`.
+- **State:** `Hover`, `Focused`, `Pressed`, `Disabled`, `Error`, `Selected` variants are **states**, not different components. Implement the default state, and use state values only as token inputs (hover color, focus ring) in Phase 3d. A screen showing a `State=Error` field means the design wants validation styling. It does not mean the field is permanently invalid.
+
+---
+
+## Step 4 — Infer Tier C (Un-componentized) Layers
+
+Use the exact values from the design context and the screenshot together:
+
+| Structure observed | Likely role |
+| --- | --- |
+| Auto-layout row, 28–56px tall, one short text (± icon), solid fill or 1px stroke, radius | `button` (emphasis from fill vs stroke vs none) |
+| Square 24–48px frame with only an icon | `icon-button` |
+| 32–56px frame with a stroke or bottom border, placeholder-grey text, optional chevron/icon | `text-field` (chevron → `select`) |
+| Repeated equal-height rows with leading icon/avatar + 1–2 text lines + trailing element | `list` |
+| Header row of labels over repeated rows aligned in columns | `data-table` |
+| Horizontal labels with one underlined or pill-highlighted item | `tabs` |
+| Small rounded pill with short text | `tag` or `chip` (`chip` when it has a close or select affordance) |
+| Circle 24–64px with an image or initials | `avatar` |
+
+Rules for Tier C:
+
+- **Confidence is low by default.** List Tier C mappings separately in the Phase 1g review so the user can correct them.
+- **Purely decorative or bespoke layouts** (hero sections, marketing tiles, KPI cards) stay plain semantic HTML plus CSS. Do not force them into a component because a name suggests one.
+- **Interactive controls stay components.** If a Tier C frame is clearly an input, select, date field, table, or tab strip, use the Ignite UI component even when its anatomy differs. The component brings keyboard, focus, ARIA, and form behavior that a custom frame lacks.
+
+---
+
+## Code Connect Caveat
+
+`figma_get_code_connect_map` may return mappings to **another** library, for example a shadcn kit connected to `@/components/ui/button`, or an in-house kit connected to the company's React package. Use these mappings as **strong evidence of the role and props** (a Code Connect snippet `<Button variant="outline" size="sm">` confirms *button / medium emphasis / small*). **Never** copy their imports, tags, or props into the implementation. The target is always Ignite UI.
+
+---
+
+## False Friends — Same Name, Different Ignite UI Component
+
+| Name in the kit | Usually means | Ignite UI Angular choice |
+| --- | --- | --- |
+| **Badge** (shadcn, Untitled UI, Bootstrap) | A text pill / status label | `igx-badge` with `[value]` for short status; `igx-chip` when removable or selectable |
+| **Badge** (Material, Fluent) | Dot or count on another element | `igx-badge` positioned over the host |
+| **Dropdown** | A form field in some kits, a menu in others | `igx-select` (field) vs `igx-drop-down` + `igxToggleAction` (menu) |
+| **Select** with search (shadcn Combobox, Ant Select `showSearch`) | Filterable single select | `igx-simple-combo` |
+| **Autocomplete** / free-text typeahead | Suggestions under a text input | `igxAutocomplete` on an `igx-input-group` input + `igx-drop-down` |
+| **Tabs** styled as a pill track (shadcn, Fluent "segmented") | Either view switching or a value toggle | `igx-tabs` if it switches panels; `igx-buttongroup` if it sets a value |
+| **Sheet** / **Drawer** (overlay) | Temporary side panel | `igx-nav-drawer` for navigation. There is no dedicated sheet component: for content panels use `igx-dialog` or custom markup, and record it as an anatomy delta |
+| **Alert** | Inline message (not modal) | `igx-banner`, or semantic HTML for static callouts |
+| **Toast** vs **Snackbar** | Transient message | `igx-toast` (text only) or `igx-snackbar` (with action) |
+| **Card** with complex internal layout | A surface container | `igx-card` only if header/content/actions anatomy fits; otherwise a Table B surface |
+| **Navigation rail** | Icon-only side nav | Pinned `igx-nav-drawer` with an `igxDrawerMini` template, kept **closed**. The mini template renders only while the drawer is closed |
+| **Tab bar** at the bottom (iOS, M3 navigation bar) | App-level navigation | `igx-bottom-nav` |
+| **Breadcrumb** | Navigation trail | No Angular breadcrumb component. Use semantic `<nav><ol>` markup with router links |
+
+---
+
+## Output of This Step
+
+Fill the **Tier**, **Kit / Source**, **Canonical Role + Props**, **Confidence**, **Token Work**, and **Suspected Anatomy Deltas** columns of the Phase 1g **Table A**. The table and its column rules are defined once, in `figma-exploration.md § 1g`.
+
+Only the **Suspected Anatomy Deltas** column feeds the Phase 2d delta ledger. Token Work is never a delta.