How to Search Design System Libraries with `search_design_system` in Figma MCP

The search_design_system tool enables AI agents to query across all subscribed Figma design libraries for existing components, variables, and styles, ensuring maximum reuse and preventing duplicate token creation before any new assets are generated.

The Figma MCP Server Guide repository defines a complete workflow for AI-assisted design system management through the Figma MCP server. At its core, the search_design_system function serves as the discovery gateway that allows agents to locate reusable assets across linked libraries, forming the foundation of an idempotent, single-source-of-truth design system workflow.

What search_design_system Does and Why It Matters

Unlike standard Figma Plugin API calls, search_design_system operates across all subscribed design libraries that a file can access. According to the repository's README.md and skill documentation, this tool runs three parallel searches to locate:

• Components that match your query string
• Variables (design tokens) with matching names or metadata
• Styles including text, color, and effect styles

The tool returns keys and IDs that can be directly imported using importComponentByKeyAsync, importVariableByKeyAsync, or importStyleByKeyAsync. Because the MCP client cannot see remote library contents through normal Plugin API methods, search_design_system is the only safe mechanism to discover existing assets before creating duplicates.

The method signature requires specific parameters:

search_design_system({
  query: "button",           // Search string
  fileKey: figma.root.id,    // Current file identifier
  includeComponents: true,   // Search component libraries
  includeVariables: true,    // Search variable collections
  includeStyles: true        // Search style definitions
})

Repository Architecture and the Skill System

The Figma MCP Server Guide (figma/mcp-server-guide) organizes functionality into skills—markdown-driven instruction bundles that teach agents how to invoke MCP tools correctly. The architecture spans several critical areas:

