igniteui-angular 22.2.0-rc.1 → 22.2.0

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

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

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

@@ -2,8 +2,7 @@
 
 > **Part of the [`igniteui-angular-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.
+> This file contains setup instructions for all four MCP servers required by this skill. Configure all four before running the Figma-to-app workflow.
 
 ---
 
@@ -11,7 +10,7 @@
 
 | Server                                     | Purpose                                             | Verify with                                    |
 | ------------------------------------------ | --------------------------------------------------- | ---------------------------------------------- |
-| **Figma**                                  | Read artboard structure, screenshots, design tokens | `figma_get_metadata` (no nodeId)               |
+| **Figma**                                  | Read artboard structure, screenshots, design tokens | `figma_get_metadata` tool schema               |
 | **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` |
@@ -20,141 +19,122 @@
 
 ## 1. Figma MCP
 
-The Figma MCP server connects your AI tool to the Figma desktop app or a Figma file URL.
-It requires a **Figma personal access token**.
+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/
 
-### Get a Figma Access Token
+| 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 |
 
-1. Open Figma → click your avatar (top-right) → **Settings**
-2. Scroll to **Personal access tokens** → **Generate new token**
-3. Give it a name (e.g. `mcp-agent`) → copy the token value
+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.
 
-### VS Code
+### Desktop server
 
-Create or edit `.vscode/mcp.json`:
+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
+```json
 {
   "servers": {
-    "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+    "figma-desktop": {
+      "type": "http",
+      "url": "http://127.0.0.1:3845/mcp"
     }
   }
 }
-~~~
-
-### Cursor
+```
 
-Create or edit `.cursor/mcp.json`:
+**Cursor** (`.cursor/mcp.json`):
 
 ```json
 {
   "mcpServers": {
-    "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
     }
   }
 }
 ```
 
-### Claude Code
+**Claude Code:**
 
 ```bash
-claude mcp add figma -- npx -y @figma/mcp@latest --figma-access-token YOUR_TOKEN_HERE
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
 ```
 
-Or add the entry to the project's `.mcp.json` (created at the repo root):
+**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
 {
-  "mcpServers": {
+  "servers": {
     "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
     }
   }
 }
 ```
 
-### JetBrains IDEs
+**Cursor:** use the one-click install link from Figma's guide, or add the same URL as an HTTP server in `.cursor/mcp.json`.
 
-1. **Settings → Tools → AI Assistant → MCP Servers → + Add MCP Server**
-2. Command: `npx`, Arguments: `-y @figma/mcp@latest`
-3. Environment: `FIGMA_ACCESS_TOKEN=YOUR_TOKEN_HERE`
+**Claude Code:**
 
-### Figma Desktop App Plugin (Recommended)
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
 
-If you use the Figma desktop app, the preferred setup is through the Figma MCP plugin for your editor. Follow Figma's official installation guide: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+The client opens Figma's OAuth flow the first time a tool is called.
 
-This approach connects to the currently open Figma file and the selected node without needing to pass node IDs manually.
+Official guide: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
 
-> **Session-binding behaviour:** The Figma MCP tools (`figma_get_screenshot`,
-> `figma_get_design_context`, `figma_get_variable_defs`) always operate on the
-> **currently selected node in the Figma desktop app**. Any `nodeId` parameter passed
-> to these tools is **silently ignored** — the tool returns data for whatever is
-> selected, not for the specified ID.
->
-> **Consequence:** you cannot programmatically navigate between artboards by passing
-> node IDs. To get screenshots or design context for a specific artboard you **must**
-> ask the user to click that artboard frame in Figma before calling the tool.
->
-> The correct pattern in every Phase 1 step:
-> ```
-> // 1. Ask the user
-> "In Figma, please click the [Artboard Name] frame to select it, then confirm."
-> // 2. Wait for confirmation
-> // 3. Only then call the tool
-> figma_get_screenshot({})
-> figma_get_design_context({ clientLanguages: "typescript", clientFrameworks: "angular", ... })
-> ```
+> Neither server needs a secret in the config file, so both entries are safe to commit.
 
-### Verifying Figma MCP
+### Personal access token (REST API only)
 
-Call `figma_get_metadata` with **no `nodeId`**. It should return either:
+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`).
 
