@sarjallab09/figma-intelligence 1.0.0 → 1.1.0

package/README.md

@@ -1,159 +1,110 @@
-# Figma Intelligence Layer
+# Figma Intelligence
 
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![npm](https://img.shields.io/npm/v/@sarjallab09/figma-intelligence)](https://www.npmjs.com/package/@sarjallab09/figma-intelligence)
 [![License: CC BY-NC-ND 4.0](https://img.shields.io/badge/License-CC%20BY--NC--ND%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-nd/4.0/)
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-64-blue)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-88-blue)]()
 
-> An AI-powered design assistant that lives inside Figma — connect Claude, OpenAI Codex, or Google Gemini CLI and let AI build, edit, and modify your designs in real time.
+> 88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.
 
 ```
-You (chat in Figma plugin) ◄──► Bridge Relay ◄──► Claude / OpenAI Codex / Gemini CLI
+You (chat in Figma plugin) ◄──► Local Relay ◄──► Claude / OpenAI Codex / Gemini CLI
 ```
 
 ---
 
-## What does this do?
+## Quick Start (3 steps)
 
-Type something like *"Make a login screen with a blue button"* and the selected provider will actually create the components and layers in your Figma file — not just describe how to do it.
+### 1. Install the Figma plugin
 
-The bundled Figma MCP server exposes **64 tools**, including high-level generation tools (`figma_page_architect`, `figma_intent_translator`, `figma_layout_intelligence`, `figma_design_from_ref`, `figma_generate_spec`) and direct editing and inspection tools.
+Search **"Figma Intelligence"** in the Figma Community plugins, or install it from the plugin page.
 
----
+> **Note:** Requires Figma Desktop app — the browser version won't work.
 
-## Before you start — what you need
+### 2. Install an AI CLI and log in
 
-You need Node.js, Figma Desktop, and at least one supported AI CLI on your computer. If you already have them, skip to Step 1.
+You need at least one. All three use your existing subscription — no extra API costs.
 
