Initial commit

2025-11-30 09:03:47 +08:00
commit 3ce986fa9b
14 changed files with 1118 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,14 @@
+{
+  "name": "figma-desktop-plugin",
+  "description": "Extract UI code, design tokens, and screenshots from Figma designs via desktop app. Use when implementing designs, building component libraries, or documenting design systems.",
+  "version": "0.5.1",
+  "author": {
+    "name": "ulasbilgen"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "agents": [
+    "./agents"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# figma-desktop-plugin
+
+Extract UI code, design tokens, and screenshots from Figma designs via desktop app. Use when implementing designs, building component libraries, or documenting design systems.
--- a/agents/figma-desktop.md
+++ b/agents/figma-desktop.md
@@ -0,0 +1,265 @@
+---
+name: figma-desktop
+description: Design-to-code automation specialist using Figma Desktop MCP server. Use when users need to extract UI code, design tokens, or screenshots from Figma designs. Expert at converting Figma components to production code (React, Vue, HTML/CSS) and extracting design system variables.
+skills: mcp-figma-desktop
+model: sonnet
+tools: Bash, Read, Write, Edit, Grep, Glob
+---
+
+# Figma Desktop Design-to-Code Agent
+
+You are a specialist in design-to-code workflows using the mcp-figma-desktop skill to extract code and design specifications from Figma Desktop.
+
+## When to Use This Agent
+
+Invoke this agent for:
+- **Design-to-Code Conversion**: Extract React, Vue, or HTML/CSS code from Figma components
+- **Design Token Extraction**: Get color palettes, typography, spacing variables
+- **Component Documentation**: Generate visual and code documentation for design systems
+- **Screenshot Capture**: Export component visuals for documentation or testing
+- **Design System Analysis**: Extract design patterns and create system guidelines
+- **FigJam Integration**: Work with FigJam board content
+
+## Available Capabilities
+
+The mcp-figma-desktop skill provides 6 tools organized into categories:
+
+### 1. Design Extraction
+- **get_design_context** - Primary tool for extracting UI code from nodes
+  - Generates HTML, CSS, React components with TypeScript
+  - Supports framework context (React, Vue, Angular, etc.)
+  - Works with selected nodes or specific node IDs
+- **get_metadata** - Get page/component structure overview in XML
+  - Find node IDs, layer types, names, positions, sizes
+  - Useful for planning extraction strategy
+
+### 2. Assets & Variables
+- **get_variable_defs** - Extract design system variables
+  - Colors, typography, spacing, and other tokens
+  - Returns in design token format
+- **get_screenshot** - Capture visual representation
+  - PNG screenshots of components for documentation
+
+### 3. Design Systems
+- **create_design_system_rules** - Generate design system guidelines
+  - Analyzes patterns and suggests naming conventions
+  - Creates documentation framework
+
+### 4. FigJam Support
+- **get_figjam** - Extract FigJam board content
+  - Works specifically with FigJam files (not regular Figma designs)
+
+## How to Use This Skill
+
+### Prerequisites Check
+
+Always verify before starting:
+1. **Figma Desktop app** is running with a file open
+2. **mcp2rest** is running: `curl http://localhost:28888/health`
+3. **figma-desktop server** is connected:
+   ```bash
+   curl http://localhost:28888/servers | grep figma-desktop
+   # Should show: "status": "connected"
+   ```
+4. **Dependencies** are installed in skill scripts directory
+
+### Standard Workflows
+
+#### Workflow 1: Extract Component Code
+
+**Goal**: Convert Figma component to production code
+
+**Steps**:
+1. User provides Figma URL or selects component in Figma Desktop
+2. Extract node ID from URL if provided:
+   - URL format: `https://figma.com/design/ABC123/MyApp?node-id=42-156`
+   - Convert: `42-156` → `42:156` (replace dash with colon)
+3. Extract UI code with framework context:
+   ```bash
+   node scripts/get_design_context.js \
+     --nodeId "42:156" \
+     --clientLanguages "typescript" \
+     --clientFrameworks "react"
+   ```
+4. Get design variables for the component:
+   ```bash
+   node scripts/get_variable_defs.js --nodeId "42:156"
+   ```
+5. Capture screenshot for documentation:
+   ```bash
+   node scripts/get_screenshot.js --nodeId "42:156"
+   ```
+
+**Output**: React/TypeScript code, design tokens, component screenshot
+
+#### Workflow 2: Build Design Token System
+
+**Goal**: Extract all design system variables
+
+**Steps**:
+1. Identify design system page (usually first page: `0:1`)
+2. Get page structure to find token groups:
+   ```bash
+   node scripts/get_metadata.js --nodeId "0:1"
+   ```
+3. Extract all variables:
+   ```bash
+   node scripts/get_variable_defs.js --nodeId "0:1"
+   ```
+4. Generate design system documentation:
+   ```bash
+   node scripts/create_design_system_rules.js \
+     --clientLanguages "css,javascript" \
+     --clientFrameworks "unknown"
+   ```
+
+**Output**: Complete design token hierarchy, naming conventions, CSS mappings
+
+#### Workflow 3: Quick Extraction from Selection
+
+**Goal**: Fastest workflow using Figma's current selection
+
+**Steps**:
+1. User selects node in Figma Desktop
+2. Extract without specifying nodeId (uses selection):
+   ```bash
+   node scripts/get_design_context.js
+   node scripts/get_variable_defs.js
+   node scripts/get_screenshot.js
+   ```
+
+**Note**: All tools work with currently selected node when no `--nodeId` provided
+
+### Node ID Handling
+
+**Extracting from URLs**:
+- Design files: `?node-id=1-2` → use `1:2`
+- FigJam boards: `?node-id=5-10` → use `5:10`
+- **Always replace dash with colon**
+
+**Finding node IDs**:
+- Method 1: Right-click in Figma → "Copy link to selection" → extract from URL
+- Method 2: Use `get_metadata` on page to list all node IDs
+- Method 3: Select in Figma Desktop and omit `--nodeId` parameter
+
+### Framework Context Best Practices
+
+Always specify target languages and frameworks for better code generation:
+
+```bash
+# React + TypeScript
+--clientLanguages "typescript" --clientFrameworks "react"
+
+# Vue + JavaScript
+--clientLanguages "javascript" --clientFrameworks "vue"
+
+# Plain HTML/CSS
+--clientLanguages "html,css,javascript" --clientFrameworks "unknown"
+
+# Multiple targets
+--clientLanguages "typescript,javascript" --clientFrameworks "react,nextjs"
+```
+
+## Important Notes
+
+- **Skill documentation auto-loaded**: The complete SKILL.md is in your context
+- **Refer to workflows**: See detailed workflow examples in SKILL.md
+- **State persistence**: Figma Desktop maintains state between calls
+- **Selection-based workflow**: Fastest method for interactive design work
+- **MCP server requirement**: Built into Figma Desktop v1.0.0+, accessed via HTTP
+
+## Troubleshooting
+
+### Connection Issues
+
+```bash
+# Check mcp2rest health
+curl http://localhost:28888/health
+
+# Verify figma-desktop server
+curl http://localhost:28888/servers
+```
+
+**If server not connected**:
+1. Ensure Figma Desktop app is running
+2. Restart Figma Desktop
+3. Restart mcp2rest
+4. Check that mcp2rest is configured to connect to http://127.0.0.1:3845/mcp
+
+### Node ID Errors
+
+**"Node not found" error**:
+- Verify format uses `:` not `-` (e.g., `1:2` not `1-2`)
+- Ensure node exists in currently open file
+- Try using selection instead of explicit node ID
+
+### Empty Output
+
+**get_design_context returns no code**:
+- Check node has actual design properties to extract
+- Try `--forceCode` flag to force generation
+- Verify correct file is open in Figma Desktop
+- Ensure node contains content (not empty frame)
+
+### FigJam Issues
+
+**Tool fails on FigJam board**:
+- Use `get_figjam` specifically for FigJam (not get_design_context)
+- Verify URL starts with `figma.com/board/` not `figma.com/design/`
+
+### Script Execution
+
+```bash
+# Navigate to skill scripts
+cd skills/mcp-figma-desktop/scripts/
+
+# Verify dependencies installed
+test -d node_modules && echo "✓ Dependencies OK" || npm install
+
+# Check script help
+node get_design_context.js --help
+```
+
+## Example User Interactions
+
+**User**: "Extract the Button component from this Figma URL"
+**You**:
+1. Parse URL to extract node ID
+2. Ask for target framework if not specified
+3. Run get_design_context with appropriate context
+4. Present generated code
+5. Offer to extract variables or screenshot
+
+**User**: "Get all color tokens from our design system"
+**You**:
+1. Ask for design system page URL or use selection
+2. Run get_metadata to see structure
+3. Run get_variable_defs to extract all variables
+4. Parse and organize token hierarchy
+5. Optionally generate design system rules document
+
+**User**: "Create documentation for all button variants"
+**You**:
+1. Use get_metadata to find all variant node IDs
+2. Loop through variants:
+   - Screenshot each variant
+   - Extract code for each
+3. Compile into documentation format
+4. Include visual references and code examples
+
+## Related Documentation
+
+- Complete skill reference: `skills/mcp-figma-desktop/SKILL.md`
+- Tool usage examples in SKILL.md workflows section
+- Node ID reference guide in SKILL.md
+- Troubleshooting guide in SKILL.md
+
+## Success Criteria
+
+When working with this skill:
+- ✓ Always verify Figma Desktop and mcp2rest are running first
+- ✓ Convert node IDs correctly (dash → colon)
+- ✓ Provide framework context for better code generation
+- ✓ Extract both code and variables for complete specifications
+- ✓ Capture screenshots for visual documentation
+- ✓ Verify output before presenting to user
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,85 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:ulasbilgen/mcp-skills-plugins:figma-desktop-plugin",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "384c09ee4bdc77d713c46c43cc6d7eaed9aa9526",
+    "treeHash": "f3ed7ad42f4bd796745f46bddcab82adae8610e0b182be28413eeb2818b9bf47",
+    "generatedAt": "2025-11-28T10:28:50.551086Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "figma-desktop-plugin",
+    "description": "Extract UI code, design tokens, and screenshots from Figma designs via desktop app. Use when implementing designs, building component libraries, or documenting design systems.",
+    "version": "0.5.1"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "cee93488c26948c83156ccc85ab2fe2cf8c30a7a7fcf2837c18544d7537ca638"
+      },
+      {
+        "path": "agents/figma-desktop.md",
+        "sha256": "92a6a0af77f0250913a41a39a7eda23e8ccdabfe5aaf18e34be522ef327a5556"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "bb5ba8ca4be332cce8bc5193f3a96d2b5ab60c99221176fdbc6ddc9f70f165ef"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/.skill-metadata.json",
+        "sha256": "c6cec64390eacd483760471f7e550491df58f0ca84676b8c1ba5a9e9482a4c34"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/SKILL.md",
+        "sha256": "875372c991f69013162b0114e6d4522d5a096eaa6820a9b0b983c7c5c92ee923"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/get_variable_defs.js",
+        "sha256": "eed2e83558f45727b8f1b854bd06f64f97ff39a33f133e12e1a81c3c36eeee30"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/get_figjam.js",
+        "sha256": "5b2311ee5e5e60ab6b46d896a933d5f3dabd099563f82519287176f126bbeae9"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/get_design_context.js",
+        "sha256": "08c4b9622b86102f2f9f30e5e648039e64a4c9811c6ca90cc7ebd41ecfb5f514"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/create_design_system_rules.js",
+        "sha256": "a8f9338e5e9c760316daa2b3183793f49cdc20e09b5cf88641e5fe3d68d4b930"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/package.json",
+        "sha256": "835e8fc39db7b42776a3670c0496162156adacb0e33eb5e8ea8c10b269415e4d"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/mcp_client.js",
+        "sha256": "ebc5ac33bac673c9e496caa260fd6d3eb22dafa2ea162ecbbd36dc9e62b19084"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/get_metadata.js",
+        "sha256": "3042dd91148d066e6c410848eed87dfb03dee8eb221b91a5ea7da5afae02dc2e"
+      },
+      {
+        "path": "skills/mcp-figma-desktop/scripts/get_screenshot.js",
+        "sha256": "0d31a31e61bdf802482aa6cfca686f87311187450099d46cf7f913e71f776fd3"
+      }
+    ],
+    "dirSha256": "f3ed7ad42f4bd796745f46bddcab82adae8610e0b182be28413eeb2818b9bf47"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/mcp-figma-desktop/.skill-metadata.json
+++ b/skills/mcp-figma-desktop/.skill-metadata.json
@@ -0,0 +1,12 @@
+{
+  "serverName": "figma-desktop",
+  "serverVersion": "1.0.0",
+  "serverVersionInfo": {
+    "name": "Figma Dev Mode MCP Server",
+    "version": "1.0.0",
+    "websiteUrl": "https://developers.figma.com/docs/figma-mcp-server/"
+  },
+  "generatedAt": "2025-11-23T23:49:37.592Z",
+  "mcp2scriptsVersion": "0.3.1",
+  "mcp2restUrl": "http://localhost:28888"
+}
--- a/skills/mcp-figma-desktop/SKILL.md
+++ b/skills/mcp-figma-desktop/SKILL.md
@@ -0,0 +1,380 @@
+---
+name: mcp-figma-desktop
+description: Extract UI code, design tokens, and screenshots from Figma designs via desktop app. Use when implementing designs, building component libraries, or documenting design systems.
+---
+
+# Figma Desktop Skill
+
+Interact with Figma designs directly through the Figma desktop app. Extract UI code (React, Vue, SwiftUI, etc.), design tokens (colors, spacing, typography), screenshots, and metadata from design files. Perfect for implementing design specs, creating component libraries, and maintaining design-code consistency.
+
+## Prerequisites
+
+- Figma desktop app installed and running
+- mcp2rest running on http://localhost:28888
+- figma-desktop server loaded in mcp2rest (http://127.0.0.1:3845/mcp)
+- Node.js 18+ installed
+
+**Verify connection:**
+```bash
+curl http://localhost:28888/health
+curl http://localhost:28888/servers | grep figma-desktop
+```
+
+## Quick Start
+
+Most tools work with either:
+- **Currently selected node** in Figma (no parameters)
+- **Specific node ID** (via `--nodeId` parameter)
+- **Figma URL** (automatically extracts node ID)
+
+**Example: Get code for selected component**
+```bash
+cd .claude/skills/mcp-figma-desktop/scripts
+
+# 1. Select a component in Figma desktop app
+# 2. Run this to get React code:
+node get_design_context.js --clientFrameworks react
+
+# Output: React component code with props, styling, and structure
+```
+
+**Example: Get code from Figma URL**
+```bash
+# Extract node 123-456 from URL: https://figma.com/design/abc/MyFile?node-id=123-456
+node get_design_context.js --nodeId "123:456" --clientFrameworks react,typescript
+```
+
+## Available Tools
+
+### Design Code Generation
+
+**get_design_context.js** - Generate production-ready UI code
+- **Use for:** Converting designs to React/Vue/SwiftUI/etc components
+- **Parameters:**
+  - `--nodeId` (optional) - Node ID like "123:456", or omit to use selected node
+  - `--clientLanguages` (optional) - Language preferences (e.g., typescript, swift)
+  - `--clientFrameworks` (optional) - Framework preferences (e.g., react, vue, swiftui)
+  - `--forceCode` (optional) - Force code generation even if not recommended
+
+**get_figjam.js** - Generate code from FigJam boards
+- **Use for:** Extracting content from FigJam files (NOT regular Figma files)
+- **Parameters:**
+  - `--nodeId` (optional) - FigJam node ID or omit for selected node
+  - `--clientLanguages` (optional) - Language preferences
+  - `--clientFrameworks` (optional) - Framework preferences
+  - `--includeImagesOfNodes` (optional) - Include embedded images
+
+**Important:** FigJam URLs use `/board/` instead of `/design/`:
+- FigJam: `https://figma.com/board/:fileKey/:fileName?node-id=1-2` → nodeId: "1:2"
+- Figma: `https://figma.com/design/:fileKey/:fileName?node-id=1-2` → nodeId: "1:2"
+
+### Design Tokens & Variables
+
+**get_variable_defs.js** - Extract design system variables
+- **Use for:** Getting reusable design tokens (colors, spacing, typography)
+- **Parameters:**
+  - `--nodeId` (optional) - Node ID or omit for selected node
+  - `--clientLanguages` (optional) - Output format preferences
+  - `--clientFrameworks` (optional) - Framework-specific token formats
+
+**Output example:**
+```json
+{
+  "icon/default/secondary": "#949494",
+  "spacing/base": "8px",
+  "font/heading/large": "32px"
+}
+```
+
+### Visual Assets
+
+**get_screenshot.js** - Generate high-quality screenshots
+- **Use for:** Creating visual documentation, design reviews, presentations
+- **Parameters:**
+  - `--nodeId` (optional) - Node to screenshot, or omit for selected
+  - `--clientLanguages` (optional) - Format preferences
+  - `--clientFrameworks` (optional) - Context for screenshot generation
+
+### Structure & Metadata
+
+**get_metadata.js** - Extract structural information
+- **Use for:** Understanding design hierarchy before detailed extraction
+- **Returns:** XML with node IDs, types, names, positions, sizes
+- **Note:** Prefer `get_design_context` for most use cases
+- **Parameters:**
+  - `--nodeId` (optional) - Node or page ID (e.g., "0:1" for whole page)
+  - `--clientLanguages` (optional)
+  - `--clientFrameworks` (optional)
+
+**When to use metadata:**
+1. Get overview of large page structure
+2. Find specific node IDs for detailed extraction
+3. Understand design organization before processing
+
+### Design System
+
+**create_design_system_rules.js** - Generate design system documentation
+- **Use for:** Creating design system rules for your codebase
+- **Returns:** Prompt/template for documenting design patterns
+- **Parameters:**
+  - `--clientLanguages` (optional) - Language context
+  - `--clientFrameworks` (optional) - Framework context
+
+## Common Workflows
+
+### Workflow 1: Implement Component from Design
+
+**Scenario:** Designer shares Figma link, you need to build the component
+
+**Checklist:**
+- [ ] Copy Figma URL from designer (e.g., `https://figma.com/design/abc/Button?node-id=12-34`)
+- [ ] Extract node ID from URL: `12-34` becomes `12:34`
+- [ ] Get component code: `node get_design_context.js --nodeId "12:34" --clientFrameworks react,typescript`
+- [ ] Review generated code and component props
+- [ ] Extract design tokens: `node get_variable_defs.js --nodeId "12:34"`
+- [ ] Create screenshot for documentation: `node get_screenshot.js --nodeId "12:34"`
+- [ ] Implement component using generated code as reference
+- [ ] Verify design tokens match
+
+**Example:**
+```bash
+cd .claude/skills/mcp-figma-desktop/scripts
+
+# 1. Get React + TypeScript code
+node get_design_context.js --nodeId "12:34" --clientFrameworks react,typescript
+
+# 2. Get design variables
+node get_variable_defs.js --nodeId "12:34"
+
+# 3. Take screenshot for docs
+node get_screenshot.js --nodeId "12:34"
+```
+
+**Expected output:**
+- TypeScript React component with props interface
+- Design tokens (colors, spacing, typography)
+- High-quality PNG screenshot
+
+### Workflow 2: Build Component Library
+
+**Scenario:** Create reusable component library from design system
+
+**Checklist:**
+- [ ] Open design system file in Figma desktop
+- [ ] Get page structure: `node get_metadata.js --nodeId "0:1"` (page root)
+- [ ] Identify component node IDs from metadata XML
+- [ ] For each component:
+  - [ ] Extract code: `node get_design_context.js --nodeId "{id}" --clientFrameworks react`
+  - [ ] Extract tokens: `node get_variable_defs.js --nodeId "{id}"`
+  - [ ] Generate screenshot: `node get_screenshot.js --nodeId "{id}"`
+- [ ] Create design system rules: `node create_design_system_rules.js`
+- [ ] Organize components into library structure
+- [ ] Document usage patterns
+
+**Example: Button component extraction**
+```bash
+# 1. Get page structure to find button variants
+node get_metadata.js --nodeId "0:1" > structure.xml
+
+# From XML, identify button node IDs: 45:12, 45:13, 45:14
+
+# 2. Extract primary button
+node get_design_context.js --nodeId "45:12" --clientFrameworks react,typescript > Button.tsx
+node get_variable_defs.js --nodeId "45:12" > button-tokens.json
+node get_screenshot.js --nodeId "45:12" > button-primary.png
+
+# 3. Repeat for secondary, tertiary variants
+```
+
+### Workflow 3: Design-to-Code for FigJam Wireframes
+
+**Scenario:** Convert FigJam wireframes into initial code structure
+
+**Important:** Use `get_figjam.js` for FigJam files, NOT `get_design_context.js`
+
+**Checklist:**
+- [ ] Open FigJam board in Figma desktop
+- [ ] Select wireframe frame/section
+- [ ] Extract structure: `node get_figjam.js --includeImagesOfNodes true`
+- [ ] Review generated code skeleton
+- [ ] Refine with actual design components
+
+**Example:**
+```bash
+cd .claude/skills/mcp-figma-desktop/scripts
+
+# From FigJam URL: https://figma.com/board/xyz/Wireframes?node-id=5-10
+# Extract node "5:10"
+
+node get_figjam.js --nodeId "5:10" --clientFrameworks react --includeImagesOfNodes true
+```
+
+**Expected output:**
+- Basic component structure matching wireframe layout
+- Placeholder content from FigJam sticky notes/text
+- Embedded images if present
+
+### Workflow 4: Extract Design Tokens for Theme
+
+**Scenario:** Create theme configuration from design variables
+
+**Checklist:**
+- [ ] Select root design system frame in Figma
+- [ ] Extract all variables: `node get_variable_defs.js`
+- [ ] Parse output into theme format (CSS custom properties, JS theme object, etc.)
+- [ ] Validate variable naming conventions
+- [ ] Generate theme documentation
+
+**Example:**
+```bash
+# 1. Get all design tokens from selected design system root
+node get_variable_defs.js > design-tokens.json
+
+# Output will include:
+# {
+#   "color/primary/500": "#3B82F6",
+#   "color/primary/600": "#2563EB",
+#   "spacing/xs": "4px",
+#   "spacing/sm": "8px",
+#   "typography/heading/h1": "32px"
+# }
+
+# 2. Convert to CSS variables or theme object in your build process
+```
+
+## Node ID Format
+
+Figma uses colon-separated node IDs internally:
+
+**From Figma URLs:**
+- URL: `...?node-id=123-456` → Node ID: `"123:456"` (replace hyphen with colon)
+- Always use quotes: `--nodeId "123:456"`
+
+**From metadata:**
+- XML includes actual node IDs: `id="123:456"`
+- Copy directly into commands
+
+**Page IDs:**
+- Pages typically start with `0:` (e.g., `0:1`, `0:2`)
+- Use for getting entire page structure
+
+## State Persistence
+
+The figma-desktop server maintains state between calls:
+- Selected node in Figma remains consistent across commands
+- Can run multiple extractions without re-selecting
+- Server state persists until Figma desktop app is closed
+
+**Best practice:** For batch operations, keep Figma desktop app open and navigate to each node before running scripts.
+
+## Troubleshooting
+
+### Connection Issues
+
+**Error: Cannot connect to mcp2rest**
+```bash
+# 1. Check mcp2rest is running
+curl http://localhost:28888/health
+
+# 2. Verify figma-desktop server is loaded
+curl http://localhost:28888/servers
+
+# 3. Look for figma-desktop in output with "connected" status
+```
+
+**Error: figma-desktop server not found**
+- Ensure Figma desktop app is running
+- Restart mcp2rest: `mcp2rest restart`
+- Check server URL matches: `http://127.0.0.1:3845/mcp`
+
+### Tool-Specific Issues
+
+**No output or empty response**
+- Ensure a node is selected in Figma desktop app
+- Try providing explicit `--nodeId` parameter
+- Verify node ID format uses colon: `"123:456"` not `"123-456"`
+
+**Wrong framework/language output**
+- Use `--clientFrameworks` to specify: `react`, `vue`, `swiftui`, etc.
+- Use `--clientLanguages` to specify: `typescript`, `javascript`, `swift`
+- Combine multiple: `--clientFrameworks react,typescript`
+
+**FigJam extraction fails**
+- Ensure using `get_figjam.js` for FigJam files (not `get_design_context.js`)
+- Check URL contains `/board/` (FigJam) not `/design/` (Figma)
+- FigJam requires `--includeImagesOfNodes` for embedded images
+
+### Getting Help
+
+```bash
+# View help for any script
+node scripts/get_design_context.js --help
+node scripts/get_variable_defs.js --help
+node scripts/get_screenshot.js --help
+```
+
+## Advanced Usage
+
+### Custom Language/Framework Output
+
+Most tools support `--clientLanguages` and `--clientFrameworks` for customization:
+
+```bash
+# React with TypeScript
+node get_design_context.js --nodeId "12:34" --clientFrameworks react,typescript
+
+# Vue with Composition API
+node get_design_context.js --nodeId "12:34" --clientFrameworks vue,composition-api
+
+# SwiftUI
+node get_design_context.js --nodeId "12:34" --clientFrameworks swiftui --clientLanguages swift
+
+# Multiple frameworks for comparison
+node get_design_context.js --nodeId "12:34" --clientFrameworks react,vue,svelte
+```
+
+### Batch Processing
+
+Process multiple nodes in sequence:
+
+```bash
+# Save node IDs to file
+echo "12:34" > nodes.txt
+echo "45:67" >> nodes.txt
+echo "89:01" >> nodes.txt
+
+# Process each node
+while read nodeId; do
+  echo "Processing $nodeId..."
+  node get_design_context.js --nodeId "$nodeId" --clientFrameworks react > "component_${nodeId//:/_}.tsx"
+  node get_screenshot.js --nodeId "$nodeId" > "screenshot_${nodeId//:/_}.png"
+done < nodes.txt
+```
+
+### Integration with Build Tools
+
+Example: Extract design tokens during build:
+
+```json
+{
+  "scripts": {
+    "extract-tokens": "cd .claude/skills/mcp-figma-desktop/scripts && node get_variable_defs.js > ../../src/theme/tokens.json",
+    "prebuild": "npm run extract-tokens"
+  }
+}
+```
+
+## Tips for Best Results
+
+1. **Use specific frameworks:** `--clientFrameworks react` gives better output than generic
+2. **Select precise nodes:** Select the exact component/frame in Figma for accurate extraction
+3. **Verify metadata first:** Use `get_metadata.js` to explore structure before detailed extraction
+4. **Consistent naming:** Use Figma naming conventions that match your code (e.g., `Button/Primary`, `Icon/Close`)
+5. **Design tokens:** Set up variables in Figma for automatic token extraction
+6. **Batch operations:** Keep Figma desktop open and process multiple nodes in sequence for efficiency
+
+## Related Resources
+
+- [Figma Desktop Plugin MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/figma-desktop)
+- [mcp2rest Documentation](https://github.com/ulasbilgen/mcp2skill-tools/tree/main/packages/mcp2rest)
+- [Figma Variables Guide](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)
--- a/skills/mcp-figma-desktop/scripts/create_design_system_rules.js
+++ b/skills/mcp-figma-desktop/scripts/create_design_system_rules.js
@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: create_design_system_rules
+ *
+ * Provides a prompt to generate design system rules for this repo.
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('create_design_system_rules')
+  .description('Provides a prompt to generate design system rules for this repo.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'create_design_system_rules', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/get_design_context.js
+++ b/skills/mcp-figma-desktop/scripts/get_design_context.js
@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: get_design_context
+ *
+ * Generate UI code for a given node or the currently selected node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`.
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('get_design_context')
+  .description('Generate UI code for a given node or the currently selected node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`.')
+  .option('--nodeId <value>', 'The ID of the node in the Figma document, eg. \"123:456\" or \"123-456\". This should be a valid node ID in the Figma document.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .option('--forceCode', 'Whether code should always be returned, instead of returning just metadata if the output size is too large. Only set this when the user directly requests to force the code. ')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.nodeId !== undefined) {
+    args['nodeId'] = options.nodeId;
+  }
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+  if (options.forceCode) {
+    args['forceCode'] = true;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'get_design_context', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/get_figjam.js
+++ b/skills/mcp-figma-desktop/scripts/get_figjam.js
@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: get_figjam
+ *
+ * Generate UI code for a given FigJam node or the currently selected FigJam node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/board/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`. IMPORTANT: This tool only works for FigJam files, not other Figma files.
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('get_figjam')
+  .description('Generate UI code for a given FigJam node or the currently selected FigJam node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/board/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`. IMPORTANT: This tool only works for FigJam files, not other Figma files.')
+  .option('--nodeId <value>', 'The ID of the node in the Figma document, eg. \"123:456\" or \"123-456\". This should be a valid node ID in the Figma document.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .option('--includeImagesOfNodes', 'Whether to include images of nodes in the response')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.nodeId !== undefined) {
+    args['nodeId'] = options.nodeId;
+  }
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+  if (options.includeImagesOfNodes) {
+    args['includeImagesOfNodes'] = true;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'get_figjam', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/get_metadata.js
+++ b/skills/mcp-figma-desktop/scripts/get_metadata.js
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: get_metadata
+ *
+ * IMPORTANT: Always prefer to use get_design_context tool. Get metadata for a node or page in the Figma desktop app in XML format. Useful only for getting an overview of the structure, it only includes node IDs, layer types, names, positions and sizes. You can call get_design_context on the node IDs contained in this response. Use the nodeId parameter to specify a node id, it can also be the page id (e.g. 0:1). If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`.
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('get_metadata')
+  .description('IMPORTANT: Always prefer to use get_design_context tool. Get metadata for a node or page in the Figma desktop app in XML format. Useful only for getting an overview of the structure, it only includes node IDs, layer types, names, positions and sizes. You can call get_design_context on the node IDs contained in this response. Use the nodeId parameter to specify a node id, it can also be the page id (e.g. 0:1). If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`.')
+  .option('--nodeId <value>', 'The ID of the node in the Figma document, eg. \"123:456\" or \"123-456\". This should be a valid node ID in the Figma document.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.nodeId !== undefined) {
+    args['nodeId'] = options.nodeId;
+  }
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'get_metadata', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/get_screenshot.js
+++ b/skills/mcp-figma-desktop/scripts/get_screenshot.js
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: get_screenshot
+ *
+ * Generate a screenshot for a given node or the currently selected node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('get_screenshot')
+  .description('Generate a screenshot for a given node or the currently selected node in the Figma desktop app. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`')
+  .option('--nodeId <value>', 'The ID of the node in the Figma document, eg. \"123:456\" or \"123-456\". This should be a valid node ID in the Figma document.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.nodeId !== undefined) {
+    args['nodeId'] = options.nodeId;
+  }
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'get_screenshot', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/get_variable_defs.js
+++ b/skills/mcp-figma-desktop/scripts/get_variable_defs.js
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * MCP Server: figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ * Tool: get_variable_defs
+ *
+ * Get variable definitions for a given node id. E.g. {'icon/default/secondary': #949494}Variables are reusable values that can be applied to all kinds of design properties, such as fonts, colors, sizes and spacings. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`
+ */
+
+import { program } from 'commander';
+import { callTool } from './mcp_client.js';
+
+program
+  .name('get_variable_defs')
+  .description('Get variable definitions for a given node id. E.g. {\'icon/default/secondary\': #949494}Variables are reusable values that can be applied to all kinds of design properties, such as fonts, colors, sizes and spacings. Use the nodeId parameter to specify a node id. If no node id is provided, the currently selected node will be used. If a URL is provided, extract the node id from the URL, for example, if given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2, the extracted nodeId would be `1:2`')
+  .option('--nodeId <value>', 'The ID of the node in the Figma document, eg. \"123:456\" or \"123-456\". This should be a valid node ID in the Figma document.')
+  .option('--clientLanguages <value>', 'A comma separated list of programming languages used by the client in the current context in string form, e.g. `javascript`, `html,css,typescript`, etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which languages are being used. If you are unsure, it is better to list `unknown` than to make a guess.')
+  .option('--clientFrameworks <value>', 'A comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django` etc. If you do not know, please list `unknown`. This is used for logging purposes to understand which frameworks are being used. If you are unsure, it is better to list `unknown` than to make a guess')
+  .parse();
+
+const options = program.opts();
+
+  // Build arguments object
+  const args = {};
+  if (options.nodeId !== undefined) {
+    args['nodeId'] = options.nodeId;
+  }
+  if (options.clientLanguages !== undefined) {
+    args['clientLanguages'] = options.clientLanguages;
+  }
+  if (options.clientFrameworks !== undefined) {
+    args['clientFrameworks'] = options.clientFrameworks;
+  }
+
+// Call the tool
+try {
+  const result = await callTool('figma-desktop', 'get_variable_defs', args);
+  console.log(result);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
--- a/skills/mcp-figma-desktop/scripts/mcp_client.js
+++ b/skills/mcp-figma-desktop/scripts/mcp_client.js
@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * MCP REST Client for figma-desktop
+ * Server Version: 1.0.0
+ * Generated: 2025-11-23
+ *
+ * Shared MCP REST client for tool scripts.
+ */
+
+import axios from 'axios';
+
+// MCP2REST endpoint (configurable via environment variable)
+const MCP_REST_URL = process.env.MCP_REST_URL || 'http://localhost:28888';
+
+/**
+ * Call an MCP tool via mcp2rest REST API.
+ *
+ * @param {string} server - Server name (e.g., "chrome-devtools")
+ * @param {string} tool - Tool name (e.g., "click")
+ * @param {object} args - Tool arguments as object
+ * @returns {Promise<string>} Tool result as formatted string
+ */
+export async function callTool(server, tool, args) {
+  const url = `${MCP_REST_URL}/call`;
+  const payload = {
+    server,
+    tool,
+    arguments: args || {},
+  };
+
+  try {
+    const response = await axios.post(url, payload, {
+      headers: { 'Content-Type': 'application/json' },
+      timeout: 30000,
+    });
+
+    const data = response.data;
+
+    if (data.success) {
+      // Extract and format result
+      const result = data.result || {};
+      const content = result.content || [];
+
+      // Format output nicely
+      const outputParts = [];
+      for (const item of content) {
+        if (item.type === 'text') {
+          outputParts.push(item.text || '');
+        } else if (item.type === 'image') {
+          // For images, just note their presence
+          const dataLen = (item.data || '').length;
+          outputParts.push(`[Image data: ${dataLen} bytes]`);
+        } else if (item.type === 'resource') {
+          outputParts.push(JSON.stringify(item.resource || {}, null, 2));
+        }
+      }
+
+      return outputParts.length > 0 ? outputParts.join('\n') : JSON.stringify(result, null, 2);
+    } else {
+      const error = data.error || {};
+      const errorMsg = error.message || 'Unknown error';
+      const errorCode = error.code || 'UNKNOWN';
+      console.error(`Error [${errorCode}]: ${errorMsg}`);
+      process.exit(1);
+    }
+  } catch (error) {
+    if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+      console.error(`Error: Cannot connect to mcp2rest at ${MCP_REST_URL}`);
+      console.error('Make sure mcp2rest is running.');
+    } else if (error.code === 'ETIMEDOUT' || error.code === 'ECONNABORTED') {
+      console.error('Error: Request timed out after 30 seconds');
+    } else if (error.response) {
+      console.error(`Error: HTTP ${error.response.status} - ${error.response.data}`);
+    } else {
+      console.error(`Error: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
--- a/skills/mcp-figma-desktop/scripts/package.json
+++ b/skills/mcp-figma-desktop/scripts/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "mcp-figma-desktop-skill",
+  "version": "1.0.0",
+  "description": "Claude Code skill scripts for figma-desktop MCP server",
+  "type": "module",
+  "dependencies": {
+    "axios": "^1.6.2",
+    "commander": "^11.1.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "skill",
+    "figma-desktop"
+  ],
+  "author": "",
+  "license": "MIT"
+}