​

Available Tools - Detailed Documentation

Note: Local Mode (NPX/Git) provides 114 tools with full read/write capabilities and real-time monitoring. Remote Mode provides 9 read-only tools by default, or 101 tools (including full write access) when paired with the Desktop Bridge plugin via Cloud Relay. Tools marked “Local” in the table below require Local Mode. Tools marked “Local / Cloud” work in both Local Mode and Cloud Mode (after pairing).

​

Quick Reference

​

🧭 Navigation & Status Tools

​

figma_navigate

figma_navigate({
  url: 'https://www.figma.com/design/abc123/My-Design?node-id=1-2',
  lock: true  // optional — pin this file as the target (Local Mode)
})

• Navigation status
• Current URL
• Connection or monitoring status
• locked — whether the target is now pinned (Local Mode)

​

figma_get_status

figma_get_status()

• Setup validation (local mode only):
  • setup.valid - Whether the WebSocket transport is available
  • setup.message - Human-readable status
  • setup.transport - Transport status (websocket or none)
  • setup.setupInstructions - Step-by-step setup guide (if no transport available)
  • setup.ai_instruction - Guidance for AI assistants
• Browser connection status
• Console monitoring active/inactive
• Current URL (if navigated)
• Number of captured console logs

{
  "mode": "local",
  "setup": {
    "valid": true,
    "message": "✅ Figma Desktop connected via WebSocket (Desktop Bridge Plugin)"
  }
}

{
  "mode": "local",
  "setup": {
    "valid": false,
    "message": "❌ No connection to Figma Desktop",
    "setupInstructions": {
      "step1": "Install Desktop Bridge Plugin: Figma → Plugins → Development → Import from manifest",
      "step2": "Run the plugin in your Figma file"
    }
  }
}

• Call this tool first when starting a session in local mode
• If setup.valid is false, guide user to install and run the Desktop Bridge Plugin

​

📋 Console Tools (Plugin Debugging)

​

figma_get_console_logs

💡 Plugin Developers in Local Mode: This tool works immediately - no navigation required! Just check logs, run your plugin in Figma Desktop, check logs again. All [Main], [Swapper], etc. plugin logs appear instantly.

figma_get_console_logs({
  count: 50,           // Number of logs to retrieve (default: 100)
  level: 'error',      // Filter by level: 'log', 'info', 'warn', 'error', 'debug', 'all'
  since: 1234567890    // Unix timestamp (ms) - only logs after this time
})

• count (optional): Number of recent logs to retrieve (default: 100)
• level (optional): Filter by log level (default: ‘all’)
• since (optional): Unix timestamp in milliseconds - only logs after this time

• Array of console log entries with:
  • timestamp: Unix timestamp (ms)
  • level: ‘log’, ‘info’, ‘warn’, ‘error’, ‘debug’
  • message: The log message
  • args: Additional arguments passed to console method
  • stackTrace: Stack trace (for errors)

// Get last 20 error logs
figma_get_console_logs({ count: 20, level: 'error' })

// Get all logs from last 30 seconds
const thirtySecondsAgo = Date.now() - (30 * 1000);
figma_get_console_logs({ since: thirtySecondsAgo })

​

figma_watch_console

figma_watch_console({
  duration: 30,        // Watch for 30 seconds (default: 30, max: 300)
  level: 'all'         // Filter by level (default: 'all')
})

• duration (optional): How long to watch in seconds (default: 30, max: 300)
• level (optional): Filter by log level (default: ‘all’)

• Real-time stream of console logs captured during the watch period
• Summary of total logs captured by level

​

figma_clear_console

figma_clear_console()

• Confirmation of buffer cleared
• Number of logs that were cleared

​

🔍 Debugging Tools

​

figma_take_screenshot

figma_take_screenshot({
  target: 'plugin',           // 'plugin', 'full-page', or 'viewport'
  format: 'png',              // 'png' or 'jpeg'
  quality: 90,                // JPEG quality 0-100 (default: 90)
  filename: 'my-screenshot'   // Optional filename
})

• target (optional): What to screenshot
  • 'plugin': Just the plugin UI (default)
  • 'full-page': Entire scrollable page
  • 'viewport': Current visible viewport
• format (optional): Image format (default: ‘png’)
• quality (optional): JPEG quality 0-100 (default: 90)
• filename (optional): Custom filename

• Screenshot image
• Metadata (dimensions, format, size)

​

figma_reload_plugin

figma_reload_plugin({
  clearConsole: true   // Clear console logs before reload (default: true)
})

• Reload status
• New page URL (if changed)

​

🔁 Token Sync Tools

​

figma_export_tokens

figma_export_tokens()

figma_export_tokens({
  format: "dtcg",
  outputPath: "src/styles/tokens",
  splitByMode: true,
  splitByCollection: true,
  prefix: "ds-"
})

​

figma_import_tokens

figma_import_tokens()

figma_import_tokens({
  format: "dtcg",
  payload: "{ \"color\": { \"primary\": { \"$type\": \"color\", \"$value\": \"#FF00AA\" } } }",
  strategy: "dry-run"   // preview first
})

1. Figma variable ID stored in $extensions["figma-console-mcp"].variableId. Survives renames.
2. Token path (e.g. color.primary). Used when metadata is absent (first sync, hand-authored DTCG).
3. Value fingerprint. Used to detect no-op writes — same hash means no API call.

• ✅ toUpdate (value changes on existing variables): applied via the plugin bridge (figma.variables.setValueForMode). Multi-mode supported. Renames matched by round-trip variable ID apply as name changes on the existing variable — a token-path rename never becomes a create+delete pair. scopes and codeSyntax metadata changes apply too (a code-side absent field means “no opinion” and never resets Figma metadata).
• ✅ toCreate (new variables and collections): missing collections are created with their full mode lists; missing variables are created with inferred or round-trip-recorded types, values set across all modes in dependency order — literal values first, alias values in a second pass so their targets exist. TIMING/EASING tokens are skipped with a clear warning (the Plugin API cannot create those types).
• ✅ Alias updates (code-side {color.primary} references): written as real { type: "VARIABLE_ALIAS", id } values. Resolver priority: just-created variable → live Figma snapshot → pending in this batch → recorded $extensions variable ID. Unresolvable references are skipped with a warning.
• ✅ toDelete (Figma-only variables): applied only under strategy: "replace", and announced loudly in the response. The default merge strategy reports them without deleting.

​

🎨 Design System Tools

⚠️ All Design System tools require FIGMA_ACCESS_TOKEN configured in your MCP client. See Installation Guide for setup instructions.

​

figma_get_variables

figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123',
  includePublished: true,                        // Include published library variables
  enrich: true,                                  // Add CSS/Tailwind exports
  export_formats: ['css', 'tailwind', 'sass'],   // Export formats
  include_usage: true,                           // Show where variables are used
  include_dependencies: true                     // Show variable dependencies
})

// Path-based branch URL
figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123/branch/xyz789/My-File'
})

// Query-based branch URL
figma_get_variables({
  fileUrl: 'https://figma.com/design/abc123/My-File?branch-id=xyz789'
})

