figma-local 1.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-local",
-  "version": "1.9.0",
+  "version": "2.0.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-library/SKILL.md

@@ -11,162 +11,145 @@ allowed-tools:
 
 # Figma Library
 
-Access team library components and variables from other Figma files. Index libraries, search components by name, import by key, and browse design tokens.
+Access team library components and variables from other Figma files. Index libraries via REST API or plugin, search components by name, import by key, and browse design tokens.
 
 ## Prerequisites
 
 - The `fig` CLI must be connected: `fig daemon status`. If not: `fig connect --safe`.
 - The Figma plugin must have `teamlibrary` permission in its manifest. If library commands fail with a permission error, re-import the plugin in Figma (Plugins → Development → Import from manifest).
-- Libraries must be enabled in the current Figma file (check Assets panel → team library icon).
 
 ## IMPORTANT: How to access library components
 
-Figma's plugin API does **not** allow browsing library components directly. To work with library components, you must **index** them first:
+Figma's plugin API does **not** allow browsing library components directly. To work with library components, you must **index** them first. There are three ways to index:
 
-1. Open the **library file** in Figma (the file that contains the components)
-2. Run `fig library index` — this scans all pages and saves every component with its key
-3. Switch to your **working file**
-4. Run `fig library search --name "button"` — finds components from indexed libraries
-5. Run `fig library import --key "<key>"` — imports the component
+### Option A: REST API (recommended for large files)
 
-## Usage
+No plugin needed. Works on any file size without hanging Figma.
 
-### Index a library (run in the library file)
+**First time — provide token and file URL:**
+```bash
+fig library index --api --token "figd_xxxxx" --file "https://www.figma.com/design/ABC123/MyFile"
+```
 
-Open the library/design system file in Figma, then:
+The token is saved for future use. Get one from: Figma → Settings → Personal Access Tokens.
 
+**After first time — just provide the file URL:**
 ```bash
-fig library index
+fig library index --api --file "https://www.figma.com/design/ABC123/MyFile"
 ```
 
-This scans ALL pages in the file and saves every component (name, key, description, page, size, component set) to `~/.figma-local/libraries/<filename>.json`.
+### Option B: Page-by-page (for large files via plugin)
 
-Re-run this command after the library is updated to refresh the index.
-
-### Search indexed libraries
-
-Search across all indexed libraries by component name:
+Open the library file in Figma, then scan one page at a time:
 
 ```bash
-fig library search --name "button"
-fig library search --name "input"
-fig library search --name "card"
-fig library search --name "checkbox"
+fig library index --page "Buttons"
+fig library index --page "Inputs"
+fig library index --page "Cards"
 ```
 
-Returns: component name, key (for importing), component set, page, size, and library name.
+Each page's components are merged into the same index file. This avoids hanging on large files.
+
+### Option C: Full scan (small files only)
 
-Use `--json` for structured output:
+Open the library file in Figma, then:
 
 ```bash
-fig library search --name "button" --json
+fig library index
 ```
 
-### List indexed libraries
+**Warning:** This scans ALL pages at once. Only use on small files — large design systems will cause Figma to hang.
 
-See what libraries have been indexed:
+## After indexing: Search and Import
+
+### Search indexed libraries
 
 ```bash
-fig library list
+fig library search --name "button"
+fig library search --name "input"
+fig library search --name "card"
+fig library search --name "checkbox"
 ```
 
-Returns: library name, component count, page count, and when it was indexed.
-
-### Import a component by key
+Returns: component name, key (for importing), component set, page, and library name.
 
-Import a library component onto the canvas by its key:
+### List indexed libraries
 
 ```bash
-fig library import --key "abc123def456..."
+fig library list
 ```
 
-Import and rename:
+### Import by key
 
 ```bash
-fig library import --key "abc123def456..." --name "PrimaryButton"
+fig library import --key "<key-from-search>"
+fig library import --key "<key>" --name "PrimaryButton"
 ```
 
-The imported component instance is placed at the viewport center and selected.
+The component is placed at viewport center and selected.
 
-### List library variable collections
-
-See what variable collections are available from linked libraries:
+### Inspect the imported component
 
 ```bash
-fig library collections
+fig inspect --deep
 ```
 
-### List library variables
+## Variables (no indexing needed)
 
-Browse all variables across all linked library collections:
+Library variables are available directly via the plugin API:
 
 ```bash
-fig library variables
-fig library variables --name "color"
-fig library variables --name "spacing"
+fig library collections                    # List variable collections
+fig library variables                      # List all variables
+fig library variables --name "color"       # Search by name
 ```
 
