How It Works

uSpec connects your AI agent and Figma into a single pipeline. You provide a component link or a plugin capture, and the system produces either annotations rendered back into Figma or a single self-contained .md specification.

Two rendering paths

uSpec supports two paths from the same source component. Pick the one that matches where the documentation needs to live.

Figma-native path

Output is rendered as annotation frames next to the component in your Figma file. Best for design reviews, spec handoff inside Figma, and component libraries where the spec lives beside the component.

Component Markdown path

Output is a single .md file saved to disk. Best for feeding specs to any LLM (Cursor, Claude Design, GPT), committing alongside code, or diffing across design iterations.

Figma-native path

Every Figma-native skill extracts component data through the MCP and renders documentation directly in Figma. The internal steps differ depending on what each skill needs to analyze. The diagrams below show what happens inside each skill.

Component Markdown path

The plugin runs deterministic extraction inside Figma’s sandbox (no network calls), producing a _base.json that captures every variant, token binding, and sub-component. The create-component-md skill then runs four parallel interpretation agents (API, structure, color, voice), reconciles their outputs, and renders a single Markdown file. See the Component Markdown page for the full pipeline diagram.

Triggering a skill

Cursor
Claude Code
Codex

Skills are triggered by typing @ followed by the skill name in Cursor’s chat.

Type @

In Cursor’s chat, type @. Cursor shows an autocomplete menu of available skills.

Select a skill

Continue typing to filter (e.g., @create-v) or use arrow keys to select. The skill name must match exactly: @create-voice, not create voice or voice spec.

Add your prompt

After the skill name, paste a Figma link and add any context about states, variants, or behaviors.

If autocomplete doesn’t show the skill, verify your project is open in Cursor and that .cursor/skills/ is populated. If the directory is empty, run npx uspec-skills install --platform cursor from the project root.

Skills are triggered with /skill-name or by asking naturally — Claude auto-discovers skills from their description.

Invoke a skill

Type /create-voice to invoke directly, or just describe what you need (e.g., “create a screen reader spec”). Claude matches skills from .claude/skills/ by their description.

Add your Figma link

Paste the Figma component URL and describe the states, variants, or behaviors you want documented.

Skills live in .claude/skills/ under the project where you ran npx uspec-skills init. Make sure you launch claude from that directory so it can discover them.

Skills are triggered with $skill-name or matched implicitly from their description.

Invoke a skill

Type $ to mention a skill explicitly (e.g., $create-voice), or describe what you need and Codex matches skills from .agents/skills/ by their description frontmatter. Use /skills to browse available skills.

Add your Figma link

Paste the Figma component URL and describe the states, variants, or behaviors you want documented.

Skills live in .agents/skills/ under the project where you ran npx uspec-skills init. Make sure you launch Codex from that directory so it can discover them.

Inside each skill

Every skill loads an instruction file, reads platform-specific or domain-specific reference files, extracts data from Figma via MCP, runs through a checklist, and renders the output. The reference files determine what the agent knows about each domain.

The create-component-md orchestrator is the only skill that does not render into Figma. It consumes a plugin-produced _base.json, dispatches four interpretation specialists (one serial, three in parallel), reconciles typed disagreements, then renders a single .md file to disk.The API specialist runs first and solo because its output (the property dictionary) anchors the three downstream specialists on a shared property and state vocabulary. Structure, color, and voice then run in a single parallel batch so their contexts stay isolated and the parent orchestrator only holds the returned summaries. Reconciliation is typed and deterministic: each disagreement has a defined signature (conflicting child classification, mismatched axes, missing states), and only the matching specialist is re-dispatched. The integrity gate validates cache-file shapes, axis consistency, and the structure coverage matrix before the Markdown renderer runs.See the Component Markdown spec page for install, usage, and output details.

The property skill extracts variant axes, boolean toggles, variable modes, and child component properties, then renders visual exhibits with live instance previews directly in Figma.The skill reads componentPropertyDefinitions to discover all variant axes, boolean toggles, and instance swap properties. Variable mode collections (shape, density) are detected automatically. Child component properties are rendered in-context on parent instances.

The API skill loads its instruction file, identifies all configurable properties (including sub-component slots), and renders property tables with configuration examples directly in Figma.Transient states like hovered and pressed are excluded from the API. They are handled at runtime. Only persistent, configurable properties like isDisabled or isSelected become API entries.

The structure skill uses a two-tier architecture: deterministic scripts handle data extraction and rendering, while AI reasoning is focused on interpretation and planning.The AI’s reasoning budget is spent on interpretation — building the section plan, writing design-intent notes, and detecting anomalies — rather than data gathering. Deterministic scripts (~60% of the pipeline) handle extraction, cross-variant comparison, table rendering, and native Figma measurements. Values are reported as token references when bound to a variable (e.g., sizing-button-lg (56)) or as plain numbers when hardcoded.

The motion skill is unique: instead of extracting data from Figma, it reads pre-computed animation data exported from After Effects. The export-timeline.jsx script does the heavy lifting — pairing keyframes into segments, computing cubic-bezier easing curves, and filtering out static segments. The agent reads the segments directly and renders them as a timeline visualization in Figma.This is a two-step process: first run the export script in After Effects to get the JSON, then run the create-motion skill with that output. The JSON contains composition metadata (name, duration, fps, dimensions) and a flat array of layers, each with pre-computed segments containing timing, values, bar labels, and easing data. The agent computes only layout values (track width, pixels per millisecond) and passes everything else through to Figma.

What the agent sees vs. what you provide

The agent can extract structure, tokens, and styles from Figma automatically. But some information only exists in your head:

The agent can extract	You need to describe
Component layers and hierarchy	States not visible in the current frame
Design token names and values	Behavioral modes (fill vs. hug, truncation)
Variant axes and properties	Focus order preferences
Visual dimensions and spacing	Platform-specific interaction details
Styles and color values	Business logic or conditional rules

The more context you provide in your prompt, the more accurate the output. A one-line prompt works, but adding states, behaviors, and edge cases produces significantly better specs.

Architecture overview

uSpec supports two Figma MCP providers — choose the one that fits your setup:

Figma Console MCP (by Southleft) connects via a Desktop Bridge plugin running inside Figma Desktop, communicating over WebSocket. It exposes 59+ tools for design creation and variable management.
Native Figma MCP (by Figma) connects directly to Figma’s API with read and write access. No Desktop Bridge plugin required.

Both providers give the agent real-time access to component data, tokens, styles, and screenshots. Every skill renders through the MCP, regardless of which provider or host you use. See Getting Started for setup instructions.

MCP providers update their capabilities and setup instructions frequently. For the latest details, see the Figma Console MCP docs or the native Figma MCP docs.

Documentation Index

​Two rendering paths

Figma-native path

Component Markdown path

​Figma-native path

​Component Markdown path

​Triggering a skill

​Inside each skill

​What the agent sees vs. what you provide

​Architecture overview

Two rendering paths

Figma-native path

Component Markdown path

Triggering a skill

Inside each skill

What the agent sees vs. what you provide

Architecture overview