// First navigate to the branch
figma_navigate({ url: 'https://figma.com/design/abc123/branch/xyz789/My-File' })

// Then get variables from the current file
figma_get_variables({ refreshCache: true })

• fileUrl (optional): Figma file URL - supports main files and branches (uses current if navigated)
• includePublished (optional): Include published variables (default: true)
• enrich (optional): Add exports and usage analysis (default: false)
• export_formats (optional): Code formats to generate
• include_usage (optional): Include usage in styles/components
• include_dependencies (optional): Include dependency graph
• refreshCache (optional): Force fresh data fetch, bypassing cache

• Variable collections
• Variables with modes and values
• Summary statistics
• Export code (if enrich: true)
• Usage information (if include_usage: true)
• Branch info (when using branch URL): fileKey, branchId, isBranch

​

figma_get_styles

figma_get_styles({
  fileUrl: 'https://figma.com/design/abc123',
  enrich: true,                                  // Add code exports
  export_formats: ['css', 'tailwind'],           // Export formats
  include_usage: true,                           // Show component usage
  include_exports: true                          // Include code examples
})

• fileUrl (optional): Figma file URL
• enrich (optional): Add exports and usage (default: false)
• export_formats (optional): Code formats to generate
• include_usage (optional): Show where styles are used
• include_exports (optional): Include code examples

• All styles (color, text, effect, grid)
• Style metadata and properties
• Export code (if enrich: true)
• Usage information (if requested)

​

figma_get_component

// Metadata format (default) - for documentation and style guides
figma_get_component({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '123:456',
  format: 'metadata',  // or omit for default
  enrich: true         // Add token coverage analysis
})

// Reconstruction format - for programmatic component creation
figma_get_component({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '123:456',
  format: 'reconstruction'  // Compatible with Figma Component Reconstructor plugin
})

• fileUrl (optional): Figma file URL
• nodeId (required): Component node ID (e.g., ‘123:456’)
• format (optional): Export format - 'metadata' (default) or 'reconstruction'
• enrich (optional): Add quality metrics (default: false, only for metadata format)

• Component metadata and documentation
• Properties and variants
• Bounds and layout info
• Token coverage (if enrich: true)
• Use for: Documentation, style guides, design system references

• Complete node tree specification
• All visual properties (fills, strokes, effects)
• Layout properties (auto-layout, padding, spacing)
• Text properties with font information
• Color values in 0-1 normalized RGB format
• Validation of spec against plugin requirements
• Use for: Programmatic component creation, version control, component migration
• Compatible with: Figma Component Reconstructor plugin

​

figma_get_component_for_development

figma_get_component_for_development({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '695:313',
  includeImage: true   // Include rendered image (default: true)
})

• fileUrl (optional): Figma file URL
• nodeId (required): Component node ID
• includeImage (optional): Include rendered image (default: true)

• Component image (rendered at 2x scale)
• Filtered component data with:
  • Layout properties (auto-layout, padding, spacing)
  • Visual properties (fills, strokes, effects)
  • Typography
  • Component properties and variants
  • Bounds and positioning

​

figma_get_component_image

figma_get_component_image({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '695:313',
  scale: 2,              // Image scale (0.01-4, default: 2)
  format: 'png'          // 'png', 'jpg', 'svg', 'pdf'
})

• fileUrl (optional): Figma file URL
• nodeId (required): Node ID to render
• scale (optional): Scale factor (default: 2)
• format (optional): Image format (default: ‘png’)

• Image URL (expires after 30 days)
• Image metadata

​

figma_get_file_data

figma_get_file_data({
  fileUrl: 'https://figma.com/design/abc123',
  depth: 2,                  // Levels of children (0-3, default: 1)
  verbosity: 'standard',     // 'summary', 'standard', 'full'
  nodeIds: ['123:456'],      // Specific nodes only (optional)
  enrich: true               // Add file statistics and health metrics
})

• fileUrl (optional): Figma file URL
• depth (optional): Depth of children tree (max: 3)
• verbosity (optional): Data detail level
  • 'summary': IDs, names, types only (~90% smaller)
  • 'standard': Essential properties (~50% smaller)
  • 'full': Everything
• nodeIds (optional): Retrieve specific nodes only
• enrich (optional): Add statistics and metrics

• File metadata
• Document tree (filtered by verbosity)
• Component/style counts
• Statistics (if enrich: true)

​

figma_get_file_for_plugin

figma_get_file_for_plugin({
  fileUrl: 'https://figma.com/design/abc123',
  depth: 3,                  // Higher depth allowed (max: 5)
  nodeIds: ['123:456']       // Specific nodes (optional)
})

• fileUrl (optional): Figma file URL
• depth (optional): Depth of children (max: 5, default: 2)
• nodeIds (optional): Specific nodes only

• Filtered file data with:
  • IDs, names, types
  • Plugin data (pluginData, sharedPluginData)
  • Component relationships
  • Lightweight bounds
  • Structure for navigation

​

Tool Comparison

​

When to Use Each Tool

• figma_get_component_for_development - Best for implementing UI components (includes image + layout data)
• figma_get_component_image - Just need a visual reference
• figma_get_component - Need full component metadata

• figma_get_file_for_plugin - Optimized file structure for plugins
• figma_get_console_logs - Debug plugin code
• figma_watch_console - Monitor plugin execution

• figma_get_variables - Design tokens with code exports
• figma_get_styles - Traditional styles with code exports
• figma_get_file_data - Full file structure with verbosity control

• figma_get_console_logs - Retrieve specific logs
• figma_watch_console - Live monitoring
• figma_take_screenshot - Visual debugging
• figma_get_status - Check connection health

​

✏️ Design Creation Tools

⚠️ Requires Desktop Bridge Plugin: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using figma_pair_plugin to connect through the cloud relay.

​

figma_execute

• Creating UI components (buttons, cards, modals, notifications)
• Building frames with auto-layout
• Adding text with specific fonts and styles
• Creating shapes (rectangles, ellipses, vectors)
• Applying effects, fills, and strokes
• Creating pages or organizing layers
• Any operation that requires the full Figma Plugin API

figma_execute({
  code: `
    // Create a button component
    const button = figma.createFrame();
    button.name = "Button";
    button.resize(120, 40);
    button.cornerRadius = 8;
    button.fills = [{ type: 'SOLID', color: { r: 0.23, g: 0.51, b: 0.96 } }];

    // Add auto-layout
    button.layoutMode = "HORIZONTAL";
    button.primaryAxisAlignItems = "CENTER";
    button.counterAxisAlignItems = "CENTER";

    // Add text
    await figma.loadFontAsync({ family: "Inter", style: "Medium" });
    const text = figma.createText();
    text.characters = "Click me";
    text.fontName = { family: "Inter", style: "Medium" };
    text.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
    button.appendChild(text);

    // Position and select
    button.x = figma.viewport.center.x;
    button.y = figma.viewport.center.y;
    figma.currentPage.selection = [button];

    return { nodeId: button.id, name: button.name };
  `,
  timeout: 10000  // Optional: max execution time in ms (default: 5000)
})