-### List components on current page
+## Components on current page
 
-Find library components that are already used on the current page:
+Find library components already dragged onto the current page:
 
 ```bash
 fig library components
 fig library components --name "button"
 ```
 
-### JSON output
-
-All commands support `--json` for structured output.
+## Full workflow
 
-## Workflow: Building UI with library components
-
-1. **Index** the library (one-time, in the library file):
+1. **Index** the library (pick one method):
    ```bash
-   fig library index
+   # Best for large files:
+   fig library index --api --token "figd_..." --file "https://..."
+   # Or page by page:
+   fig library index --page "Buttons"
    ```
 
-2. **Switch** to your working file in Figma.
-
-3. **Search** for the components you need:
+2. **Search** for components:
    ```bash
-   fig library search --name "button"
-   fig library search --name "input"
+   fig library search --name "button" --json
    ```
 
-4. **Import** each component by key:
+3. **Import** into your working file:
    ```bash
-   fig library import --key "<key-from-search>"
+   fig library import --key "<key>"
    ```
 
-5. **Inspect** the imported component to get its full specs:
+4. **Inspect** for full specs:
    ```bash
    fig inspect --deep
    ```
 
-6. **Get variables** for design tokens:
+5. **Get variables** for tokens:
    ```bash
    fig library variables --name "primary" --json
    ```
 
-7. **Replicate** in code using the exact specs and token values.
-
-## Workflow: Extracting a full design system
-
-1. Open the design system file → `fig library index`
-2. Get all components: `fig library search --name "" --json`
-3. Get all variables: `fig library variables --json`
-4. Import key components one by one and document them:
-   ```bash
-   fig library import --key "<key>"
-   fig document --json
-   ```
+6. **Replicate** in code.
 
 ## Tips
 
-- **Index once, search many times** — the index is saved locally and persists across sessions.
-- Re-index when the library is updated: open the library file → `fig library index`.
-- `fig library components` only finds components already on the current page. Use `search` for the full library.
-- After importing a component, use `fig inspect --deep` to get full specs including variable bindings.
+- **REST API is fastest** for large design systems — no file opening needed.
+- Token is saved after first use in `~/.figma-local/figma-token`.
+- Page-by-page indexing merges results — run multiple times to build up the index.
+- Re-index when the library is updated to get new components.
+- `fig library search --name "" --json` returns ALL indexed components.
 - Component keys are stable across file versions — save them for repeated imports.
-- Use `fig library search --name "button" --json | jq '.[].key'` to extract just the keys.

package/src/index.js

@@ -10581,27 +10581,34 @@ program
   .option('--key <key>', 'Component key for importing')
   .option('--name <name>', 'Filter by name (partial match)')
   .option('--json', 'Output raw JSON')
