figma-local 1.0.0 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# figma-cli
+# figma-local
 
 > Control Figma Desktop with Claude Code. Design tokens, shadcn/ui components, AI prompt export, lint, and more — no API key required.
 
@@ -12,7 +12,7 @@
 
 ## What is this?
 
-**figma-cli** connects directly to Figma Desktop and lets you — or Claude Code — control it with natural language and `fig` commands.
+**figma-local** connects directly to Figma Desktop and lets you — or Claude Code — control it with natural language and `fig` commands.
 
 - **Write** — Create frames, components, design tokens, icons, and full UI kits
 - **Read** — Extract design context in a lean staged format (91–97% fewer tokens than raw data dumps)
@@ -51,16 +51,22 @@ npm install -g figma-local
 
 Gives you `fig` and `fig-start` globally on your PATH.
 
+**Update to latest:**
+
+```bash
+npm update -g figma-local
+```
+
 ### curl (one-line)
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/thepreakerebi/figma-cli/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/thepreakerebi/figma-local/main/install.sh | bash
 ```
 
 ### Homebrew
 
 ```bash
-brew tap thepreakerebi/figma-cli
+brew tap thepreakerebi/figma-local
 brew install figma-cli
 ```
 
@@ -73,8 +79,8 @@ npx figma-local read
 ### From source
 
 ```bash
-git clone https://github.com/thepreakerebi/figma-cli.git
-cd figma-cli
+git clone https://github.com/thepreakerebi/figma-local.git
+cd figma-local
 npm install && npm install -g .
 ```
 
@@ -99,7 +105,7 @@ npm install && npm install -g .
 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 **FigCli** in the plugin list → **Add to toolbar**
+5. Right-click **Figma Local** in the plugin list → **Add to toolbar**
 
 ### 2. Connect
 
@@ -107,14 +113,14 @@ npm install && npm install -g .
 fig-start --safe
 ```
 
-This starts the daemon, waits for you to click FigCli in Figma, then launches Claude Code.
+This starts the daemon, waits for you to click Figma Local in Figma, then launches Claude Code.
 
 ---
 
 ## Every session after that
 
 ```
-1. Open Figma → click FigCli in the toolbar
+1. Open Figma → click Figma Local in the toolbar
 2. In terminal: fig-start --safe
 ```
 
@@ -127,14 +133,60 @@ Claude Code reads `CLAUDE.md` and knows every command automatically.
 ### Read & understand your canvas
 
 ```bash
-fig read                           # List all frames (fast)
-fig read "Login Screen"            # Layout + components + used tokens only
-fig read "Login Screen" --tokens   # Just the design tokens that frame uses
+fig read                           # List all frames on the current page
+fig read "Login Screen"            # Get the layout tree, components, and design tokens for that frame
+fig read "Login Screen" --tokens   # Show only the design tokens (colors, spacing) that frame uses
+fig read --selection               # Read whatever you have selected right now in Figma
+fig read --link "https://..."      # Read a specific node from a Figma selection link
 fig find "Button"                  # Find nodes by name
 fig node tree                      # Layer hierarchy
 fig canvas info                    # Raw canvas info
 ```
 