• code (required): JavaScript code to execute. Has access to figma global object.
• timeout (optional): Execution timeout in ms (default: 5000, max: 30000)
• fileKey (optional, Local Mode only): Run against a specific connected file instead of the active one, without changing the active file or releasing target lock. Get connected fileKeys from figma_list_open_files. Cloud Mode pairs with a single plugin instance and rejects this parameter rather than silently running against the paired file.

• Whatever the code returns (use return statement)
• Execution success/failure status
• fileContext — the file name and key as reported by the plugin that ran the code, so you can confirm it executed where you intended

1. Always use await for async operations (loadFontAsync, getNodeByIdAsync)
2. Return useful data (node IDs, names) for follow-up operations
3. Position elements relative to viewport center for visibility
4. Select created elements so users can see them immediately
5. Use try/catch for error handling in complex operations

// Create a page
const page = figma.createPage();
page.name = "My New Page";
await figma.setCurrentPageAsync(page);

// Find and modify existing node
const node = await figma.getNodeByIdAsync("123:456");
node.name = "New Name";

// Create component from frame
const component = figma.createComponent();
// ... add children

// Apply auto-layout
frame.layoutMode = "VERTICAL";
frame.itemSpacing = 8;
frame.paddingTop = 16;
frame.paddingBottom = 16;
frame.paddingLeft = 16;
frame.paddingRight = 16;

​

figma_execute_across_files

• Checking the same thing across a library split over multiple files (“which files still use the old text styles?”)
• Applying one mechanical fix across a known set of files
• Any read that you’d otherwise repeat file by file

// Preferred: name the files you mean.
figma_execute_across_files({
  fileKeys: ["abc123", "def456"],     // from figma_list_open_files
  code: `
    const detached = figma.currentPage.findAll(n => n.type === "INSTANCE" && !n.mainComponent);
    return { detachedCount: detached.length };
  `,
  timeout: 10000
})

// Every connected file — opt in explicitly.
figma_execute_across_files({
  allFiles: true,
  code: `return { pageCount: figma.root.children.length };`
})

• code (required): JavaScript to run in each targeted file. Same figma global as figma_execute.
• fileKeys (optional): Which connected files to target. Get them from figma_list_open_files.
• allFiles (optional, default false): Target every connected file.
• timeout (optional): Per-file timeout in ms (default: 10000, max: 30000). Applied independently per file — one unresponsive file doesn’t delay the rest.

{
  "results": {
    "abc123": {
      "fileName": "Design System — Core",
      "success": true,
      "result": { "detachedCount": 3 },
      "fileContext": { "fileName": "Design System — Core", "fileKey": "abc123" }
    },
    "def456": {
      "fileName": "Design System — Icons",
      "success": false,
      "error": "WebSocket command EXECUTE_CODE timed out after 10000ms"
    }
  },
  "totalTargeted": 2,
  "totalSucceeded": 1,
  "totalFailed": 1,
  "missingFileKeys": ["ghi789"]
}

• fileContext is reported by the plugin that actually ran the code — use it to confirm each result came from the file you addressed.
• missingFileKeys lists requested files that aren’t currently connected; the rest still run.
• The response is only marked as an error if every targeted file failed.

​

🔧 Variable Management Tools

⚠️ Requires Desktop Bridge Plugin: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using figma_pair_plugin to connect through the cloud relay.

​

figma_create_variable_collection

• Setting up a new design system
• Creating themed variable sets (colors, spacing, typography)
• Organizing variables into logical groups

figma_create_variable_collection({
  name: "Brand Colors",
  initialModeName: "Light",        // Optional: rename default mode
  additionalModes: ["Dark", "High Contrast"]  // Optional: add more modes
})

• name (required): Collection name
• initialModeName (optional): Name for the default mode (otherwise “Mode 1”)
• additionalModes (optional): Array of additional mode names to create

• Created collection with ID, name, modes, and mode IDs

​

figma_create_variable

• Adding design tokens to your system
• Creating colors, spacing values, text strings, or boolean flags
• Setting up multi-mode variable values

figma_create_variable({
  name: "colors/primary/500",
  collectionId: "VariableCollectionId:123:456",
  resolvedType: "COLOR",
  valuesByMode: {
    "1:0": "#3B82F6",    // Light mode
    "1:1": "#60A5FA"     // Dark mode
  },
  description: "Primary brand color",  // Optional
  scopes: ["ALL_FILLS"]                 // Optional
})

• name (required): Variable name (use / for grouping)
• collectionId (required): Target collection ID
• resolvedType (required): "COLOR", "FLOAT", "STRING", or "BOOLEAN"
• valuesByMode (optional): Object mapping mode IDs to values
• description (optional): Variable description
• scopes (optional): Where variable can be applied

• COLOR: Hex string "#FF0000" or "#FF0000FF" (with alpha)
• FLOAT: Number 16 or 1.5
• STRING: Text "Hello World"
• BOOLEAN: true or false

​

figma_update_variable

• Changing existing token values
• Updating theme-specific values
• Modifying design system tokens

figma_update_variable({
  variableId: "VariableID:123:456",
  modeId: "1:0",
  value: "#10B981"  // New color value
})

• variableId (required): Variable ID to update
• modeId (required): Mode ID to update value in
• value (required): New value (format depends on variable type)

​

figma_rename_variable

• Reorganizing variable naming conventions
• Fixing typos in variable names
• Moving variables to different groups

figma_rename_variable({
  variableId: "VariableID:123:456",
  newName: "colors/brand/primary"
})

• variableId (required): Variable ID to rename
• newName (required): New name (can include / for grouping)

​

figma_delete_variable

• Removing unused tokens
• Cleaning up design system
• Removing deprecated variables

figma_delete_variable({
  variableId: "VariableID:123:456"
})

​

figma_delete_variable_collection

• Removing entire token sets
• Cleaning up unused collections
• Resetting design system sections

figma_delete_variable_collection({
  collectionId: "VariableCollectionId:123:456"
})

​

figma_add_mode

• Adding theme variants (Dark mode, High Contrast)
• Adding responsive breakpoints (Mobile, Tablet, Desktop)
• Adding brand variants

figma_add_mode({
  collectionId: "VariableCollectionId:123:456",
  modeName: "Dark"
})

• collectionId (required): Collection to add mode to
• modeName (required): Name for the new mode

• Updated collection with new mode ID

​

figma_rename_mode

• Fixing mode names
• Updating naming conventions
• Making mode names more descriptive

figma_rename_mode({
  collectionId: "VariableCollectionId:123:456",
  modeId: "1:0",
  newName: "Light Theme"
})

• collectionId (required): Collection containing the mode
• modeId (required): Mode ID to rename
• newName (required): New name for the mode

​

figma_batch_create_variables

• Creating multiple design tokens at once (e.g., a full color palette)
• Importing variables from an external source
• Any time you need to create more than 2-3 variables

