---
name: add-icon-set
description: Organize a pasted icon set into the library as swappable components, deduplicate, rename with category paths, and optionally wire icons into existing library components (buttons, inputs, alerts, nav, etc.) as instance swap properties.
---

# Add Icon Set to Library

Integrate a user-provided icon set into the current library file as organized, swappable components.

## Running this with Claude and the Figma MCP

Written for Figma's built-in agent, adapted for Claude (Claude Code, Claude Desktop or claude.ai) connected to the official Figma MCP server.

- **Get the file.** If you don't have a Figma link, ask for one. The file key is the segment after `/design/`; a `node-id=1-2` parameter means node `1:2`.
- **Start a session.** Call `create_session` with the file key before any other Figma tool, and pass the returned session ID on every later call.
- **Read before writing.** `get_metadata` shows the structure and the user's current selection, `get_variable_defs` lists the variables on a node, `search_design_system` finds published components, variables and styles, and `get_screenshot` shows what's on the canvas.
- **Write with `use_figma`.** It runs Plugin API JavaScript in the file. Load the `figma-use` skill first (plus `figma-generate-library` when you create variables, styles or components) and list them in `skillNames`. Scripts use top-level `await` and `return` everything they create: nothing persists between calls, so pass node and variable IDs forward as string literals. Colors are 0–1, not 0–255. Switch pages with `await figma.setCurrentPageAsync(page)`, at most once per call; for multi-page work, run one call per page in parallel. `figma.notify()` isn't available.
- **Ask, then wait.** Wherever a step says to ask the user, ask in chat (in Claude Code, use the AskUserQuestion tool) and wait for the answer before building.
- **Clear helper fills.** `figma.createAutoLayout()` frames start with a white fill. Set `fills = []` on rows and wrappers that should be transparent, or they show up as white bars (most visibly in dark-mode previews).
- **Check the result.** After a build step, take one screenshot (`await node.screenshot()` inside `use_figma`, or `get_screenshot`) and fix only what's wrong.

## Step 1: Determine where the icons are

Ask the user how they'd like to provide the icons. Common options:

- **Already pasted onto a page** — Ask which page, or check if there's an "Icons" page with content.
- **A published library** — Find the icons with `search_design_system` and bring them in with `figma.importComponentByKeyAsync(key)`. The MCP can't copy nodes out of a file that isn't published as a library, so for a community file or other link, ask the user to paste the icons into this file instead.
- **SVGs dragged onto the canvas** — The raw vectors are already on the canvas and need to be converted to components.

If the user isn't sure, suggest they paste the icons onto an "Icons" page (create one if it doesn't exist) and re-invoke the skill.

## Step 2: Audit the pasted icons

Once icons are on the canvas, inspect them:

1. **Count and catalog** all icon nodes — note types (COMPONENT, FRAME, GROUP, VECTOR, INSTANCE, etc.)
2. **Check sizing consistency** — all icons should be the same size (typically 16×16, 20×20, or 24×24). Flag inconsistencies.
3. **Identify categories** — icons may be grouped inside named frames (e.g., "General (solid)", "Arrows (outline)"). Record each group and its style (solid/outline/other).
4. **Detect duplicates** — find frames with identical or near-identical icon names. Determine if duplicates are true copies (remove one) or solid/outline pairs (keep both, label correctly). To distinguish solid vs. outline, check whether child vectors primarily use fills (solid) or strokes (outline). Take screenshots (`get_screenshot`) to visually confirm ambiguous cases.
5. **Report findings** to the user: total icon count, categories found, duplicates detected, any sizing issues.

## Step 3: Convert to components (if needed)

If the icons are not already components (e.g., raw SVGs pasted as frames, groups, or vectors):

1. For each icon, create a component with the icon's contents.
2. Ensure consistent sizing — resize all to the most common size, or ask the user for a preferred size.
3. Place components back into their category frames.

## Step 4: Clean up and rename

1. **Merge near-duplicate frames** — if two frames for the same category exist and share most icons, merge unique icons from one into the other, then delete the duplicate.
2. **Remove true duplicate frames** — if two frames have 100% icon overlap and the same style, remove one.
3. **Rename all icon components** using the pattern:
   `Icons / {Category} / {Style} / {icon-name}`
   - Examples: `Icons / General / Solid / star`, `Icons / Arrows / Outline / arrow-left`
   - If a category has no solid/outline distinction (e.g., Brands), omit the style level: `Icons / Brands / github`
4. **Rename parent frames** to clean category names (e.g., "General Solid", "Arrows Outline").

## Step 5: Offer to wire icons into library components

After the icons are organized, scan the library file for existing component sets that could benefit from an icon instance swap property. Look across ALL pages for component sets — common candidates include:

- Buttons
- Inputs / text fields
- Alerts / toasts / banners
- Navigation bars / nav links
- Badges / tags
- Cards
- Menu items / list items
- Tabs
- Tooltips
- Any other component that could logically include an icon

For each candidate found:

1. Check if it already has an icon instance swap property — skip if so.
2. Present the user with the list of components that could benefit from icons.
3. Ask which ones they'd like to update.

For each component the user selects:

1. Pick a sensible default icon (e.g., a generic "star" or "placeholder" icon).
2. Add an `Icon` instance swap property to the component set.
3. Add a `Show icon` boolean property to toggle visibility.
4. Insert an icon instance into every variant at a logical position (typically before the text label).
5. Match the icon fill/stroke color to the text color in each variant so contrast is correct across all styles and states.
6. Take a screenshot to verify the result and show the user.

## Step 6: Summary

Report to the user:
- Total icons added and category breakdown
- Any duplicates removed
- Which components were updated with icon swap properties
- Remind them to publish the library to make the icons available in other files