+### Inspect design specs
+
+```bash
+fig inspect                        # Full specs for the selected element (spacing, colors, fonts, effects)
+fig inspect --node "123:456"       # Inspect a specific node by ID
+fig inspect --json                 # Raw JSON output
+```
+
+Returns dimensions, padding, gap, colors (hex + rgba), typography (font family, size, weight, line-height, letter-spacing), border radius, strokes, shadows, opacity, and variable bindings (name + resolved value + per-mode values for Light/Dark) — all in **px and rem**.
+
+### Generate CSS / Tailwind from design
+
+```bash
+fig css                            # CSS for current selection (rem units)
+fig css --px                       # CSS in px units
+fig css --tailwind                 # Tailwind utility classes
+fig css --link "https://..."       # CSS from a Figma link
+```
+
+### Measure spacing
+
+```bash
+fig measure                        # Select 2 elements in Figma, get the spacing between them
+```
+
+### Extract style guide from a frame
+
+```bash
+fig styles "Login Screen"          # All text styles, colors, spacing values, and radii used
+fig styles --selection             # Styles from current selection
+fig styles --json                  # Raw JSON
+```
+
+### Document a component (full recursive spec)
+
+```bash
+fig document                       # Document selected component — all children, all specs
+fig document --json                # Structured JSON for coding agents
+fig document --link "https://..."  # Document from a Figma link
+fig document --tokens-only         # Just the design tokens used
+```
+
+Returns a complete breakdown: summary, all unique design tokens (colors, typography, spacing, radii, shadows), and a recursive tree of every element with full specs. One command gives a coding agent everything it needs to replicate the component.
+
 ### Design tokens
 
 ```bash
@@ -247,7 +299,7 @@ fig fj connect "ID1" "ID2"
 | | Safe Mode | Yolo Mode |
 |-|-----------|-----------|
 | How | Plugin bridge | Direct CDP |
-| Setup per session | Start FigCli plugin | Nothing (after one-time patch) |
+| Setup per session | Start Figma Local plugin | Nothing (after one-time patch) |
 | Speed | Standard | ~10× faster |
 | Extra permissions | None | macOS: Full Disk Access / Windows: Admin |
 | Command | `fig connect --safe` | `fig connect` |
@@ -271,7 +323,7 @@ The daemon runs only on `127.0.0.1` (never exposed to the network) and is protec
 | 1 MB request/message body cap | Memory exhaustion from oversized payloads |
 | Plugin input validation | Code size cap (512 KB), batch size cap (50), strict field types |
 | Rate limiting | Max 30 evals per 10 s per connection |
-| Idle auto-shutdown | Daemon stops after 10 minutes of inactivity |
+| Idle auto-shutdown | Daemon stops after 1 hour of inactivity |
 
 The session token is generated fresh on every `fig connect`, stored at `~/.figma-ds-cli/.daemon-token` with `chmod 600` (owner-read only).
 
@@ -286,6 +338,31 @@ 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:
+
+| Skill | Triggers on |
+|-------|------------|
+| **figma-local** | "read the design", "what's on the canvas", "Figma to code" |
+| **figma-inspect** | "get specs", "what font/color/spacing", "design specs" |
+| **figma-css** | "generate CSS", "Tailwind classes", "convert to CSS" |
+| **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" |
+
+### Install the skills
+
+Install via [skills.sh](https://skills.sh):
+
+```bash
+npx skills add thepreakerebi/figma-local
+```
+
+Once installed, restart Claude Code. It automatically knows all `fig` commands and uses them when your tasks involve Figma designs.
+
+---
+
 ## For teams
 
 ```bash
@@ -299,7 +376,7 @@ npm install -g figma-local
 Pin a version for consistency:
 
 ```bash
-npm install -g @jetro/figma-local@1.0.0
+npm install -g figma-local@1.0.0
 ```
 
 ---
@@ -311,7 +388,7 @@ npm uninstall -g figma-local
 rm -rf ~/.figma-cli ~/.figma-ds-cli
 ```
 
-Remove the plugin in Figma: Plugins → Development → right-click FigCli → Remove.
+Remove the plugin in Figma: Plugins → Development → right-click Figma Local → Remove.
 
 ---
 
@@ -320,8 +397,8 @@ Remove the plugin in Figma: Plugins → Development → right-click FigCli → R
 Issues and PRs welcome. For major changes, open an issue first to discuss.
 
 ```bash
-git clone https://github.com/thepreakerebi/figma-cli.git
-cd figma-cli
+git clone https://github.com/thepreakerebi/figma-local.git
+cd figma-local
 npm install
 node src/index.js --help
 npm test

package/bin/fig-start