figma_batch_create_variables({
  collectionId: "VariableCollectionId:123:456",
  variables: [
    {
      name: "colors/primary/500",
      resolvedType: "COLOR",
      description: "Primary brand color",
      valuesByMode: { "1:0": "#3B82F6", "1:1": "#60A5FA" }
    },
    {
      name: "colors/primary/600",
      resolvedType: "COLOR",
      valuesByMode: { "1:0": "#2563EB", "1:1": "#3B82F6" }
    },
    {
      name: "spacing/md",
      resolvedType: "FLOAT",
      valuesByMode: { "1:0": 16 }
    }
  ]
})

• collectionId (required): Collection ID to create all variables in
• variables (required): Array of 1-100 variable definitions, each with:
  • name (required): Variable name (use / for grouping)
  • resolvedType (required): "COLOR", "FLOAT", "STRING", or "BOOLEAN"
  • description (optional): Variable description
  • valuesByMode (optional): Object mapping mode IDs to values

{
  "success": true,
  "message": "Batch created 3 variables (0 failed)",
  "created": 3,
  "failed": 0,
  "results": [
    { "success": true, "name": "colors/primary/500", "id": "VariableID:1:1" },
    { "success": true, "name": "colors/primary/600", "id": "VariableID:1:2" },
    { "success": true, "name": "spacing/md", "id": "VariableID:1:3" }
  ]
}

​

figma_batch_update_variables

• Updating many token values at once (e.g., theme refresh)
• Syncing variable values from an external source
• Any time you need to update more than 2-3 variables

figma_batch_update_variables({
  updates: [
    { variableId: "VariableID:1:1", modeId: "1:0", value: "#2563EB" },
    { variableId: "VariableID:1:2", modeId: "1:0", value: "#1D4ED8" },
    { variableId: "VariableID:1:3", modeId: "1:0", value: 20 }
  ]
})

• updates (required): Array of 1-100 updates, each with:
  • variableId (required): Variable ID to update
  • modeId (required): Mode ID to update value in
  • value (required): New value (COLOR: hex "#FF0000", FLOAT: number, STRING: text, BOOLEAN: true/false)

{
  "success": true,
  "message": "Batch updated 3 variables (0 failed)",
  "updated": 3,
  "failed": 0,
  "results": [
    { "success": true, "variableId": "VariableID:1:1", "name": "colors/primary/500" },
    { "success": true, "variableId": "VariableID:1:2", "name": "colors/primary/600" },
    { "success": true, "variableId": "VariableID:1:3", "name": "spacing/md" }
  ]
}

​

figma_setup_design_tokens

• Setting up a new design system from scratch
• Importing CSS custom properties or design tokens into Figma
• Creating themed token sets (Light/Dark) with all values at once
• Bootstrapping a new project with a full token foundation

figma_setup_design_tokens({
  collectionName: "Brand Tokens",
  modes: ["Light", "Dark"],
  tokens: [
    {
      name: "color/background",
      resolvedType: "COLOR",
      description: "Page background",
      values: { "Light": "#FFFFFF", "Dark": "#1A1A2E" }
    },
    {
      name: "color/text",
      resolvedType: "COLOR",
      values: { "Light": "#111827", "Dark": "#F9FAFB" }
    },
    {
      name: "spacing/page",
      resolvedType: "FLOAT",
      values: { "Light": 24, "Dark": 24 }
    },
    {
      name: "color/action/primary",
      resolvedType: "COLOR",
      // Alias values: DTCG brace references resolve to real variable aliases
      values: { "Light": "{color.background}", "Dark": "{color.background}" }
    }
  ]
})

• collectionName (required): Name for the new collection
• modes (required): Array of 1-4 mode names (first becomes default)
• tokens (required): Array of 1-100 token definitions, each with:
  • name (required): Token name (use / for grouping)
  • resolvedType (required): "COLOR", "FLOAT", "STRING", or "BOOLEAN"
  • description (optional): Token description
  • values (required): Object mapping mode names (not IDs) to values. A value can be a literal or a DTCG brace reference ("{color.blue.600}", set-qualified forms like "{primitives.color.blue.600}" too) — resolved via createVariableAlias against both variables created in the same call and variables that already exist in the file.

{
  "success": true,
  "message": "Created collection 'Brand Tokens' with 2 modes and 3 tokens (0 failed)",
  "collectionId": "VariableCollectionId:1:1",
  "collectionName": "Brand Tokens",
  "modes": { "Light": "1:0", "Dark": "1:1" },
  "created": 3,
  "failed": 0,
  "results": [
    { "success": true, "name": "color/background", "id": "VariableID:1:1" },
    { "success": true, "name": "color/text", "id": "VariableID:1:2" },
    { "success": true, "name": "spacing/page", "id": "VariableID:1:3" }
  ]
}

​

🧩 Component Tools

⚠️ Requires Desktop Bridge Plugin: These tools require the Desktop Bridge plugin running in Figma. In Local Mode, the plugin connects via WebSocket. In Cloud Mode, pair first using figma_pair_plugin to connect through the cloud relay.

​

figma_search_components

• Finding existing components to instantiate
• Discovering available UI building blocks
• Searching a published design system library from another file
• Checking if a component already exists before creating

// Search local file (existing behavior)
figma_search_components({
  query: "Button"
})

// Search a published library by file key
figma_search_components({
  query: "Button",
  libraryFileKey: "abc123XYZ"
})

// Search a published library by URL
figma_search_components({
  query: "Card",
  libraryFileUrl: "https://www.figma.com/design/abc123/My-Design-System"
})

• query (optional): Search term to match against component names or descriptions
• category (optional): Filter by category
• libraryFileKey (optional): File key of a published library for cross-file search
• libraryFileUrl (optional): URL of a published library file (alternative to libraryFileKey)
• limit (optional): Max results (default: 10, max: 25)
• offset (optional): Pagination offset

• Array of matching components with keys, names, variant info, and source (“local” or “library”)

​

figma_get_library_components

• Browsing all components in a published design system
• Getting component keys for instantiation from another file
• Auditing a library’s component inventory with variant detail

// By file key
figma_get_library_components({
  libraryFileKey: "abc123XYZ",
  query: "Button"
})

// By URL with full variant detail
figma_get_library_components({
  libraryFileUrl: "https://www.figma.com/design/abc123/My-Design-System",
  includeVariants: true,
  limit: 50
})

• libraryFileUrl (optional): URL of the library file
• libraryFileKey (optional): File key of the library file
• query (optional): Filter by component name or description
• limit (optional): Max results (default: 25, max: 100)
• offset (optional): Pagination offset
• includeVariants (optional): Include individual variant components (default: false)

• Component sets with variant counts and keys, standalone components, summary stats, and instantiation examples

1. Call figma_get_library_components with your design system file
2. Find the component you want and note its key
3. Call figma_instantiate_component with that componentKey — the component is imported from the published library automatically

​

figma_get_library_component_by_key

• You have a component key (40-char hex) from any search tool and want to inspect what properties / variants it exposes before instantiating
• You need each variant’s published key so figma_instantiate_component can target a specific one
• You want per-variant visual specs (fills, strokes, padding, typography) for code-generation fidelity