-### 1. Node.js (a programming tool that runs behind the scenes)
+| Provider | Install | Log in |
+|---|---|---|
+| **Claude** | [claude.ai/download](https://claude.ai/download) | `claude login` |
+| **OpenAI Codex** | `npm install -g @openai/codex` | `codex login` |
+| **Google Gemini** | `npm install -g @google/gemini-cli` | `gemini` (opens Google sign-in) |
 
-- Go to [nodejs.org](https://nodejs.org) and download the **LTS** version (the one labelled "Recommended for most users")
-- Install it like any normal app (open the downloaded file, click Next/Install)
-- To check it worked: open Terminal (Mac) or Command Prompt (Windows), type `node -v`, and press Enter — you should see a version number like `v20.0.0`
+### 3. Run setup
 
-### 2. Figma Desktop app
+Open your terminal and run:
 
-- Download from [figma.com/downloads](https://www.figma.com/downloads/)
-- This must be the **desktop app** — the browser version won't work
+```bash
+npx @sarjallab09/figma-intelligence setup
+```
 
-### 3. An AI tool
+This will:
+- Install dependencies and build the MCP server
+- Detect which AI CLIs you have and check their login status
+- Ask for your **Figma Personal Access Token** ([how to get one](#figma-personal-access-token))
+- Register the MCP server with your detected providers
+- Start the local relay server
+- Optionally install as a background service (macOS)
 
-Install at least one of these — the setup will detect whichever you have:
+**That's it.** Open the plugin in Figma — it auto-connects.
 
-| Tool | How to install |
-|---|---|
-| **Claude Code** | Download from claude.ai/download, sign in with `claude login` |
-| **VS Code** (GitHub Copilot) | Download from code.visualstudio.com |
-| **Cursor** | Download from cursor.com |
-| **Windsurf** | Download from codeium.com/windsurf |
-| **Zed** | Download from zed.dev |
-| **Continue.dev** | Install the VS Code extension from continue.dev |
-| **OpenAI Codex CLI** | `npm install -g @openai/codex`, then `codex login` |
-| **Google Gemini CLI** | `npm install -g @google/gemini-cli`, then run `gemini` and complete Google sign-in |
-| **Kiro** (AWS) | Download from kiro.dev |
-
-If you install Claude, Codex, and Gemini CLI, `npm run setup` prepares all of them so provider switching does not require restarting the bridge.
+---
 
-### 4. A Figma Personal Access Token
+## Figma Personal Access Token
 
-This is like a password that lets the plugin read and edit your Figma files.
+Required so the plugin can read and edit your Figma files.
 
 1. Open Figma Desktop
-2. Click your profile photo (top-left)
-3. Go to **Settings → Security**
-4. Scroll down to **Personal access tokens** → click **Generate new token**
-5. Give it any name (e.g. "Claude Plugin")
-6. **Copy the token and save it somewhere** — you'll need it in Step 2 below and Figma only shows it once
+2. Click your profile photo (top-left) > **Settings** > **Security**
+3. Scroll to **Personal access tokens** > **Generate new token**
+4. Give it any name (e.g. "Figma Intelligence")
+5. Copy the token — Figma only shows it once
 
 ---
 
-## Setup (one-time, takes about 2 minutes)
-
-### Step 1 — Open Terminal in the project folder
-
-**On Mac:**
-1. Open the **Terminal** app (search for it in Spotlight with Cmd+Space)
-2. Type `cd ` (with a space after), then drag the project folder onto the Terminal window — this fills in the path automatically
-3. Press Enter
+## Commands
 
-**On Windows:**
-1. Open the project folder in File Explorer
-2. Click the address bar at the top, type `cmd`, press Enter
-
-### Step 2 — Run the setup command
+After setup, you can manage the relay with these commands:
 
 ```bash
-npm run setup
+npx @sarjallab09/figma-intelligence start    # Start the relay server
+npx @sarjallab09/figma-intelligence stop     # Stop the relay server
+npx @sarjallab09/figma-intelligence status   # Show relay + provider status
+npx @sarjallab09/figma-intelligence doctor   # Diagnose issues
+npx @sarjallab09/figma-intelligence setup    # Full setup (first time or reconfigure)
 ```
 
-Type exactly that and press Enter. The setup will:
-- Install everything needed (you'll see a lot of text scroll by — that's normal)
-- Detect your Claude, Codex, and Gemini logins
-- Prompt you to sign in to any installed provider that is not ready yet, so both subscriptions can be prepared in one pass
-- Register the Figma MCP server for Claude, Codex, Gemini CLI, and VS Code
-- If you choose OpenAI in the plugin later, it will use the account currently logged into `codex` without restarting `npm start`
-- If you choose Gemini in the plugin later and Gemini CLI is authenticated, it will use Gemini CLI subscription mode with the same Figma MCP server
-- Ask you to **paste your Figma token** — paste it and press Enter
-- Start the background bridge that lets the plugin talk to Figma
-
-> If it says "npm: command not found" — Node.js is not installed correctly. Go back and reinstall it from [nodejs.org](https://nodejs.org).
-
-### Step 3 — Load the plugin into Figma
-
-1. Open **Figma Desktop**
-2. Open any file (or create a new one)
-3. **Right-click** anywhere on the canvas (the blank white area)
-4. In the menu that appears, go to: **Plugins → Development → Import plugin from manifest…**
-5. A file picker opens — navigate to the project folder, then into the `figma-bridge-plugin` folder, and select **manifest.json**
-6. Click **Open**
-
-### Step 4 — Start the plugin
+---
 
-1. **Right-click** the canvas again
-2. Go to **Plugins → Development → Figma Intelligence Bridge**
-3. A panel will open — click **▶ Start**
-4. You should see **✅ Connected** — you're all set!
+## Every time you restart your computer
 
-### Step 5 — Connect any other AI tools (optional)
+If you installed the background service during setup (macOS), the relay starts automatically — no action needed.
 
-Already using Cursor, Windsurf, Zed, Continue.dev, or Kiro? Run:
+Otherwise, just run:
 
 ```bash
-npm run connect
+npx @sarjallab09/figma-intelligence start
 ```
 
-It auto-detects which tools you have installed and registers the Figma MCP server with all of them in one go. You can also target a specific tool:
+Then open the Figma plugin — it reconnects automatically.
 
-```bash
-npm run connect -- --tool cursor
-npm run connect -- --tool windsurf
-npm run connect -- --tool zed
-npm run connect -- --tool continue
-npm run connect -- --tool vscode
-npm run connect -- --tool kiro
-npm run connect -- --tool codex
-```
-
-### Step 6 — Restart your AI tool
+---
 
-Restart VS Code, Cursor, Windsurf, Zed, or whichever tool you connected, so it picks up the new MCP server.
+## What does this do?
 
-### Step 7 — Quick health check (recommended)
+Type something like *"Make a login screen with a blue button"* and the AI will actually create the components and layers in your Figma file — not just describe how to do it.
 
-Run:
+The plugin exposes **88 MCP tools** across 5 phases:
 
-```bash
-npm run status
-```
-
-This verifies relay socket state, plugin connection, MCP connection, build output, and token setup in one command.
-
-If you use OpenAI provider and it reports missing Codex MCP registration, run:
-
-```bash
-npm run register:codex-mcp
-```
-
-If you plan to use Gemini subscription mode, verify that `gemini --version` works and that running `gemini` completes Google sign-in before you open the plugin.
+| Phase | Tools | Examples |
+|---|---|---|
+| **Visual Intelligence** | 7 | Screen cloning, visual audit, accessibility audit, sketch-to-design |
+| **Design System Accuracy** | 6 | Intent translation, layout intelligence, variant expansion, linting |
+| **Generation & Scaffolding** | 13 | Page architect, swarm build, prototype wiring, composition builder |
+| **Sync & Bidirectionality** | 9 | Token export (16 formats), component code gen, handoff specs |
+| **Governance & Health** | 15 | Health reports, token docs, design system scaffolding, DTCG validation |
+| **Node Operations** | 38 | Create, read, update, delete nodes, variables, styles, components |
 
 ---
 
@@ -200,114 +151,37 @@ Setup registers the same Figma MCP server for Claude, Codex, and Gemini CLI, so
 
 The active provider will show its signed-in email in the auth strip when available.
 
-## Gemini CLI workflow
-
-If you want Gemini to use the real Figma MCP tools instead of API-key text mode, use Gemini CLI.
-
-### 1. Install Gemini CLI
-
-```bash
-npm install -g @google/gemini-cli
-```
-
-### 2. Sign in with your Google account
-
-Run either of these:
-
-```bash
-gemini
-```
-
-```bash
-gemini auth login
-```
-
-That opens the Google browser OAuth flow. After it completes, re-run:
-
-```bash
-npm run setup
-```
-
-Setup writes the Figma MCP registration into `~/.gemini/settings.json`, so the Gemini CLI subprocess can call the same 64 Figma tools as Claude and Codex.
-
-### 3. Use Gemini inside the plugin
-
-1. Start the bridge with `npm start`
-2. Open the Figma plugin
-3. Choose the **Gemini** provider
-4. Send a design request
-
-When Gemini CLI auth is present, the relay uses Gemini CLI subscription mode. If Gemini CLI is not authenticated, the plugin falls back to Gemini API-key mode, which is lower fidelity and does not provide the same MCP-driven tool execution.
-
----
-
-## Every time you restart your computer
-
-If setup completed successfully on macOS, the bridge relay is installed as a background service and should start automatically after login.
-
-If you ever need to start it manually:
-
-1. Open Terminal in the project folder (same as Step 1 above)
-2. Run:
-
-```bash
-npm start
-```
-
-3. Open Figma and click **▶ Start** in the plugin panel
-
-4. Run:
-
-```bash
-npm run status
-```
-
-That's it — you're connected again.
-
----
-
 ## Troubleshooting
 
 | What went wrong | How to fix it |
 |---|---|
 | **"npm: command not found"** | Node.js is not installed — download it from [nodejs.org](https://nodejs.org) |
-| **Plugin shows "Disconnected"** | Run `npm start` in Terminal first, then click Start in the plugin |
-| **Not sure what is broken** | Run `npm run status` for a one-command diagnostic and follow the printed next actions |
-| **OpenAI provider can chat but cannot use Figma tools** | Run `npm run register:codex-mcp`, then `npm run status` |
-| **Gemini appears to answer but does not build in Figma** | Install Gemini CLI with `npm install -g @google/gemini-cli`, run `gemini` to sign in, then re-run `npm run setup` |
-| **Chat does nothing / no response** | Open Terminal and run `claude login` for Claude, `codex login` for OpenAI, or `gemini` for Gemini. Then switch providers once in the plugin or reconnect it — no `npm start` restart needed |
-| **`unexpected argument '--approval-mode'` in plugin chat** | Your plugin is using an older Codex CLI invocation. Update to the latest repo version or patch `figma-bridge-plugin/codex-runner.js` to use `codex exec --json` instead of `--approval-mode` / `--quiet` |
-| **"dist/index.js not found"** | Run `cd figma-intelligence-layer && npm run build` in Terminal |
-| **Wrong Figma token / token expired** | Re-run `npm run setup` and paste your new token when asked |
-| **MCP tools missing in VS Code / Cursor / Zed etc.** | Run `npm run connect` then restart the tool |
-| **"Design + Code" shows "VS Code not connected"** | Restart VS Code after running `npm run setup` — the bridge extension loads on startup |
-| **Port 9001 already in use** | `npm run setup` now handles this automatically — just run it again |
+| **Plugin shows "Server offline"** | Run `npx @sarjallab09/figma-intelligence start` in your terminal |
+| **Plugin shows setup guide** | Follow the on-screen steps — run the setup command in your terminal |
+| **Not sure what is broken** | Run `npx @sarjallab09/figma-intelligence doctor` for full diagnostics |
+| **Chat does nothing / no response** | Run `claude login` / `codex login` / `gemini` to authenticate your AI provider |
+| **Gemini doesn't build in Figma** | Install Gemini CLI: `npm i -g @google/gemini-cli`, run `gemini` to sign in, re-run setup |
+| **Wrong Figma token / token expired** | Re-run `npx @sarjallab09/figma-intelligence setup` and paste your new token |
+| **Port 9001 already in use** | Run `npx @sarjallab09/figma-intelligence stop` then `start` again |
 
 ---
 
 ## Folder structure (for the curious)
 
 ```
-setup.sh                         ← the one-command setup script (does everything)
+bin/cli.js                       ← CLI entrypoint (npx @sarjallab09/figma-intelligence)
 figma-bridge-plugin/
-  manifest.json                  ← import this file into Figma
-  bridge-relay.js                ← background bridge (npm start runs this)
+  manifest.json                  ← Figma plugin manifest
+  bridge-relay.js                ← local WebSocket relay server
   chat-runner.js                 ← connects Claude to the plugin chat
   codex-runner.js                ← connects OpenAI Codex to the plugin chat
   gemini-cli-runner.js           ← connects Gemini CLI to the plugin chat
-  shared-prompt-config.js        ← system prompts, design systems, dual output prompt
-  ui.html / code.js              ← the plugin's visual panel (Chat / Code / Design+Code)
+  ui.html / code.js              ← plugin UI panel (Chat / Code / Design+Code)
 figma-intelligence-layer/
-  src/                           ← source code for the AI tools
-  dist/index.js                  ← built/compiled version (created by setup)
-vscode-chat-extension/           ← VS Code bridge extension (auto-installed by setup)
-  src/extension.ts               ← background service that writes code files
-  src/dual-output.ts             ← parses code output from AI responses
-  src/code-generator.ts          ← writes component files to workspace
-  src/preview-server.ts          ← Storybook live preview manager
-design-bridge/                   ← Asset MCP bridge (Stitch, Unsplash, Pexels, Iconify)
-ui-components/                   ← Generated React component library with Storybook
-scripts/                         ← Utility scripts (status, connect, cleanup)
+  src/tools/                     ← 88 MCP tool implementations (5 phases)
+  dist/index.js                  ← built MCP server (created by setup)
+design-bridge/                   ← Asset MCP bridge (Unsplash, Pexels, Iconify)
+scripts/                         ← Utility scripts (status, connect)
 ```
 
 ---
@@ -315,9 +189,9 @@ scripts/                         ← Utility scripts (status, connect, cleanup)
 ## Contributing
 
 1. Fork the repo and create a feature branch
-2. Run `npm run setup` to install all dependencies
+2. Run `npx @sarjallab09/figma-intelligence setup` to install all dependencies
 3. Make your changes
-4. Run `npm run status` to verify everything works
+4. Run `npx @sarjallab09/figma-intelligence doctor` to verify everything works
 5. Open a pull request
 
 ---

package/figma-bridge-plugin/bridge-relay.js

@@ -1220,6 +1220,83 @@ function requestFromPlugin(method, params, timeoutMs = 15000) {
   });
 }
 
+// ── UX Researcher: capture current Figma selection as compact context ────────
+
+const SELECTION_CONTEXT_MAX_CHARS = 3000;
+const SELECTION_MAX_NODES = 5;
+
+async function captureSelectionContext() {
+  const selection = await requestFromPlugin("getSelection", {});
+  if (!selection || !Array.isArray(selection) || selection.length === 0) return null;
+
+  const nodesToFetch = selection.slice(0, SELECTION_MAX_NODES);
+  const nodeDetails = await Promise.all(
+    nodesToFetch.map((n) => requestFromPlugin("getNode", { nodeId: n.id }).catch(() => null))
+  );
+
+  const lines = [];
+  for (const node of nodeDetails) {
+    if (!node) continue;
+    lines.push(formatNodeForContext(node, 0));
+  }
+  if (selection.length > SELECTION_MAX_NODES) {
+    lines.push(`[... ${selection.length - SELECTION_MAX_NODES} more selected nodes omitted]`);
+  }
+
+  let body = lines.join("\n");
+  if (body.length > SELECTION_CONTEXT_MAX_CHARS) {
+    body = body.slice(0, SELECTION_CONTEXT_MAX_CHARS) + "\n[... truncated for brevity]";
+  }
+
+  return `=== CURRENT FIGMA SELECTION ===\n${body}\n=== END SELECTION ===`;
+}
+
+function formatNodeForContext(node, depth) {
+  const indent = "  ".repeat(depth);
+  const parts = [`${indent}[${node.type}] "${node.name}"`];
+
+  // Dimensions
+  if (node.width != null && node.height != null) {
+    parts[0] += ` (${Math.round(node.width)}×${Math.round(node.height)})`;
+  }
+
+  // Auto-layout
+  if (node.layoutMode && node.layoutMode !== "NONE") {
+    parts.push(`${indent}  layout: ${node.layoutMode}, spacing: ${node.itemSpacing}px, padding: ${node.paddingTop}/${node.paddingRight}/${node.paddingBottom}/${node.paddingLeft}`);
+  }
+
+  // Text content
+  if (node.characters) {
+    const text = node.characters.length > 120 ? node.characters.slice(0, 120) + "…" : node.characters;
+    parts.push(`${indent}  text: "${text}"`);
+    if (node.fontSize) parts.push(`${indent}  fontSize: ${node.fontSize}`);
+  }
+
+  // Component instance
+  if (node.mainComponentName) {
+    parts.push(`${indent}  component: ${node.mainComponentName}`);
+  }
+
+  // Corner radius
+  if (node.cornerRadius != null && node.cornerRadius > 0) {
+    parts.push(`${indent}  radius: ${node.cornerRadius}`);
+  }
+
+  // Children (1 level deep)
+  if (node.children && node.children.length > 0) {
+    const maxChildren = 10;
+    const shown = node.children.slice(0, maxChildren);
+    for (const child of shown) {
+      parts.push(`${indent}  - [${child.type}] "${child.name}"`);
+    }
+    if (node.children.length > maxChildren) {
+      parts.push(`${indent}  ... +${node.children.length - maxChildren} more children`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
 function sendToVscode(payload, targetWs) {
   if (targetWs && targetWs.readyState === 1) {
     targetWs.send(JSON.stringify(payload));
@@ -2200,6 +2277,38 @@ wss.on("connection", (ws, req) => {
           const anthropicKey = getAnthropicApiKey();
           if (chatMode === "chat" && anthropicKey) {
             // Tier 3: Direct Anthropic API — fast streaming (~200ms first token)
+            const isResearcher = msg.researcherMode === true;
+
+            if (isResearcher) {
+              // UX Researcher mode: async — capture selection, force Haiku, use researcher prompt
+              (async () => {
+                try {
+                  const selectionCtx = await captureSelectionContext();
+                  if (selectionCtx) {
+                    chatMessage = selectionCtx + "\n\n" + chatMessage;
+                    console.log("  🔬 Researcher: attached Figma selection context");
+                  }
+                } catch (e) {
+                  console.error("  ⚠ Researcher selection capture failed:", e.message);
+                }
+
+                const { buildUxResearcherPrompt } = require("./shared-prompt-config");
+                proc = runAnthropicChat({
+                  message: chatMessage,
+                  attachments: msg.attachments,
+                  conversation: msg.conversation,
+                  requestId,
+                  apiKey: anthropicKey,
+                  model: "claude-haiku-4-5-20251001",
+                  systemPrompt: buildUxResearcherPrompt(),
+                  onEvent,
+                });
+                activeChatProcesses.set(requestId, proc);
+                proc.on("close", () => activeChatProcesses.delete(requestId));
+              })();
+              return;
+            }
+
             const { buildChatPrompt } = require("./shared-prompt-config");
             proc = runAnthropicChat({
               message: chatMessage,
@@ -2213,6 +2322,39 @@ wss.on("connection", (ws, req) => {
             });
           } else {
             // Tier 4: Claude CLI subprocess (code/dual mode, or no API key)
+            const cliResearcher = msg.researcherMode === true && chatMode === "chat";
+
+            if (cliResearcher) {
+              // Researcher mode via CLI: async — capture selection, then spawn CLI
+              (async () => {
+                try {
+                  const selectionCtx = await captureSelectionContext();
+                  if (selectionCtx) {
+                    chatMessage = selectionCtx + "\n\n" + chatMessage;
+                    console.log("  🔬 Researcher (CLI): attached Figma selection context");
+                  }
+                } catch (e) {
+                  console.error("  ⚠ Researcher selection capture failed:", e.message);
+                }
+
+                proc = runClaude({
+                  message: chatMessage,
+                  attachments: msg.attachments,
+                  conversation: msg.conversation,
+                  requestId,
+                  model: msg.model,
+                  designSystemId: activeDesignSystemId,
+                  mode: chatMode,
+                  frameworkConfig: msg.frameworkConfig || {},
+                  researcherMode: true,
+                  onEvent,
+                });
+                activeChatProcesses.set(requestId, proc);
+                proc.on("close", () => activeChatProcesses.delete(requestId));
+              })();
+              return;
+            }
+
             proc = runClaude({
               message: chatMessage,
               attachments: msg.attachments,

package/figma-bridge-plugin/chat-runner.js

@@ -19,6 +19,7 @@ const {
   SYSTEM_PROMPT,
   buildSystemPrompt,
   buildChatPrompt,
+  buildUxResearcherPrompt,
   buildDualOutputPrompt,
   buildSkillAddendum,
   detectActiveSkills,
@@ -26,6 +27,7 @@ const {
 } = require("./shared-prompt-config");
 
 const MCP_CONFIG_PATH = join(tmpdir(), "figma-intelligence-chat-mcp.json");
+const EMPTY_MCP_CONFIG_PATH = join(tmpdir(), "figma-intelligence-no-mcp.json");
 const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 
 // Use the absolute claude binary path stored by setup.sh in launchd env.
@@ -118,6 +120,8 @@ function writeMcpConfig(bridgePort) {
 
 // Write initial config (will be rewritten with actual port once relay starts)
 writeMcpConfig();
+// Write empty MCP config for researcher mode (no tools)
+try { writeFileSync(EMPTY_MCP_CONFIG_PATH, JSON.stringify({ mcpServers: {} })); } catch {}
 
 function getCleanEnv() {
   const env = { ...process.env };
@@ -175,17 +179,27 @@ function processAttachments(attachments) {
 const CLAUDE_DEFAULT_MODEL = "claude-opus-4-6";
 const CLAUDE_VALID_MODELS = new Set(["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"]);
 
-function runClaude({ message, attachments, conversation, requestId, model, designSystemId, mode, frameworkConfig, onEvent }) {
+function runClaude({ message, attachments, conversation, requestId, model, designSystemId, mode, frameworkConfig, researcherMode, onEvent }) {
   const { imageArgs, extraText, tempFiles } = processAttachments(attachments);
 
-  const resolvedModel = CLAUDE_VALID_MODELS.has(model) ? model : CLAUDE_DEFAULT_MODEL;
+  const isResearcher = researcherMode === true;
+  const resolvedModel = isResearcher ? "claude-haiku-4-5-20251001" : (CLAUDE_VALID_MODELS.has(model) ? model : CLAUDE_DEFAULT_MODEL);
   const sessionMode = mode || "code";
 
   const rawText = (message || "").trim() || (extraText ? "Please analyse the attached image(s) and help me create a Figma design based on them." : "");
   const userText = rawText; // No more expandShortPrompt — Claude handles short prompts natively
 
   // Detect active skills early — needed for session reset decision
-  const skills = (sessionMode === "code" || sessionMode === "dual") ? detectActiveSkills(userText) : [];
+  // Skip skill detection in researcher mode — it's a pure chat persona
+  const skills = (!isResearcher && (sessionMode === "code" || sessionMode === "dual")) ? detectActiveSkills(userText) : [];
+
+  // Force new session when researcher mode is toggled.
+  // The researcher session uses a different system prompt and no MCP tools,
+  // so it cannot share a session with normal chat mode.
+  if (isResearcher && activeSessionIds[sessionMode]) {
+    console.log(`[chat-runner] Researcher mode — resetting ${sessionMode} session for researcher prompt`);
+    activeSessionIds[sessionMode] = null;
+  }
 
   // Force new session when Component Doc Generator skill is detected.
   // This ensures the system prompt includes the spec-type reference and
@@ -217,6 +231,8 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     }
     const modeLabel = sessionMode === "dual" ? "Dual (Design + Code)" : "Code";
     onEvent({ type: "phase_start", id: requestId, phase: `${modeLabel} · ${resolvedModel} · MCP: figma-intelligence-layer` });
+  } else if (isResearcher) {
+    onEvent({ type: "phase_start", id: requestId, phase: `UX Researcher · ${resolvedModel}` });
   } else {
     onEvent({ type: "phase_start", id: requestId, phase: `Chat · ${resolvedModel}` });
   }
@@ -225,7 +241,9 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
   if (isFirstMessage) {
     // First message: create session with full config
     let baseSystemPrompt;
-    if (sessionMode === "chat") {
+    if (isResearcher) {
+      baseSystemPrompt = buildUxResearcherPrompt();
+    } else if (sessionMode === "chat") {
       baseSystemPrompt = buildChatPrompt();
     } else if (sessionMode === "dual") {
       baseSystemPrompt = buildDualOutputPrompt(designSystemId, frameworkConfig);
@@ -249,6 +267,10 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     if (sessionMode === "code" || sessionMode === "dual") {
       args.push("--mcp-config", MCP_CONFIG_PATH, "--strict-mcp-config");
     }
+    // Researcher mode: block ALL MCP tools — pure chat persona
+    if (isResearcher) {
+      args.push("--mcp-config", EMPTY_MCP_CONFIG_PATH, "--strict-mcp-config");
+    }
   } else {
     // Subsequent messages: resume session — context already loaded.
     // MUST re-pass --mcp-config and --strict-mcp-config on resume too,
@@ -263,6 +285,10 @@ function runClaude({ message, attachments, conversation, requestId, model, desig
     if (sessionMode === "code" || sessionMode === "dual") {
       args.push("--mcp-config", MCP_CONFIG_PATH, "--strict-mcp-config");
     }
+    // Researcher mode: block ALL MCP tools on resume too
+    if (isResearcher) {
+      args.push("--mcp-config", EMPTY_MCP_CONFIG_PATH, "--strict-mcp-config");
+    }
     console.log(`[chat-runner] Resuming ${sessionMode} session: ${currentSessionId}`);
   }
 

package/figma-bridge-plugin/code.js

@@ -866,7 +866,7 @@ figma.ui.onmessage = async (msg) => {
       case "getNode": {
         const node = await figma.getNodeByIdAsync(params.nodeId);
         if (!node) throw new Error("Node not found: " + params.nodeId);
-        result = serializeNode(node);
+        result = await serializeNode(node);
         break;
       }
 
@@ -1459,7 +1459,7 @@ figma.ui.onmessage = async (msg) => {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function serializeNode(node) {
+async function serializeNode(node) {
   const base = {
     id: node.id,
     name: node.name,
@@ -1511,9 +1511,15 @@ function serializeNode(node) {
       type: c.type,
     }));
   }
-  if ("mainComponent" in node) {
-    base.mainComponentId = node.mainComponent ? node.mainComponent.id : undefined;
-    base.mainComponentName = node.mainComponent ? node.mainComponent.name : undefined;
+  if (node.type === "INSTANCE") {
+    try {
+      const main = await node.getMainComponentAsync();
+      base.mainComponentId = main ? main.id : undefined;
+      base.mainComponentName = main ? main.name : undefined;
+    } catch (e) {
+      base.mainComponentId = undefined;
+      base.mainComponentName = undefined;
+    }
   }
 
   return base;

package/figma-bridge-plugin/references/SKILL.md

@@ -11,7 +11,7 @@ description: >
   specification in Figma. Also trigger when users mention "component docs", "spec
   pages", "design handoff docs", "anatomy markers", "API table", "property overview",
   "color annotation", "structure spec", "screen reader spec", or "a11y spec".
-  Works with Figma Console MCP and native Figma MCP.
+  Works with Figma Intelligence MCP via the bridge-relay.
 ---
 
 # Component Documentation Generator
@@ -20,7 +20,7 @@ Generate production-quality design system component documentation directly in Fi
 
 ## Overview
 
-This skill connects to your Figma file through Figma MCP (Console MCP or native Figma MCP), extracts component data programmatically, applies AI reasoning for classification and semantics, and renders structured documentation frames directly in your Figma file.
+This skill connects to your Figma file through Figma Intelligence MCP (via the bridge-relay local server), extracts component data programmatically, applies AI reasoning for classification and semantics, and renders structured documentation frames directly in your Figma file.
 
 **The pipeline for every spec type follows the same pattern:**
 1. **Extract** — Read component layers, properties, variables, and styles from Figma via MCP
@@ -31,7 +31,7 @@ This skill connects to your Figma file through Figma MCP (Console MCP or native
 
 ## Prerequisites
 
-- **Figma MCP connected** — Either Figma Console MCP (with Desktop Bridge plugin) or native Figma MCP
+- **Figma Intelligence MCP connected** — Via the bridge-relay local server
 - **A Figma component link** — The URL to a component set or standalone component
 - **Template library** (optional but recommended) — A published Figma library with documentation templates
 

package/figma-bridge-plugin/shared-prompt-config.js

@@ -254,6 +254,46 @@ function buildChatPrompt() {
   return CHAT_SYSTEM_PROMPT;
 }
 
+// ── UX Researcher Mode Prompt ────────────────────────────────────────────────
+
+const UX_RESEARCHER_PROMPT = `You are a senior UX researcher with 15 years of practice embedded in a Figma design tool. You speak designers' language — affordance, hierarchy, contrast, density, gestalt, scanability, cognitive load, jobs-to-be-done — and you are direct and concise. No fluff, no preamble, no "great question."
+
+You must NEVER use any tools, execute any code, or call any MCP functions. You analyze and critique designs based on the context provided to you — you do not modify anything. When the user asks you to actually build, create, or modify something in Figma, tell them to switch to Code mode for that.
+
+When the user shares a Figma selection (indicated by a === CURRENT FIGMA SELECTION === block in the message), critique it against UX principles concretely: name the heuristic, point at the specific element by its layer or component name, and propose a fix. Push back when the design contradicts a principle. If the user asks "what's wrong" or "check this" and a selection is attached, always analyze it — this is your primary job.
+
+Structure every answer as: **diagnosis → principle → evidence → fix.** Default to the top 3 highest-impact issues unless the user asks for an exhaustive review.
+
+Prioritize these qualities (in order): clarity, hierarchy, cognitive load, error prevention, accessibility, trust, conversion.
+
+You ground every claim in the established UX canon. When you cite, name the source by title and author the way a designer would in conversation: "Krug calls this 'self-evident' design in Don't Make Me Think," "Nielsen's heuristic #5 (error prevention)," "NN/g on form usability," "Refactoring UI talks about hierarchy through size and color," "Material Design's elevation system," "Apple HIG on touch targets," "WCAG 2.1 AA contrast," "the WAI-ARIA Authoring Practices Guide."
+
+Trusted sources you should reach for first:
+- Nielsen Norman Group (nngroup.com)
+- UX Matters
+- Smashing Magazine
+- Don't Make Me Think (Krug)
+- The Design of Everyday Things (Norman)
+- Refactoring UI (Wathan & Schoger)
+- About Face (Cooper)
+- 100 Things Every Designer Needs to Know About People (Weinschenk)
+- Material Design
+- Apple Human Interface Guidelines
+- WCAG
+- ARIA Authoring Practices Guide (APG)
+
+**Citation rule:** Cite source families and named principles naturally. Never fabricate specific article URLs or titles you are not certain about. If your memory of a specific source is fuzzy, cite the author or principle family instead.
+
+When the user's intent is ambiguous, ask one clarifying question instead of guessing.
+
+When knowledge sources or web references are provided in the context, incorporate them into your analysis. Cite the source name when referencing specific material.
+
+Format: short paragraphs. Use bullets when listing more than two issues. **Bold** the principle name. Never invent page numbers or section references you are unsure of.`;
+
+function buildUxResearcherPrompt() {
+  return UX_RESEARCHER_PROMPT;
+}
+
 // ── Active Skill Detection ───────────────────────────────────────────────────
 
 function detectActiveSkills(text) {
@@ -594,6 +634,7 @@ module.exports = {
   DESIGN_SYSTEMS,
   buildSystemPrompt,
   buildChatPrompt,
+  buildUxResearcherPrompt,
   buildDualOutputPrompt,
   buildSkillAddendum,
   buildDesignSystemAddendum,

package/figma-bridge-plugin/ui.html

@@ -581,6 +581,34 @@
     }
     .model-badge:hover { background: rgba(255,255,255,0.07); color: var(--text-secondary); }
 
+    /* UX Researcher toggle */
+    .ux-researcher-toggle {
+      display: flex; align-items: center; gap: 4px;
+      font-size: 10px;
+      color: var(--text-muted);
+      padding: 2px 6px;
+      border-radius: 5px;
+      cursor: pointer;
+      user-select: none;
+      transition: background 0.13s, color 0.13s;
+    }
+    .ux-researcher-toggle:hover { background: rgba(255,255,255,0.07); color: var(--text-secondary); }
+    .ux-researcher-toggle.active {
+      background: rgba(168, 130, 255, 0.15);
+      color: #c4a1ff;
+    }
+    .ux-researcher-toggle.active:hover {
+      background: rgba(168, 130, 255, 0.22);
+    }
+    .ux-researcher-dot {
+      width: 6px; height: 6px; border-radius: 50%;
+      background: var(--text-muted);
+      transition: background 0.13s;
+    }
+    .ux-researcher-toggle.active .ux-researcher-dot {
+      background: #c4a1ff;
+    }
+
     /* Model dropdown */
     .model-dropdown {
       position: absolute;
@@ -1878,6 +1906,10 @@
           <input type="file" id="file-input" multiple style="display:none" accept="image/*,.pdf,.txt,.json,.csv,.svg,.md,.html,.css,.js,.ts,.jsx,.tsx,.py,.go,.rs,.java,.rb,.yml,.yaml,.xml,.sql,.sh">
         </div>
         <div class="toolbar-right">
+          <div class="ux-researcher-toggle" id="ux-researcher-toggle" onclick="toggleUxResearcher()" title="UX Researcher — fast Haiku-powered UX critique. Auto-attaches your current Figma selection." style="display:none">
+            <span class="ux-researcher-dot"></span>
+            <span>UXR</span>
+          </div>
           <div class="model-badge" id="model-badge" onclick="toggleModelDropdown(event)">
             <span id="model-label">Sonnet</span>
             <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
@@ -3030,6 +3062,7 @@
     }
     renderThreadForProvider(selectedLoginProvider);
     updateStatus();
+    syncResearcherToggle();
 
     if (ws && ws.readyState === WebSocket.OPEN) sendProviderToRelay();
   }
@@ -3174,8 +3207,49 @@
 
     // Show VS Code connection indicator for dual mode
     updateVscodeStatus();
+
+    // Sync researcher toggle visibility on mode change
+    syncResearcherToggle();
   };
 
+  /* ── UX Researcher Mode ──────────────────────────────────────────────── */
+  var isUxResearcherMode = false;
+  var UX_RESEARCHER_KEY = "figma-intelligence:researcher-mode";
+  try {
+    if (localStorage.getItem(UX_RESEARCHER_KEY) === "1") isUxResearcherMode = true;
+  } catch(e) {}
+
+  window.toggleUxResearcher = function() {
+    isUxResearcherMode = !isUxResearcherMode;
+    try { localStorage.setItem(UX_RESEARCHER_KEY, isUxResearcherMode ? "1" : "0"); } catch(e) {}
+    syncResearcherToggle();
+  };
+
+  function syncResearcherToggle() {
+    var el = document.getElementById("ux-researcher-toggle");
+    if (!el) return;
+
+    // Only show when provider is Claude and mode is Chat
+    var show = (getActiveProvider() === "claude") && (activeMode === "chat");
+    el.style.display = show ? "" : "none";
+
+    if (show) {
+      el.className = "ux-researcher-toggle" + (isUxResearcherMode ? " active" : "");
+    }
+
+    // Update input placeholder
+    if (input) {
+      if (show && isUxResearcherMode) {
+        input.placeholder = "Ask the UX researcher\u2026";
+      } else if (activeMode === "chat") {
+        input.placeholder = "Ask me anything...";
+      }
+    }
+  }
+
+  // Initial sync on load
+  setTimeout(syncResearcherToggle, 0);
+
   function isChatOnlyProvider() {
     return selectedLoginProvider === "bridge" || selectedLoginProvider === "perplexity";
   }
@@ -4027,7 +4101,7 @@
     if (/^\s*\/knowledge\b/i.test(messageText)) {
       var kQuery = messageText.replace(/^\s*\/knowledge\s*/i, "").trim();
       // Send to relay for hub processing (not as a chat message to AI)
-      ws.send(JSON.stringify({ type: "chat", id: currentRequestId, message: messageText, mode: activeMode, model: getSelectedModel(activeProvider), conversation: [] }));
+      ws.send(JSON.stringify({ type: "chat", id: currentRequestId, message: messageText, mode: activeMode, model: getSelectedModel(activeProvider), conversation: [], researcherMode: isUxResearcherMode }));
       // Reset input color
       input.style.color = "";
       return;
@@ -4040,6 +4114,7 @@
       model: getSelectedModel(activeProvider),
       conversation: conversation,
       mode: activeMode,
+      researcherMode: isUxResearcherMode,
     };
 
     if (attachedFiles.length > 0) {

package/figma-intelligence-layer/src/index.ts

@@ -2088,7 +2088,7 @@ async function dispatch(name: string, args: AnyArgs): Promise<unknown> {
     case "figma_get_node_deep": {
       const bridge = await getBridge();
       const a = args as { nodeId: string; maxDepth?: number };
-      return bridge.getNodeDeep(a.nodeId, a.maxDepth);
+      return await bridge.getNodeDeep(a.nodeId, a.maxDepth);
     }
     case "figma_batch_get_nodes": {
       const bridge = await getBridge();

package/figma-intelligence-layer/src/shared/figma-bridge.ts

@@ -633,9 +633,14 @@ export class FigmaBridge {
       const page = figma.currentPage;
       const found = page.findAll(n => n.type === 'INSTANCE');
       for (const inst of found) {
+        let mainComponentId = '';
+        try {
+          const main = await inst.getMainComponentAsync();
+          if (main) mainComponentId = main.id;
+        } catch (e) {}
         instances.push({
           id: inst.id,
-          mainComponentId: inst.mainComponent ? inst.mainComponent.id : '',
+          mainComponentId,
           name: inst.name,
           pageId: page.id,
         });
@@ -1073,7 +1078,7 @@ export class FigmaBridge {
 (async () => {
   const maxDepth = ${Math.min(maxDepth, 20)};
 
-  function serializeNode(node, depth) {
+  async function serializeNode(node, depth) {
     const data = {
       id: node.id,
       name: node.name,
@@ -1125,9 +1130,14 @@ export class FigmaBridge {
     // Component metadata
     if ('componentPropertyReferences' in node) data.componentPropertyReferences = node.componentPropertyReferences;
     if ('variantProperties' in node && node.variantProperties) data.variantProperties = node.variantProperties;
-    if (node.type === 'INSTANCE' && node.mainComponent) {
-      data.mainComponentId = node.mainComponent.id;
-      data.mainComponentName = node.mainComponent.name;
+    if (node.type === 'INSTANCE') {
+      try {
+        const main = await node.getMainComponentAsync();
+        if (main) {
+          data.mainComponentId = main.id;
+          data.mainComponentName = main.name;
+        }
+      } catch (e) { /* mainComponent unavailable */ }
     }
     if (node.description) data.description = node.description;
 
@@ -1150,7 +1160,7 @@ export class FigmaBridge {
     if ('children' in node && node.children && depth < maxDepth) {
       data.children = [];
       for (const child of node.children) {
-        data.children.push(serializeNode(child, depth + 1));
+        data.children.push(await serializeNode(child, depth + 1));
       }
       data.childCount = node.children.length;
     } else if ('children' in node && node.children) {
@@ -1164,7 +1174,7 @@ export class FigmaBridge {
 
   const root = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
   if (!root) throw new Error('Node not found: ' + ${JSON.stringify(nodeId)});
-  return serializeNode(root, 0);
+  return await serializeNode(root, 0);
 })();
     `, 60000); // 60s timeout for deep trees
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarjallab09/figma-intelligence",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "88 AI-powered design tools for Figma. Works with your Claude, OpenAI Codex, or Gemini CLI subscription. One command to set up.",
   "author": "Figma Intelligence Contributors",
   "license": "CC-BY-NC-ND-4.0",
@@ -31,5 +31,16 @@
     "scripts/",
     "README.md"
   ],
-  "keywords": ["figma", "mcp", "claude", "openai", "codex", "gemini", "ai", "design", "design-system", "figma-plugin"]
+  "keywords": [
+    "figma",
+    "mcp",
+    "claude",
+    "openai",
+    "codex",
+    "gemini",
+    "ai",
+    "design",
+    "design-system",
+    "figma-plugin"
+  ]
 }