igniteui-webcomponents 7.3.2 → 7.4.1

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

@@ -0,0 +1,363 @@
+# MCP Server Setup — All Four Servers
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> This file contains setup instructions for all four MCP servers required by this skill. Configure all four before running the Figma-to-app workflow.
+
+---
+
+## Overview
+
+| Server                                     | Purpose                                             | Verify with                                    |
+| ------------------------------------------ | --------------------------------------------------- | ---------------------------------------------- |
+| **Figma**                                  | Read artboard structure, screenshots, design tokens | Tool listed; configured URL (no call)          |
+| **Ignite UI CLI** (`igniteui-cli`)         | Component docs, API reference                       | `list_components`                              |
+| **Ignite UI Theming** (`igniteui-theming`) | Palette + component-level theming code              | `theming_detect_platform`                      |
+| **Playwright**                             | Browser automation, screenshots, DOM measurement    | `playwright_browser_navigate` to `about:blank` |
+
+> **Fast path for the two Ignite UI servers:** run `npx -y igniteui-cli ai-config` in the project root. It configures `igniteui-cli` **and** `igniteui-theming` and copies the Agent Skills, preserving existing entries. Projects created with `npx igniteui-cli new --framework=webcomponents` already have both, in the config file of the assistant chosen with `--assistants` (`.mcp.json` by default) — they normally need only Figma and Playwright added.
+
+---
+
+## 1. Figma MCP
+
+Figma provides two official MCP servers. Both are HTTP servers — there is **no npm package** to install for either one. Source: https://developers.figma.com/docs/figma-mcp-server/
+
+| Server | URL | Authentication | How tools find a node |
+| --- | --- | --- | --- |
+| **Desktop** (local) | `http://127.0.0.1:3845/mcp` | None — the Figma desktop app must be running with the server enabled | The **file open in the desktop app**: the current selection, or the node ID taken from a pasted frame link |
+| **Remote** | `https://mcp.figma.com/mcp` | Figma OAuth sign-in on first use | A **link** to a frame or layer, from which the file key and node ID are taken. No selection |
+
+Prefer the **remote** server when the user can share file links: you can move between artboards without asking the user to click anything. Use the **desktop** server when the file is only available in the user's desktop app.
+
+### Desktop server
+
+1. In the Figma desktop app, open the design file and switch to **Dev Mode**.
+2. In the inspect panel's **MCP server** section, select **Enable desktop MCP server**. A confirmation appears at the bottom of the screen.
+3. Add the server to the client:
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "figma-desktop": {
+      "type": "http",
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+```
+
+**JetBrains IDEs:** **Settings → Tools → AI Assistant → MCP Servers → + Add MCP Server**, then add an HTTP server with the URL `http://127.0.0.1:3845/mcp`.
+
+Official guide: https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+
+### Remote server
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}
+```
+
+**Cursor:** use the one-click install link from Figma's guide, or add the same URL as an HTTP server in `.cursor/mcp.json`.
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+The client opens Figma's OAuth flow the first time a tool is called.
+
+Official guide: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+
+> Neither server needs a secret in the config file, so both entries are safe to commit.
+
+### Personal access token (REST API only)
+
+The MCP servers do **not** use a personal access token. You need one only for the Figma **REST API** calls in this skill: Tier 1 asset export (`asset-extraction.md`) and reading exact variant properties (`design-provenance.md § Step 1`).
+
+1. Figma → avatar → **Settings** → **Security** → **Personal access tokens** → **Generate new token**, with read access to file content.
+2. Ask the user to export it in the shell that runs the agent (`export FIGMA_TOKEN=…`). **Never** write it into a project file, `mcp.json`, or source control.
+
+Without a token, asset extraction falls back to Tier 2/3 and variant properties come from the design context only.
+
+### Verifying Figma MCP
+
+Check that the Figma tools (`figma_get_metadata`, `figma_get_design_context`, …) are listed. Do not spend a call just to verify: View/Collab seats have very small quotas. Tell which server is connected from its **configured URL** (`127.0.0.1:3845` → desktop, `mcp.figma.com` → remote); see `figma-exploration.md` for how each is driven.
+
+> **Rate limits** (per seat; 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 on Starter and Professional, and 600/day on Organization and Enterprise, with per-minute caps of 10–20. Use `figma_get_metadata` for structural discovery and `figma_get_design_context` only for target artboards to conserve quota.
+
+### Troubleshooting Figma MCP
+
+| Problem                               | Fix                                                                                                                       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `figma_get_metadata` returns an error | Desktop: the Figma desktop app is closed, the server is not enabled in Dev Mode, or no file is open. Remote: sign in again through OAuth |
+| Tools not available after config      | Restart the editor/IDE                                                                                                    |
+| `File not found`                      | Verify the Figma file URL and your access; `/design/` URLs only (not `/board/`, `/make/`)                                  |
+| Monthly/daily call quota exceeded     | A View/Collab seat allows 6 calls/month (20 on Starter) — use a Dev/Full seat, or the Figma REST API with a personal access token for metadata and assets |
+
+---
+
+## 2. Ignite UI CLI MCP (`igniteui-cli`)
+
+> Projects created with `npx igniteui-cli new` already have this configured. For existing projects, `npx -y igniteui-cli ai-config` sets up this server and the theming server in one step. Use the manual steps below only when `ai-config` is unavailable or does not cover your editor.
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "igniteui-cli": {
+      "command": "npx",
+      "args": ["-y", "igniteui-cli", "mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "igniteui-cli": {
+      "command": "npx",
+      "args": ["-y", "igniteui-cli", "mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add igniteui-cli -- npx -y igniteui-cli mcp
+```
+
+### JetBrains IDEs
+
+1. **Settings → Tools → AI Assistant → MCP Servers → + Add MCP Server**
+2. Command: `npx`, Arguments: `-y igniteui-cli mcp`
+
+### Verifying Ignite UI CLI MCP
+
+Ask: *"List all available Ignite UI Web Components."* The `list_components` tool should return the catalog for `framework: "webcomponents"`.
+
+Tools this skill relies on: `list_components`, `get_doc`, `search_docs`, `search_api`, `get_api_reference`, `get_project_setup_guide`.
+
+---
+
+## 3. Ignite UI Theming MCP (`igniteui-theming`)
+
+> `npx -y igniteui-cli ai-config` configures this server too (see section 2).
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "igniteui-theming": {
+      "command": "npx",
+      "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "igniteui-theming": {
+      "command": "npx",
+      "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add igniteui-theming -- npx -y igniteui-theming igniteui-theming-mcp
+```
+
+### JetBrains IDEs
+
+1. **Settings → Tools → AI Assistant → MCP Servers → + Add MCP Server**
+2. Command: `npx`, Arguments: `-y igniteui-theming igniteui-theming-mcp`
+
+### Verifying Ignite UI Theming MCP
+
+Ask: *"Detect which Ignite UI platform my project uses."* `detect_platform` should analyze `package.json` and return `webcomponents`.
+
+Tools this skill relies on: `detect_platform`, `create_palette`, `create_custom_palette`, `create_typography`, `create_elevations`, `create_theme`, `get_component_design_tokens`, `create_component_theme`, `get_color`, `get_chart_series_colors`, `set_size`, `set_spacing`, `set_roundness`, `read_resource`.
+
+---
+
+## 4. Playwright MCP
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add playwright -- npx -y @playwright/mcp@latest
+```
+
+### JetBrains IDEs
+
+1. **Settings → Tools → AI Assistant → MCP Servers → + Add MCP Server**
+2. Command: `npx`, Arguments: `-y @playwright/mcp@latest`
+
+### Verifying Playwright MCP
+
+Ask: *"Navigate the browser to `about:blank`."* `playwright_browser_navigate` should open the page without error.
+
+### Troubleshooting Playwright MCP
+
+| Problem                                               | Fix                                                                                     |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Screenshots are blank                                 | Make sure the dev server is running (`npm start`; Vite defaults to port 5173)             |
+| Page resets to `about:blank` after resize             | Always re-navigate after `playwright_browser_resize`                                      |
+| `ERR_CONNECTION_REFUSED`                              | The dev server is not running, or the port differs from 5173                               |
+| `browser_evaluate` fails with *"Invalid input: expected string, received undefined"* | Pass code via the `function` parameter, not `script`                                       |
+| Selector returns `null` for something clearly visible | It is inside a shadow root — use the deep-query helper in `validation-patterns.md`         |
+| Element measures `0` height                           | Measured before upgrade/render, or the host lacks `display: block` — see the same file     |
+
+---
+
+## Combined JSON Config (All Four Servers)
+
+> **If your project was created with `npx igniteui-cli new`:** `igniteui-cli` and `igniteui-theming` are already in your client's config file (the one chosen with `--assistants`; `.mcp.json` by default). Add only the Figma and Playwright entries below — do not duplicate the others.
+>
+> **Fresh setup:** use the complete blocks below. They use Figma's **remote** server; for the desktop server, replace the `figma` entry with the desktop entry from section 1 (`http://127.0.0.1:3845/mcp`). No Figma token belongs in these files.
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    },
+    "igniteui-cli": {
+      "command": "npx",
+      "args": ["-y", "igniteui-cli", "mcp"]
+    },
+    "igniteui-theming": {
+      "command": "npx",
+      "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp"
+    },
+    "igniteui-cli": {
+      "command": "npx",
+      "args": ["-y", "igniteui-cli", "mcp"]
+    },
+    "igniteui-theming": {
+      "command": "npx",
+      "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### Claude Code (`.mcp.json` in the project root)
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    },
+    "igniteui-cli": {
+      "command": "npx",
+      "args": ["-y", "igniteui-cli", "mcp"]
+    },
+    "igniteui-theming": {
+      "command": "npx",
+      "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+> Newly added MCP servers require an editor or session reload before their tools appear.

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

@@ -0,0 +1,105 @@
+# Project Detection and Scaffolding
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 0b to detect an existing Ignite UI Web Components project or scaffold a new one, and in Phase 4 for the view layout and file structure ([Implementation Layout](#implementation-layout)). Read the setup part in full before checking the project or running `igniteui-cli new`.
+
+Check whether the current working directory contains a valid Web Components + Ignite UI project:
+
+```
+1. Does package.json exist?
+2. Does it list "igniteui-webcomponents" in dependencies?
+3. Is there a src/ directory with an entry module (src/index.ts, src/main.ts, or similar)?
+```
+
+## If a valid project is found
+
+- Note the package layout: `igniteui-webcomponents` (MIT). Commercial packages — `igniteui-webcomponents-grids` (trial) / `@infragistics/igniteui-webcomponents-grids` (licensed) , `igniteui-webcomponents-charts` (trial) / `@infragistics/igniteui-webcomponents-charts` (licensed), `igniteui-webcomponents-core` (trial) / `@infragistics/igniteui-webcomponents-core` (licensed), `igniteui-dockmanager` (trial) / `@infragistics/igniteui-dockmanager` (licensed).
+- Note the host setup: plain Lit/vanilla app, or a framework wrapper (React/Angular/Vue). If a wrapper is in play, registration and event binding follow [`igniteui-wc-integrate-with-framework`](../../igniteui-wc-integrate-with-framework/SKILL.md), not the raw `defineComponents` pattern.
+- Note whether **Sass** is configured (a `.scss` entry file, `sass` in `devDependencies`, or a bundler Sass plugin). This decides the Phase 3 output format — CSS or Sass.
+- **Check the MCP configuration for all four required server entries** — a Figma entry (`figma` or `figma-desktop`), `igniteui-cli`, `igniteui-theming`, and `playwright`, in the config file your client reads (`.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json`, …). If `igniteui-cli` or `igniteui-theming` is missing, run `npx -y igniteui-cli ai-config` (or `ig ai-config` when `igniteui-cli` is installed globally) from the project root yourself — it configures both servers and copies the Agent Skills, preserving existing entries. Add a missing Figma entry and `playwright` from [mcp-setup.md](mcp-setup.md). Projects scaffolded with `npx igniteui-cli new` already have `igniteui-cli` **and** `igniteui-theming` wired; they typically lack Figma and Playwright. A reload is required before newly configured servers' tools appear: ask the user to reload, then stop.
+- Inform the user: "Found existing Ignite UI Web Components project. Proceeding with the Figma workflow."
+
+## If no valid project is found
+
+Present this message and wait for the user's choice:
+
+> "No Ignite UI Web Components project found in the current directory. Would you like me to scaffold a new one using the Ignite UI CLI before implementing the Figma design?
+>
+> `npx -y igniteui-cli new` creates a Vite + Lit + TypeScript project pre-configured with `igniteui-webcomponents`, a starter theme, and the Ignite UI CLI and Theming MCP servers configured for your coding assistant. No global install required.
+>
+> Alternatively, point me at an existing project directory."
+
+If the user confirms scaffolding:
+
+1. Ask for a project name. If the user has already shared a Figma URL, suggest a name derived from the Figma file name; otherwise prompt.
+
+2. Choose the project template based on the artboard structure. Because Phase 1 has not run yet, use the lightest signal available:
+
+   | Signal                                                      | Template to use                                  |
+   | ----------------------------------------------------------- | ------------------------------------------------ |
+   | User mentions a persistent sidebar or multiple routed views | `side-nav`                                       |
+   | User mentions an icon-rail / collapsible sidebar            | `side-nav-mini`                                  |
+   | No strong signal — default                                  | `empty` (routing + home page; easiest to extend) |
+
+3. Create the project:
+
+   ```bash
+   npx -y igniteui-cli new <project-name> --framework=webcomponents --type=igc-ts --template=<empty|side-nav|side-nav-mini> --assistants=<generic|vscode|cursor|gemini|junie> --agents=<generic|claude|copilot|cursor|…>
+   ```
+
+   `--assistants` picks the MCP config file: `generic` → `.mcp.json` (the default; Claude Code, GitHub Copilot, and others), `vscode` → `.vscode/mcp.json`, `cursor` → `.cursor/mcp.json`, `gemini` → `.gemini/settings.json`, `junie` → `.junie/mcp/mcp.json`. `--agents` picks where the Agent Skills are copied (`generic` → `.agents/skills`, `claude` → `.claude/skills`, `copilot` → `.github/skills`, …). Pass both: without them the CLI asks interactively.
+
+   This produces a standard Vite workspace and additionally:
+   - Installs and configures `igniteui-webcomponents` and `lit`, with a starter theme: a `<link>` in `index.html` to `themes/light/bootstrap.css` or `themes/light/material.css`, depending on the template (Phase 3a treats it as "no theme")
+   - Wires `@vaadin/router` routing in `src/app/app-routing.ts`
+   - Runs the `ai-config` setup: adds the `igniteui-cli` **and** `igniteui-theming` MCP servers to the chosen assistant's config file, and copies the Agent Skills for the chosen agents
+   - Copies static assets from `src/assets` via `vite-plugin-static-copy`
+
+4. `cd <project-name>`.
+
+5. Add the Figma and Playwright entries from [mcp-setup.md](mcp-setup.md) to the same config file the scaffold wrote (the one for `--assistants`).
+
+6. Confirm the project builds:
+   ```bash
+   npm run build
+   ```
+   Do not run `npm start` in the foreground: the Vite dev server never exits. Start it in the background, or ask the user to run it, when Phase 5 needs it (default `http://localhost:5173`).
+
+7. The new servers and the new folder only take effect in a new session. Ask the user to **reopen the editor or agent session in the new project folder**, then stop. Phase 1 continues in that session.
+
+## Implementation Layout
+
+Used in Phase 4.
+
+### Layout Strategy
+
+Translate Figma frame dimensions into CSS Grid first:
+
+```css
+/* Artboard: 1440×900px, sidebar 280px, content 1160px */
+.app-layout {
+  display: grid;
+  grid-template-columns: 280px 1fr;
+  grid-template-rows: 64px 1fr;
+  min-height: 100vh;
+}
+```
+
+Match desktop proportions before adding responsive breakpoints.
+
+> A Lit component's host is `display: inline` by default — set `:host { display: block }` (or `grid`/`flex`) or the layout collapses. Charts and grids inside a flexible grid track need an explicit height on both the track and the element.
+
+### Project Structure
+
+For a new view generated from a Figma artboard in a CLI-scaffolded project:
+
+```
+src/app/
+  <artboard-name>/
+    <artboard-name>.ts        ← Lit component: template, static styles, registration
+    data.ts                   ← typed mock data for the view
+    _assets.ts                ← asset manifest from Phase 1h (when the view has images)
+```
+
+Register the route in `src/app/app-routing.ts` when the project uses routing. In a non-Lit project, follow the structure already in the repository.

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

@@ -0,0 +1,180 @@
+# Theme Generation
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 3 to generate the global theme and per-component tokens. Read in full, together with [`design-token-bridge.md`](design-token-bridge.md), before calling any theming tool.
+
+> **Tool names:** like SKILL.md, this file writes theming tools as `theming_<tool>`. Match by the tool's base name (`create_palette`, `create_theme`, `create_component_theme`, …) on the connected `igniteui-theming` server; your client may show them as `mcp__igniteui-theming__create_palette` or similar. The `licensed` parameter is for Angular only — do not pass it for Web Components.
+
+**Goal:** produce theming code that matches the Figma design's visual language, using the kit variables from Phase 1e (Path A) or the color census and measurements from Phase 1d (Path B).
+
+> **Output format decision — make it once, here.** Pass `output: "css"` (the default) when the project has no Sass; pass `output: "sass"` only when Phase 0b found a Sass setup. Every theming tool that generates code (`create_*`, `set_size`, `set_spacing`, `set_roundness`) accepts `output`. Do not emit Sass into a project that cannot compile it, and do not use the Angular-only `core()` / `theme()` mixins — the Web Components Sass API uses `igniteui-theming` with individual `palette()`, `typography()`, `elevations()`, and `spacing()` mixins.
+
+## 3a: Inspect the Existing Theme (Guard)
+
+Check **all three** places a theme can come from: `index.html`, the app entry point (`src/index.ts` / `main.ts`), and the global stylesheet (`styles.css` or the project's equivalent). Look for:
+
+- a pre-built theme import or `<link>`, such as `igniteui-webcomponents/themes/dark/material.css`
+- `--ig-theme` / `--ig-theme-variant` declarations on `:root`
+- a `configureTheme(...)` call
+- existing palette overrides (`--ig-primary-500`, …) or app-level semantic variables
+
+Then classify what you found:
+
+| Found | Meaning | Action |
+| --- | --- | --- |
+| Nothing | No theme | Continue with 3b–3c |
+| Only the CLI scaffold's theme: a `<link rel="stylesheet" href="./node_modules/igniteui-webcomponents/themes/light/<bootstrap\|material>.css">` in `index.html` (the template decides which), with no `--ig-*` palette overrides and no `configureTheme` call | The scaffold's starter theme, not a choice made for this app | Treat it as no theme. In 3c, **replace** that `<link>` with the resolved design system and variant; never load two pre-built themes |
+| Any other theme | A theme the app's authors chose | Keep it for now. Finish the comparison below after 3b |
+
+**Existing app theme — compare after 3b.** Reuse it, and skip to 3d, only when **all three** match the design:
+
+1. the light/dark **variant** (the import path, or `--ig-theme-variant`);
+2. the **design system** (the import path, or `--ig-theme`);
+3. the **primary color**: the seed color on the high-emphasis controls, as seen in the design (Path A: the kit variables; Path B: the color census).
+
+If any of them differs, **ask the user** before changing the global theme. It affects every existing view in the app. If the user declines, scope the design's palette overrides, type-style variables, and component tokens to the new view's host selector instead of `:root`. The design system and variant cannot be scoped: components read `--ig-theme` and `--ig-theme-variant` from the document root. Pass the app's `designSystem` / `variant` to `create_component_theme`, and tell the user which anatomy differences will remain.
+
+Detect the Figma design's variant from Phase 1e: if a `color/mode` variable exists, use its value. Otherwise use the artboard background color: near-black (`#121212`, `#1a1a1a`, `#000`) → `"dark"`; near-white (`#fff`, `#f5f5f5`) → `"light"`.
+
+## 3b: Resolve the Design System
+
+**Choose the path from the dominant Phase 1f tier** (see `design-token-bridge.md § Two Paths`):
+
+- **Path B (mostly Tier B/C):** the design system is the **closest baseline**, not a match. Choose it with `design-token-bridge.md § B1`, in this order: the user's request, then the kit's direct counterpart (Material 3 → `material`, Fluent 2 → `fluent`, Bootstrap → `bootstrap`), then text-field label placement, then control heights. A design whose fields have labels *above* them should not get `material`. Then continue: apply B2–B4 in 3c and B5–B8 in 3d.
+- **Path A (mostly Tier A):** use this **strict precedence order**. Stop at the first signal that gives a clear answer:
+
+1. **Explicit user request** — "make it Material", "use Fluent", etc.
+2. **Library source name in design context** — the `figma_get_design_context` or `figma_get_metadata` response may reference the source library file name (e.g. `"Indigo.Design UI Kit for Material"` → `material`).
+3. **Variable collection names from Phase 1e** — collection names like `Material/color/primary` identify the kit variant directly.
+4. **Elevation variable structure** — inspect the `Elevations/*` variables:
+   - **Three-layer DROP_SHADOW** (umbra + penumbra + ambient) → **Material**
+   - **Single-layer DROP_SHADOW** → Indigo, Fluent, or Bootstrap
+5. **Palette shade naming** — `primary/500`, `primary/100`–`primary/900` follows the Material 100–900 convention → likely **Material**.
+6. **Visual heuristics** (only when all above are inconclusive): layered shadows + ripple effects → `"material"`; flat surfaces + sharp corners + Segoe/Inter font → `"fluent"`; component borders + Bootstrap grid → `"bootstrap"`; rounded purple/indigo accents without Material shadows → `"indigo"`.
+
+> **Never use font name as a primary signal.** "Titillium Web" is the default body font in the Indigo.Design UI Kit for Material — it is not exclusive to any single kit variant.
+
+Supported values: `material`, `bootstrap`, `fluent`, `indigo`.
+
+> **Web Components read the active design system from CSS variables for the initial theme.** Components read `--ig-theme` and `--ig-theme-variant` (falling back to `bootstrap` / `light` when absent). A generated palette alone does **not** switch the design system — use the pre-built theme CSS or generated `:root` block for that. `configureTheme(ds, variant)` switches registered components at runtime but does not rewrite those root variables.
+
+## 3c: Generate the Global Theme
+
+Extract the following using [design-token-bridge.md](design-token-bridge.md):
+
+```
+Path A (Indigo.Design kits) — from Phase 1e variables:
+primaryColor    ← from "color/primary/500" or "primary/500"
+secondaryColor  ← from "color/secondary/500" or "secondary/500"
+surfaceColor    ← from "color/surface" or "surface/default"
+fontFamily      ← from "typography/font-family" or "typography/body/font-family"
+
+Path B (any other kit, or none) — from the Phase 1d color census (`design-token-bridge.md § B2`):
+primaryColor    ← color painted on high-emphasis buttons / active indicators
+secondaryColor  ← a second accent actually used, else = primary
+                  (material baseline: controls use secondary — seed it with the button color)
+surfaceColor    ← page background
+fontFamily      ← family of the text styles in use
+type overrides  ← kit type ramp by role (`design-token-bridge.md § B3`), incl. button text transform (§ B4)
+```
+
+Read the theming guidance resources before generating, so you extract only values the theme system actually accepts:
+
+```
+theming_read_resource({ uri: "theming://guidance/colors/rules" })   // luminance + variant rules
+theming_read_resource({ uri: "theming://platforms/webcomponents" }) // platform specifics
+```
+
+> **Parameter names differ between tools** — `theming_create_palette` uses `primary`, `secondary`, `surface`, `gray`, `success`, `warn`, `error`, `info`, and `variant`. `theming_create_theme` uses `primaryColor`, `secondaryColor`, `surfaceColor`, and has no `gray` or status colors. Do not mix them up.
+
+**CSS path (default — no Sass in the project):**
+
+1. Load the pre-built theme CSS for the resolved design system and variant — in the app entry point, or by replacing the scaffold's `<link>` in `index.html` (per 3a). This sets `--ig-theme`, `--ig-theme-variant`, the full palette, typography, and elevations in one line:
+
+   ```typescript
+   import 'igniteui-webcomponents/themes/dark/material.css';
+   ```
+
+2. Generate the palette overrides from the seed colors (add `gray` and the status colors when the design needs them):
+
+   ```
+   theming_create_palette({
+     primary: primaryColor,
+     secondary: secondaryColor,
+     surface: surfaceColor,
+     variant: "<light|dark>",
+     platform: "webcomponents",
+     output: "css"
+   })
+   ```
+
+   Apply the generated custom properties to `:root` in the global stylesheet. The overrides must load **after** the theme: load both through the same mechanism, in order — import the theme CSS and then `styles.css` from the entry module, or put both as `<link>` tags in `index.html`, theme first. (Vite injects CSS imported from JS after any `<link>` in `index.html`, so mixing the two can let the theme win.)
+
+3. Apply the font family with plain CSS (`--ig-font-family` or `font-family`) or the CSS output of `theming_create_typography({ fontFamily, designSystem, platform: "webcomponents", output: "css" })`. Do not pass `customScale`: the tool accepts it but its generators ignore it. Do not emit Sass typography mixins into a CSS-only app.
+
+4. Read and act on any **luminance warning** the palette tools return. When the design has several distinct surface depths that one generated surface color cannot express, use `theming_create_custom_palette`, or define semantic variables (`--surface-1`, `--surface-2`) for the extra depths.
+
+**Sass path (only when Sass is configured):**
+
+```
+theming_create_theme({
+  platform: "webcomponents",
+  designSystem: "<resolved design system>",
+  primaryColor, secondaryColor, surfaceColor,
+  variant: "<light|dark>",
+  fontFamily,
+  includeTypography: true,
+  includeElevations: true,
+  includeSpacing: true,
+  output: "sass"
+})
+```
+
+`theming_create_theme` emits the `@use 'igniteui-theming'` imports, the `palette()` / `elevations()` / `typography()` / `spacing()` mixin calls, and the `:root` block with `--ig-theme` and `--ig-theme-variant`. Apply its output as instructed in the response. For `gray`, status colors, or a full custom ramp, add the output of `theming_create_palette` or `theming_create_custom_palette` **after** it; its `:root` palette variables override the generated ones. Remove the scaffold's theme `<link>` from `index.html` (3a), so only one theme loads.
+
+> `theming_create_elevations` takes **`designSystem`** (`"material"` or `"indigo"`) — there is no `preset` parameter.
+
+**Path B type overrides (both paths).** After the theme, add a `:root` block that sets the `--ig-<style>-<property>` variables for the type styles that differ from the baseline, including the button's text transform. See `design-token-bridge.md § B4`.
+
+**Runtime switching.** When the design needs light and dark at runtime, swap the pre-built stylesheet (or the palette block) **and** call the library API with the same design system and variant. Components cache the design system they read from `--ig-theme` on first use, so neither step alone switches both the palette and the component styles:
+
+```typescript
+import { configureTheme } from 'igniteui-webcomponents';
+// after loading the dark material stylesheet:
+configureTheme('material', 'dark');
+```
+
+**Grid and chart packages carry their own themes.** The premium grids need `igniteui-webcomponents-grids/grids/themes/<variant>/<design-system>.css` in addition to the core theme, and inside a Lit component that CSS must be imported `?inline` and injected into the shadow root:
+
+```typescript
+import gridTheme from 'igniteui-webcomponents-grids/grids/themes/dark/material.css?inline';
+// in render(): html`<style>${gridTheme}</style> <igc-grid ...></igc-grid>`
+```
+
+## 3d: Per-Component Token Mapping
+
+> **Scope:** applies to every Ignite UI family that exposes design tokens — card, inputs, select, combo, navbar, nav drawer, list, tabs, date pickers, chips, grids, etc. Charts, gauges, and maps have **no design tokens**; configure those through component properties (see 3e).
+
+For **every** Ignite UI component in your plan, run this loop:
+
+1. `theming_get_component_design_tokens({ component: "<theme-key>" })` — review all token names, types, and descriptions, plus any **related themes** listed for compound components. Theme keys are not always the tag name: inputs are `input-group`, the nav drawer is `navdrawer`, progress bars are `progress-linear` / `progress-circular`, a single-select combo is `simple-combo`, and buttons need the variant name (`contained-button`, `flat-icon-button`, …). See `design-token-bridge.md § Per-Component Token Resolution` for the full map.
+2. Find the values for this component's surfaces (background, text, border, hover state). **Path A:** from the Phase 1e kit variables. **Path B:** from the Phase 1d color census and measurements. Variables, when they exist, only confirm them.
+3. `theming_create_component_theme({ component: "<theme-key>", platform: "webcomponents", designSystem: "<3b result>", variant: "<light|dark>", tokens: { <only differing tokens> }, output: "css" | "sass" })`. Always pass `designSystem` and `variant`: the tool defaults to Material light and would compute the theme against the wrong schema.
+4. Apply the generated block exactly as returned — to the component selector or to the `selector` you passed. Color token values must reference palette variables (`var(--ig-primary-500)`), never raw hex.
+5. For compound components — any component whose `get_component_design_tokens` result lists related themes (for example `combo`, `select`, the date pickers, `card`, `navbar`, `dialog`, `banner`, and the grids) — follow the related-theme chain from step 1 and theme each child with its scoped selector. Styling only the parent leaves the dropdown or calendar off-theme. Exception: the grid theme **derives** its children (`action-strip`, `column-actions`, toolbar, paginator, …); theme the grid and do not call `create_component_theme` for those keys separately.
+
+**Path B additions to this loop** (see `design-token-bridge.md § B5–B8`): include the component's **radius** tokens at the measured px value, its **border** and **shadow/elevation** tokens as the design shows them, and its hover/focus/disabled **state** tokens from the kit's state variants, in the same `theming_create_component_theme` call. Choose `--ig-size` per component family from the measured control heights (`design-token-bridge.md § B7`) before tuning individual components.
+
+When a specific component needs a different density or spacing from the global default, use `theming_set_size` or `theming_set_spacing` with the `component` parameter — this scopes `--ig-size` or `--ig-spacing` to that component's selector rather than applying globally. For compound components, use `scope` with a sub-component selector. Only apply these globally (`:root`) when the entire app has a clearly distinct density (Path B: when every component family moves the same way, see `design-token-bridge.md § B7`). Leave `theming_set_roundness` at its default unless the user explicitly requests a change. For Path B, express radius through per-component tokens instead, because one global factor cannot reproduce a kit's radii. Never derive multiplier values from Figma pixel values — see `design-token-bridge.md § Spacing, Sizing, and Roundness`.
+
+## 3e: Chart Series Colors
+
+Charts have no design tokens, and they default to their own brush palette — which will not match the Figma series colors. Before implementing any chart:
+
+```
+theming_get_chart_series_colors({ chartType: "<e.g. category-chart>" })
+theming_get_chart_series_colors({ customBrushes: ["#9DE772", "#6DB1FF"] })   // validate Figma colors
+```
+
+The first call lists which theme tokens on that chart type accept a brush list; the second validates the colors you extracted in Phase 1d and flags pairs that are hard to tell apart. Apply the result through the chart's brush properties, assigned on the element: `brushes` / `outlines` on most charts, `brush` on `igc-sparkline`, `fillBrushes` on `igc-treemap`, and `brushes` / `outlines` on each `igc-ring-series` of a doughnut chart.