@@ -123,11 +123,14 @@ for arg in "$@"; do
 done
 
 if [ "$1" = "--setup" ]; then
-    printf "${BOLD}Enter the path to your figma-cli repo:${NC} "
+    printf "${BOLD}Enter the absolute path to your figma-local folder:${NC} "
     read -r repo_path < /dev/tty
     repo_path="${repo_path/#\~/$HOME}"
-    if [ ! -f "$repo_path/src/index.js" ]; then
-        echo -e "${RED}Not a valid figma-cli repo:${NC} $repo_path"
+    if [[ "$repo_path" != /* ]]; then
+        repo_path="$(cd "$repo_path" 2>/dev/null && pwd)"
+    fi
+    if [ -z "$repo_path" ] || [ ! -f "$repo_path/src/index.js" ]; then
+        echo -e "${RED}Not a valid figma-local folder.${NC} Expected src/index.js inside it."
         exit 1
     fi
     save_repo_path "$repo_path"
@@ -139,21 +142,34 @@ fi
 REPO_PATH=$(get_repo_path)
 
 if [ -z "$REPO_PATH" ] || [ ! -d "$REPO_PATH" ]; then
-    # Try to find it relative to this script
+    # Try to find it relative to this script (works for both git clone and npm -g installs)
     SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
     if [ -f "$SCRIPT_DIR/src/index.js" ]; then
         REPO_PATH="$SCRIPT_DIR"
         save_repo_path "$REPO_PATH"
     else
-        echo -e "${YELLOW}figma-cli repo not configured.${NC}"
-        printf "${BOLD}Enter the path to your figma-cli repo:${NC} "
-        read -r REPO_PATH < /dev/tty
-        REPO_PATH="${REPO_PATH/#\~/$HOME}"
-        if [ ! -f "$REPO_PATH/src/index.js" ]; then
-            echo -e "${RED}Not a valid figma-cli repo:${NC} $REPO_PATH"
-            exit 1
+        # Try npm global install location
+        NPM_GLOBAL="$(npm root -g 2>/dev/null)/figma-local"
+        if [ -f "$NPM_GLOBAL/src/index.js" ]; then
+            REPO_PATH="$NPM_GLOBAL"
+            save_repo_path "$REPO_PATH"
+        else
+            echo -e "${YELLOW}figma-local repo not configured.${NC}"
+            echo -e "${DIM}If you installed via npm, run: fig-start --setup${NC}"
+            printf "${BOLD}Enter the absolute path to your figma-local folder:${NC} "
+            read -r REPO_PATH < /dev/tty
+            REPO_PATH="${REPO_PATH/#\~/$HOME}"
+            # Convert relative paths to absolute
+            if [[ "$REPO_PATH" != /* ]]; then
+                REPO_PATH="$(cd "$REPO_PATH" 2>/dev/null && pwd)"
+            fi
+            if [ -z "$REPO_PATH" ] || [ ! -f "$REPO_PATH/src/index.js" ]; then
+                echo -e "${RED}Not a valid figma-local folder.${NC} Expected src/index.js inside it."
+                echo -e "${DIM}Tip: use the full path, e.g. /Users/yourname/figma-local${NC}"
+                exit 1
+            fi
+            save_repo_path "$REPO_PATH"
         fi
-        save_repo_path "$REPO_PATH"
     fi
 fi
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "figma-local",
-  "version": "1.0.0",
-  "description": "Figma CLI — control Figma Desktop with Claude Code. Smart read, write, and AI-prompt export. No API key required.",
+  "version": "1.2.0",
+  "description": "Control Figma Desktop with Claude Code. Smart read, write, and AI-prompt export. No API key required.",
   "author": "elvke",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,9 @@
   },
   "files": [
     "src",
-    "bin"
+    "bin",
+    "plugin",
+    "skills"
   ],
   "keywords": [
     "figma",
@@ -25,11 +27,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/thepreakerebi/figma-cli.git"
+    "url": "git+https://github.com/thepreakerebi/figma-local.git"
   },
-  "homepage": "https://github.com/thepreakerebi/figma-cli",
+  "homepage": "https://github.com/thepreakerebi/figma-local",
   "bugs": {
-    "url": "https://github.com/thepreakerebi/figma-cli/issues"
+    "url": "https://github.com/thepreakerebi/figma-local/issues"
   },
   "scripts": {
     "setup-alias": "bash bin/setup-alias.sh",

package/plugin/code.js

@@ -0,0 +1,178 @@
+/**
+ * Figma CLI Bridge Plugin — code.js
+ *
+ * Safe Mode: Connects to CLI daemon via WebSocket.
+ * No debug port, no patching required.
+ *
+ * Security hardening:
+ *  - All incoming messages from the UI are validated before execution
+ *  - Code and batch payloads are size-capped
+ *  - Batch arrays are length-capped
+ *  - Notify text is sanitised (no arbitrary HTML/script injection)
+ *  - Rate limiting: max 30 evals per 10-second window
+ */
+
+// ── Constants ──────────────────────────────────────────────────
+const MAX_CODE_BYTES   = 512 * 1024;  // 512 KB max per eval code string
+const MAX_BATCH_COUNT  = 50;          // Max codes in a single eval-batch
+const MAX_NOTIFY_CHARS = 200;         // Max chars shown in Figma notification
+
+// ── Rate limiter ───────────────────────────────────────────────
+// Prevents a rogue daemon (or compromised WebSocket) from flooding
+// the plugin with eval calls.
+const RATE_WINDOW_MS = 10000;
+const RATE_MAX       = 30;
+let rateCount        = 0;
+let rateWindowStart  = Date.now();
+
+function isRateAllowed() {
+  const now = Date.now();
+  if (now - rateWindowStart > RATE_WINDOW_MS) {
+    rateCount = 0;
+    rateWindowStart = now;
+  }
+  if (rateCount >= RATE_MAX) return false;
+  rateCount++;
+  return true;
+}
+
+// ── Input validators ───────────────────────────────────────────
+function isValidId(id) {
+  return typeof id === 'number' && Number.isFinite(id) && id >= 0;
+}
+
+function isValidCode(code) {
+  return typeof code === 'string' && code.length > 0 && code.length <= MAX_CODE_BYTES;
+}
+
+function sanitiseNotify(text) {
+  if (typeof text !== 'string') return 'Unknown error';
+  // Strip anything that looks like HTML tags, keep plain text only
+  return text.replace(/<[^>]*>/g, '').slice(0, MAX_NOTIFY_CHARS);
+}
+
+// Show minimal UI (needed for WebSocket connection)
+figma.showUI(__html__, {
+  width: 200,
+  height: 92
+});
+
+// Execute code with auto-return and timeout protection
+async function executeCode(code, timeoutMs = 25000) {
+  let trimmed = code.trim();
+
+  // Don't add return if code already starts with return
+  if (!trimmed.startsWith('return ')) {
+    const isSimpleExpr = !trimmed.includes(';');
+    const isIIFE = trimmed.startsWith('(function') || trimmed.startsWith('(async function');
+    const isArrowIIFE = trimmed.startsWith('(() =>') || trimmed.startsWith('(async () =>');
+
+    if (isSimpleExpr || isIIFE || isArrowIIFE) {
+      trimmed = `return ${trimmed}`;
+    } else {
+      const lastSemicolon = trimmed.lastIndexOf(';');
+      if (lastSemicolon !== -1) {
+        const beforeLast = trimmed.substring(0, lastSemicolon + 1);
+        const lastStmt = trimmed.substring(lastSemicolon + 1).trim();
+        if (lastStmt && !lastStmt.startsWith('return ')) {
+          trimmed = beforeLast + ' return ' + lastStmt;
+        }
+      }
+    }
+  }
+
+  const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+  const fn = new AsyncFunction('figma', `return (async () => { ${trimmed} })()`);
+
+  // Execute with timeout protection
+  const execPromise = fn(figma);
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error(`Execution timeout (${timeoutMs/1000}s)`)), timeoutMs)
+  );
+
+  return Promise.race([execPromise, timeoutPromise]);
+}
+
+// Handle messages from UI (WebSocket bridge)
+figma.ui.onmessage = async (msg) => {
+  if (!msg || typeof msg.type !== 'string') return;
+
+  // ── Single eval ─────────────────────────────────────────────
+  if (msg.type === 'eval') {
+    // Validate id and code before doing anything
+    if (!isValidId(msg.id)) return;
+    if (!isValidCode(msg.code)) {
+      figma.ui.postMessage({ type: 'result', id: msg.id, error: 'Invalid or oversized code payload' });
+      return;
+    }
+    if (!isRateAllowed()) {
+      figma.ui.postMessage({ type: 'result', id: msg.id, error: 'Rate limit exceeded — slow down' });
+      return;
+    }
+    try {
+      const result = await executeCode(msg.code);
+      figma.ui.postMessage({ type: 'result', id: msg.id, result });
+    } catch (error) {
+      figma.ui.postMessage({ type: 'result', id: msg.id, error: error.message });
+    }
+    return;
+  }
+
+  // ── Batch eval ──────────────────────────────────────────────
+  if (msg.type === 'eval-batch') {
+    if (!isValidId(msg.id)) return;
+    if (!Array.isArray(msg.codes)) {
+      figma.ui.postMessage({ type: 'batch-result', id: msg.id, results: [{ success: false, error: 'codes must be an array' }] });
+      return;
+    }
+    // Cap array length
+    if (msg.codes.length > MAX_BATCH_COUNT) {
+      figma.ui.postMessage({ type: 'batch-result', id: msg.id, results: [{ success: false, error: `Batch too large (max ${MAX_BATCH_COUNT})` }] });
+      return;
+    }
+    // Validate each code string
+    for (const c of msg.codes) {
+      if (!isValidCode(c)) {
+        figma.ui.postMessage({ type: 'batch-result', id: msg.id, results: [{ success: false, error: 'Invalid or oversized code in batch' }] });
+        return;
+      }
+    }
+    if (!isRateAllowed()) {
+      figma.ui.postMessage({ type: 'batch-result', id: msg.id, results: [{ success: false, error: 'Rate limit exceeded' }] });
+      return;
+    }
+    const results = [];
+    for (const code of msg.codes) {
+      try {
+        const result = await executeCode(code);
+        results.push({ success: true, result });
+      } catch (error) {
+        results.push({ success: false, error: error.message });
+      }
+    }
+    figma.ui.postMessage({ type: 'batch-result', id: msg.id, results });
+    return;
+  }
+
+  // ── Connection lifecycle (no eval, safe to handle directly) ──
+  if (msg.type === 'connected') {
+    figma.notify('✓ Figma Local connected', { timeout: 2000 });
+    return;
+  }
+  if (msg.type === 'disconnected') {
+    figma.notify('Figma Local disconnected', { timeout: 2000 });
+    return;
+  }
+  if (msg.type === 'error') {
+    // Sanitise before displaying in Figma UI
+    figma.notify('Figma Local: ' + sanitiseNotify(msg.message), { error: true });
+    return;
+  }
+};
+
+// Keep plugin alive
+figma.on('close', () => {
+  // Plugin closed
+});
+
+console.log('Figma DS CLI plugin started');

package/plugin/manifest.json

@@ -0,0 +1,14 @@
+{
+  "name": "Figma Local",
+  "id": "figma-cli-bridge",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "capabilities": [],
+  "enableProposedApi": false,
+  "editorType": ["figma", "figjam"],
+  "networkAccess": {
+    "allowedDomains": ["*"],
+    "reasoning": "Connects to local CLI daemon for command execution"
+  }
+}