1. Tries Figma REST /v1/component_sets/{key} first (most common case — buttons, inputs, anything with variants)
2. On 404, falls back to /v1/components/{key} (standalone components)
3. Extracts file_key + node_id from the response
4. Fetches the node at depth=2 to read componentPropertyDefinitions and the variant subtree
5. For COMPONENT_SETs, also fetches the source file’s /components list in parallel so each variant child node can be mapped to its published variant key

// Resolve a component set by key
figma_get_library_component_by_key({
  componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197"
})

// Summary mode — properties and variant names only (no visual specs)
figma_get_library_component_by_key({
  componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197",
  format: "summary"
})

// Skip visual specs entirely (faster, smaller response)
figma_get_library_component_by_key({
  componentKey: "806826503bbd2ab15d0ff77d076a9406a5a83197",
  includeVisualSpecs: false
})

• componentKey (required): The 40-char hex component key from search results. Works for both COMPONENT_SET and standalone COMPONENT keys.
• includeVisualSpecs (optional, default true): Include per-variant fills/strokes/padding/typography. Auto-stripped if the response would exceed 500KB.
• format (optional, "full" | "summary", default "full"): summary omits per-variant visual specs. Auto-downgrades on large responses.

• resolvedAs: "COMPONENT_SET" or "COMPONENT"
• fileKey + nodeId: source file + node id
• name, description, thumbnail_url, containing_frame, user, created_at, updated_at
• properties: componentPropertyDefinitions (VARIANT / BOOLEAN / TEXT / INSTANCE_SWAP)
• variants[]: each with name, nodeId, key (the value to pass to figma_instantiate_component), and optional visualSpec
• visualSpec: root-level fills/strokes/effects/padding/typography
• bounds: width × height of the component set
• compression (only when stripped): { originalSizeKB, finalSizeKB, strippedVisualSpecs: true }
• warnings[]: non-fatal issues (e.g. variant-key resolution skipped)

​

figma_get_library_variables

• Inventory what design tokens (colors, spacing, typography sizes) are available from your subscribed libraries
• Find the key of a specific library variable so you can import it
• Build a design system overview that includes shared tokens (not just file-local ones)

// Everything subscribed
figma_get_library_variables()

// Filter by library name (case-insensitive substring)
figma_get_library_variables({ libraryName: "Northright" })

// Filter to only color tokens from a specific collection
figma_get_library_variables({
  libraryName: "Altitude",
  collectionName: "Colors",
  resolvedType: "COLOR"
})

• libraryName (optional): Case-insensitive substring filter on the source library’s name
• collectionName (optional): Case-insensitive substring filter on the collection name within a library
• resolvedType (optional, "COLOR" | "FLOAT" | "STRING" | "BOOLEAN"): Filter to a single token type. Auto-prunes empty collections after filtering.

• summary: { totalCollections, totalVariables }
• filters: echoed back so you can verify
• collections[]: [{ libraryName, collectionKey, collectionName, variableCount, variables: [{ key, name, resolvedType }] }]

​

figma_import_library_variable

• After figma_get_library_variables, you’ve picked a token and want to use it in the current file
• You’re building a composition that mixes file-local variables with library tokens

// Step 1: find the variable
const list = await figma_get_library_variables({
  libraryName: "Northright",
  resolvedType: "COLOR"
});

// Step 2: import it
const result = await figma_import_library_variable({
  variableKey: list.collections[0].variables[0].key
});

// Step 3: use the returned id to bind it to a node
await figma_set_fills({
  nodeId: "...",
  fills: [{ type: "SOLID", boundVariables: { color: { type: "VARIABLE_ALIAS", id: result.imported.id } } }]
});

• variableKey (required): The variable’s library key from figma_get_library_variables (the collections[].variables[].key field — distinct from the local id you’ll get back).

• imported: { id, key, name, resolvedType, description, variableCollectionId, remote }
• usage.bind: a hint string showing how to use the returned id with binding tools

• If the source library isn’t subscribed by the current file, returns a specific hint pointing to Figma > Assets panel > Libraries. The Plugin API rejects with a generic message; this tool detects the pattern and explains it.

​

figma_get_component_details

figma_get_component_details({
  componentKey: "abc123def456"  // Component key from search results
})

• componentKey (required): The component’s key identifier

• Full component details including properties, variants, and metadata

​

figma_instantiate_component

• Adding existing components to your design
• Building compositions from component library
• Creating layouts using design system components

figma_instantiate_component({
  componentKey: "abc123def456",
  x: 100,                        // X position
  y: 200,                        // Y position
  overrides: {                   // Property overrides
    "Button Label": "Click Me",
    "Show Icon": true
  }
})

• componentKey (required): Component key to instantiate
• x (optional): X position on canvas
• y (optional): Y position on canvas
• overrides (optional): Property overrides for the instance

• Created instance with node ID

​

figma_create_component_set

• Building a component’s full variant matrix (states × sizes × …) from a single base component
• Combining existing loose components into a proper component set
• Any time you’d otherwise script combineAsVariants by hand

1. Generate from a base component — pass baseComponentId + properties (the variant axes matrix). The base is cloned for every combination of the axes, each variant named Prop=Value comma-joined (e.g. State=hover, Size=sm), then combined into a set. The base component itself becomes the first variant (same node ID), so existing instances of the base survive as instances of that variant.
2. Combine existing components — pass componentIds, optionally with variantProperties (aligned 1:1 by index) to rename each component to Prop=Value form before combining. Property names and values must not contain = or ,. On any pre-combine failure, a unified rollback restores the components’ original names.

figma_create_component_set({
  baseComponentId: "123:456",
  properties: {
    State: ["default", "hover", "disabled"],
    Size: ["sm", "lg"]
  },                              // → 6 variants: State=default, Size=sm … State=disabled, Size=lg
  name: "Button",
  autoArrange: true               // labeled grid inside a white container
})

figma_create_component_set({
  componentIds: ["123:1", "123:2", "123:3"],
  variantProperties: [
    { State: "default" },
    { State: "hover" },
    { State: "disabled" }
  ],
  name: "Button"
})

• baseComponentId (optional): Node ID of an existing COMPONENT to use as the base. Mutually exclusive with componentIds.
• properties (required with baseComponentId): Variant property axes — { State: ["default", "hover"], Size: ["sm", "lg"] }. Max 100 combinations.
• componentIds (optional): Node IDs of existing COMPONENT nodes to combine. Components already inside a component set are rejected.
• variantProperties (optional, only with componentIds): One property map per component, aligned by index. Without it, existing names are kept (names lacking = become Property 1=<name>).
• name (optional): Name for the component set (defaults to Figma’s derived name)
• parentId (optional): Container frame/section to create the set in (defaults to current page)
• position (optional): { x, y } position within the parent
• autoArrange (optional, default false): Lay the new set out as a labeled grid (columns = last property, rows = other properties) inside a white container — same in-place layout as figma_arrange_component_set
• arrangeOptions (optional): gap, cellPadding, columnProperty — used when autoArrange is true

• The component set’s id, name, and key
• Each variant’s name, nodeId, and key — instantiate with a variant’s key via figma_instantiate_component, not the set’s key

​

figma_arrange_component_set

• After creating multiple component variants
• Organizing messy component sets
• Adding row/column labels to variant grids
• Getting the purple dashed border Figma styling

