figma-local 1.2.0 → 1.4.0

package/README.md

@@ -99,32 +99,66 @@ npm install && npm install -g .
 
 ## Setup (one time only)
 
-### 1. Import the Figma plugin
+### Step 1 — Install the CLI
 
-1. Open **Figma Desktop**
-2. Hamburger menu → **Plugins → Development → Import plugin from manifest...**
-3. Navigate to the `plugin/` folder in this repo (or `$(npm root -g)/figma-local/plugin/`)
-4. Select `manifest.json` → click **Open**
-5. Right-click **Figma Local** in the plugin list → **Add to toolbar**
+Pick one of the install methods above (npm recommended):
 
-### 2. Connect
+```bash
+npm install -g figma-local
+```
+
+Verify it worked:
 
 ```bash
-fig-start --safe
+fig --help
+```
+
+### Step 2 — Import the Figma plugin into Figma Desktop
+
+The plugin lets figma-local talk to Figma. You only need to do this once per Figma account.
+
+1. Open **Figma Desktop** (not the browser — the desktop app)
+2. Open any design file
+3. Click the **hamburger menu** (☰) in the top-left corner
+4. Go to **Plugins → Development → Import plugin from manifest...**
+5. In the file picker, navigate to the plugin folder:
+   - If you installed via **npm**: run `echo "$(npm root -g)/figma-local/plugin"` in your terminal to get the path, then navigate there
+   - If you cloned the **repo**: go to `figma-local/plugin/` in the cloned folder
+6. Select `manifest.json` → click **Open**
+7. You should see **"Figma Local"** appear in your plugin list
+8. *(Optional but recommended)* Right-click **Figma Local** in the plugin list → **Add to toolbar** for one-click access
+
+### Step 3 — Connect and verify
+
+1. In Figma, start the plugin: **Plugins → Development → Figma Local** (or click it in your toolbar)
+2. You should see a small widget that says **"Figma Local"** with a connecting status
+3. In your terminal, run:
+
+```bash
+fig connect --safe
 ```
 
-This starts the daemon, waits for you to click Figma Local in Figma, then launches Claude Code.
+4. The plugin widget should show a **green dot** and say **"Connected"**
+5. Try reading your canvas:
+
+```bash
+fig read
+```
+
+If you see a list of frames, you're all set!
 
 ---
 
 ## Every session after that
 
-```
-1. Open Figma → click Figma Local in the toolbar
-2. In terminal: fig-start --safe
+```bash
+# 1. Open Figma Desktop and your design file
+# 2. Click "Figma Local" in the toolbar (or Plugins → Development → Figma Local)
+# 3. In your terminal:
+fig-start --safe
 ```
 
-Claude Code reads `CLAUDE.md` and knows every command automatically.
+This connects to Figma and launches Claude Code. Claude reads `CLAUDE.md` and knows every `fig` command automatically.
 
 ---
 
@@ -255,13 +289,34 @@ fig prompt "Login" \
 
 Generates ~45 tokens of structured text instead of attaching a Figma frame (300–500+ hidden tokens). **91–97% smaller input, more consistent AI output.**
 
+### Screenshots
+
+```bash
+fig screenshot                           # Screenshot current selection
+fig screenshot --node "123:456"          # Screenshot a specific node
+fig screenshot --link "https://..."      # Screenshot from a Figma link
+fig screenshot -o design.png -s 2        # Save to file at 2x scale
+fig screenshot -f svg -o icon.svg        # Export as SVG
+```
+
 ### Verify & compare
 
 ```bash
-fig verify                         # Screenshot of selection for AI review
-fig verify --compare "https://..."  # Diff prototype vs Figma design → correction prompts
+fig verify                                          # Screenshot of selection for AI review
+fig verify --link "https://..."                     # Verify from a Figma link
+fig verify --node "123:456"                         # Verify a specific node
+fig verify --compare "https://..."                  # Diff prototype vs Figma design → correction prompts
+
+# Visual comparison between any two sources
+fig compare --a selection --b "123:456"              # Compare selection vs a node
+fig compare --a design.png --b "123:456"             # Compare a screenshot file vs a Figma node
+fig compare --a design.png --b coded.png             # Compare two screenshot files
+fig compare --a-link "https://..." --b-link "https://..."  # Compare two Figma links
+fig compare --a "123:456" --b "789:012"              # Compare two nodes by ID
 ```
 
+Sources for `--a` and `--b` can be: `selection`, a node ID (`123:456`), or a file path (`screenshot.png`). Use `--a-link` / `--b-link` for Figma selection URLs.
+
 ### Export
 
 ```bash
