# Figma Annotations

> VS Code extension — annotate Figma designs alongside code, export structured prompts for AI-assisted implementation. Works with cursor-talk-to-figma MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-richardplg2-figma-annotations`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [richardplg2](https://agentstack.voostack.com/s/richardplg2)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [richardplg2](https://github.com/richardplg2)
- **Source:** https://github.com/richardplg2/figma-annotations

## Install

```sh
agentstack add mcp-richardplg2-figma-annotations
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Figma Annotations

Annotate and organize Figma design references directly in VS Code. Connect to Figma in real-time, capture design frames with notes, link them to code selections, and export structured prompts for AI-assisted implementation.

Built to work with [cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp) — the same WebSocket relay powers both this extension and the MCP server.

## Features

- **Real-time Figma connection** via WebSocket relay — select frames in Figma, load them into VS Code
- **Collections** — organize design frames and code annotations into named groups
- **Design frame viewer** — view cached Figma frames in a webview panel with node overlay
- **Code annotations** — select code in the editor, attach it to a collection with notes
- **Design notes** — annotate specific nodes within a design frame
- **XML export** — copy collections as structured XML for AI agents
- **Markdown prompt export** — multi-select collections, include channel ID and MCP tools reference for AI workflows
- **Claude Code skill** — `/talk-to-figma-design` enriches exported prompts via Figma MCP, explores your codebase, and generates a design spec

## Prerequisites