figma_arrange_component_set({
  componentSetId: "123:456",     // Component set to arrange
  options: {
    gap: 24,                     // Gap between cells
    cellPadding: 20,             // Padding inside cells
    columnProperty: "State"      // Property to use for columns
  }
})

• componentSetId (optional): ID of component set to arrange (uses selection if not provided)
• componentSetName (optional): Find component set by name
• options (optional): Layout options
  • gap: Gap between grid cells (default: 24)
  • cellPadding: Padding inside each cell (default: 20)
  • columnProperty: Property to use for columns (default: auto-detect, usually “State”)

• Arranged component set with:
  • White container frame with title
  • Row labels (vertically centered)
  • Column headers (horizontally centered)
  • Purple dashed border (Figma’s native styling)

┌─────────────────────────────────────────┐
│  Button                                 │
│         Default  Hover  Pressed  Disabled
│  ┌─────────────────────────────────────┐
│  │ Primary/Small  [btn] [btn] [btn] [btn]
│  │ Primary/Medium [btn] [btn] [btn] [btn]
│  │ Primary/Large  [btn] [btn] [btn] [btn]
│  │ Secondary/...  [btn] [btn] [btn] [btn]
│  └─────────────────────────────────────┘
└─────────────────────────────────────────┘

​

figma_create_slot

figma_create_slot({
  nodeId: "123:456",        // COMPONENT node (standalone OR a variant inside a set)
  name: "Content",          // optional slot layer name
  width: 320, height: 140,  // optional initial size (each independent)
  layoutMode: "VERTICAL"    // optional: NONE | HORIZONTAL | VERTICAL (GRID rejected by Figma)
})
// → { success, slot: { id, name, propertyKey, width, height, layoutMode } }

​

figma_get_slots

​

figma_append_to_slot

// Clone an existing node into the slot
figma_append_to_slot({
  instanceId: "123:789", slotName: "Content",  // or slotId directly
  sourceNodeId: "123:111",                     // node to clone (clone: false moves it)
  clearExisting: true                           // optional: replace current content
})

// Or create new content in place
figma_append_to_slot({
  instanceId: "123:789", slotName: "Content",
  nodeType: "TEXT",                            // FRAME | RECTANGLE | ELLIPSE | TEXT | LINE | POLYGON | STAR | VECTOR
  properties: { text: "Hello", name: "Label", width: 200, height: 24 }
})

​

figma_reset_slot

​

figma_add_slot_property

​

figma_set_description

• Documenting components for developers
• Adding usage guidelines
• Writing design system documentation

figma_set_description({
  nodeId: "123:456",
  description: "Primary action button. Use for main CTAs.\n\n**Variants:**\n- Size: Small, Medium, Large\n- State: Default, Hover, Pressed, Disabled"
})

• nodeId (required): Node ID of component/style to document
• description (required): Description text (supports markdown)

• Confirmation with updated node info

​

🔧 Node Manipulation Tools

​

figma_resize_node

figma_resize_node({
  nodeId: "123:456",
  width: 200,
  height: 100
})

​

figma_move_node

figma_move_node({
  nodeId: "123:456",
  x: 100,
  y: 200
})

​

figma_clone_node

figma_clone_node({
  nodeId: "123:456"
})

• New node ID of the clone

​

figma_delete_node

figma_delete_node({
  nodeId: "123:456"
})

​

figma_rename_node

figma_rename_node({
  nodeId: "123:456",
  newName: "Header Section"
})

​

figma_set_text

figma_set_text({
  nodeId: "123:456",
  characters: "Hello World"
})

​

figma_set_fills

figma_set_fills({
  nodeId: "123:456",
  fills: [{ type: "SOLID", color: "#FF0000" }]
})

​

figma_set_strokes

figma_set_strokes({
  nodeId: "123:456",
  strokes: [{ type: "SOLID", color: "#000000" }],
  strokeWeight: 2
})

​

figma_create_child

figma_create_child({
  parentId: "123:456",
  type: "FRAME",
  name: "New Frame"
})

​

🏷️ Component Property Tools

​

figma_add_component_property

figma_add_component_property({
  nodeId: "123:456",
  propertyName: "Show Icon",
  propertyType: "BOOLEAN",
  defaultValue: true
})

• nodeId (required): Component node ID
• propertyName (required): Name for the new property
• propertyType (required): "BOOLEAN", "TEXT", "INSTANCE_SWAP", or "VARIANT"
• defaultValue (required): Default value for the property

​

figma_edit_component_property

figma_edit_component_property({
  nodeId: "123:456",
  propertyName: "Label",
  newValue: {
    name: "Button Text",
    defaultValue: "Click me"
  }
})

​

figma_delete_component_property

figma_delete_component_property({
  nodeId: "123:456",
  propertyName: "Deprecated Prop"
})

​

📦 Design System Kit

​

figma_get_design_system_kit

​

figma_audit_design_system_report

// Bounded readable summary (default)
figma_audit_design_system_report({})

// Chunked drill-down: full findings for ONE category
figma_audit_design_system_report({ category: "accessibility" })

// Complete scored JSON (examples/locations clamped)
figma_audit_design_system_report({ format: "full" })

// Re-crawl after editing the file (results cache for ~5 minutes)
figma_audit_design_system_report({ forceRefresh: true })

• Component data is fetched live-first through the Desktop Bridge — one page per plugin roundtrip (30s cap each, failures isolated per page) — with the REST published-library endpoints as fallback. The chosen source is disclosed in the report (bridge-live / rest-published / none) because a published snapshot can be stale: scores from different sources are not comparable.
• The bridge crawl is fileKey-verified: if the plugin is connected to a different file than requested, the audit refuses the data and falls back to REST rather than silently scoring the wrong file.
• Raw audit data caches for 5 minutes, so a summary call plus per-category drill-downs cost one crawl.
• The default summary output stays bounded regardless of file size; use category for detail instead of format: "full" when working interactively.

// Full design system extraction
figma_get_design_system_kit({
  fileKey: "abc123def"
})

// Only tokens and components, with images
figma_get_design_system_kit({
  fileKey: "abc123def",
  include: ["tokens", "components"],
  includeImages: true
})

// Specific components only
figma_get_design_system_kit({
  fileKey: "abc123def",
  include: ["components"],
  componentIds: ["1:234", "5:678"]
})

// Compact format for large design systems
figma_get_design_system_kit({
  fileKey: "abc123def",
  format: "compact"
})

• full — Complete data with visual specs and resolved style values. Best for implementing specific components.
• summary — Strips variant-level visual specs (medium payload). Good for overview + a few deep-dives.
• compact — Only names, types, and property definitions. Best for large design systems or getting an inventory.

• tokens — Variables grouped by collection, with full mode support (light/dark/etc.)
• components — Published components with property definitions, variant specs, and visual specs (fills, strokes, effects, corner radius, layout, typography)
• styles — Color, text, and effect styles with resolved values
• ai_instruction — Guidance for the AI on how to use the extracted data
• errors — Any sections that failed to extract (partial results are still returned)