@@ -340,7 +395,7 @@ fig-start --safe --here     # launch from your project dir; Claude sees both you
 
 ## Claude Code Plugin (Skills)
 
-figma-local ships as a Claude Code plugin with 6 skills that teach coding agents how to use it automatically:
+figma-local ships as a Claude Code plugin with 8 skills that teach coding agents how to use it automatically:
 
 | Skill | Triggers on |
 |-------|------------|
@@ -350,6 +405,8 @@ figma-local ships as a Claude Code plugin with 6 skills that teach coding agents
 | **figma-styles** | "style guide", "extract colors/fonts", "spacing scale" |
 | **figma-measure** | "measure spacing", "gap between elements" |
 | **figma-document** | "document this component", "full spec sheet", "deep breakdown" |
+| **figma-screenshot** | "take a screenshot", "export as PNG/SVG", "capture this" |
+| **figma-compare** | "compare", "does this match", "visual diff", "check against design" |
 
 ### Install the skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-local",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Control Figma Desktop with Claude Code. Smart read, write, and AI-prompt export. No API key required.",
   "author": "elvke",
   "license": "MIT",

package/skills/figma-compare/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: figma-compare
+description: |
+  Use this skill when the user wants to visually compare two things — two Figma elements, a screenshot vs a Figma component, two screenshots, or a design vs coded output. Triggers on: "compare", "diff", "does this match", "check against", "visual comparison", "how close is this", "spot the differences", "compare design to code", "compare these two", "are they the same". Also use when verifying coded UI matches a Figma design. Requires the fig CLI to be connected.
+allowed-tools:
+  - Bash(fig compare *)
+  - Bash(fig compare)
+  - Bash(fig verify *)
+  - Bash(fig verify)
+  - Bash(fig screenshot *)
+  - Bash(fig screenshot)
+  - Read
+---
+
+# Figma Compare
+
+Visually compare any two sources: Figma selections, node IDs, Figma links, or screenshot files. Outputs both images and a structured gap report template for analysis.
+
+## Prerequisites
+
+The `fig` CLI must be connected. Check with `fig daemon status`. If not connected: `fig connect --safe`.
+
+## Usage
+
+### Compare current selection vs a node
+
+```bash
+fig compare --a selection --b "123:456"
+```
+
+### Compare two screenshot files
+
+```bash
+fig compare --a design.png --b coded-output.png
+```
+
+### Compare a screenshot file vs a Figma node
+
+```bash
+fig compare --a screenshot.png --b "123:456"
+```
+
+### Compare two Figma links
+
+```bash
+fig compare --a-link "https://www.figma.com/...?node-id=1-2" --b-link "https://www.figma.com/...?node-id=3-4"
+```
+
+### Compare selection vs a Figma link
+
+```bash
+fig compare --a selection --b-link "https://www.figma.com/...?node-id=123-456"
+```
+
+### Compare two nodes by ID
+
+```bash
+fig compare --a "123:456" --b "789:012"
+```
+
+## Source types
+
+The `--a` and `--b` options accept three source types:
+
+| Source | Example | Description |
+|--------|---------|-------------|
+| `selection` | `--a selection` | Whatever is currently selected in Figma |
+| Node ID | `--a "123:456"` | A specific Figma node by its ID |
+| File path | `--a design.png` | An existing screenshot/image file on disk |
+
+For Figma selection URLs, use `--a-link` / `--b-link` instead.
+
+## Options
+
+```bash
+fig compare --a selection --b "123:456" -s 2         # 2x scale for exports
+fig compare --a selection --b "123:456" --max 3000    # Max dimension 3000px
+fig compare --a selection --b "123:456" --save-dir .  # Save images to current dir
+```
+
+## Output
+
+The command exports both sources as PNG images (saved to `/tmp/` by default) and outputs:
+
+1. **File paths** for both images — use `Read` tool to view them
+2. **Structured JSON** with a gap report template:
+   - `matches` — elements that are the same
+   - `differences` — table of element, property, value in A, value in B, severity
+   - `summary` — overall assessment
+
+## Workflow: Design vs Code Comparison
+
+1. Take a screenshot of the coded output (browser screenshot or `fig screenshot`)
+2. Get the Figma node ID or link for the original design
+3. Run compare:
+   ```bash
+   fig compare --a coded-output.png --b-link "https://www.figma.com/...?node-id=123-456"
+   ```
+4. Read both output images to visually analyze differences
+5. Use `fig inspect` on the Figma node to get exact specs for fixing differences
+
+## Workflow: Before/After Comparison
+
+1. Screenshot the current state: `fig screenshot --node "123:456" -o before.png`
+2. Make changes in Figma
+3. Compare: `fig compare --a before.png --b "123:456"`
+
+## Verify command (simpler alternative)
+
+For quick verification of a single element without a full comparison:
+
+```bash
+fig verify                              # Screenshot selection for AI review
+fig verify --node "123:456"             # Verify specific node
+fig verify --link "https://..."         # Verify from Figma link
+fig verify --compare "https://..."      # Compare against a prototype URL
+```
+
+## Tips
+
+- Use `--save-dir .` to save comparison images in your project directory instead of `/tmp/`
+- For AI-powered analysis, read both output images with the `Read` tool after running compare
+- Combine with `fig inspect --deep` on the Figma source to get exact specs for fixing any differences
+- When comparing design to code, screenshot the browser at the same viewport width as the Figma frame for best results