-- A list of top-level pages if something is selected in the Figma desktop app, or
-- A prompt to open a Figma file
+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.
 
-> **Rate limits:** Starter plan: 6 calls/month · Organization: 200/day · Enterprise: 600/day.
-> Use `figma_get_metadata` for structural discovery and `figma_get_design_context` only for
-> target artboards to conserve quota.
+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 | Token may be expired or invalid — regenerate it                                                                           |
+| `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 is correct and you have access                                                                  |
-| 6 calls/month exceeded                | Upgrade to an Organization plan or use the Figma REST API with a personal access token for higher-volume development work |
+| 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.**
-> `npx igniteui-cli new` writes the Ignite UI CLI MCP entry into `.vscode/mcp.json`
-> automatically during scaffolding. For existing projects that lack this config, run:
+> **Projects created with `npx igniteui-cli new` already have this configured.** `npx igniteui-cli new` runs the same setup as `ai-config`: it adds both `igniteui-cli` and `igniteui-theming` to the config file of the assistant chosen with `--assistants` (`.mcp.json` by default). For existing projects that lack this config, run:
 >
 > ```bash
 > npx -y igniteui-cli ai-config
 > ```
 >
-> This configures **both** the `igniteui-cli` and `igniteui-theming` MCP servers and copies
-> the Agent Skills in one step, preserving existing server entries. Only follow the manual
-> steps below (and in section 3) when `npx igniteui-cli ai-config` is not available or you
-> need to configure an editor it does not cover.
+> This configures **both** the `igniteui-cli` and `igniteui-theming` MCP servers and copies the Agent Skills in one step, preserving existing server entries. Agents should run it themselves rather than asking the user to. Only follow the manual steps below (and in section 3) when `npx igniteui-cli ai-config` is not available or you need to configure an editor it does not cover.
+>
+> When `igniteui-cli` is installed globally (`npm install -g igniteui-cli`), `ig ai-config` and `ig mcp` are equivalent to the `npx` commands, and a server entry can use `"command": "ig", "args": ["mcp"]`.
 
 ### VS Code
 
@@ -220,8 +200,7 @@ The `list_components` tool should return a full component list for the Angular f
 
 ## 3. Ignite UI Theming MCP (`igniteui-theming`)
 
-> **`npx -y igniteui-cli ai-config` configures this server too** (see section 2). Use the
-> manual steps below only when `ai-config` is unavailable or doesn't cover your editor.
+> **`npx -y igniteui-cli ai-config` configures this server too** (see section 2). Use the manual steps below only when `ai-config` is unavailable or doesn't cover your editor.
 
 ### VS Code
 
@@ -281,8 +260,7 @@ Or add the entry to the project's `.mcp.json` (created at the repo root):
 
 Ask your AI assistant: _"Detect which Ignite UI platform my project uses."_
 
-The `theming_detect_platform` tool should analyze your `package.json` and return the
-detected platform (e.g., `angular`, `angular-licensed`).
+The `theming_detect_platform` tool should analyze your `package.json` and return the detected platform (`angular`). Licensed projects (`@infragistics/igniteui-angular`) are also detected as `angular`, with `licensed: true`.
 
 ---
 
@@ -344,7 +322,7 @@ Or add the entry to the project's `.mcp.json` (created at the repo root):
 
 ### Verifying Playwright MCP
 
-Navigate to a URL: _"Navigate the browser to `https://example.com`."_
+Navigate to a URL: _"Navigate the browser to `about:blank`."_
 
 The `playwright_browser_navigate` tool should open the page without error.
 
@@ -355,20 +333,18 @@ The `playwright_browser_navigate` tool should open the page without error.
 | Screenshots are blank                                 | Make sure the dev server is running (`npm start`)           |
 | Page resets to `about:blank` after resize             | Always re-navigate after `playwright_browser_resize`        |
 | Console shows `ERR_CONNECTION_REFUSED`                | The Angular dev server is not running                       |
