figma-local 1.6.0 → 1.8.0

package/README.md

@@ -395,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 8 skills that teach coding agents how to use it automatically:
+figma-local ships as a Claude Code plugin with 9 skills that teach coding agents how to use it automatically:
 
 | Skill | Triggers on |
 |-------|------------|
@@ -407,6 +407,7 @@ figma-local ships as a Claude Code plugin with 8 skills that teach coding agents
 | **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" |
+| **figma-library** | "library components", "import from library", "team library variables" |
 
 ### Install the skills
 

package/package.json

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

package/plugin/manifest.json

@@ -5,6 +5,7 @@
   "main": "code.js",
   "ui": "ui.html",
   "capabilities": [],
+  "permissions": ["teamlibrary"],
   "enableProposedApi": false,
   "editorType": ["figma", "figjam"],
   "networkAccess": {

package/skills/figma-library/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: figma-library
+description: |
+  Use this skill when the user wants to access, browse, import, or use components and variables from a Figma team library or external Figma file. Triggers on: "library components", "import component", "library variables", "team library", "use components from another file", "get the button from the library", "what components are available", "design system components", "import from library", "library collections". Also use when building UI and the user references a design system or component library in another Figma file.
+allowed-tools:
+  - Bash(fig library *)
+  - Bash(fig library)
+  - Bash(fig inspect *)
+  - Bash(fig read *)
+---
+
+# Figma Library
+
+Access team library components and variables from other Figma files. Import components by key and browse available 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).
+
+## Usage
+
+### List library variable collections
+
+See what variable collections are available from linked libraries:
+
+```bash
+fig library collections
+```
+
+Returns: collection name, library name, and collection key for each.
+
+### List library variables
+
+Browse all variables across all linked library collections:
+
+```bash
+fig library variables
+```
+
+Filter by name:
+
+```bash
+fig library variables --name "color"
+fig library variables --name "spacing"
+fig library variables --name "radius"
+```
+
+Returns: variable name, type (COLOR, FLOAT, STRING), key, collection, and library name.
+
+### List library components
+
+Find library components that are already used on the current page:
+
+```bash
+fig library components
+```
+
+Filter by name:
+
+```bash
+fig library components --name "button"
+fig library components --name "input"
+fig library components --name "card"
+```
+
+Returns: component name, component set, key, description, and whether it's remote (library) or local.
+
+### Import a component by key
+
+Import a library component onto the canvas by its key:
+
+```bash
+fig library import --key "abc123def456..."
+```
+
+Import and rename:
+
+```bash
+fig library import --key "abc123def456..." --name "PrimaryButton"
+```
+
+The imported component instance is placed at the viewport center and selected.
+
+### JSON output
+
+All commands support `--json` for structured output:
+
+```bash
+fig library collections --json
+fig library variables --json
+fig library variables --name "color" --json
+fig library components --json
+```
+
+## Workflow: Building with library components
+
+1. **Discover** what's available:
+   ```bash
+   fig library collections
+   fig library variables --name "color"
+   fig library components --name "button"
+   ```
+
+2. **Import** the components you need:
+   ```bash
+   fig library import --key "<key-from-step-1>"
+   ```
+
+3. **Inspect** the imported component to get its specs:
+   ```bash
+   fig inspect --deep
+   ```
+
+4. **Read** variables to get token values:
+   ```bash
+   fig library variables --name "primary" --json
+   ```
+
+5. **Replicate** in code using the exact specs and token values.
+
+## Workflow: Extracting a design system
+
+1. List all variable collections:
+   ```bash
+   fig library collections --json
+   ```
+
+2. Export all variables grouped by type:
+   ```bash
+   fig library variables --name "color" --json > colors.json
+   fig library variables --name "spacing" --json > spacing.json
+   fig library variables --name "radius" --json > radii.json
+   ```
+
+3. Find key components:
+   ```bash
+   fig library components --json
+   ```
+
+4. Import and document each:
+   ```bash
+   fig library import --key "<key>"
+   fig document --json
+   ```
+
+## Tips
+
+- If `fig library components` returns empty, drag some components from the Assets panel onto the page first — the command scans instances on the current page.
+- Use `fig library variables --json` and pipe to `jq` for filtering: `fig library variables --json | jq '.[] | select(.resolvedType == "COLOR")'`
+- After importing a component, use `fig inspect --deep` to get full specs including variable bindings.
+- Component keys are stable across file versions — save them for repeated imports.

package/src/index.js

@@ -10573,4 +10573,228 @@ program
     }
   });
 