{
  "fileKey": "abc123",
  "fileName": "My Design System",
  "generatedAt": "2025-01-15T10:30:00Z",
  "format": "full",
  "tokens": {
    "collections": [{
      "name": "Colors",
      "modes": [{ "name": "Light" }, { "name": "Dark" }],
      "variables": [{
        "name": "primary",
        "type": "COLOR",
        "valuesByMode": {
          "Light": { "r": 0.26, "g": 0.46, "b": 1 },
          "Dark": { "r": 0.37, "g": 0.64, "b": 0.98 }
        }
      }]
    }],
    "summary": { "totalCollections": 3, "totalVariables": 45 }
  },
  "components": {
    "items": [{
      "name": "Button",
      "properties": { "variant": { "type": "VARIANT", "values": ["primary", "secondary"] } },
      "variants": [{ "name": "variant=primary", "id": "1:234" }],
      "visualSpec": {
        "fills": [{ "type": "SOLID", "color": "#4375FF" }],
        "cornerRadius": 8,
        "layout": { "mode": "HORIZONTAL", "paddingTop": 12, "paddingLeft": 24 }
      }
    }],
    "summary": { "totalComponents": 12, "totalComponentSets": 5 }
  },
  "styles": {
    "items": [{ "name": "Primary/Default", "styleType": "FILL", "resolvedValue": { "fills": [{ "color": "#4375FF" }] } }],
    "summary": { "totalStyles": 28 }
  }
}

​

📊 Design System Summary Tools

​

figma_get_design_system_summary

figma_get_design_system_summary()

• Component count and categories
• Variable collections and counts
• Style summary (colors, text, effects)
• Page structure overview

​

figma_get_token_values

figma_get_token_values({
  collectionName: "Brand Colors"  // Optional: filter by collection
})

• Variables organized by collection
• Values for each mode
• Variable metadata

​

AI Decision Guide: Which Tool to Use?

​

For Design System Extraction

Tip: Prefer figma_get_design_system_kit over calling figma_get_variables, figma_get_component, and figma_get_styles separately. It returns all three in a single optimized call with visual specs and resolved values.

​

For Design Creation

​

For Variable Management

​

For Design-Code Parity

​

Prerequisites Checklist

1. ✅ Running in Local Mode (NPX/Git)
2. ✅ Desktop Bridge plugin is running in your Figma file
3. ✅ figma_get_status returns setup.valid: true

1. ✅ Desktop Bridge plugin is running in your Figma file with Cloud Mode enabled
2. ✅ Paired via figma_pair_plugin (or natural language: “connect to my Figma plugin”)

​

🔍 Design-Code Parity Tools

​

figma_check_design_parity

• Before sign-off on a component implementation
• During design system audits to catch drift between design and code
• To verify that code accurately reflects the design spec

figma_check_design_parity({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '695:313',
  codeSpec: {
    visual: {
      backgroundColor: '#FFFFFF',
      borderColor: '#E4E4E7',
      borderRadius: 12,
      opacity: 1
    },
    spacing: {
      paddingTop: 24,
      paddingRight: 24,
      paddingBottom: 24,
      paddingLeft: 24,
      gap: 24
    },
    componentAPI: {
      props: [
        { name: 'className', type: 'string', required: false },
        { name: 'children', type: 'ReactNode', required: false }
      ]
    },
    metadata: {
      name: 'Card',
      filePath: 'src/components/card/card.tsx'
    }
  },
  canonicalSource: 'design',
  enrich: true
})

• fileUrl (optional): Figma file URL (uses current URL if omitted)
• nodeId (required): Component node ID
• codeSpec (required): Structured code-side data with sections:
  • visual: backgroundColor, borderColor, borderRadius, opacity, shadow, etc.
  • spacing: paddingTop/Right/Bottom/Left, gap, width, height, minWidth, maxWidth
  • typography: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color
  • tokens: usedTokens array, hardcodedValues array, tokenCoverage percentage
  • componentAPI: props array (name, type, required, defaultValue, description)
  • accessibility: role, ariaLabel, keyboardInteraction, focusManagement, contrastRatio
  • metadata: name, filePath, version, status, tags, description
• canonicalSource (optional): Which source is truth — "design" (default) or "code"
• enrich (optional): Enable token/enrichment analysis (default: true)

• summary: Total discrepancies, parity score (0-100), counts by severity (critical/major/minor/info), categories breakdown
• discrepancies: Array of property mismatches with category, severity, design value, code value, and suggestion
• actionItems: Structured fix instructions specifying which side to fix, which Figma tool or code change to apply
• designData: Raw Figma data extracted from the component (fills, strokes, spacing, properties)
• codeData: The codeSpec as provided
• ai_instruction: Structured presentation guide for consistent report formatting

​

figma_generate_component_doc

• Generating design system component documentation
• Creating developer handoff documentation
• Building a component reference library

figma_generate_component_doc({
  fileUrl: 'https://figma.com/design/abc123',
  nodeId: '695:313',
  codeInfo: {
    importStatement: "import { Button } from '@mylib/ui'",
    props: [
      { name: 'variant', type: "'primary' | 'secondary' | 'ghost'", required: false, defaultValue: "'primary'", description: 'Visual style variant' },
      { name: 'size', type: "'sm' | 'md' | 'lg'", required: false, defaultValue: "'md'", description: 'Button size' }
    ],
    events: [
      { name: 'onClick', payload: 'React.MouseEvent<HTMLButtonElement>', description: 'Fires when clicked' }
    ],
    usageExamples: [
      { title: 'Basic', code: '<Button>Click me</Button>' },
      { title: 'Destructive', code: '<Button variant="destructive"><Trash2 /> Delete</Button>' }
    ]
  },
  systemName: 'MyDesignSystem',
  includeFrontmatter: true,
  enrich: true
})

• fileUrl (optional): Figma file URL (uses current URL if omitted)
• nodeId (required): Component node ID
• codeInfo (optional): Code-side documentation info. Read the component source code first, then fill in relevant sections:
  • importStatement: Import path
  • filePath: Component file path
  • packageName: Package name
  • props: Array of prop definitions (name, type, required, defaultValue, description)
  • events: Array of event definitions (name, payload, description)
  • slots: Array of slot/sub-component definitions (name, description)
  • usageExamples: Array of code examples (title, code, language)
  • changelog: Version history entries (version, date, changes)
  • variantDefinition: CVA or variant definition code block (rendered in Implementation section)
  • subComponents: Array of composable sub-parts (name, description, element, dataSlot, props)
  • sourceFiles: Array of related files (path, role, variants, description) — used for Source Files table and Storybook link detection
  • baseComponent: Base component attribution (name, url, description) — e.g., “Built on shadcn/ui Alert”