package/skills/figma-screenshot/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: figma-screenshot
+description: |
+  Use this skill when the user wants to take a screenshot or export an image from Figma — current selection, a specific node, or from a Figma link. Triggers on: "screenshot", "take a screenshot", "export as PNG", "export as SVG", "capture this", "save as image", "export this frame", "get an image of". Requires the fig CLI to be connected.
+allowed-tools:
+  - Bash(fig screenshot *)
+  - Bash(fig screenshot)
+---
+
+# Figma Screenshot
+
+Export any Figma element as an image (PNG, JPG, SVG, or PDF).
+
+## Prerequisites
+
+The `fig` CLI must be connected. Check with `fig daemon status`. If not connected: `fig connect --safe`.
+
+## Usage
+
+### Screenshot current selection
+
+The user must select an element in Figma first, then:
+
+```bash
+fig screenshot
+```
+
+Saves to `screenshot.png` in the current directory by default.
+
+### Screenshot from a Figma link
+
+```bash
+fig screenshot --link "https://www.figma.com/design/FILEID/Name?node-id=123-456"
+```
+
+### Screenshot a specific node by ID
+
+```bash
+fig screenshot --node "123:456"
+```
+
+### Options
+
+```bash
+fig screenshot -o design.png          # Custom output file name
+fig screenshot -s 2                   # 2x scale (default is 2)
+fig screenshot -s 4                   # 4x scale for high-res
+fig screenshot -f svg                 # SVG format
+fig screenshot -f jpg                 # JPG format
+fig screenshot -f pdf                 # PDF format
+```
+
+### Combine options
+
+```bash
+fig screenshot --link "https://..." -o hero-section.png -s 3
+fig screenshot --node "123:456" -f svg -o icon.svg
+```
+
+## Export a specific node by ID (alternative)
+
+```bash
+fig export node "123:456"                    # PNG at 2x
+fig export node "123:456" -f svg -o out.svg  # SVG
+```
+
+## Tips
+
+- Default scale is 2x which gives crisp images on retina displays
+- Use `-s 1` for pixel-accurate exports (1:1 with Figma dimensions)
+- SVG format is best for icons and vector graphics
+- For AI verification of created components, use `fig verify` instead (optimized for smaller file size)
+- Screenshots can be used with `fig compare` to visually diff against other screenshots or Figma nodes

package/src/index.js

@@ -5205,18 +5205,30 @@ const exp = program
 
 exp
   .command('screenshot')
-  .description('Take a screenshot of selected node or current page')
+  .description('Take a screenshot of selected node, specific node, or from a Figma link')
   .option('-o, --output <file>', 'Output file', 'screenshot.png')
   .option('-s, --scale <number>', 'Export scale (1-4)', '2')
   .option('-f, --format <format>', 'Format: png, jpg, svg, pdf', 'png')