+// ============ LIBRARY — access team library components & variables ============
+
+program
+  .command('library <action>')
+  .description('Access team library components and variables from other Figma files')
+  .option('--key <key>', 'Component key for importing')
+  .option('--name <name>', 'Filter by name (partial match)')
+  .option('--json', 'Output raw JSON')
+  .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 (use --name to filter)
+  import         Import a component by key (use --key)
+
+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 import --key "abc123..."       Import a component by its key
+  fig library import --key "abc123..." --name "MyButton"  Import and rename
+`)
+  .action(async (action, options) => {
+    checkConnection();
+    const spinner = ora('Accessing library...').start();
+
+    try {
+      if (action === 'collections') {
+        spinner.text = 'Fetching library variable collections...';
+        const code = `(async function() {
+          try {
+            var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            return cols.map(function(c) {
+              return { name: c.name, key: c.key, libraryName: c.libraryName };
+            });
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library collections. Make sure teamlibrary permission is enabled.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Found ${result.length} library variable collection${result.length !== 1 ? 's' : ''}`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log(chalk.yellow('No library variable collections found. Make sure you have libraries enabled in this file.'));
+          }
+          for (const col of result) {
+            console.log(`  ${chalk.cyan(col.name)} ${chalk.gray('from')} ${chalk.white(col.libraryName)}`);
+            console.log(`    ${chalk.gray('key:')} ${col.key}`);
+          }
+        }
+      } else if (action === 'variables') {
+        spinner.text = 'Fetching library variables...';
+        const nameFilter = options.name ? options.name.toLowerCase() : '';
+        const code = `(async function() {
+          try {
+            var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            var allVars = [];
+            for (var i = 0; i < cols.length; i++) {
+              try {
+                var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(cols[i].key);
+                for (var j = 0; j < vars.length; j++) {
+                  allVars.push({
+                    name: vars[j].name,
+                    key: vars[j].key,
+                    resolvedType: vars[j].resolvedType,
+                    collection: cols[i].name,
+                    library: cols[i].libraryName
+                  });
+                }
+              } catch(e2) {}
+            }
+            ${nameFilter ? `allVars = allVars.filter(function(v) { return v.name.toLowerCase().indexOf('${nameFilter}') !== -1; });` : ''}
+            return allVars;
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library variables.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Found ${result.length} library variable${result.length !== 1 ? 's' : ''}`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log(chalk.yellow('No variables found.' + (nameFilter ? ` Try a different search term.` : '')));
+          }
+          let currentCollection = '';
+          for (const v of result) {
+            const collLabel = `${v.collection} (${v.library})`;
+            if (collLabel !== currentCollection) {
+              currentCollection = collLabel;
+              console.log(chalk.cyan(`\n  ${collLabel}`));
+            }
+            console.log(`    ${chalk.white(v.name)} ${chalk.gray(`[${v.resolvedType}]`)} ${chalk.gray('key:')} ${v.key}`);
+          }
+        }
+      } else if (action === 'components') {
+        spinner.text = 'Fetching library components...';
+        const nameFilter = options.name ? options.name.toLowerCase() : '';
+        const code = `(async function() {
+          try {
+            var collections = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            var libraryNames = collections.map(function(c) { return c.libraryName; });
+          } catch(e) { var libraryNames = []; }
+          try {
+            // Get components from the assets panel search
+            var components = [];
+            // Try to find components by listing component sets and instances on the current page
+            function findComponents(node) {
+              if (node.type === 'INSTANCE' && node.mainComponent) {
+                try {
+                  var mc = node.mainComponent;
+                  var parent = mc.parent;
+                  components.push({
+                    name: mc.name,
+                    key: mc.key,
+                    componentSetName: parent && parent.type === 'COMPONENT_SET' ? parent.name : null,
+                    description: mc.description || '',
+                    remote: mc.remote
+                  });
+                } catch(e) {}
+              }
+              if ('children' in node) {
+                for (var i = 0; i < node.children.length; i++) {
+                  findComponents(node.children[i]);
+                }
+              }
+            }
+            findComponents(figma.currentPage);
+            // Deduplicate by key
+            var seen = {};
+            var unique = [];
+            for (var i = 0; i < components.length; i++) {
+              if (!seen[components[i].key]) {
+                seen[components[i].key] = true;
+                unique.push(components[i]);
+              }
+            }
+            ${nameFilter ? `unique = unique.filter(function(c) { return c.name.toLowerCase().indexOf('${nameFilter}') !== -1 || (c.componentSetName && c.componentSetName.toLowerCase().indexOf('${nameFilter}') !== -1); });` : ''}
+            return { components: unique, note: unique.length === 0 ? 'No library components found on this page. Drag some components from the Assets panel first, or use fig library import --key <key> if you have the component key.' : null };
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library components.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        const comps = result.components || [];
+        spinner.succeed(`Found ${comps.length} component${comps.length !== 1 ? 's' : ''} on this page`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.note) {
+            console.log(chalk.yellow(`  ${result.note}`));
+          }
+          for (const c of comps) {
+            const setLabel = c.componentSetName ? chalk.gray(` (set: ${c.componentSetName})`) : '';
+            const remoteLabel = c.remote ? chalk.blue(' [library]') : chalk.gray(' [local]');
+            console.log(`  ${chalk.white(c.name)}${setLabel}${remoteLabel}`);
+            console.log(`    ${chalk.gray('key:')} ${c.key}`);
+            if (c.description) console.log(`    ${chalk.gray('desc:')} ${c.description}`);
+          }
+        }
+      } else if (action === 'import') {
+        if (!options.key) {
+          spinner.fail('--key is required. Get the key from: fig library components, or fig library variables');
+          process.exit(1);
+        }
+        spinner.text = `Importing component ${options.key}...`;
+        const importName = options.name || '';
+        const code = `(async function() {
+          try {
+            var component = await figma.importComponentByKeyAsync('${options.key}');
+            if (!component) return { error: 'Component not found for key: ${options.key}' };
+            // Create an instance
+            var instance = component.createInstance();
+            // Place it in the center of the viewport
+            var vp = figma.viewport.center;
+            instance.x = Math.round(vp.x);
+            instance.y = Math.round(vp.y);
+            ${importName ? `instance.name = '${importName}';` : ''}
+            figma.currentPage.selection = [instance];
+            return {
+              name: instance.name,
+              id: instance.id,
+              componentName: component.name,
+              w: Math.round(instance.width),
+              h: Math.round(instance.height)
+            };
+          } catch(e) {
+            return { error: e.message || 'Failed to import component. Check the key is valid.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Imported "${result.componentName}" as ${result.name} (${result.w}x${result.h})`);
+        console.log(`  ${chalk.gray('id:')} ${result.id}`);
+        console.log(chalk.gray('  Component is now selected on the canvas.'));
+      } else {
+        spinner.fail(`Unknown action: ${action}. Use: collections, variables, components, import`);
+        process.exit(1);
+      }
+    } catch (e) {
+      spinner.fail(`Library access failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();