• sections (optional): Toggle individual sections on/off (overview, statesAndVariants, visualSpecs, implementation, accessibility, changelog)
• outputPath (optional): Suggested file path for saving
• systemName (optional): Design system name for documentation headers
• enrich (optional): Enable enrichment analysis (default: true)
• includeFrontmatter (optional): Include YAML frontmatter metadata (default: true)
• history (optional): Pull an ongoing changelog instead of relying on hand-written codeInfo.changelog entries. Both sources are off by default, so existing callers are unaffected.
  • figma (default false): Walk Figma version history and diff each consecutive pair scoped to this component, producing one row per version that actually changed it
  • git (default false): Run git log for the component’s source files. Local mode only — the Cloudflare Worker runtime has no filesystem or git binary
  • versions (default 5, max 20): How many Figma versions to walk back
  • includeAutosaves (default false): Include unlabeled Figma auto-saves. Prefers labeled versions, but auto-falls back to auto-saves when a file has none (see below), so you rarely need to set this
  • mode (summary | standard | detailed, default standard): detailed names individual component properties and variable bindings instead of counting them
  • gitLimit (default 10, max 50): How many commits to list
  • gitPaths (optional): Explicit paths to log. Defaults to codeInfo.filePath plus every codeInfo.sourceFiles[].path
  • repoPath (optional): Repo directory to run git in. Defaults to the server’s working directory

• componentName: Resolved component name
• markdown: Complete markdown documentation with frontmatter, overview, states & variants, visual specs, implementation, accessibility sections
• includedSections: Which sections were generated
• dataSourceSummary: What data sources were available (Figma enriched, code info, variables, styles)
• historySummary: Present only when history was requested — per-source row counts, API calls made, resolved git paths, and any degradation notes
• suggestedOutputPath: Where to save the file
• ai_instruction: Guidance for the AI on next steps (saving file, asking user for path)

​

Component History (history)

figma_generate_component_doc({
  nodeId: '695:313',
  codeInfo: { filePath: 'src/components/Button/Button.tsx' },
  history: { figma: true, git: true, versions: 10, mode: 'detailed' }
})

## History

### Design history

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| v1.2 icon slot | 2026-03-01 | carol | Added 1 layer: `Icon`<br>Property `Disabled` added (BOOLEAN) |

### Code history

| Commit | Date | Author | Message |
|--------|------|--------|---------|
| `a1b2c3d` | 2026-03-02 | TJ | feat(button): add icon slot |

### Release notes

| Version | Date | Changes |
|---------|------|---------|
| 2.1.0 | 2026-03-05 | Icon slot support |

• Figma’s REST version snapshots omit description and Dev Mode annotation edits, raw layout/visual properties, and variable value changes. Structure (child layers), component property definitions, variable bindings, and renames are tracked, at depth 2
• Version-history retention is plan-dependent, so lower tiers expose a shorter window
• Reading version history requires the file_versions:read OAuth scope, or the Versions Read permission on a Personal Access Token. Without it the section degrades to an explanatory note rather than failing the doc
• git history uses --follow (renames traced) only when exactly one path is resolved — git supports it for a single pathspec only

​

💬 Comment Tools

​

figma_get_comments

• Reviewing feedback threads on a design file
• Checking for open comments before a release
• Retrieving comment IDs to reply to or delete

figma_get_comments({
  fileUrl: 'https://figma.com/design/abc123',
  include_resolved: false,
  as_md: true
})

• fileUrl (optional): Figma file URL (uses current URL if omitted)
• as_md (optional): Return comment message bodies as markdown (default: false)
• include_resolved (optional): Include resolved comment threads (default: false)

• comments: Array of comment objects with id, message, user, created_at, resolved_at, client_meta (pinned location)
• summary: Total, active, resolved, and returned counts

​

figma_post_comment

• After figma_check_design_parity to notify designers of drift
• Leaving feedback on specific components or elements
• Replying to an existing comment thread

// Pin a comment to a specific node
figma_post_comment({
  fileUrl: 'https://figma.com/design/abc123',
  message: 'Border-radius in code uses 8px but Figma shows 6px. Please update.',
  node_id: '695:313'
})

// Reply to an existing comment thread
figma_post_comment({
  fileUrl: 'https://figma.com/design/abc123',
  message: 'Fixed in the latest push.',
  reply_to_comment_id: '1627922741'
})

• fileUrl (optional): Figma file URL (uses current URL if omitted)
• message (required): The comment message text
• node_id (optional): Node ID to pin the comment to (e.g., '695:313')
• x (optional): X offset for comment placement relative to the node
• y (optional): Y offset for comment placement relative to the node
• reply_to_comment_id (optional): ID of an existing comment to reply to

• comment: Created comment object with id, message, created_at, user, client_meta

​

figma_delete_comment

• Cleaning up test or outdated comments
• Removing resolved feedback after fixes are confirmed
• Managing comment threads programmatically

figma_delete_comment({
  fileUrl: 'https://figma.com/design/abc123',
  comment_id: '1627922741'
})

• fileUrl (optional): Figma file URL (uses current URL if omitted)
• comment_id (required): The ID of the comment to delete (get IDs from figma_get_comments)

• success: Boolean indicating deletion success
• deleted_comment_id: The ID that was deleted

​

📝 Annotation Tools

​

figma_get_annotations

• Discovering designer specs on a component before implementation
• Reading animation timings, interaction behaviors, or accessibility requirements
• Getting all annotations across a component tree for documentation

// Read annotations from a component
figma_get_annotations({ nodeId: '695:313' })

// Read annotations from a component and all its children
figma_get_annotations({ nodeId: '695:313', include_children: true, depth: 3 })

• nodeId, nodeName, nodeType: The target node info
• annotations: Array of annotations with label, labelMarkdown, properties (pinned design properties), categoryId, categoryName
• annotationCount: Number of annotations on this node
• children: (when include_children=true) Array of child nodes with their annotations
• childAnnotationCount: Total annotations across children
• availableCategories: List of annotation categories in the file

​

figma_set_annotations

• Documenting animation timings and easing curves on components
• Adding accessibility requirements to design nodes
• Communicating implementation notes from design reviews
• Clearing outdated annotations after implementation is complete

// Write annotations with markdown and pinned properties
figma_set_annotations({
  nodeId: '695:313',
  annotations: [
    { label: 'Supports keyboard navigation via Tab and Enter' },
    {
      labelMarkdown: '**Animation:** Press uses `ease-out` with `150ms`',
      properties: [{ type: 'fills' }, { type: 'padding' }],
      categoryId: '1026:1'
    }
  ]
})

// Append to existing annotations
figma_set_annotations({
  nodeId: '695:313',
  annotations: [{ label: 'Min touch target: 44x44px' }],
  mode: 'append'
})

// Clear all annotations
figma_set_annotations({ nodeId: '695:313', annotations: [] })

• success: Boolean indicating write success
• nodeId: The target node ID
• nodeName: The node name
• annotationCount: Number of annotations after the operation
• mode: The write mode used

Note: Pinned properties must be valid for the node type. For example, cornerRadius works on COMPONENT nodes but not on COMPONENT_SET nodes. Use figma_get_annotation_categories to discover valid category IDs.

​

figma_get_annotation_categories

• Discovering available categories before creating annotations
• Listing category IDs for use with figma_set_annotations

figma_get_annotation_categories()
// Returns: { categories: [{ id: '1026:0' }, { id: '1026:1' }, ...] }

• categories: Array of { id, name } category objects

​

Annotations Workflow

​

🖼️ Image Tools