- **VS Code** >= 1.85.0
- **Node.js** >= 18
- **cursor-talk-to-figma-mcp** relay running — [setup guide](https://github.com/grab/cursor-talk-to-figma-mcp#getting-started)

## Installation

### Download from Releases (recommended)

1. Go to [Releases](https://github.com/richardplg2/figma-annotations/releases/latest)
2. Download the `.vsix` file
3. Install in VS Code:

```bash
code --install-extension figma-annotations-*.vsix
```

Or open VS Code > Extensions sidebar > `...` menu > **Install from VSIX...** > select the downloaded file.

### From Source

```bash
git clone https://github.com/richardplg2/figma-annotations.git
cd figma-annotations
npm install
npm run compile
```

Then press **F5** in VS Code to launch the extension in debug mode.

### Package as VSIX

```bash
npm install -g @vscode/vsce
vsce package
code --install-extension figma-annotations-0.0.1.vsix
```

## Setup

### 1. Start the WebSocket Relay

The extension communicates with Figma through the [cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp) WebSocket relay.

```bash
# Clone the MCP server
git clone https://github.com/grab/cursor-talk-to-figma-mcp.git
cd cursor-talk-to-figma-mcp

# Install and start the relay
bun install
bun socket
```

The relay runs on `ws://localhost:3055`.

### 2. Install the Figma Plugin

Install the **Cursor Talk To Figma** plugin in Figma:
1. Open Figma
2. Go to **Plugins > Manage plugins**
3. Search for "Cursor Talk To Figma" or install from the [Figma Community](https://www.figma.com/community/plugin/cursor-talk-to-figma)
4. Run the plugin — it will show a **channel ID**

### 3. Connect from VS Code

1. Open the **Figma Annotations** sidebar (bookmark icon in the activity bar)
2. Click the **plug icon** or run `Figma Annotations: Connect to Figma`
3. Enter the **channel ID** from the Figma plugin
4. Status bar shows `Figma: Connected` when ready

## Usage

### Collecting Design References

1. **Create a collection** — click `+` in the sidebar header
2. **Load Figma frames** — select frames in Figma, right-click a collection > "Load Figma Selection"
3. **Add code annotations** — select code in the editor, right-click > "Add Code to Collection"
4. **Add design notes** — open the Figma viewer, click nodes to add notes

### Exporting for AI

#### XML Export (single collection)
Right-click a collection > **Copy Collection as XML** or **Insert Collection to Claude Code**

```xml

  
    Form validation logic
  
  
    Handles OAuth redirect
  

```

#### Markdown Prompt Export (multiple collections)
Click the **export icon** in the sidebar header > select collections > enter channel ID > choose clipboard or terminal.

The markdown prompt includes:
- Figma connection info (channel ID, relay URL)
- All design frames with node IDs and notes
- All code references with snippets
- MCP tools reference guide
- Instructions for the `/talk-to-figma-design` skill

### Claude Code Skill: `/talk-to-figma-design`

This repo ships a Claude Code skill that turns exported prompts into enriched design specs.

#### Install the Skill

```bash
# Clone this repo (if you haven't already)
git clone https://github.com/richardplg2/figma-annotations.git
cd figma-annotations

# Option 1: Install globally (available in all projects)
./install-skill.sh --global

# Option 2: Install into a specific project
./install-skill.sh --project /path/to/your-project

# Option 3: Install into current directory
./install-skill.sh --project .
```

This copies `skills/talk-to-figma-design/` into the appropriate `.claude/skills/` directory.

#### Manual Install

If you prefer, copy the skill directory manually:

```bash
# Global install
cp -r skills/talk-to-figma-design ~/.claude/skills/

# Project install
cp -r skills/talk-to-figma-design /path/to/your-project/.claude/skills/
```

#### Prerequisites for the Skill

The skill uses MCP tools from [cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp). Make sure:

1. The MCP server is configured in your Claude Code settings (`.mcp.json` or Claude Code MCP config)
2. The WebSocket relay is running (`bun socket` on port 3055)
3. The Figma plugin is active with a channel ID

Optional: [GitNexus](https://github.com/nicholasgriffintn/gitnexus) for codebase exploration (the skill degrades gracefully without it).

#### Usage

After exporting the markdown prompt from the VS Code extension into Claude Code, invoke:

```
/talk-to-figma-design
```

The skill will:
1. **Parse** the exported prompt (detect `` marker)
2. **Enrich** via Figma MCP — `get_node_info`, `scan_text_nodes`, `get_styles` for each frame
3. **Explore** the codebase via GitNexus — find existing components that match the design
4. **Generate** a design spec file with requirements, existing component matches, and design tokens
5. **Invoke** `/superpowers:brainstorming` to refine requirements and plan implementation

Optional arguments:
- `--channel ` — override channel ID
- `--collection ""` — process only specific collection
- `` — name for the spec file

## Commands

| Command | Description |
|---------|-------------|
| `Figma Annotations: Create Collection` | Create a new named collection |
| `Figma Annotations: Connect to Figma` | Connect to relay with channel ID |
| `Figma Annotations: Load Figma Selection` | Import selected frames into collection |
| `Figma Annotations: Add Code to Collection` | Add editor selection as annotation |
| `Figma Annotations: Copy Collection as XML` | Copy single collection as XML |
| `Figma Annotations: Insert Collection to Claude Code` | Insert XML into terminal |
| `Figma Annotations: Export Collections as Prompt` | Multi-select markdown export |
| `Figma Annotations: Open Figma Viewer` | View design frame in webview |
| `Figma Annotations: Edit Note` | Edit annotation note |
| `Figma Annotations: Reload Design Frame` | Re-fetch frame from Figma |

## Data Storage

Annotations are stored in `.annotations.json` at the workspace root. This file is auto-created and should be added to `.gitignore` (it contains cached image data).

## Development

```bash
# Install dependencies
npm install

# Compile (type-check + bundle)
npm run compile

# Watch mode (auto-rebuild)
npm run watch

# Debug in VS Code
# Press F5 — launches Extension Development Host
```

### Project Structure

```
src/
  extension.ts          — Entry point, all command registrations
  types.ts              — TypeScript interfaces and data models
  storageService.ts     — File I/O for .annotations.json
  collectionProvider.ts — VS Code TreeView provider
  figmaService.ts       — WebSocket client for Figma relay
  figmaViewerPanel.ts   — Webview panel for design viewer
  rangeResolver.ts      — Code range tracking and relocation
  xmlFormatter.ts       — XML serialization
  markdownFormatter.ts  — Markdown prompt formatting
  webview/viewer.html   — Figma viewer webview
```

## Related Projects

- [cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp) — MCP server + Figma plugin + WebSocket relay that this extension connects to
- [Claude Code](https://claude.ai/claude-code) — AI coding assistant that can use the exported prompts and `/talk-to-figma-design` skill

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [richardplg2](https://github.com/richardplg2)
- **Source:** [richardplg2/figma-annotations](https://github.com/richardplg2/figma-annotations)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-richardplg2-figma-annotations
- Seller: https://agentstack.voostack.com/s/richardplg2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.