figma-local 1.9.0 → 2.1.0

package/package.json

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

@@ -0,0 +1,110 @@
+---
+name: figma-component-audit
+description: |
+  Use this skill when the user wants to audit, review, or check the quality of Figma components. Triggers on: "audit", "audit components", "audit all components", "check component quality", "what's wrong with my components", "component issues", "find problems in components", "review my design system components", "component health", "component score", "check for hardcoded colors", "missing descriptions", "detached instances", "incomplete variants". Requires a Figma file to be open and the daemon connected.
+allowed-tools:
+  - Bash(fig component-audit *)
+  - Bash(fig component-audit)
+  - Bash(fig daemon status)
+---
+
+# Figma Component Audit
+
+Audit Figma components for design-system quality issues. Returns a score (0–100) and a categorized list of issues per component.
+
+## Prerequisites
+
+The `fig` CLI must be connected. Check with `fig daemon status`. If not connected: `fig connect --safe`.
+
+## Usage
+
+### Audit current selection
+
+Select a component or frame in Figma, then:
+
+```bash
+fig component-audit
+```
+
+### Audit a specific component by name
+
+```bash
+fig component-audit "Button"
+fig component-audit "Card"
+fig component-audit "Navigation Bar"
+```
+
+### Audit ALL components on the current page
+
+```bash
+fig component-audit --all
+```
+
+This is the most useful command for a full design-system review. It scans every `COMPONENT` and `COMPONENT_SET` on the page, ranks them by score (worst first), and prints a summary.
+
+### Audit by node ID
+
+```bash
+fig component-audit --node "123:456"
+```
+
+### JSON output (for piping or saving)
+
+```bash
+fig component-audit --all --json
+fig component-audit --all --json > audit-report.json
+```
+
+### Include info-level issues
+
+By default, only errors and warnings are shown. Add `--verbose` to also see info-level suggestions:
+
+```bash
+fig component-audit --all --verbose
+fig component-audit "Button" --verbose
+```
+
+## What Gets Checked
+
+| Rule | Severity | What it flags |
+|------|----------|---------------|
+| `missing-description` | warning | Component has no description set |
+| `incomplete-variants` | warning | Component set is missing expected variant combinations |
+| `hidden-layer` | info | A child layer is hidden (dead weight in the file) |
+| `generic-layer-name` | info | Layer has a default name like "Frame 2" or "Rectangle" |
+| `empty-text` | warning | A text node exists but has no content |
+| `hardcoded-color` | warning | A solid fill color with no variable binding |
+| `no-auto-layout` | info | A frame with 2+ children but no auto layout enabled |
+| `detached-instance` | error | An instance whose main component is missing |
+| `deep-nesting` | info | A node nested 7+ levels deep |
+
+## Scoring
+
+`score = 100 − (errors × 15) − (warnings × 5) − (info × 2)`
+
+- **≥ 80** — Good
+- **60–79** — Fair
+- **< 60** — Needs work
+
+## Workflow: Full Design-System Audit
+
+1. Open the Figma file containing your component library
+2. Make sure `fig` is connected: `fig daemon status`
+3. Run the full audit:
+   ```bash
+   fig component-audit --all
+   ```
+4. Review the output — components sorted worst-first
+5. For a detailed look at the worst component:
+   ```bash
+   fig component-audit "ComponentName" --verbose
+   ```
+6. Fix the issues in Figma, then re-run to verify improvement
+
+## Tips
+
+- Run `--all --json` to save a baseline report and compare over time
+- `detached-instance` errors (score −15 each) are the highest priority to fix
+- `hardcoded-color` warnings usually mean a token should be created in your variable collection
+- Use `fig var list` to see available variable collections before fixing hardcoded colors
+- `incomplete-variants` means your component set has a property with N options but fewer than the expected NxM combinations

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/component-audit.js