+  .option('--api', 'Use Figma REST API instead of plugin (for index)')
+  .option('--token <token>', 'Figma personal access token (for --api)')
+  .option('--file <url>', 'Figma file URL (for --api)')
+  .option('--page <pageName>', 'Index only a specific page (for index)')
   .addHelpText('after', `
 Actions:
   collections    List all available library variable collections
   variables      List variables from a library collection (use --name to filter)
   components     List available library components on current page (use --name to filter)
-  index          Scan the current open file and save all components to a local index
+  index          Scan and save all components to a local index
   search         Search indexed libraries for components (use --name to filter)
   import         Import a component by key (use --key)
   list           List all indexed libraries
 
+Index modes:
+  fig library index                                           Scan current file via plugin (small files)
+  fig library index --page "Buttons"                          Scan only one page (large files)
+  fig library index --api --token "figd_..." --file "URL"     Use REST API (best for large files)
+  fig library index --api --file "URL"                        Use saved token
+
 Examples:
   fig library collections                    List all library variable collections
-  fig library variables                      List all library variables
   fig library variables --name "color"       List variables matching "color"
-  fig library components                     List available library components
   fig library components --name "button"     Find button components
-  fig library index                          Index all components in the current open file
+  fig library index --api --token "figd_..." --file "https://www.figma.com/design/ABC/..."
   fig library search --name "button"         Search indexed libraries for "button"
   fig library list                           List all indexed libraries
   fig library import --key "abc123..."       Import a component by its key
-  fig library import --key "abc123..." --name "MyButton"  Import and rename
 `)
   .action(async (action, options) => {
     checkConnection();
@@ -10794,13 +10801,214 @@ Examples:
         console.log(`  ${chalk.gray('id:')} ${result.id}`);
         console.log(chalk.gray('  Component is now selected on the canvas.'));
       } else if (action === 'index') {
-        spinner.text = 'Scanning all pages for components...';
-        const code = `(function() {
+        // Helper to save index data and print summary
+        function saveIndexAndPrint(result, opts) {
+          const libDir = join(homedir(), '.figma-local', 'libraries');
+          mkdirSync(libDir, { recursive: true });
+          const safeName = result.fileName.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+          const libFile = join(libDir, `${safeName}.json`);
+
+          // If file exists and we're doing page-by-page, merge
+          let existingComponents = [];
+          let existingPages = new Set();
+          if (opts.page && existsSync(libFile)) {
+            try {
+              const existing = JSON.parse(readFileSync(libFile, 'utf8'));
+              // Keep components from OTHER pages
+              existingComponents = (existing.components || []).filter(c => c.page !== opts.page);
+              existing.components.forEach(c => existingPages.add(c.page));
+            } catch (e) { /* fresh start */ }
+          }
+          const mergedComponents = [...existingComponents, ...result.components];
+          result.components.forEach(c => existingPages.add(c.page));
+
+          const indexData = {
+            fileName: result.fileName,
+            fileKey: result.fileKey || '',
+            indexedAt: new Date().toISOString(),
+            pageCount: opts.page ? existingPages.size : result.pageCount,
+            componentCount: mergedComponents.length,
+            components: mergedComponents
+          };
+          writeFileSync(libFile, JSON.stringify(indexData, null, 2));
+          return { indexData, libFile };
+        }
+
+        function printIndexSummary(indexData, libFile, opts) {
+          console.log(`  ${chalk.gray('Saved to:')} ${libFile}`);
+          if (opts.json) {
+            console.log(JSON.stringify(indexData, null, 2));
+          } else {
+            const sets = {};
+            const standalone = [];
+            for (const c of indexData.components) {
+              if (c.componentSet) {
+                if (!sets[c.componentSet]) sets[c.componentSet] = [];
+                sets[c.componentSet].push(c);
+              } else {
+                standalone.push(c);
+              }
+            }
+            if (Object.keys(sets).length > 0) {
+              console.log(chalk.cyan('\n  Component Sets:'));
+              for (const [setName, variants] of Object.entries(sets)) {
+                console.log(`    ${chalk.white(setName)} ${chalk.gray(`(${variants.length} variant${variants.length !== 1 ? 's' : ''})`)}`);
+              }
+            }
+            if (standalone.length > 0) {
+              console.log(chalk.cyan('\n  Standalone Components:'));
+              for (const c of standalone.slice(0, 50)) {
+                console.log(`    ${chalk.white(c.name)} ${chalk.gray(`[${c.page}]`)}`);
+              }
+              if (standalone.length > 50) {
+                console.log(chalk.gray(`    ... and ${standalone.length - 50} more`));
+              }
+            }
+          }
+        }
+
+        // ---- REST API mode ----
+        if (options.api) {
+          // Get or save token
+          const configDir = join(homedir(), '.figma-local');
+          mkdirSync(configDir, { recursive: true });
+          const tokenFile = join(configDir, 'figma-token');
+          let token = options.token || '';
+          if (!token && existsSync(tokenFile)) {
+            token = readFileSync(tokenFile, 'utf8').trim();
+          }
+          if (!token) {
+            spinner.fail('Figma token required. Get one from: Figma → Settings → Personal Access Tokens\nThen run: fig library index --api --token "figd_..." --file "URL"');
+            process.exit(1);
+          }
+          // Save token for future use
+          if (options.token) {
+            writeFileSync(tokenFile, token);
+          }
+
+          if (!options.file) {
+            spinner.fail('--file is required with --api. Provide a Figma file URL.\nExample: fig library index --api --file "https://www.figma.com/design/ABC123/MyFile"');
+            process.exit(1);
+          }
+
+          // Extract file key from URL
+          const fileKeyMatch = options.file.match(/(?:file|design)\/([a-zA-Z0-9]+)/);
+          if (!fileKeyMatch) {
+            spinner.fail('Could not extract file key from URL. Use a URL like: https://www.figma.com/design/ABC123/MyFile');
+            process.exit(1);
+          }
+          const fileKey = fileKeyMatch[1];
+
+          spinner.text = `Fetching file metadata from Figma API...`;
+
+          // Fetch the file from the REST API
+          const https = await import('https');
+          function figmaApiGet(endpoint) {
+            return new Promise((resolve, reject) => {
+              const url = `https://api.figma.com/v1${endpoint}`;
+              const req = https.get(url, { headers: { 'X-Figma-Token': token } }, (res) => {
+                let data = '';
+                res.on('data', chunk => data += chunk);
+                res.on('end', () => {
+                  if (res.statusCode === 403) {
+                    reject(new Error('Access denied. Check your token has read access to this file.'));
+                  } else if (res.statusCode === 404) {
+                    reject(new Error('File not found. Check the URL is correct.'));
+                  } else if (res.statusCode !== 200) {
+                    reject(new Error(`Figma API returned ${res.statusCode}: ${data.slice(0, 200)}`));
+                  } else {
+                    try { resolve(JSON.parse(data)); }
+                    catch (e) { reject(new Error('Invalid JSON response from Figma API')); }
+                  }
+                });
+              });
+              req.on('error', reject);
+            });
+          }
+
           try {
-            var components = [];
-            var pages = figma.root.children;
-            for (var p = 0; p < pages.length; p++) {
-              var page = pages[p];
+            // Get file components via the components endpoint (lightweight)
+            spinner.text = 'Fetching components from Figma API...';
+            const compData = await figmaApiGet(`/files/${fileKey}/components`);
+
+            const components = [];
+            if (compData.meta && compData.meta.components) {
+              for (const comp of compData.meta.components) {
+                const c = {
+                  name: comp.name,
+                  key: comp.key,
+                  id: comp.node_id,
+                  page: comp.containing_frame ? comp.containing_frame.pageName || '' : '',
+                  description: comp.description || '',
+                };
+                if (comp.containing_frame && comp.containing_frame.name) {
+                  // The containing_frame for component set variants shows the set name
+                  c.componentSet = comp.containing_frame.name !== comp.name ? comp.containing_frame.name : undefined;
+                }
+                components.push(c);
+              }
+            }
+
+            // Also get component sets
+            spinner.text = 'Fetching component sets from Figma API...';
+            try {
+              const setsData = await figmaApiGet(`/files/${fileKey}/component_sets`);
+              if (setsData.meta && setsData.meta.component_sets) {
+                for (const set of setsData.meta.component_sets) {
+                  // Mark components that belong to this set
+                  for (const comp of components) {
+                    if (comp.id && set.node_id && comp.componentSet === undefined) {
+                      // Check if node is child of this set by matching containing_frame
+                    }
+                  }
+                }
+              }
+            } catch (e) { /* component_sets endpoint may not exist for all plans */ }
+
+            // Get file name
+            spinner.text = 'Fetching file info...';
+            let fileName = fileKey;
+            try {
+              const fileInfo = await figmaApiGet(`/files/${fileKey}?depth=1`);
+              if (fileInfo.name) fileName = fileInfo.name;
+            } catch (e) { /* use fileKey as fallback */ }
+
+            const result = {
+              fileName,
+              fileKey,
+              pageCount: 0,
+              componentCount: components.length,
+              components
+            };
+
+            const { indexData, libFile } = saveIndexAndPrint(result, options);
+            spinner.succeed(`Indexed ${components.length} components from "${fileName}" via API`);
+            printIndexSummary(indexData, libFile, options);
+
+          } catch (e) {
+            spinner.fail(`Figma API error: ${e.message}`);
+            process.exit(1);
+          }
+
+        // ---- Plugin mode with --page filter ----
+        } else if (options.page) {
+          const pageName = options.page;
+          spinner.text = `Scanning page "${pageName}" for components...`;
+          const safePageName = pageName.replace(/'/g, "\\'");
+          const code = `(function() {
+            try {
+              var components = [];
+              var targetPage = null;
+              var pages = figma.root.children;
+              for (var p = 0; p < pages.length; p++) {
+                if (pages[p].name === '${safePageName}' || pages[p].name.toLowerCase().indexOf('${safePageName.toLowerCase()}') !== -1) {
+                  targetPage = pages[p];
+                  break;
+                }
+              }
+              if (!targetPage) {
+                return { error: 'Page "${safePageName}" not found. Available pages: ' + pages.map(function(p) { return p.name; }).join(', ') };
+              }
               function scanNode(node, pageName) {
                 if (node.type === 'COMPONENT') {
                   var comp = {
@@ -10823,66 +11031,79 @@ Examples:
                   }
                 }
               }
-              scanNode(page, page.name);
+              scanNode(targetPage, targetPage.name);
+              return {
+                fileName: figma.root.name,
+                fileKey: figma.fileKey || '',
+                pageCount: 1,
+                componentCount: components.length,
+                components: components
+              };
+            } catch(e) {
+              return { error: e.message || 'Failed to scan page for components.' };
             }
-            return {
-              fileName: figma.root.name,
-              fileKey: figma.fileKey || '',
-              pageCount: pages.length,
-              componentCount: components.length,
-              components: components
-            };
-          } catch(e) {
-            return { error: e.message || 'Failed to scan file for components.' };
+          })()`;
+          const result = await daemonExec('eval', { code });
+          if (result.error) {
+            spinner.fail(result.error);
+            process.exit(1);
           }
-        })()`;
-        const result = await daemonExec('eval', { code });
-        if (result.error) {
-          spinner.fail(result.error);
-          process.exit(1);
-        }
-        // Save to ~/.figma-local/libraries/
-        const libDir = join(homedir(), '.figma-local', 'libraries');
-        mkdirSync(libDir, { recursive: true });
-        const safeName = result.fileName.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
-        const libFile = join(libDir, `${safeName}.json`);
-        const indexData = {
-          fileName: result.fileName,
-          fileKey: result.fileKey,
-          indexedAt: new Date().toISOString(),
-          pageCount: result.pageCount,
-          componentCount: result.componentCount,
-          components: result.components
-        };
-        writeFileSync(libFile, JSON.stringify(indexData, null, 2));
-        spinner.succeed(`Indexed ${result.componentCount} components from "${result.fileName}" (${result.pageCount} pages)`);
-        console.log(`  ${chalk.gray('Saved to:')} ${libFile}`);
-        if (options.json) {
-          console.log(JSON.stringify(indexData, null, 2));
+          const { indexData, libFile } = saveIndexAndPrint(result, { page: pageName });
+          spinner.succeed(`Indexed ${result.componentCount} components from page "${pageName}" (${indexData.componentCount} total in library)`);
+          printIndexSummary(indexData, libFile, options);
+
+        // ---- Plugin mode full scan ----
         } else {
-          // Show summary by component set
-          const sets = {};
-          const standalone = [];
-          for (const c of result.components) {
-            if (c.componentSet) {
-              if (!sets[c.componentSet]) sets[c.componentSet] = [];
-              sets[c.componentSet].push(c);
-            } else {
-              standalone.push(c);
-            }
-          }
-          if (Object.keys(sets).length > 0) {
-            console.log(chalk.cyan('\n  Component Sets:'));
-            for (const [setName, variants] of Object.entries(sets)) {
-              console.log(`    ${chalk.white(setName)} ${chalk.gray(`(${variants.length} variant${variants.length !== 1 ? 's' : ''})`)}`);
-            }
-          }
-          if (standalone.length > 0) {
-            console.log(chalk.cyan('\n  Standalone Components:'));
-            for (const c of standalone) {
-              console.log(`    ${chalk.white(c.name)} ${chalk.gray(`[${c.page}]`)}`);
+          spinner.text = 'Scanning all pages for components...';
+          const code = `(function() {
+            try {
+              var components = [];
+              var pages = figma.root.children;
+              for (var p = 0; p < pages.length; p++) {
+                var page = pages[p];
+                function scanNode(node, pageName) {
+                  if (node.type === 'COMPONENT') {
+                    var comp = {
+                      name: node.name,
+                      key: node.key,
+                      id: node.id,
+                      page: pageName,
+                      description: node.description || '',
+                      w: Math.round(node.width),
+                      h: Math.round(node.height)
+                    };
+                    if (node.parent && node.parent.type === 'COMPONENT_SET') {
+                      comp.componentSet = node.parent.name;
+                    }
+                    components.push(comp);
+                  }
+                  if ('children' in node) {
+                    for (var i = 0; i < node.children.length; i++) {
+                      scanNode(node.children[i], pageName);
+                    }
+                  }
+                }
+                scanNode(page, page.name);
+              }
+              return {
+                fileName: figma.root.name,
+                fileKey: figma.fileKey || '',
+                pageCount: pages.length,
+                componentCount: components.length,
+                components: components
+              };
+            } catch(e) {
+              return { error: e.message || 'Failed to scan file for components.' };
             }
+          })()`;
+          const result = await daemonExec('eval', { code });
+          if (result.error) {
+            spinner.fail(result.error);
+            process.exit(1);
           }
+          const { indexData, libFile } = saveIndexAndPrint(result, {});
+          spinner.succeed(`Indexed ${result.componentCount} components from "${result.fileName}" (${result.pageCount} pages)`);
+          printIndexSummary(indexData, libFile, options);
         }
       } else if (action === 'search') {
         const nameFilter = options.name ? options.name.toLowerCase() : '';