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

> Effortlessly search Figma design system libraries with search_design_system. Find existing components, variables, and styles to maximize reuse and prevent duplicates.

- Repository: [Figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)
- Tags: how-to-guide
- Published: 2026-03-30

---

**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`](https://github.com/figma/mcp-server-guide/blob/main/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:

```javascript
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`](https://github.com/figma/mcp-server-guide/blob/main/server.json)** – Registers the MCP endpoint (`https://mcp.figma.com/mcp`) and server metadata
- **[`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md)** – Primary prerequisite skill containing API rules and constraints
- **[`skills/figma-generate-library/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/SKILL.md)** – Orchestrates the design-system-builder workflow (Phases 0-4)
- **[`skills/figma-generate-library/references/discovery-phase.md`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/discovery-phase.md). This workflow ensures idempotency:

1. **Inspect** – Run [`inspectFileStructure.js`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/createVariableCollection.js) or [`createSemanticTokens.js`](https://github.com/figma/mcp-server-guide/blob/main/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:

```javascript
// 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:

```javascript
// 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:

```javascript
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`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/discovery-phase.md) | Phase 0 workflow and search strategy documentation |
| [`skills/figma-generate-library/references/component-creation.md`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/working-with-design-systems/wwds-variables--using.md) | Variable binding and alias patterns |
| [`skills/figma-generate-library/scripts/inspectFileStructure.js`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/scripts/inspectFileStructure.js) | Initial file snapshot script |
| [`skills/figma-generate-library/scripts/createVariableCollection.js`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/scripts/createVariableCollection.js) | Idempotent collection creation reference |
| [`skills/figma-generate-library/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/SKILL.md) | Master orchestration document for the design-system-builder skill |
| [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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.