• server.json – Registers the MCP endpoint (https://mcp.figma.com/mcp) and server metadata
• skills/figma-use/SKILL.md – Primary prerequisite skill containing API rules and constraints
• skills/figma-generate-library/SKILL.md – Orchestrates the design-system-builder workflow (Phases 0-4)
• skills/figma-generate-library/references/discovery-phase.md – Documents the search_design_system usage pattern
• skills/figma-generate-library/scripts/ – JavaScript helpers including inspectFileStructure.js

The skill system works hierarchically: figma-generate-library declares figma-use as a prerequisite, and when a tool is invoked, the agent passes skillNames (e.g., "figma-generate-library") so the server can log usage and apply the correct reference documentation.

The Phase 0 Discovery Workflow

The repository mandates a Phase 0 discovery step before any creation occurs, documented in skills/figma-generate-library/references/discovery-phase.md. This workflow ensures idempotency:

1. Inspect – Run inspectFileStructure.js to snapshot existing pages, components, and variable collections in the current file
2. Search – Call search_design_system for each required asset name
3. Import – If results exist, import using the appropriate import*ByKeyAsync method
4. Create – Only if no results return, proceed to creation scripts like createVariableCollection.js or createSemanticTokens.js

This pattern guarantees that your design system maintains a single source of truth across all linked libraries, preventing the token sprawl that occurs when multiple agents or users create similar assets independently.

Practical Code Examples for Searching and Importing

The repository provides production-ready patterns for common search_design_system use cases. These snippets are designed to be embedded directly into use_figma calls.

Searching for Components and Creating Instances

When you need to find and instantiate a component from a shared library:

// Search connected libraries for a "Button" component
const results = await search_design_system({
  query: "button",
  fileKey: figma.root.id,
  includeComponents: true,
});

// Import and instantiate if found
if (results.components?.length) {
  const componentKey = results.components[0].key; // Format: "1234:5678"
  const component = await figma.importComponentByKeyAsync(componentKey);
  
  // Place instance on canvas
  const instance = component.createInstance();
  figma.currentPage.appendChild(instance);
  instance.x = 100;
  instance.y = 100;
  
  return { createdNodeIds: [instance.id] };
}

return { createdNodeIds: [], note: "No matching button component found" };

Locating and Binding Color Variables

For applying semantic color tokens to new shapes:

// Search for a semantic color variable
const varResults = await search_design_system({
  query: "color/bg/primary",
  fileKey: figma.root.id,
  includeVariables: true,
});

if (varResults.variables?.length) {
  const varId = varResults.variables[0].id;
  const variable = await figma.variables.getVariableByIdAsync(varId);
  
  // Create shape and bind fill to variable
  const rect = figma.createRectangle();
  rect.resize(200, 40);
  rect.fills = [{
    type: "SOLID",
    color: { r: 0, g: 0, b: 0 },
    opacity: 1,
    blendMode: "NORMAL",
    visible: true,
    boundVariables: { color: { type: "VARIABLE_ALIAS", id: variable.id } }
  }];
  
  figma.currentPage.appendChild(rect);
  return { createdNodeIds: [rect.id] };
}

Finding and Applying Text Styles

To maintain typography consistency across generated screens:

const styleResults = await search_design_system({
  query: "heading",
  fileKey: figma.root.id,
  includeStyles: true,
});

if (styleResults.styles?.length) {
  const styleKey = styleResults.styles[0].key;
  const textStyle = await figma.importStyleByKeyAsync(styleKey);
  
  const txt = figma.createText();
  await figma.loadFontAsync(textStyle.fontName);
  txt.characters = "Welcome to the design system";
  txt.textStyleId = textStyle.id;
  
  figma.currentPage.appendChild(txt);
  txt.x = 100;
  txt.y = 300;
  
  return { createdNodeIds: [txt.id] };
}

Critical Files for Implementation

These specific files in the figma/mcp-server-guide repository contain the authoritative patterns for search_design_system usage:

File	Purpose
skills/figma-generate-library/references/discovery-phase.md	Phase 0 workflow and search strategy documentation
skills/figma-generate-library/references/component-creation.md	Component import patterns and decision matrices
skills/figma-use/references/working-with-design-systems/wwds-variables--using.md	Variable binding and alias patterns
skills/figma-generate-library/scripts/inspectFileStructure.js	Initial file snapshot script
skills/figma-generate-library/scripts/createVariableCollection.js	Idempotent collection creation reference
skills/figma-generate-library/SKILL.md	Master orchestration document for the design-system-builder skill
README.md	Central tool listing and search_design_system description (lines 47-60)

Summary

• search_design_system queries across all subscribed Figma libraries simultaneously for components, variables, and styles using the parameters query, fileKey, includeComponents, includeVariables, and includeStyles.
• The Phase 0 discovery workflow in skills/figma-generate-library mandates searching before creation to ensure idempotency and prevent duplicate tokens.
• Results provide keys compatible with importComponentByKeyAsync, importVariableByKeyAsync, and importStyleByKeyAsync for immediate use in the current file.
• The skill-based architecture requires loading figma-use or figma-generate-library skills before invoking the tool, with reference documentation stored in skills/figma-generate-library/references/.

Frequently Asked Questions

What parameters does search_design_system accept?

The tool accepts five key parameters: query (the search string), fileKey (the current file identifier, typically figma.root.id), and three boolean flags—includeComponents, includeVariables, and includeStyles—which control which asset types to search across linked libraries.

How does search_design_system prevent duplicate design tokens?

By running as Phase 0 discovery before any creation scripts, the tool checks all subscribed libraries for existing matches. If search_design_system returns results, the agent imports those assets rather than creating new ones, maintaining a single source of truth and avoiding the token sprawl that occurs when multiple agents create identical components independently.

Which skill should I load before using search_design_system?

Load the figma-generate-library skill, which automatically includes figma-use as a prerequisite. According to skills/figma-generate-library/SKILL.md, this skill orchestrates the complete design-system-builder workflow and ensures the agent has access to the correct reference documentation for the discovery phase.

Can I search for only specific asset types with search_design_system?

Yes. Set the boolean flags selectively—use includeComponents: true with includeVariables: false and includeStyles: false to search only for components, or enable only includeVariables when looking specifically for design tokens. This targeted approach improves search performance and result relevance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}