@@ -0,0 +1,312 @@
+/**
+ * component-audit.js — Figma component audit logic
+ *
+ * Generates Figma plugin JS code that inspects components for:
+ *   - Naming issues (unnamed layers, generic names)
+ *   - Missing descriptions
+ *   - Hardcoded colors (no variable bindings)
+ *   - Missing auto layout
+ *   - Hidden layers (dead weight)
+ *   - Empty text nodes
+ *   - Excessive nesting depth (>6 levels)
+ *   - Variant completeness for component sets
+ *   - Detached instances within a component
+ */
+
+/**
+ * Build the Figma JS code to audit a single component node by ID.
+ * @param {string} nodeId
+ */
+export function buildSingleAuditCode(nodeId) {
+  return `
+(function() {
+  var node = figma.getNodeById(${JSON.stringify(nodeId)});
+  if (!node) return { error: 'Node not found: ${nodeId}' };
+  if (node.type !== 'COMPONENT' && node.type !== 'COMPONENT_SET' && node.type !== 'FRAME') {
+    return { error: 'Node is not a COMPONENT, COMPONENT_SET, or FRAME. Got: ' + node.type };
+  }
+  return auditComponent(node);
+  ${AUDIT_HELPERS}
+})()
+`;
+}
+
+/**
+ * Build the Figma JS code to audit ALL components on the current page.
+ */
+export function buildAllAuditCode() {
+  return `
+(function() {
+  var page = figma.currentPage;
+  var results = [];
+
+  function collectComponents(node) {
+    if (node.type === 'COMPONENT_SET') {
+      results.push(auditComponent(node));
+      return; // children are COMPONENT variants — covered by set audit
+    }
+    if (node.type === 'COMPONENT') {
+      // Skip components that are children of a COMPONENT_SET (audited via the set)
+      if (!node.parent || node.parent.type !== 'COMPONENT_SET') {
+        results.push(auditComponent(node));
+      }
+      return;
+    }
+    if (node.children) {
+      for (var i = 0; i < node.children.length; i++) {
+        collectComponents(node.children[i]);
+      }
+    }
+  }
+
+  collectComponents(page);
+  return {
+    page: page.name,
+    total: results.length,
+    components: results
+  };
+  ${AUDIT_HELPERS}
+})()
+`;
+}
+
+/**
+ * Build the Figma JS code to audit the current selection.
+ */
+export function buildSelectionAuditCode() {
+  return `
+(function() {
+  var sel = figma.currentPage.selection;
+  if (!sel || sel.length === 0) return { error: 'Nothing selected. Select a component or frame in Figma first.' };
+  var node = sel[0];
+  if (node.type !== 'COMPONENT' && node.type !== 'COMPONENT_SET' && node.type !== 'FRAME') {
+    return { error: 'Selection is not a COMPONENT, COMPONENT_SET, or FRAME. Got: ' + node.type };
+  }
+  return auditComponent(node);
+  ${AUDIT_HELPERS}
+})()
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helper code injected into every eval string.
+// Written as a plain string so it can be appended inside the IIFE.
+// ---------------------------------------------------------------------------
+const AUDIT_HELPERS = `
+  function auditComponent(node) {
+    var issues = [];
+    var stats = { textNodes: 0, hiddenNodes: 0, instances: 0, detachedInstances: 0, maxDepth: 0 };
+
+    // ── 1. Description check ─────────────────────────────────────────────────
+    if (node.type === 'COMPONENT' || node.type === 'COMPONENT_SET') {
+      if (!node.description || node.description.trim() === '') {
+        issues.push({ rule: 'missing-description', severity: 'warning', message: 'Component has no description' });
+      }
+    }
+
+    // ── 2. Variant completeness (COMPONENT_SET only) ─────────────────────────
+    if (node.type === 'COMPONENT_SET') {
+      var propDefs = node.componentPropertyDefinitions || {};
+      var propKeys = Object.keys(propDefs);
+      var variantProps = propKeys.filter(function(k) { return propDefs[k].type === 'VARIANT'; });
+      if (variantProps.length > 0) {
+        var expected = 1;
+        variantProps.forEach(function(k) {
+          expected *= (propDefs[k].variantOptions || []).length;
+        });
+        var actual = (node.children || []).length;
+        if (actual < expected) {
+          issues.push({
+            rule: 'incomplete-variants',
+            severity: 'warning',
+            message: 'Variant set has ' + actual + ' of ' + expected + ' expected combinations',
+            details: { expected: expected, actual: actual, properties: variantProps }
+          });
+        }
+      }
+    }
+
+    // ── 3. Deep tree walk ────────────────────────────────────────────────────
+    var GENERIC_NAMES = /^(Frame|Rectangle|Ellipse|Group|Vector|Polygon|Star|Line|Image|Component)\\s*\\d*$/i;
+
+    function walk(n, depth) {
+      if (depth > stats.maxDepth) stats.maxDepth = depth;
+
+      // Hidden layers
+      if (depth > 0 && n.visible === false) {
+        stats.hiddenNodes++;
+        issues.push({ rule: 'hidden-layer', severity: 'info', message: 'Hidden layer: "' + n.name + '"', nodeId: n.id });
+      }
+
+      // Generic / unnamed layer
+      if (depth > 0 && GENERIC_NAMES.test(n.name)) {
+        issues.push({ rule: 'generic-layer-name', severity: 'info', message: 'Generic layer name: "' + n.name + '"', nodeId: n.id });
+      }
+
+      // Text nodes
+      if (n.type === 'TEXT') {
+        stats.textNodes++;
+        if (!n.characters || n.characters.trim() === '') {
+          issues.push({ rule: 'empty-text', severity: 'warning', message: 'Empty text node: "' + n.name + '"', nodeId: n.id });
+        }
+      }
+
+      // Hardcoded colors — fills with no variable binding
+      if (n.fills && Array.isArray(n.fills)) {
+        for (var i = 0; i < n.fills.length; i++) {
+          var fill = n.fills[i];
+          if (fill.type === 'SOLID' && fill.visible !== false) {
+            var hasBinding = n.boundVariables && n.boundVariables.fills;
+            if (!hasBinding) {
+              var r = Math.round((fill.color.r || 0) * 255);
+              var g = Math.round((fill.color.g || 0) * 255);
+              var b = Math.round((fill.color.b || 0) * 255);
+              var hex = '#' + r.toString(16).padStart(2,'0') + g.toString(16).padStart(2,'0') + b.toString(16).padStart(2,'0');
+              // Only flag non-transparent, non-white fills that look like intentional colors
+              if (hex !== '#ffffff' && hex !== '#000000' && !(r === g && g === b)) {
+                issues.push({ rule: 'hardcoded-color', severity: 'warning', message: 'Hardcoded fill color ' + hex + ' on "' + n.name + '" — consider using a variable', nodeId: n.id });
+              }
+            }
+          }
+        }
+      }
+
+      // Missing auto layout on FRAME nodes that contain multiple children
+      if (n.type === 'FRAME' && depth > 0) {
+        var childCount = (n.children || []).length;
+        if (childCount >= 2 && n.layoutMode === 'NONE') {
+          issues.push({ rule: 'no-auto-layout', severity: 'info', message: 'Frame "' + n.name + '" has ' + childCount + ' children but no auto layout', nodeId: n.id });
+        }
+      }
+
+      // Instances (check for detached)
+      if (n.type === 'INSTANCE') {
+        stats.instances++;
+        if (!n.mainComponent) {
+          stats.detachedInstances++;
+          issues.push({ rule: 'detached-instance', severity: 'error', message: 'Detached instance: "' + n.name + '" — main component missing', nodeId: n.id });
+        }
+      }
+
+      // Excessive nesting
+      if (depth === 7) {
+        issues.push({ rule: 'deep-nesting', severity: 'info', message: 'Node "' + n.name + '" is nested 7+ levels deep', nodeId: n.id });
+      }
+
+      if (n.children) {
+        for (var ci = 0; ci < n.children.length; ci++) {
+          walk(n.children[ci], depth + 1);
+        }
+      }
+    }
+
+    walk(node, 0);
+
+    // ── 4. Score ─────────────────────────────────────────────────────────────
+    var errors   = issues.filter(function(i) { return i.severity === 'error'; }).length;
+    var warnings = issues.filter(function(i) { return i.severity === 'warning'; }).length;
+    var infos    = issues.filter(function(i) { return i.severity === 'info'; }).length;
+    var score = Math.max(0, 100 - errors * 15 - warnings * 5 - infos * 2);
+
+    return {
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      score: score,
+      summary: { errors: errors, warnings: warnings, info: infos },
+      stats: stats,
+      issues: issues
+    };
+  }
+`;
+
+// ---------------------------------------------------------------------------
+// Formatter — turns raw audit result into human-readable CLI output
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a single component audit result for terminal output.
+ * @param {object} result - from auditComponent()
+ * @param {object} chalk  - chalk instance
+ * @param {boolean} verbose - show info-level issues
+ */
+export function formatAuditResult(result, chalk, verbose = true) {
+  if (result.error) return chalk.red('✗ ' + result.error);
+
+  const lines = [];
+  const scoreColor = result.score >= 80 ? chalk.green : result.score >= 60 ? chalk.yellow : chalk.red;
+  const scoreLabel = result.score >= 80 ? 'Good' : result.score >= 60 ? 'Fair' : 'Needs work';
+
+  lines.push(`\n${chalk.bold(result.name)} ${chalk.gray('(' + result.type + ')')}`);
+  lines.push(
+    `  Score: ${scoreColor(result.score + '/100')} ${chalk.gray('(' + scoreLabel + ')')}  ` +
+    chalk.red(result.summary.errors + ' errors') + '  ' +
+    chalk.yellow(result.summary.warnings + ' warnings') + '  ' +
+    chalk.gray(result.summary.info + ' info')
+  );
+  lines.push(
+    chalk.gray(
+      `  Stats: ${result.stats.textNodes} text nodes, ${result.stats.instances} instances` +
+      (result.stats.detachedInstances ? chalk.red(` (${result.stats.detachedInstances} detached)`) : '') +
+      `, ${result.stats.hiddenNodes} hidden, max depth ${result.stats.maxDepth}`
+    )
+  );
+
+  const shown = result.issues.filter(i => verbose || i.severity !== 'info');
+  if (shown.length === 0) {
+    lines.push(chalk.green('  ✓ No issues found'));
+  } else {
+    lines.push('');
+    for (const issue of shown) {
+      const icon = issue.severity === 'error' ? chalk.red('✗') :
+                   issue.severity === 'warning' ? chalk.yellow('⚠') : chalk.gray('ℹ');
+      const ruleTag = chalk.gray(`[${issue.rule}]`);
+      lines.push(`  ${icon} ${issue.message}  ${ruleTag}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the all-components audit result for terminal output.
+ * @param {object} result - { page, total, components[] }
+ * @param {object} chalk
+ * @param {boolean} verbose
+ */
+export function formatAllAuditResult(result, chalk, verbose = false) {
+  if (result.error) return chalk.red('✗ ' + result.error);
+
+  const lines = [];
+  const comps = result.components || [];
+  const totalErrors   = comps.reduce((s, c) => s + c.summary.errors, 0);
+  const totalWarnings = comps.reduce((s, c) => s + c.summary.warnings, 0);
+  const avgScore = comps.length ? Math.round(comps.reduce((s, c) => s + c.score, 0) / comps.length) : 0;
+
+  lines.push('');
+  lines.push(chalk.bold(`Component Audit — ${result.page}`));
+  lines.push(
+    `  ${comps.length} component${comps.length !== 1 ? 's' : ''} scanned  ` +
+    chalk.red(totalErrors + ' errors') + '  ' +
+    chalk.yellow(totalWarnings + ' warnings') + '  ' +
+    `Avg score: ${avgScore}/100`
+  );
+  lines.push('');
+
+  // Sort: worst score first
+  const sorted = [...comps].sort((a, b) => a.score - b.score);
+
+  for (const comp of sorted) {
+    lines.push(formatAuditResult(comp, chalk, verbose));
+  }
+
+  lines.push('');
+  lines.push(chalk.gray('─'.repeat(60)));
+  lines.push(
+    `${comps.filter(c => c.score >= 80).length} good  ` +
+    `${comps.filter(c => c.score >= 60 && c.score < 80).length} fair  ` +
+    `${comps.filter(c => c.score < 60).length} need work`
+  );
+
+  return lines.join('\n');
+}