talk-to-figma-design

name	talk-to-figma-design
description	Parse Figma design prompt, enrich via MCP, explore codebase, generate design spec, and invoke brainstorming

talk-to-figma-design

Collect Figma design requirements, enrich them with live Figma data and codebase analysis, then hand off to the brainstorming pipeline for implementation planning.

Trigger

User invokes /talk-to-figma-design after pasting a markdown prompt exported from the figma-annotations VS Code extension.

Arguments (all optional):

• --channel <id> — override channel ID from prompt
• --collection "<name>" — process only the named collection's items
• <topic> — free text topic name for the spec file (default: derived from first frame name)

Prerequisites

• cursor-talk-to-figma MCP server running (bun socket on port 3055)
• Figma plugin active in the Figma file
• GitNexus index available in the current project (optional — skipped gracefully if missing)

Workflow

Follow these steps in order. Do NOT skip steps. Do NOT implement any code — this skill only collects, enriches, and generates a spec.

Step 1: Parse Prompt

1. Scan the conversation for the <!-- talk-to-figma-design --> marker
2. If no marker found, tell the user: "No Figma design prompt found. Export collections from the figma-annotations VS Code extension first using 'Export Collections as Prompt'."
3. Extract from the prompt:
   • Channel ID from the ## Connection section
   • Design frames with their nodeIds, names, types, dimensions, notes, and collection names
   • Code references with file paths, line ranges, language, code, notes, and collection names
4. If --channel argument provided, use it instead of the prompt's channel ID
5. If --collection argument provided, filter to only items from that collection

Step 2: Enrich from Figma MCP

Use the cursor-talk-to-figma MCP tools to gather detailed design data.

1. Connect: Call join_channel with the resolved channel ID
2. For each design frame nodeId:
   • Call get_node_info(nodeId) — capture children hierarchy, layout properties, auto-layout settings
   • Call scan_text_nodes(nodeId) — capture all text content within the frame
3. Global design data:
   • Call get_styles() — capture color tokens, typography, effects
   • Call get_local_components() — capture available component library

Error handling: If MCP connection fails (relay not running, wrong channel), warn the user and continue with the prompt data only. Note in the spec that enrichment was skipped.

Step 3: Explore Codebase with GitNexus

Use GitNexus to find existing components in the user's codebase that can be reused or adapted.

1. For each design frame:

   • Analyze the frame name + design notes + enriched children + text content
   • Infer what type of component this is: form, card, header, modal, list, table, etc.
   • Infer its function: authentication, product display, navigation, data entry, etc.
   • Call gitnexus_query with the inferred type and function:
     • e.g. gitnexus_query({query: "authentication form with email password"})
     • e.g. gitnexus_query({query: "product card with price image add to cart"})
     • e.g. gitnexus_query({query: "navigation header with logo menu items"})
   • If matches found, call gitnexus_context on the top match to understand its full interface

2. Global patterns:

   • Call gitnexus_query({query: "design system UI components shared"}) — find reusable patterns
   • Call gitnexus_query({query: "layout components page structure"}) — find layout patterns

3. Map results: For each design frame, record:

   • Existing component path (if match found)
   • Similarity assessment: "reuse as-is", "adapt/extend", or "create new"
   • Reusable hooks, utilities, or patterns discovered

Error handling: If GitNexus is not indexed in this project, skip this step entirely. Note in the spec that codebase exploration was skipped and recommend running npx gitnexus analyze first.

Step 4: Generate Design Spec

Write the spec to docs/figma-design-spec-YYYY-MM-DD-<topic>.md using this template:

# Design Spec: <topic>

## Overview
<Synthesized summary from all collections and enriched data.
What is being built? What screens/flows does it cover? What is the scope?>

## Design System

### Colors
<From get_styles — list color tokens with their values>

### Typography
<From get_styles — font families, sizes, weights>

### Components
<From get_local_components — reusable Figma components available>

## Screens / Frames

### <FrameName> (<nodeType>, <width>x<height>)
- **Node ID:** `<nodeId>`
- **Layout:** <auto-layout mode, padding, spacing from enriched data>
- **Children:** <hierarchy from get_node_info — list key elements>
- **Text Content:** <from scan_text_nodes — actual text values>
- **Design Notes:** <from original prompt notes>
- **Related Code:** <link to code refs from the same collection, if any>
- **Existing Match:** <from GitNexus — component path and assessment, or "new component needed">

## Code Context

### <file>:<lines>
<code snippet in fenced code block>
> <note from the prompt>

## Existing Components (from codebase)

### Matches Found
| Design Frame | Existing Component | Assessment |
|---|---|---|
| <frameName> | <component path> | reuse / adapt / new |

### Reusable Patterns
<List components, hooks, utilities, layouts that can be leveraged>

## Requirements
<Synthesize actionable requirements from:
 - Design notes (what the designer intended)
 - Enriched frame details (actual structure, text, layout)
 - Code context (existing implementation state)
 - Existing component analysis (what to reuse vs create)

Format as a numbered list of concrete, implementable requirements.>

Step 5: Invoke Brainstorming

After writing the spec file:

1. Tell the user: "Design spec generated at <path>. Now invoking brainstorming to refine requirements and plan implementation."
2. Invoke the /superpowers:brainstorming skill with the spec file as context
3. Brainstorming will:
   • Read the spec
   • Ask the user clarifying questions about design intent
   • Propose implementation approaches
   • Generate an approved design
   • Chain into /superpowers:writing-plans for implementation planning

Channel ID Resolution

Priority order:

1. --channel CLI argument (highest)
2. Channel ID from the ## Connection section of the parsed prompt
3. Ask the user to input a channel ID

Important Notes

• This skill does NOT write any implementation code
• This skill does NOT modify Figma — it only reads
• All MCP enrichment is optional — the skill degrades gracefully if Figma or GitNexus are unavailable
• The skill works in the context of the user's project (not the figma-annotations extension repo)