+  .option('--node <id>', 'Screenshot a specific node by ID')
+  .option('--link <url>', 'Screenshot a node from a Figma selection link')
   .action((options) => {
     checkConnection();
     const format = options.format.toUpperCase();
     const scale = parseFloat(options.scale);
+    let nodeResolver;
+    if (options.link) {
+      const nodeId = parseNodeIdFromLink(options.link);
+      if (!nodeId) { console.error(chalk.red('✗'), 'Could not parse node ID from link'); process.exit(1); }
+      nodeResolver = `node = await figma.getNodeByIdAsync('${nodeId}');`;
+    } else if (options.node) {
+      nodeResolver = `node = await figma.getNodeByIdAsync('${options.node}');`;
+    } else {
+      nodeResolver = `const sel = figma.currentPage.selection; node = sel.length > 0 ? sel[0] : figma.currentPage;`;
+    }
     const code = `(async () => {
-const sel = figma.currentPage.selection;
-const node = sel.length > 0 ? sel[0] : figma.currentPage;
-if (!node) return { error: 'No page or selection' };
+let node;
+${nodeResolver}
+if (!node) return { error: 'No node found' };
 if (!('exportAsync' in node)) return { error: 'Node cannot be exported' };
 const bytes = await node.exportAsync({ format: '${format}', constraint: { type: 'SCALE', value: ${scale} } });
 return {
@@ -5333,14 +5345,25 @@ program
   .option('--save [path]', 'Save as PNG file (default: /tmp/figma-verify-{id}.png)')
   .option('--compare <url>', 'Compare against a prototype/preview URL and generate correction prompts')
   .option('--compare-save <path>', 'Save prototype screenshot to this path when using --compare')
+  .option('--link <url>', 'Verify a node from a Figma selection link')
+  .option('--node <id>', 'Verify a specific node by ID')
   .action(async (nodeId, options) => {
     checkConnection();
     const scale = parseFloat(options.scale);
     const maxDim = parseInt(options.max);
 
+    // Resolve node: --link > --node > positional nodeId > selection
+    let resolvedNodeId = nodeId;
+    if (options.link) {
+      resolvedNodeId = parseNodeIdFromLink(options.link);
+      if (!resolvedNodeId) { console.error(chalk.red('✗'), 'Could not parse node ID from link'); process.exit(1); }
+    } else if (options.node) {
+      resolvedNodeId = options.node;
+    }
+
     const code = `(async () => {
       let node;
-      ${nodeId ? `node = await figma.getNodeByIdAsync('${nodeId}');` : `
+      ${resolvedNodeId ? `node = await figma.getNodeByIdAsync('${resolvedNodeId}');` : `
       const sel = figma.currentPage.selection;
       node = sel.length > 0 ? sel[0] : null;
       `}
@@ -5441,6 +5464,137 @@ program
     }
   });
 
+// ============ COMPARE (Visual Comparison) ============
+
+function exportNodeScreenshot(nodeResolver, scale, maxDim) {
+  const code = `(async () => {
+    let node;
+    ${nodeResolver}
+    if (!node) return { error: 'No node found' };
+    if (!('exportAsync' in node)) return { error: 'Node cannot be exported' };
+    const nodeWidth = node.width || 100;
+    const nodeHeight = node.height || 100;
+    let finalScale = ${scale};
+    const maxNodeDim = Math.max(nodeWidth, nodeHeight);
+    if (maxNodeDim * finalScale > ${maxDim}) finalScale = ${maxDim} / maxNodeDim;
+    if (maxNodeDim * finalScale > 7500) finalScale = 7500 / maxNodeDim;
+    const bytes = await node.exportAsync({ format: 'PNG', constraint: { type: 'SCALE', value: finalScale } });
+    return {
+      name: node.name,
+      id: node.id,
+      type: node.type,
+      width: Math.round(nodeWidth * finalScale),
+      height: Math.round(nodeHeight * finalScale),
+      originalWidth: Math.round(nodeWidth),
+      originalHeight: Math.round(nodeHeight),
+      bytes: Array.from(bytes)
+    };
+  })()`;
+  return figmaEvalSync(code);
+}
+
+program
+  .command('compare')
+  .description('Compare two things visually: screenshots, Figma nodes, or a mix. Outputs both images for AI analysis.')
+  .option('--a <source>', 'First source: file path, node ID, or "selection"', 'selection')
+  .option('--b <source>', 'Second source: file path, node ID, or Figma link')
+  .option('--a-link <url>', 'First source from a Figma selection link')
+  .option('--b-link <url>', 'Second source from a Figma selection link')
+  .option('-s, --scale <number>', 'Export scale for Figma nodes', '1')
+  .option('--max <pixels>', 'Max dimension for exports', '2000')
+  .option('--save-dir <dir>', 'Directory to save comparison images', '/tmp')
+  .addHelpText('after', `
+Examples:
+  fig compare --a selection --b "123:456"          Compare selection vs a node
+  fig compare --a design.png --b "123:456"         Compare a screenshot file vs a Figma node
+  fig compare --a design.png --b coded.png         Compare two screenshot files
+  fig compare --a-link "https://..." --b-link "https://..."   Compare two Figma links
+  fig compare --a selection --b-link "https://..."  Compare selection vs a Figma link
+  fig compare --a "123:456" --b "789:012"          Compare two nodes by ID
+`)
+  .action((options) => {
+    checkConnection();
+    const scale = parseFloat(options.scale);
+    const maxDim = parseInt(options.max);
+    const saveDir = options.saveDir;
+    const timestamp = Date.now();
+
+    function resolveSource(source, linkOpt, label) {
+      // If it's a --link option
+      if (linkOpt) {
+        const nodeId = parseNodeIdFromLink(linkOpt);
+        if (!nodeId) { console.error(chalk.red('✗'), `Could not parse node ID from ${label} link`); process.exit(1); }
+        const result = exportNodeScreenshot(`node = await figma.getNodeByIdAsync('${nodeId}');`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      // File path (existing screenshot)
+      if (source && existsSync(source)) {
+        return { type: 'file', name: source.split('/').pop(), path: source };
+      }
+
+      // "selection"
+      if (source === 'selection') {
+        const result = exportNodeScreenshot(`const sel = figma.currentPage.selection; node = sel.length > 0 ? sel[0] : null;`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      // Node ID (contains ":")
+      if (source && source.includes(':')) {
+        const result = exportNodeScreenshot(`node = await figma.getNodeByIdAsync('${source}');`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      console.error(chalk.red('✗'), `${label}: "${source}" is not a valid file path, node ID, or "selection"`);
+      process.exit(1);
+    }
+
+    const sourceA = resolveSource(options.a, options.aLink, 'a');
+    const sourceB = resolveSource(options.b, options.bLink, 'b');
+
+    console.log(chalk.bold('\n## Visual Comparison\n'));
+    console.log(chalk.cyan('Source A:'), sourceA.name, sourceA.type === 'figma-node' ? `(${sourceA.nodeType} ${sourceA.id}, ${sourceA.originalWidth}x${sourceA.originalHeight})` : '(file)');
+    console.log(chalk.cyan('Source B:'), sourceB.name, sourceB.type === 'figma-node' ? `(${sourceB.nodeType} ${sourceB.id}, ${sourceB.originalWidth}x${sourceB.originalHeight})` : '(file)');
+    console.log('');
+    console.log(chalk.green('Image A:'), sourceA.path);
+    console.log(chalk.green('Image B:'), sourceB.path);
+    console.log('');
+
+    // Output structured data for AI agents
+    console.log(JSON.stringify({
+      mode: 'visual-comparison',
+      sourceA: { ...sourceA, bytes: undefined },
+      sourceB: { ...sourceB, bytes: undefined },
+      instructions: [
+        `1. Open and examine Image A: ${sourceA.path}`,
+        `2. Open and examine Image B: ${sourceB.path}`,
+        '3. Compare them visually for differences in:',
+        '   - Layout and spacing (padding, margins, gaps)',
+        '   - Colors (backgrounds, text, borders)',
+        '   - Typography (font size, weight, line-height)',
+        '   - Border radius and shadows',
+        '   - Missing or extra elements',
+        '   - Alignment and positioning',
+        '4. Output a structured gap report with specific differences',
+        '5. For each difference, provide the exact values from both sources',
+      ],
+      gapReportTemplate: {
+        matches: '(list elements that match between A and B)',
+        differences: '(table: element | property | value_in_A | value_in_B | severity)',
+        summary: '(brief overall assessment: how closely do they match)',
+      }
+    }, null, 2));
+  });
+
 // ============ EVAL ============
 
 program