-| `browser_evaluate` fails with `__name is not defined` | Pass code using the `function` parameter (not `script`): `playwright_browser_evaluate({ function: "() => { ... }" })` |
+| `browser_evaluate` fails with _"Invalid input: expected string, received undefined"_ | Pass code using the `function` parameter (not `script`): `playwright_browser_evaluate({ function: "() => { ... }" })` |
 | `playwright_browser_take_screenshot` returns empty    | Re-navigate to the target URL first                         |
 
 ---
 
 ## Combined JSON Config (All Four Servers)
 
-> **If your project was created with `npx igniteui-cli new`:** the Ignite UI CLI entry is already in
-> `.vscode/mcp.json`. Open that file and **add only the three entries below** (Figma,
-> Ignite UI Theming, Playwright) to the existing `"servers"` block — do not duplicate
-> the `igniteui-cli` entry.
+> **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 (no existing `.vscode/mcp.json`):** use the complete blocks below.
-> Replace `YOUR_TOKEN_HERE` with your actual Figma personal access token.
+>
+> The blocks use Figma's **remote** server. To use the desktop server instead, 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`)
 
@@ -376,11 +352,8 @@ The `playwright_browser_navigate` tool should open the page without error.
 {
   "servers": {
     "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
     },
     "igniteui-cli": {
       "command": "npx",
@@ -404,11 +377,7 @@ The `playwright_browser_navigate` tool should open the page without error.
 {
   "mcpServers": {
     "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+      "url": "https://mcp.figma.com/mcp"
     },
     "igniteui-cli": {
       "command": "npx",
@@ -432,11 +401,8 @@ The `playwright_browser_navigate` tool should open the page without error.
 {
   "mcpServers": {
     "figma": {
-      "command": "npx",
-      "args": ["-y", "@figma/mcp@latest"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
-      }
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
     },
     "igniteui-cli": {
       "command": "npx",

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

@@ -0,0 +1,63 @@
+# Project Detection and Scaffolding
+
+> **Part of the [`igniteui-angular-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 0b to detect an existing Ignite UI Angular project or scaffold a new one. Read in full before checking the project or running `igniteui-cli new`.
+
+Check whether the current working directory contains a valid Angular + Ignite UI project:
+
+```
+1. Does package.json exist?
+2. Does it list "igniteui-angular" OR "@infragistics/igniteui-angular" in dependencies?
+3. Is there a src/app/ directory?
+```
+
+**If a valid project is found:**
+
+- Note the package layout: `igniteui-angular` (open-source) or `@infragistics/igniteui-angular` (licensed)
+- Note the Angular version from `package.json`
+- **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 [references/mcp-setup.md](mcp-setup.md). Projects scaffolded with `npx igniteui-cli new` already have `igniteui-cli` **and** `igniteui-theming`; they typically lack Figma and Playwright. A reload is required before newly configured servers' tools appear.
+- Inform the user: "Found existing Ignite UI Angular 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 Angular 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 project pre-configured with Ignite UI Angular, a starter theme (prebuilt CSS or Sass), 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 sidebar, navigation drawer, or multiple routed views | `side-nav`                                       |
+   | No strong signal — default                                           | `empty` (routing + home page; easiest to extend) |
+
+3. Create the project:
+
+   ```bash
+   npx -y igniteui-cli new <project-name> --framework=angular --type=igx-ts --template=<empty|side-nav> --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 Angular workspace fully compatible with `ng` commands, and additionally:
+   - Installs and configures `igniteui-angular` with a theme: either a prebuilt theme CSS in the `angular.json` `styles` array, or a starter Sass theme in `styles.scss` (Phase 3a treats both as "no theme")
+   - 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
+
+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
+   npx ng build
+   ```
+   Do not run `npm start` in the foreground: the dev server never exits. Start it in the background, or ask the user to run it, when Phase 5 needs it.
+
+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.