igniteui-webcomponents 7.3.2 → 7.4.1

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

@@ -0,0 +1,343 @@
+# Asset Extraction from Figma
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 1h to identify and extract image assets from Figma artboards before implementation. Read it in full before calling any extraction tool.
+>
+> **Zero-placeholder policy:** every image asset visible in the Figma design must be extracted and committed 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 — Decide Where Assets Live
+
+Match the project you are in before downloading anything:
+
+| Project shape | Asset directory | Referenced as |
+| --- | --- | --- |
+| CLI-scaffolded (`igniteui-cli new --framework=webcomponents`) | `src/assets/images/`, `src/assets/icons/` | `/assets/images/hero.jpg` — copied to the build output by `vite-plugin-static-copy` |
+| Stock Vite / plain bundler | `public/images/`, `public/icons/` | `/images/hero.jpg` |
+| Bundler-processed (hashed) assets | anywhere under `src/` | `import heroUrl from '../assets/hero.jpg'` then bind the URL |
+
+Create the directories before the first `curl`:
+
+```bash
+mkdir -p src/assets/images src/assets/icons     # or public/images public/icons
+```
+
+---
+
+## Step 1 — Acquire the Figma File Key (Required for the REST API)
+
+The Figma REST API needs a **file key** — the identifier in every Figma file URL — and a **personal access token**. Reuse the file key from Phase 1 when you have it (the remote Figma server always has one). If not, ask:
+
+> "To extract image assets at the highest quality, I need the Figma file key. In the Figma desktop app: right-click the file tab → **Copy link**. The URL looks like `https://www.figma.com/design/ABCDEF1234567890/My-File-Name` — the file key is the segment after `/design/`: **`ABCDEF1234567890`**. If you cannot access it right now, I will use the fallback methods and note which assets need re-exporting at higher quality."
+
+```bash
+echo "https://www.figma.com/design/ABCDEF1234567890/My-App" \
+  | sed -E 's|.*/design/([^/]+)/.*|\1|'
+# → ABCDEF1234567890
+export FILE_KEY="ABCDEF1234567890"
+export FIGMA_TOKEN="your-personal-access-token"   # REST API only — see below
+```
+
+The Figma MCP servers do **not** use a personal access token, 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.
+
+---
+
+## Two Fundamentally Different Types of Image Assets
+
+| Type             | What it is                                                                             | Figma signal                                            | Best extraction method                   |
+| ---------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------- |
+| **Image fill**   | A photo, texture, or raster image dragged/pasted into Figma, stored as an IMAGE fill    | Layer has a fill of type `IMAGE`; `imageRef` in node data | REST API Method A → original source file |
+| **Vector asset** | A logo, icon, or illustration drawn in Figma with vector tools                           | Node type `VECTOR`, `BOOLEAN_OPERATION`, or `GROUP`     | REST API Method B → clean SVG            |
+
+Do **not** confuse either with component instances — from the Indigo.Design UI Kits or any other kit — that Phase 1f mapped to a canonical role. Those become Ignite UI components, not extracted assets.
+
+---
+
+## Step 2 — Identify Image Nodes
+
+### Naming patterns to look for in `figma_get_metadata`
+
+| Naming pattern                                   | Likely asset type | Action                                    |
+| ------------------------------------------------ | ----------------- | ----------------------------------------- |
+| `_Image`, `_Photo`, `_Picture`, `image`, `photo` | Raster image fill | Extract as PNG                            |
+| `_Hero`, `_Banner`, `_Cover`                     | Large raster fill | Extract as PNG (2× scale)                 |
+| `_Thumbnail`, `_Avatar`, `_Illustration`         | Raster image fill | Extract as PNG                            |
+| `_Logo`, `_Brand`                                | Vector or raster  | If vector: SVG; if raster: PNG            |
+| `_Icon/` prefix (custom icons)                   | Custom SVG icon   | Extract as SVG, then **register** it      |
+| `_Background`, `_Bg`                             | Large raster fill | Extract as PNG                            |
+| `_Art`, `_Pattern`                               | Vector or raster  | Classify before extracting                |
+
+> **Ignore these** — do NOT extract them as image assets:
+>
+> - Any layer that Table A maps to a component (`_Button`, `_Input`, `Button`, `Text field`, … — kit component instances from any kit)
+> - Icon glyphs available from a registerable package (Material Icons Extended, Material Symbols, Lucide, Fluent, …; see `figma-component-map.md § Icons`). Register them with `registerIconFromText` and render `<igc-icon>` instead
+> - Artboard/frame boundaries themselves
+
+### Size heuristic
+
+Large rectangles (width or height > 200px) at key layout positions (hero area, sidebar background, card thumbnail slot) are almost always image fills. Small nodes (< 48×48px) with icon-like names are usually SVG icons.
+
+### Confirm with design context
+
+`figma_get_design_context` returns the reference code **plus a JSON block of download URLs for the assets it references**. Each entry confirms the node is a real asset and gives you a directly downloadable URL. Note them — Tier 2 depends on them, and they are short-lived.
+
+---
+
+## Step 3 — Extract at the Highest Available Fidelity
+
+```
+Do you have BOTH the FILE_KEY and a FIGMA_TOKEN?
+├─ YES → Tier 1 (REST API). Always the best.
+└─ NO  → Did figma_get_design_context return an asset URL for this node?
+          (desktop server: http://localhost:3845/assets/…; remote server: short-lived https URLs)
+          ├─ YES → Tier 2 (download that URL now).
+          └─ NO  → Can you render the node on its own?
+                    ├─ YES → Tier 3 (figma_get_screenshot per node).
+                    └─ NO  → Tier 4 (CSS placeholder + TODO — last resort only).
+```
+
+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.
+
+**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."
+
+---
+
+### Tier 1 — REST API (Highest Fidelity)
+
+**Requires:** `FILE_KEY` and `FIGMA_TOKEN`.
+
+#### Method A — Original Image Fills
+
+Downloads the **original uploaded file** at native resolution — never a re-render.
+
+```bash
+# A.1 — all image fill URLs in the file
+curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/$FILE_KEY/images" \
+  -o /tmp/figma_image_fills.json
+# Response: { "images": { "<imageRef>": "<cdn-url>", ... } }
+
+# A.2 — node fill data, to match imageRef → node
+curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=$NODE_IDS" \
+  -o /tmp/figma_nodes.json
+# Look for: "fills": [{ "type": "IMAGE", "imageRef": "abc123" }]
+
+# A.3 — download
+IMAGE_URL=$(jq -r '.images["<imageRef>"]' /tmp/figma_image_fills.json)
+curl -sL "$IMAGE_URL" -o src/assets/images/hero-background.jpg
+```
+
+> **URL expiry:** image fill URLs expire in **14 days**. Download during the session.
+
+#### Method B — Node Export (SVG, PNG, JPG)
+
+```bash
+# SVG export (logos, icons, illustrations)
+curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/images/$FILE_KEY?ids=$NODE_IDS&format=svg&svg_outline_text=false&contents_only=true" \
+  -o /tmp/figma_svg_export.json
+
+jq -r '.images | to_entries[] | "\(.key)\t\(.value)"' /tmp/figma_svg_export.json | \
+while IFS=$'\t' read -r nodeId url; do
+  filename="$(echo "$nodeId" | tr ':' '-').svg"
+  curl -sL "$url" -o "src/assets/icons/$filename"
+done
+
+# PNG export at 2× (hero banners, raster compositions)
+curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/images/$FILE_KEY?ids=$NODE_IDS&format=png&scale=2&contents_only=true" \
+  -o /tmp/figma_png_export.json
+
+jq -r '.images | to_entries[] | "\(.key)\t\(.value)"' /tmp/figma_png_export.json | \
+while IFS=$'\t' read -r nodeId url; do
+  filename="$(echo "$nodeId" | tr ':' '-').png"
+  curl -sL "$url" -o "src/assets/images/$filename"
+done
+```
+
+| Parameter          | Value   | When to use                                          |
+| ------------------ | ------- | ---------------------------------------------------- |
+| `format`           | `svg`   | Logos, icons, vector illustrations                   |
+| `format`           | `png`   | Hero backgrounds, thumbnails — always pair `scale=2` |
+| `format`           | `jpg`   | Photos without transparency — use `scale=2`          |
+| `scale`            | `2`     | **Always for PNG/JPG** — retina-quality output       |
+| `svg_outline_text` | `false` | Keep text as `<text>` elements (smaller, accessible) |
+| `contents_only`    | `true`  | Render the node in isolation                         |
+
+> **Export URL expiry:** export URLs expire in **30 days**. Download immediately, then rename each file by purpose.
+
+---
+
+### Tier 2 — Download the Design Context Asset URLs
+
+**Use when:** Tier 1 is unavailable, but `figma_get_design_context` returned asset URLs for the node.
+
+```bash
+curl -sL "<asset-url-from-design-context>" -o src/assets/images/hero-background.png
+curl -sL "<asset-url-from-design-context>" -o src/assets/icons/logo.svg
+```
+
+Where the URLs appear in the response:
+
+- the JSON block of download URLs accompanying the reference code, and
+- `const imgXxx = "…";` declarations at the top of the generated code, referenced by `<img src={imgXxx} />` or `background-image`
+
+**Limitations:** these are renderer outputs, not originals — vectors may come back rasterized, and the URLs expire (a desktop-server URL dies when the Figma desktop app closes; a remote-server URL expires after a short time). Download before doing anything else, rename descriptively, and flag them in the manifest:
+
+```typescript
+// TODO: re-export via Tier 1 REST API once FILE_KEY and FIGMA_TOKEN are available
+heroBg: '/assets/images/hero-background.png',
+```
+
+---
+
+### Tier 3 — `figma_get_screenshot` per Node
+
+Address the node the same way as in Phase 1 (`figma-exploration.md § Before the First Call`):
+
+```
+// Remote server
+figma_get_screenshot({ fileKey: "<fileKey>", nodeId: "<nodeId>", maxDimension: 2048 })
+// Desktop server: the node ID (check the image), or ask the user to select the layer
+figma_get_screenshot({ nodeId: "<nodeId>", maxDimension: 2048 })
+figma_get_screenshot({})
+```
+
+If the response is a URL, download it straight into the assets directory (it is short-lived); if the image comes back inline, save it from there. Raise `maxDimension` for detail.
+
+**Limitations:** a render, not a source file; vectors are rasterized; may include surrounding canvas. Label them:
+
+```typescript
+// TODO: re-export at higher fidelity via Tier 1 — current version is a node render
+heroBg: '/assets/images/hero-background.png',
+```
+
+---
+
+### Tier 4 — CSS Fallback (Last Resort Only)
+
+**Use only when** the layer is confirmed to be a pure color fill or gradient — never because extraction felt difficult.
+
+```css
+.hero-banner {
+  /* TODO: replace with real asset — extraction blocked (no REST token and no design-context asset URL) */
+  background: linear-gradient(135deg, #0d1b3e 0%, #1a0533 100%);
+}
+```
+
+Include every Tier 4 use in the post-session handoff notes.
+
+---
+
+## Step 4 — Build an Asset Manifest
+
+```typescript
+// src/app/<page>/_assets.ts — generated during Phase 1h
+
+export const PAGE_ASSETS = {
+  // Figma node 123:456 — "Hero/Background"  · Tier 1 REST API PNG @2×
+  heroBg: '/assets/images/hero-background.jpg',
+
+  // Figma node 789:012 — "_Logo/Main"       · Tier 1 REST API SVG
+  logo: '/assets/icons/logo.svg',
+
+  // Figma node 345:678 — "Card/Thumbnail"   · Tier 2 (TODO: re-export)
+  cardThumbnail: '/assets/images/card-thumbnail.png',
+} as const;
+```
+
+Name files by layer purpose, never by node ID.
+
+---
+
+## Step 5 — Using Assets in Web Components Views
+
+### Static images in a Lit template
+
+```typescript
+import { PAGE_ASSETS } from './_assets.js';
+
+render() {
+  return html`
+    <img
+      src=${PAGE_ASSETS.heroBg}
+      alt="Dashboard hero background"
+      width="1440" height="600"
+      fetchpriority="high"
+    />
+  `;
+}
+```
+
+Always set `width`/`height` (or a CSS aspect ratio) to avoid layout shift, and `alt` for the Phase 5g accessibility check. Use `loading="lazy"` for below-the-fold images and `fetchpriority="high"` for the LCP image.
+
+### Background images in component styles
+
+```typescript
+static styles = css`
+  .dashboard-hero {
+    background-image: url('/assets/images/hero-background.jpg');
+    background-size: cover;
+    background-position: center;
+  }
+`;
+```
+
+> **Use root-absolute paths inside `css`.** A Lit `css` template is not a stylesheet file on disk — relative URLs resolve against the *document*, not the component, so `url('../x.png')` breaks on nested routes. Either use `/assets/...`, or let the bundler hash the asset:
+>
+> ```typescript
+> import heroUrl from '../../assets/images/hero-background.jpg';
+> // then: style=${`background-image:url(${heroUrl})`} or a CSS custom property
+> ```
+
+### Images inside Ignite UI components
+
+Use the component's slot rather than absolute positioning:
+
+```html
+<igc-card>
+  <igc-card-media><img src="/assets/images/card-thumbnail.png" alt="" /></igc-card-media>
+</igc-card>
+
+<igc-avatar src="/assets/images/person.jpg" alt="Jane Doe"></igc-avatar>
+```
+
+### Icons are registered, not extracted
+
+```typescript
+import { registerIconFromText } from 'igniteui-webcomponents';
+import logoSvg from '../../assets/icons/logo.svg?raw';   // Vite: ?raw gives the SVG text
+
+registerIconFromText('brand-logo', logoSvg, 'app');
+```
+
+```html
+<igc-icon name="brand-logo" collection="app"></igc-icon>
+```
+
+Registering an extracted SVG lets it inherit `color` and the theme, which a plain `<img>` cannot. See `figma-component-map.md § Icons` for the Material Icons Extended setup.
+
+---
+
+## Pitfalls
+
+| Pitfall                                                      | Consequence                                                      | Fix                                                                                 |
+| ------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Skipping asset extraction (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                  | Falls back to Tier 2/3 when Tier 1 was possible                  | Reuse the Phase 1 file key, or ask for it in Step 1, and ask for a REST token      |
+| Leaving design-context or CDN URLs in source code            | URLs expire in hours to 30 days; production breaks               | Download during the session; reference only local paths                              |
+| Naming assets by node ID (`node-123-456.png`)                | Unmaintainable                                                   | Name by purpose: `hero-background.jpg`, `company-logo.svg`                            |
+| Relative `url()` inside a Lit `css` template                 | 404s on nested routes — the URL resolves against the document     | Use `/assets/...` or a bundler import                                                |
+| Putting assets in `src/` in a stock Vite app                 | Served in dev, but not emitted by `vite build` unless imported or copied (the Ignite UI CLI scaffold copies `src/assets`); 404 in production | Use `public/`, or import the asset so the bundler emits it                            |
+| Using a node screenshot for an SVG logo                      | Rasterized logo, no scaling, no theming                          | Tier 1 Method B with `format=svg`                                                     |
+| Exporting PNG at `scale=1`                                   | Blurry on HiDPI screens                                          | Always `scale=2`                                                                      |
+| `svg_outline_text=true` (the default)                        | Text converted to paths; larger file; no accessibility           | Set `svg_outline_text=false`                                                          |
+| Extracting kit component instances as images                 | A static picture instead of a working component                  | Check Table A / `figma-component-map.md` — those are components, whatever kit they came from |
+| Extracting registerable icons as PNGs                        | Icons cannot inherit theme color                                 | Register the SVG and use `<igc-icon>`                                                 |
+| Extracting background colors or gradients as images          | Bundle bloat, breaks theming                                     | Colors → palette variables and component tokens                                       |
+| Not creating asset directories before `curl`                 | Silent failures or files in the wrong place                      | `mkdir -p` first                                                                      |

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

@@ -0,0 +1,199 @@
+# Design Provenance — Recognizing Components From Any UI Kit
+
+> **Part of the [`igniteui-wc-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 tag. 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 Web Components choice |
+| --- | --- | --- |
+| **Badge** (shadcn, Untitled UI, Bootstrap) | A text pill / status label | `igc-badge` with slotted text for short status; `igc-chip` when removable or selectable |
+| **Badge** (Material, Fluent) | Dot or count on another element | `igc-badge` positioned over the host |
+| **Dropdown** | A form field in some kits, a menu in others | `igc-select` (field) vs `igc-dropdown` (menu) |
+| **Select** with search (shadcn Combobox, Ant Select `showSearch`) | Filterable single select | `igc-combo single-select` |
+| **Tabs** styled as a pill track (shadcn, Fluent "segmented") | Either view switching or a value toggle | `igc-tabs` if it switches panels; `igc-button-group` if it sets a value |
+| **Sheet** / **Drawer** (overlay) | Temporary side panel | `igc-nav-drawer` for navigation. There is no dedicated sheet component: for content panels use `igc-dialog` or custom markup, and record it as an anatomy delta |
+| **Alert** | Inline message (not modal) | `igc-banner`, or semantic HTML for static callouts |
+| **Toast** vs **Snackbar** | Transient message | `igc-toast` (text only) or `igc-snackbar` (with action) |
+| **Card** with complex internal layout | A surface container | `igc-card` only if header/content/actions anatomy fits; otherwise a Table B surface |
+| **Navigation rail** | Icon-only side nav | `igc-nav-drawer position="relative"` with the `mini` slot, and **without** `open`. The rail is hidden while the drawer is open |
+| **Tab bar** at the bottom (iOS, M3 navigation bar) | App-level navigation | No bottom navigation in Web Components. Use `igc-tabs` or custom markup and document the substitution |
+
+---
+
+## 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.