figma-local 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-local",
-  "version": "2.0.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/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');
+}

package/src/index.js

@@ -20,6 +20,10 @@ import {
   STAGE1_METADATA, buildFrameStructureCode, buildUsedTokensCode, formatLeanContext
 } from './read.js';
 import { generatePrompt } from './prompt-templates.js';
+import {
+  buildSingleAuditCode, buildAllAuditCode, buildSelectionAuditCode,
+  formatAuditResult, formatAllAuditResult
+} from './component-audit.js';
 import {
   nullDevice, killPort, getPortPid, sleepAfterStop,
   startFigmaApp, killFigmaApp,
@@ -11199,4 +11203,121 @@ Examples:
     }
   });
 
+// ─── Component Audit ────────────────────────────────────────────────────────
+
+program
+  .command('component-audit [name]')
+  .description('Audit components for quality issues (naming, tokens, layout, variants, detached instances)')
+  .option('--all', 'Audit ALL components on the current page')
+  .option('--node <nodeId>', 'Audit a specific component by node ID')
+  .option('--json', 'Output raw JSON')
+  .option('--verbose', 'Show info-level issues in addition to errors/warnings')
+  .addHelpText('after', `
+Checks run on every component:
+  missing-description    No description set on the component
+  incomplete-variants    Component set is missing expected variant combinations
+  hidden-layer           Child layer is hidden (dead weight)
+  generic-layer-name     Layer has a default name like "Frame 2" or "Rectangle"
+  empty-text             Text node with no content
+  hardcoded-color        Solid fill with no variable binding
+  no-auto-layout         Frame with 2+ children but no auto layout
+  detached-instance      Instance whose main component is missing
+  deep-nesting           Node nested 7+ levels deep
+
+Severity:
+  error    Must fix — structural or correctness problem
+  warning  Should fix — design system or quality concern
+  info     Nice to fix — best practice recommendation (shown with --verbose)
+
+Examples:
+  fig component-audit                     Audit current selection
+  fig component-audit "Button"            Audit the component named "Button"
+  fig component-audit --all               Audit every component on this page
+  fig component-audit --node "123:456"    Audit by node ID
+  fig component-audit --all --json        Machine-readable output
+  fig component-audit --all --verbose     Include info-level issues
+`)
+  .action(async (name, options) => {
+    await checkConnection();
+    const spinner = ora('Running component audit...').start();
+
+    try {
+      // ── Determine which audit code to run ──────────────────────────────────
+      let code;
+      let isAll = false;
+
+      if (options.all) {
+        isAll = true;
+        code = buildAllAuditCode();
+        spinner.text = 'Auditing all components on page...';
+      } else if (options.node) {
+        code = buildSingleAuditCode(options.node);
+        spinner.text = `Auditing node ${options.node}...`;
+      } else if (name) {
+        // Find component by name via metadata, then audit it
+        spinner.text = `Looking up component "${name}"...`;
+        const findCode = `
+          (function() {
+            function findByName(node, n) {
+              if ((node.type === 'COMPONENT' || node.type === 'COMPONENT_SET' || node.type === 'FRAME') &&
+                  node.name.toLowerCase() === n.toLowerCase()) return node.id;
+              if (node.children) {
+                for (var i = 0; i < node.children.length; i++) {
+                  var found = findByName(node.children[i], n);
+                  if (found) return found;
+                }
+              }
+              return null;
+            }
+            return findByName(figma.currentPage, ${JSON.stringify(name)});
+          })()
+        `;
+        const nodeId = await daemonExec('eval', { code: findCode });
+        if (!nodeId) {
+          spinner.fail(`No component named "${name}" found on the current page.`);
+          process.exit(1);
+        }
+        code = buildSingleAuditCode(nodeId);
+        spinner.text = `Auditing "${name}"...`;
+      } else {
+        // Default: audit current selection
+        code = buildSelectionAuditCode();
+        spinner.text = 'Auditing selection...';
+      }
+
+      const result = await daemonExec('eval', { code });
+
+      if (result && result.error) {
+        spinner.fail(result.error);
+        process.exit(1);
+      }
+
+      // ── Output ─────────────────────────────────────────────────────────────
+      if (isAll) {
+        const comps = result.components || [];
+        spinner.succeed(
+          `Audited ${comps.length} component${comps.length !== 1 ? 's' : ''} on page "${result.page}"`
+        );
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatAllAuditResult(result, chalk, options.verbose || false));
+        }
+      } else {
+        const score = result.score;
+        const label = score >= 80 ? 'Good' : score >= 60 ? 'Fair' : 'Needs work';
+        spinner.succeed(`Audited "${result.name}" — score ${score}/100 (${label})`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatAuditResult(result, chalk, options.verbose !== false));
+        }
+      }
+    } catch (e) {
+      spinner.fail(`Audit failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();
+