figma-local 1.0.0

package/README.md

@@ -0,0 +1,342 @@
+# figma-cli
+
+> Control Figma Desktop with Claude Code. Design tokens, shadcn/ui components, AI prompt export, lint, and more — no API key required.
+
+[![npm version](https://img.shields.io/npm/v/figma-local.svg)](https://www.npmjs.com/package/figma-local)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen)](https://nodejs.org)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Windows-blue)](#)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-Ready-blue)](https://claude.ai/claude-code)
+
+---
+
+## What is this?
+
+**figma-cli** 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)
+- **Export** — Generate AI-ready prompts for Figma Make, Lovable, Pencil.dev, Paper.design, Google Stitch
+- **Analyse** — Lint designs, check accessibility, audit colors and typography
+- **Zero API key** — Connects via a local plugin bridge, no Figma API credentials needed
+
+---
+
+## Credits
+
+This project is built on the shoulders of two excellent open-source works:
+
+| Project | Author | What we built on |
+|---------|--------|------------------|
+| [**silships/figma-cli**](https://github.com/silships/figma-cli) | Sil Bormüller · [Into Design Systems](https://intodesignsystems.com) | Core daemon, plugin bridge, CDP connection, shadcn/ui component library, render engine, design token presets, FigJam support |
+| [**royvillasana/figma-to-ai-prompter**](https://github.com/royvillasana/figma-to-ai-prompter) | Roy Villasana | Staged lean extraction approach, per-tool prompt templates, token-efficiency methodology |
+
+**Our additions on top:**
+- `fig read` — 3-phase staged design extraction (metadata → frame structure → used tokens only)
+- `fig prompt` — lean tool-specific prompt generation (figma-make, lovable, pencil, paper, stitch)
+- `fig verify --compare` — prototype vs design comparison loop with correction prompts
+- Security hardening — WebSocket nonce handshake, input validation, rate limiting, body size caps
+- `fig` short command — works globally from any directory
+- Plugin UX — shows actionable "how to connect" instructions instead of infinite "Scanning..."
+
+---
+
+## Install
+
+### npm (recommended)
+
+```bash
+npm install -g figma-local
+```
+
+Gives you `fig` and `fig-start` globally on your PATH.
+
+### curl (one-line)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/thepreakerebi/figma-cli/main/install.sh | bash
+```
+
+### Homebrew
+
+```bash
+brew tap thepreakerebi/figma-cli
+brew install figma-cli
+```
+
+### npx (no install)
+
+```bash
+npx figma-local read
+```
+
+### From source
+
+```bash
+git clone https://github.com/thepreakerebi/figma-cli.git
+cd figma-cli
+npm install && npm install -g .
+```
+
+---
+
+## Requirements
+
+| | |
+|-|-|
+| Node.js | 18+ |
+| Figma Desktop | Any version (free account works) |
+| OS | macOS or Windows |
+| Claude Code | Optional but recommended |
+
+---
+
+## Setup (one time only)
+
+### 1. Import the Figma plugin
+
+1. Open **Figma Desktop**
+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**
+
+### 2. Connect
+
+```bash
+fig-start --safe
+```
+
+This starts the daemon, waits for you to click FigCli in Figma, then launches Claude Code.
+
+---
+
+## Every session after that
+
+```
+1. Open Figma → click FigCli in the toolbar
+2. In terminal: fig-start --safe
+```
+
+Claude Code reads `CLAUDE.md` and knows every command automatically.
+
+---
+
+## Commands
+
+### 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 find "Button"                  # Find nodes by name
+fig node tree                      # Layer hierarchy
+fig canvas info                    # Raw canvas info
+```
+
+### Design tokens
+
+```bash
+fig tokens preset shadcn           # 276 variables: primitives + semantic (Light/Dark)
+fig tokens tailwind                # Tailwind 242-color palette
+fig var list                       # All variables
+fig var visualize                  # Swatches on canvas
+fig var export css                 # → CSS custom properties
+fig var export tailwind            # → Tailwind config
+fig bind fill "primary/500"        # Bind variable to selection
+```
+
+### shadcn/ui components
+
+```bash
+fig shadcn list                    # 30 available components
+fig shadcn add button card input   # Add specific ones
+fig shadcn add --all               # All 30 components, 58 variants
+```
+
+Includes Button, Card, Input, Dialog, Tabs, Select, Switch, Badge, Alert, Checkbox, Radio Group, Accordion, Table, Pagination, Breadcrumb, Sheet, Tooltip, Dropdown, Avatar, Spinner, and more. All wired to Light/Dark variables.
+
+### Create anything
+
+```bash
+# Quick primitives
+fig create rect "Card" -w 320 -h 200 --fill "var:card" --radius 12
+fig create text "Hello" -s 24 -c "var:foreground" -w bold
+fig create icon lucide:home -s 24
+
+# JSX render
+fig render '<Frame name="Card" w={320} bg="var:card" rounded={16} flex="col" gap={8} p={24}>
+  <Text size={20} weight="bold" color="var:foreground">Title</Text>
+  <Text size={14} color="var:muted-foreground">Description</Text>
+</Frame>'
+
+# Pre-built blocks
+fig blocks create dashboard-01     # Full analytics dashboard
+```
+
+### Icons (150,000+)
+
+```bash
+fig create icon lucide:home -s 24
+fig create icon material:search -s 24
+fig create icon heroicons:bell -s 20 -c "var:primary"
+```
+
+Lucide, Material Design, Heroicons, Feather, and 50+ more via Iconify.
+
+### Export AI prompts
+
+```bash
+fig prompt "Screen" --target figma-make
+fig prompt "Screen" --target lovable --stack "React + shadcn/ui"
+fig prompt "Screen" --target pencil
+fig prompt "Screen" --target stitch --platform responsive
+
+# With context for better output
+fig prompt "Login" \
+  --target lovable \
+  --goal "user signs in with email and password" \
+  --interactions "submit validates form, forgot password opens modal" \
+  --guardrails "no social login"
+```
+
+Generates ~45 tokens of structured text instead of attaching a Figma frame (300–500+ hidden tokens). **91–97% smaller input, more consistent AI output.**
+
+### Verify & compare
+
+```bash
+fig verify                         # Screenshot of selection for AI review
+fig verify --compare "https://..."  # Diff prototype vs Figma design → correction prompts
+```
+
+### Export
+
+```bash
+fig export css                     # Variables → CSS
+fig export tailwind                # Variables → Tailwind config
+fig export screenshot -o out.png   # Screenshot (add -s 2 for 2x)
+fig export-jsx "1:234"             # → React JSX
+fig export-storybook "1:234"       # → Storybook stories
+```
+
+### Lint & accessibility
+
+```bash
+fig lint                           # All rules
+fig lint --fix                     # Auto-fix
+fig lint --preset accessibility    # WCAG rules only
+fig analyze colors                 # Color usage audit
+fig analyze typography
+```
+
+Rules: WCAG AA/AAA contrast ratio, touch targets (44×44px min), hardcoded colors, empty frames, deeply nested layers, missing auto-layout, minimum text size.
+
+### FigJam
+
+```bash
+fig fj sticky "Idea" -x 100 -y 100 --color "#FEF08A"
+fig fj shape "Label" -x 200 -y 100 -w 200 -h 100
+fig fj connect "ID1" "ID2"
+```
+
+---
+
+## Connection modes
+
+| | Safe Mode | Yolo Mode |
+|-|-----------|-----------|
+| How | Plugin bridge | Direct CDP |
+| Setup per session | Start FigCli 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` |
+
+**Recommendation:** Safe Mode. No system permissions needed, works on all machines including managed corporate Macs.
+
+---
+
+## Security
+
+The daemon runs only on `127.0.0.1` (never exposed to the network) and is protected by multiple layers:
+
+| Layer | Protects against |
+|-------|-----------------|
+| Binds to `127.0.0.1` | Not reachable from outside your machine |
+| Session token (`X-Daemon-Token`) | Unauthorized local processes calling the HTTP API |
+| Host header validation | DNS rebinding attacks |
+| No CORS headers | Cross-origin browser requests |
+| WebSocket nonce handshake | Rogue local processes impersonating the plugin |
+| WebSocket origin validation | Browser tabs connecting to the daemon |
+| 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 |
+
+The session token is generated fresh on every `fig connect`, stored at `~/.figma-ds-cli/.daemon-token` with `chmod 600` (owner-read only).
+
+---
+
+## Work from anywhere
+
+```bash
+fig read                    # works from any directory
+fig-start --safe --here     # launch from your project dir; Claude sees both your project and Figma
+```
+
+---
+
+## For teams
+
+```bash
+# Install once per machine
+npm install -g figma-local
+
+# Import the Figma plugin once per Figma account (5 minutes)
+# Then every designer on the team has identical fig commands
+```
+
+Pin a version for consistency:
+
+```bash
+npm install -g @jetro/figma-local@1.0.0
+```
+
+---
+
+## Uninstall
+
+```bash
+npm uninstall -g figma-local
+rm -rf ~/.figma-cli ~/.figma-ds-cli
+```
+
+Remove the plugin in Figma: Plugins → Development → right-click FigCli → Remove.
+
+---
+
+## Contributing
+
+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
+npm install
+node src/index.js --help
+npm test
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Acknowledgements
+
+- **[silships/figma-cli](https://github.com/silships/figma-cli)** by Sil Bormüller ([Into Design Systems](https://intodesignsystems.com)) — the original Figma Desktop CLI. The core engine, plugin bridge, CDP connection, shadcn/ui components, render pipeline, and design token presets all originate here. Please star their repo.
+
+- **[royvillasana/figma-to-ai-prompter](https://github.com/royvillasana/figma-to-ai-prompter)** by Roy Villasana — the staged extraction and lean prompt approach. The insight that a text context block saves 91–97% of tokens vs attaching a Figma frame comes from their work. Please star their repo too.

package/bin/fig-start

@@ -0,0 +1,289 @@
+#!/bin/bash
+
+# fig-start — Launch Figma CLI + Claude Code
+# Connects to Figma, lets you pick an open file, then launches Claude Code.
+#
+# Usage:
+#   fig-start          → Yolo Mode (default) with file selector
+#   fig-start --safe   → Safe Mode (plugin-based, no patching)
+#   fig-start --here   → Stay in current directory (don't cd to repo)
+#   fig-start --setup  → set/change the figma-cli repo path
+
+CONFIG_DIR="$HOME/.figma-cli"
+CONFIG_FILE="$CONFIG_DIR/config.json"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m'
+
+# ── Config helpers ──
+
+get_daemon_token() {
+    local token_file="$HOME/.figma-ds-cli/.daemon-token"
+    if [ -f "$token_file" ]; then
+        cat "$token_file" 2>/dev/null
+    fi
+}
+
+get_repo_path() {
+    if [ -f "$CONFIG_FILE" ]; then
+        python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('repoPath',''))" 2>/dev/null
+    fi
+}
+
+save_repo_path() {
+    mkdir -p "$CONFIG_DIR"
+    python3 -c "
+import json, os
+path = '$CONFIG_FILE'
+cfg = {}
+if os.path.exists(path):
+    with open(path) as f: cfg = json.load(f)
+cfg['repoPath'] = '$1'
+with open(path, 'w') as f: json.dump(cfg, f, indent=2)
+"
+}
+
+# ── Arrow-key selector (same UX as fancoolo-start) ──
+
+select_file() {
+    local options=("$@")
+    local count=${#options[@]}
+    local selected=0
+
+    tput civis > /dev/tty 2>/dev/null
+    trap 'tput cnorm > /dev/tty 2>/dev/null' EXIT
+
+    draw_menu() {
+        if [ "$1" = "redraw" ]; then
+            printf "\033[%dA" "$((count + 2))" > /dev/tty
+        fi
+
+        printf "${BOLD}Select a Figma file (↑↓ arrows, Enter to confirm):${NC}\n" > /dev/tty
+        printf "\n" > /dev/tty
+        for i in "${!options[@]}"; do
+            if [ "$i" -eq "$selected" ]; then
+                printf "  ${GREEN}▸ %s${NC}\n" "${options[$i]}" > /dev/tty
+            else
+                printf "    %s\n" "${options[$i]}" > /dev/tty
+            fi
+        done
+    }
+
+    draw_menu "first"
+
+    while true; do
+        IFS= read -rsn1 key < /dev/tty
+
+        case "$key" in
+            $'\x1b')
+                read -rsn2 seq < /dev/tty
+                case "$seq" in
+                    '[A')
+                        ((selected--))
+                        [ "$selected" -lt 0 ] && selected=$((count - 1))
+                        ;;
+                    '[B')
+                        ((selected++))
+                        [ "$selected" -ge "$count" ] && selected=0
+                        ;;
+                esac
+                ;;
+            ''|$'\n'|$'\r')
+                tput cnorm > /dev/tty 2>/dev/null
+                printf "\n" > /dev/tty
+                printf '%s' "${options[$selected]}"
+                return
+                ;;
+            'q')
+                tput cnorm > /dev/tty 2>/dev/null
+                printf "\n" > /dev/tty
+                return
+                ;;
+        esac
+
+        draw_menu "redraw"
+    done
+}
+
+# ── Main ──
+
+# Handle flags
+SAFE_MODE=false
+STAY_HERE=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --safe) SAFE_MODE=true ;;
+        --here) STAY_HERE=true ;;
+    esac
+done
+
+if [ "$1" = "--setup" ]; then
+    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
+    fi
+    save_repo_path "$repo_path"
+    echo -e "${GREEN}Saved.${NC} Run ${BOLD}fig-start${NC} to begin."
+    exit 0
+fi
+
+# Resolve repo path
+REPO_PATH=$(get_repo_path)
+
+if [ -z "$REPO_PATH" ] || [ ! -d "$REPO_PATH" ]; then
+    # Try to find it relative to this script
+    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
+        fi
+        save_repo_path "$REPO_PATH"
+    fi
+fi
+
+CLI="$REPO_PATH/src/index.js"
+
+echo ""
+if [ "$SAFE_MODE" = true ]; then
+    echo -e "${BOLD}  fig-start${NC} ${DIM}— Figma CLI launcher (Safe Mode)${NC}"
+else
+    echo -e "${BOLD}  fig-start${NC} ${DIM}— Figma CLI launcher${NC}"
+fi
+echo ""
+
+# Step 1: Check if Figma is running, start if not
+if ! pgrep -x "Figma" > /dev/null 2>&1; then
+    echo -e "  ${YELLOW}Starting Figma...${NC}"
+    open -a Figma
+    sleep 3
+fi
+
+# Step 2: Connect to Figma
+if [ "$SAFE_MODE" = true ]; then
+    # ── Safe Mode: plugin-based connection ──
+    # Run connect --safe interactively so user sees plugin setup instructions
+    echo -e "  ${BOLD}🔒 Safe Mode${NC} — plugin-based, no patching required"
+    echo ""
+    node "$CLI" connect --safe
+    if [ $? -ne 0 ]; then
+        echo -e "  ${RED}Connection failed.${NC}"
+        exit 1
+    fi
+    echo ""
+
+    # Skip file selector (Safe Mode only sees the active file via plugin)
+    echo -e "  ${GREEN}Launching Claude Code...${NC}"
+    echo ""
+    if [ "$STAY_HERE" = false ]; then
+        cd "$REPO_PATH" || exit 1
+    fi
+    exec claude
+else
+    # ── Yolo Mode: CDP-based connection ──
+    # Check if CDP is already accessible (avoid killing/restarting Figma)
+    CDP_OK=false
+    if curl -s -o /dev/null -w "%{http_code}" http://localhost:9222/json 2>/dev/null | grep -q "200"; then
+        CDP_OK=true
+    fi
+
+    if [ "$CDP_OK" = true ]; then
+        # Figma is already accessible — just ensure daemon is running
+        DAEMON_OK=false
+        DAEMON_TOKEN=$(get_daemon_token)
+        if [ -n "$DAEMON_TOKEN" ]; then
+            if curl -s -o /dev/null -w "%{http_code}" -H "X-Daemon-Token: $DAEMON_TOKEN" http://localhost:3456/health 2>/dev/null | grep -q "200"; then
+                DAEMON_OK=true
+            fi
+        fi
+        if [ "$DAEMON_OK" = false ]; then
+            echo -e "  Starting daemon..."
+            node "$CLI" daemon restart > /dev/null 2>&1
+            sleep 1
+        fi
+        echo -e "  ${GREEN}✓ Connected${NC}"
+    else
+        # Not accessible — run full connect (will kill + restart Figma)
+        echo -e "  Connecting to Figma..."
+        CONNECT_OUT=$(node "$CLI" connect 2>&1)
+        if [ $? -ne 0 ]; then
+            echo -e "  ${RED}Connection failed:${NC}"
+            echo "$CONNECT_OUT"
+            echo ""
+            echo -e "  ${YELLOW}Tip:${NC} Try ${BOLD}fig-start --safe${NC} if patching fails."
+            exit 1
+        fi
+        echo -e "  ${GREEN}✓ Connected${NC}"
+        # Wait for Figma to fully restore all tabs after restart
+        sleep 3
+    fi
+
+    # Step 3: List open files and let user pick
+    echo -e "  Loading open files..."
+    FILES_JSON=$(node "$CLI" files 2>/dev/null)
+
+    if [ -z "$FILES_JSON" ] || echo "$FILES_JSON" | grep -q '"error"'; then
+        echo -e "  ${RED}Could not list files.${NC} Is Figma open with a file?"
+        exit 1
+    fi
+
+    # Parse file titles
+    FILE_TITLES=()
+    while IFS= read -r title; do
+        FILE_TITLES+=("$title")
+    done < <(echo "$FILES_JSON" | python3 -c "
+import json, sys
+files = json.load(sys.stdin)
+for f in files:
+    t = f.get('title', 'Untitled')
+    # Clean up Figma title format (remove ' – Figma' suffix)
+    t = t.replace(' – Figma', '').replace(' - Figma', '')
+    print(t)
+" 2>/dev/null)
+
+    if [ ${#FILE_TITLES[@]} -eq 0 ]; then
+        echo -e "  ${YELLOW}No Figma files detected.${NC} Open a file in Figma first."
+        echo ""
+        echo -e "  Launching Claude Code anyway..."
+        echo ""
+        if [ "$STAY_HERE" = false ]; then
+            cd "$REPO_PATH" || exit 1
+        fi
+        exec claude
+    fi
+
+    SELECTED_TITLE=""
+
+    echo ""
+    SELECTED_TITLE=$(select_file "${FILE_TITLES[@]}")
+    if [ -z "$SELECTED_TITLE" ]; then
+        echo "  Cancelled."
+        exit 0
+    fi
+
+    echo -e "  ${GREEN}✓ File: ${BOLD}${SELECTED_TITLE}${NC}"
+    echo ""
+
+    # Step 4: Launch Claude Code
+    echo -e "  ${GREEN}Launching Claude Code...${NC}"
+    echo ""
+    if [ "$STAY_HERE" = false ]; then
+        cd "$REPO_PATH" || exit 1
+    fi
+    exec claude
+fi

package/bin/setup-alias.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Adds fig-start alias to ~/.zshrc (or ~/.bashrc)
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ALIAS_LINE="alias fig-start='$REPO_DIR/bin/fig-start'"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# Detect shell config file
+if [ -n "$ZSH_VERSION" ] || [ "$SHELL" = "/bin/zsh" ]; then
+    RC_FILE="$HOME/.zshrc"
+else
+    RC_FILE="$HOME/.bashrc"
+fi
+
+# Check if alias already exists
+if grep -q "alias fig-start=" "$RC_FILE" 2>/dev/null; then
+    # Update existing alias (path may have changed)
+    sed -i '' "/alias fig-start=/d" "$RC_FILE"
+fi
+
+# Add alias
+echo "" >> "$RC_FILE"
+echo "# Figma CLI" >> "$RC_FILE"
+echo "$ALIAS_LINE" >> "$RC_FILE"
+
+# Save repo path to config
+mkdir -p "$HOME/.figma-cli"
+python3 -c "
+import json, os
+path = os.path.expanduser('~/.figma-cli/config.json')
+cfg = {}
+if os.path.exists(path):
+    with open(path) as f: cfg = json.load(f)
+cfg['repoPath'] = '$REPO_DIR'
+with open(path, 'w') as f: json.dump(cfg, f, indent=2)
+"
+
+echo ""
+echo -e "  ${GREEN}Done!${NC} Added ${BOLD}fig-start${NC} alias to ${BOLD}$RC_FILE${NC}"
+echo ""
+echo -e "  Now run: ${BOLD}source $RC_FILE${NC}"
+echo -e "  Then type: ${BOLD}fig-start${NC}"
+echo ""