@dannote/figma-use 0.1.0 → 0.1.2

package/README.md

@@ -4,6 +4,39 @@ Control Figma from the command line. Like [browser-use](https://github.com/brows
 
 Built for AI agents to create and manipulate Figma designs programmatically.
 
+## Why not the official Figma MCP?
+
+The [official Figma MCP server](https://developers.figma.com/docs/figma-mcp-server/) is **read-only** — it can extract design context and take screenshots, but cannot create or modify anything.
+
+| Feature | Official MCP | figma-use |
+|---------|-------------|-----------|
+| Read node properties | ✓ | ✓ |
+| Take screenshots | ✓ | ✓ |
+| Extract variables/styles | ✓ | ✓ |
+| **Create shapes** | ✗ | ✓ |
+| **Create text** | ✗ | ✓ |
+| **Create frames & components** | ✗ | ✓ |
+| **Modify properties** | ✗ | ✓ |
+| **Set fills, strokes, effects** | ✗ | ✓ |
+| **Auto-layout** | ✗ | ✓ |
+| **Execute arbitrary code** | ✗ | ✓ |
+
+figma-use gives AI agents full control over Figma — not just reading, but **creating and editing** designs.
+
+## How it works
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│                 │     │                 │     │                 │
+│   AI Agent /    │────▶│   figma-use     │────▶│     Figma       │
+│   CLI           │ HTTP│   proxy         │ WS  │     Plugin      │
+│                 │◀────│   :38451        │◀────│                 │
+│                 │     │                 │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+The CLI sends commands to a local proxy server, which forwards them via WebSocket to a Figma plugin. The plugin executes commands using the Figma API and returns results.
+
 ## Installation
 
 ```bash
@@ -18,39 +51,44 @@ bun install -g @dannote/figma-use
 figma-use proxy
 ```
 
-### 2. Load the Figma plugin
+### 2. Install the Figma plugin
 
-Open Figma, go to **Plugins → Development → Import plugin from manifest**, and select:
+```bash
+# Quit Figma first, then:
+figma-use plugin
 
-```
-~/.bun/install/global/node_modules/@dannote/figma-use/packages/plugin/dist/manifest.json
-```
+# Or force install while Figma is running (restart required):
+figma-use plugin --force
 
-Or find it with:
+# Show plugin path only:
+figma-use plugin --path
 
-```bash
-figma-use plugin
+# Uninstall:
+figma-use plugin --uninstall
 ```
 
+Start Figma and find the plugin in **Plugins → Development → Figma Use**.
+
 ### 3. Run commands
 
 ```bash
-# Create shapes
-figma-use create-rectangle --x 0 --y 0 --width 200 --height 100 --fill "#3B82F6" --radius 8
-
-# Create text
-figma-use create-text --x 50 --y 40 --text "Hello Figma" --fontSize 24 --fill "#FFFFFF"
+# Create a styled button in one command (fill + stroke + radius + layout)
+figma-use create-frame --x 0 --y 0 --width 200 --height 48 \
+  --fill "#3B82F6" --stroke "#1D4ED8" --radius 8 \
+  --layoutMode HORIZONTAL --itemSpacing 8 --padding "12,24,12,24" \
+  --name "Button"
 
-# Get node info
-figma-use get-node --id "1:2"
+# Add text with font styling
+figma-use create-text --x 0 --y 0 --text "Click me" \
+  --fontSize 16 --fontFamily "Inter" --fontStyle "Medium" --fill "#FFFFFF" \
+  --parentId "1:23"
 
 # Export to PNG
-figma-use export-node --id "1:2" --format PNG --scale 2 --output design.png
-
-# Take screenshot
-figma-use screenshot --output viewport.png
+figma-use export-node --id "1:23" --format PNG --scale 2 --output button.png
 ```
 
+All create commands support inline styling — no need for separate `set-*` calls.
+
 ## Output Format
 
 Human-readable by default:
@@ -171,6 +209,30 @@ $ figma-use get-node --id "1:2" --json
 | `zoom-to-fit` | Zoom to fit nodes |
 | `set-viewport` | Set viewport position and zoom |
 
+### Advanced
+
+| Command | Description |
+|---------|-------------|
+| `eval` | Execute arbitrary JavaScript in Figma |
+
+#### eval
+
+Run any JavaScript code in the Figma plugin context:
+
+```bash
+# Simple expression
+figma-use eval "return 2 + 2"
+
+# Access Figma API
+figma-use eval "return figma.currentPage.name"
+
+# Create nodes
+figma-use eval "const r = figma.createRectangle(); r.resize(100, 100); return r.id"
+
+# Async code (top-level await supported)
+figma-use eval "const node = await figma.getNodeByIdAsync('1:2'); return node.name"
+```
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -180,39 +242,26 @@ $ figma-use get-node --id "1:2" --json
 
 ## For AI Agents
 
-figma-use is designed for AI agents. Example with Claude:
-
-```python
-import anthropic
-import subprocess
-
-def figma(cmd):
-    result = subprocess.run(
-        f"figma-use {cmd} --json",
-        shell=True, capture_output=True, text=True
-    )
-    return result.stdout
-
-client = anthropic.Anthropic()
-
-response = client.messages.create(
-    model="claude-sonnet-4-20250514",
-    messages=[{
-        "role": "user", 
-        "content": "Create a blue button with white text 'Click me'"
-    }],
-    tools=[{
-        "name": "figma",
-        "description": "Run figma-use CLI command",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "command": {"type": "string"}
-            }
-        }
-    }]
-)
+figma-use is designed to work with AI coding agents like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh), or any agent that can execute shell commands.
+
+### Using with Claude Code
+
+Add the [web-to-figma skill](https://github.com/anthropics/claude-code/tree/main/skills) to your agent:
+
+```bash
+# The skill teaches the agent how to:
+# - Extract styles from web pages
+# - Recreate UI components in Figma
+# - Match colors, fonts, spacing, and layout
+```
+
+Then just ask:
+
 ```
+Recreate this login form in Figma: https://example.com/login
+```
+
+The agent will use `figma-use` commands to build the design.
 
 ## License
 

package/bin/figma-use.js

@@ -4,18 +4,7 @@ import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const args = process.argv.slice(2)
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js')
 
-// If first arg is 'proxy' or 'plugin', handle specially
-if (args[0] === 'proxy') {
-  const proxyPath = join(__dirname, '..', 'dist', 'proxy', 'index.js')
-  spawn('bun', ['run', proxyPath], { stdio: 'inherit' })
-} else if (args[0] === 'plugin') {
-  const pluginPath = join(__dirname, '..', 'packages', 'plugin', 'dist')
-  console.log(`Plugin files at: ${pluginPath}`)
-  console.log('Import manifest.json into Figma via Plugins > Development > Import plugin from manifest')
-} else {
-  // CLI command
-  const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js')
-  spawn('bun', ['run', cliPath, ...args], { stdio: 'inherit' })
-}
+const child = spawn('bun', ['run', cliPath, ...process.argv.slice(2)], { stdio: 'inherit' })
+child.on('exit', (code) => process.exit(code || 0))

package/dist/cli/index.js

@@ -27,6 +27,7 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
 
 // node_modules/.bun/consola@3.4.2/node_modules/consola/dist/chunks/prompt.mjs
 var exports_prompt = {};
@@ -2450,6 +2451,8 @@ __export(exports_commands, {
   screenshot: () => screenshot_default,
   "resize-node": () => resize_node_default,
   "rename-node": () => rename_node_default,
+  proxy: () => proxy_default,
+  plugin: () => plugin_default,
   "move-node": () => move_node_default,
   "intersect-nodes": () => intersect_nodes_default,
   "import-svg": () => import_svg_default,
@@ -2466,6 +2469,7 @@ __export(exports_commands, {
   "export-selection": () => export_selection_default,
   "export-node": () => export_node_default,
   "exclude-nodes": () => exclude_nodes_default,
+  eval: () => eval_default,
   "edit-component-property": () => edit_component_property_default,
   "delete-node": () => delete_node_default,
   "delete-component-property": () => delete_component_property_default,
@@ -2489,6 +2493,249 @@ __export(exports_commands, {
   "add-component-property": () => add_component_property_default
 });
 
+// packages/cli/src/commands/proxy.ts
+import { spawn } from "child_process";
+import { resolve, dirname } from "path";
+function getPackageRoot() {
+  const currentFile = import.meta.path || import.meta.url.replace("file://", "");
+  let dir = dirname(currentFile);
+  for (let i2 = 0;i2 < 10; i2++) {
+    try {
+      const pkg = __require(resolve(dir, "package.json"));
+      if (pkg.name === "@dannote/figma-use") {
+        return dir;
+      }
+    } catch {}
+    dir = dirname(dir);
+  }
+  return dirname(dirname(dirname(currentFile)));
+}
+var proxy_default = defineCommand({
+  meta: { description: "Start the WebSocket proxy server" },
+  args: {
+    port: { type: "string", description: "Port to listen on", default: "38451" }
+  },
+  run({ args }) {
+    process.env.PORT = args.port;
+    const root = getPackageRoot();
+    const proxyPath = resolve(root, "dist", "proxy", "index.js");
+    const child = spawn("bun", ["run", proxyPath], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code || 0));
+  }
+});
+// packages/cli/src/commands/plugin.ts
+import { resolve as resolve2, dirname as dirname2, join } from "path";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+function getPackageRoot2() {
+  const currentFile = import.meta.path || import.meta.url.replace("file://", "");
+  let dir = dirname2(currentFile);
+  for (let i2 = 0;i2 < 10; i2++) {
+    try {
+      const pkg = __require(resolve2(dir, "package.json"));
+      if (pkg.name === "@dannote/figma-use") {
+        return dir;
+      }
+    } catch {}
+    dir = dirname2(dir);
+  }
+  return dirname2(dirname2(dirname2(currentFile)));
+}
+function getFigmaSettingsPath() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Application Support", "Figma", "settings.json");
+  } else if (process.platform === "win32") {
+    const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+    return join(appData, "Figma", "settings.json");
+  } else {
+    return join(home, ".config", "Figma", "settings.json");
+  }
+}
+function isFigmaRunning() {
+  try {
+    if (process.platform === "darwin") {
+      execSync("pgrep -x Figma", { stdio: "pipe" });
+      return true;
+    } else if (process.platform === "win32") {
+      execSync('tasklist /FI "IMAGENAME eq Figma.exe" | find "Figma.exe"', { stdio: "pipe" });
+      return true;
+    } else {
+      execSync("pgrep -x figma", { stdio: "pipe" });
+      return true;
+    }
+  } catch {
+    return false;
+  }
+}
+function getNextId(extensions) {
+  if (!extensions || extensions.length === 0)
+    return 1;
+  return Math.max(...extensions.map((e2) => e2.id)) + 1;
+}
+function installPlugin(manifestPath) {
+  const settingsPath = getFigmaSettingsPath();
+  if (!settingsPath || !existsSync(settingsPath)) {
+    return {
+      success: false,
+      message: "Figma settings not found. Please install Figma Desktop first."
+    };
+  }
+  if (isFigmaRunning()) {
+    return {
+      success: false,
+      message: "Figma is running. Please quit Figma first, then run this command again."
+    };
+  }
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const extensions = settings.localFileExtensions || [];
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    const pluginId = manifest.id || "figma-use-plugin";
+    const existing = extensions.find((e2) => e2.lastKnownPluginId === pluginId && e2.fileMetadata?.type === "manifest");
+    if (existing) {
+      if (existing.manifestPath !== manifestPath) {
+        existing.manifestPath = manifestPath;
+        const pluginDir2 = dirname2(manifestPath);
+        for (const ext of extensions) {
+          if (ext.fileMetadata?.manifestFileId === existing.id) {
+            if (ext.fileMetadata.type === "code") {
+              ext.manifestPath = join(pluginDir2, manifest.main || "main.js");
+            } else if (ext.fileMetadata.type === "ui") {
+              ext.manifestPath = join(pluginDir2, manifest.ui || "ui.html");
+            }
+          }
+        }
+        settings.localFileExtensions = extensions;
+        writeFileSync(settingsPath, JSON.stringify(settings));
+        return { success: true, message: "Plugin path updated" };
+      }
+      return { success: true, message: "Plugin already installed" };
+    }
+    const pluginDir = dirname2(manifestPath);
+    const manifestId = getNextId(extensions);
+    const codeId = manifestId + 1;
+    const uiId = manifestId + 2;
+    extensions.push({
+      id: manifestId,
+      manifestPath,
+      lastKnownName: manifest.name || "Figma Use",
+      lastKnownPluginId: pluginId,
+      fileMetadata: {
+        type: "manifest",
+        codeFileId: codeId,
+        uiFileIds: [uiId]
+      },
+      cachedContainsWidget: false
+    });
+    extensions.push({
+      id: codeId,
+      manifestPath: join(pluginDir, manifest.main || "main.js"),
+      fileMetadata: {
+        type: "code",
+        manifestFileId: manifestId
+      }
+    });
+    extensions.push({
+      id: uiId,
+      manifestPath: join(pluginDir, manifest.ui || "ui.html"),
+      fileMetadata: {
+        type: "ui",
+        manifestFileId: manifestId
+      }
+    });
+    settings.localFileExtensions = extensions;
+    writeFileSync(settingsPath, JSON.stringify(settings));
+    return { success: true, message: "Plugin installed successfully" };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to install: ${error instanceof Error ? error.message : error}`
+    };
+  }
+}
+function uninstallPlugin(manifestPath) {
+  const settingsPath = getFigmaSettingsPath();
+  if (!settingsPath || !existsSync(settingsPath)) {
+    return { success: false, message: "Figma settings not found" };
+  }
+  if (isFigmaRunning()) {
+    return {
+      success: false,
+      message: "Figma is running. Please quit Figma first."
+    };
+  }
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const extensions = settings.localFileExtensions || [];
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    const pluginId = manifest.id || "figma-use-plugin";
+    const manifestEntry = extensions.find((e2) => e2.lastKnownPluginId === pluginId && e2.fileMetadata?.type === "manifest");
+    if (!manifestEntry) {
+      return { success: true, message: "Plugin not installed" };
+    }
+    const manifestId = manifestEntry.id;
+    settings.localFileExtensions = extensions.filter((e2) => e2.id !== manifestId && e2.fileMetadata?.manifestFileId !== manifestId);
+    writeFileSync(settingsPath, JSON.stringify(settings));
+    return { success: true, message: "Plugin uninstalled successfully" };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to uninstall: ${error instanceof Error ? error.message : error}`
+    };
+  }
+}
+var plugin_default = defineCommand({
+  meta: { description: "Install/uninstall Figma plugin" },
+  args: {
+    uninstall: { type: "boolean", description: "Uninstall the plugin" },
+    path: { type: "boolean", description: "Show plugin path only" },
+    force: { type: "boolean", description: "Force install even if Figma is running (not recommended)" }
+  },
+  async run({ args }) {
+    const root = getPackageRoot2();
+    const pluginPath = resolve2(root, "packages", "plugin", "dist", "manifest.json");
+    if (args.path) {
+      console.log(pluginPath);
+      return;
+    }
+    if (args.uninstall) {
+      const result2 = uninstallPlugin(pluginPath);
+      if (result2.success) {
+        consola.success(result2.message);
+      } else {
+        consola.error(result2.message);
+      }
+      return;
+    }
+    if (!args.force && isFigmaRunning()) {
+      consola.error("Figma is running");
+      consola.info("Please quit Figma, then run: figma-use plugin");
+      consola.info("Or use --force to install anyway (changes will apply on restart)");
+      return;
+    }
+    const result = installPlugin(pluginPath);
+    if (result.success) {
+      consola.success(result.message);
+      if (result.message !== "Plugin already installed") {
+        consola.box(`Next steps:
+
+1. Start Figma
+2. Open any Figma file
+3. Run: figma-use proxy
+4. In Figma: Plugins \u2192 Development \u2192 Figma Use`);
+      }
+    } else {
+      consola.error(result.message);
+      consola.box({
+        title: "Manual Installation",
+        message: `1. Open Figma Desktop
+2. Go to: Plugins \u2192 Development \u2192 Import plugin from manifest
+3. Select: ${pluginPath}`
+      });
+    }
+  }
+});
 // packages/cli/src/client.ts
 init_output();
 var PROXY_URL = process.env.FIGMA_PROXY_URL || "http://localhost:38451";
