How It Works

uSpec connects your AI agent and Figma into a single pipeline. You provide a component link and context, and the system produces formatted documentation directly in your Figma file.

The pipeline at a glance

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

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 the uSpec project is open in Cursor. Skills load from the .cursor/skills/ folder.

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.

Claude Code reads CLAUDE.md at the project root for context. Make sure you’re running from the uSpec directory.

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.

Codex reads AGENTS.md at the project root. Make sure you’re in the uSpec directory.

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 anatomy skill extracts child layers, element types, and property definitions, then classifies each element’s role before rendering numbered markers with an attribute table directly in Figma.The skill reads child layers, element types, visibility, and property definitions (booleans, variant axes, instance swaps) from the component. An AI classification step then determines each element’s role (optional slot, fixed sub-component, content element, structural/decorative) and writes semantic notes. Utility sub-components like Spacer and Divider are automatically skipped. Eligible nested instances get their own per-child sections with separate markers and tables, and cross-references link back from the composition table.

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 hover 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.

Getting Started

Spec Types

Resources

How It Works

The pipeline at a glance

Triggering a skill

Inside each skill

What the agent sees vs. what you provide

Architecture overview

Getting Started

Spec Types

Resources

​The pipeline at a glance

​Triggering a skill

​Inside each skill

​What the agent sees vs. what you provide

​Architecture overview

The pipeline at a glance

Triggering a skill

Inside each skill

What the agent sees vs. what you provide

Architecture overview