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 — 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

Installation

Download from Releases (recommended)

1. Go to Releases
2. Download the .vsix file
3. Install in VS Code:

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

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

From Source

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

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 WebSocket relay.

# 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
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

<collection name="Login Flow">
  <design-frame node="LoginForm" type="COMPONENT" dimensions="320x480">
    <design-note node="EmailInput" type="COMPONENT" dimensions="280x44">Form validation logic</design-note>
  </design-frame>
  <code-annotation file="src/auth.ts" language="typescript" lines="42-51">
    <note>Handles OAuth redirect</note>
  </code-annotation>
</collection>

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

# 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:

# 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. 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 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 <!-- talk-to-figma-design --> 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 <id> — override channel ID
• --collection "<name>" — process only specific collection
• <topic> — 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

# 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 — MCP server + Figma plugin + WebSocket relay that this extension connects to
• Claude Code — AI coding assistant that can use the exported prompts and /talk-to-figma-design skill

License

MIT