@@ -2514,6 +2761,19 @@ function handleError(error) {
   process.exit(1);
 }
 
+// packages/cli/src/commands/eval.ts
+init_output();
+var eval_default = defineCommand({
+  meta: { description: "Execute arbitrary code in Figma plugin context" },
+  args: {
+    code: { type: "positional", description: "JavaScript code to execute", required: true },
+    json: { type: "boolean", description: "Output raw JSON" }
+  },
+  async run({ args }) {
+    const result = await sendCommand("eval", { code: args.code });
+    printResult(result, args.json);
+  }
+});
 // packages/cli/src/commands/status.ts
 var status_default = defineCommand({
   meta: { description: "Check if plugin is connected" },
@@ -3627,7 +3887,7 @@ var zoom_to_fit_default = defineCommand({
   }
 });
 // packages/cli/src/commands/export-node.ts
-import { writeFileSync } from "fs";
+import { writeFileSync as writeFileSync2 } from "fs";
 var export_node_default = defineCommand({
   meta: { description: "Export node as image" },
   args: {
@@ -3646,7 +3906,7 @@ var export_node_default = defineCommand({
       });
       if (args.output) {
         const buffer = Buffer.from(result.data, "base64");
-        writeFileSync(args.output, buffer);
+        writeFileSync2(args.output, buffer);
         console.log(`Exported to ${args.output}`);
       } else {
         console.log(JSON.stringify(result, null, 2));
@@ -3673,7 +3933,7 @@ var delete_node_default = defineCommand({
   }
 });
 // packages/cli/src/commands/screenshot.ts
-import { writeFileSync as writeFileSync2 } from "fs";
+import { writeFileSync as writeFileSync3 } from "fs";
 var screenshot_default = defineCommand({
   meta: { description: "Take a screenshot of current viewport" },
   args: {
@@ -3687,7 +3947,7 @@ var screenshot_default = defineCommand({
         scale: Number(args.scale)
       });
       const buffer = Buffer.from(result.data, "base64");
-      writeFileSync2(args.output, buffer);
+      writeFileSync3(args.output, buffer);
       console.log(args.output);
     } catch (e2) {
       handleError(e2);
@@ -3695,7 +3955,7 @@ var screenshot_default = defineCommand({
   }
 });
 // packages/cli/src/commands/export-selection.ts
-import { writeFileSync as writeFileSync3 } from "fs";
+import { writeFileSync as writeFileSync4 } from "fs";
 var export_selection_default = defineCommand({
   meta: { description: "Export current selection as image" },
   args: {
@@ -3713,7 +3973,7 @@ var export_selection_default = defineCommand({
         padding: Number(args.padding)
       });
       const buffer = Buffer.from(result.data, "base64");
-      writeFileSync3(args.output, buffer);
+      writeFileSync4(args.output, buffer);
       console.log(args.output);
     } catch (e2) {
       handleError(e2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dannote/figma-use",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Control Figma from the command line. Like browser-use, but for Figma.",
   "type": "module",
   "bin": {
@@ -46,14 +46,8 @@
     "elysia": "^1.2.25"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.52.0",
-    "@anthropic-ai/tokenizer": "^0.0.4",
     "@types/bun": "^1.3.6",
     "esbuild": "^0.25.4",
     "typescript": "^5.8.3"
-  },
-  "engines": {
-    "node": ">=18",
-    "bun": ">=1.0"
   }
 }

package/packages/plugin/dist/main.js

@@ -877,6 +877,17 @@
           node.remove();
           return { deleted: true };
         }
+        // ==================== EVAL ====================
+        case "eval": {
+          const { code } = args;
+          const AsyncFunction = Object.getPrototypeOf(function() {
+            return __async(this, null, function* () {
+            });
+          }).constructor;
+          const wrappedCode = code.trim().startsWith("return") ? code : `return (async () => { ${code} })()`;
+          const fn = new AsyncFunction("figma", wrappedCode);
+          return yield fn(figma);
+        }
         default:
           throw new Error(`Unknown command: ${command}`);
       }