How It Works

uSpec connects your AI agent and Figma into a single pipeline. The uSpec Extract plugin captures a component, create-component-md compiles that evidence into canonical .json and concise .md artifacts, and the create-* skills render sections of the Markdown back into Figma.

The pipeline

The JSON contract is the machine source of truth. Its concise Markdown view is the required input for every create-* render skill—there is no path that points a render skill straight at a raw Figma link.

Contract + Markdown

Canonical JSON for automation and concise Markdown for people, LLM context, code review, and design iteration.

Figma annotations

Annotation frames rendered next to the component by the create-* skills, drawn from the .md. Best for design reviews, spec handoff inside Figma, and component libraries where the spec lives beside the component.

Stage 1: compile the contract and `.md`

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 public Community build asks for the component link on first use and remembers it for that document. create-component-md prepares compact evidence, interprets four domains, validates obligation coverage, reconciles disagreements, compiles the canonical JSON, and renders the concise Markdown. See the Component Markdown page for the full pipeline.

Stage 2: render into Figma

Every create-* skill reads its section from the component .md — plus the render-meta that maps each section to Figma node ids — then renders documentation directly in Figma through the MCP. They do not re-extract the component over MCP; any live read is a small, whitelisted verification or measurement delta. The internal steps differ depending on what each skill renders. 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, pass the component .md (e.g. ./components/button.md) and add any context the spec can’t carry: which Figma node to render next to, or behaviors and edge cases.

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.

Pass the component .md

Point the skill at the component .md and describe the states, variants, behaviors, or render destination 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.

Pass the component .md

Point the skill at the component .md and describe the states, variants, behaviors, or render destination 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 render skill loads an instruction file, reads platform-specific or domain-specific reference files, reads its section from the component .md (plus the render-meta node ids), runs through a checklist, and renders the output via the MCP. Any live Figma read is a small, whitelisted verification or measurement delta — not a re-extraction. The reference files determine what the agent knows about each domain. (create-component-md, the stage-1 generator, is the exception: it reads a plugin _base.json rather than a .md.)

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, validates their evidence obligations, reconciles typed disagreements, compiles canonical JSON, and renders concise Markdown.The API specialist runs first because its property dictionary anchors the downstream specialists on a shared vocabulary. Structure, Color, and Voice then run in parallel. Validation requires every prepared obligation and semantic row to resolve to supported evidence. Reconciliation re-dispatches only the specialist that owns a typed mismatch. Contract compilation and Markdown assembly are deterministic after the semantic render plan is written.See the Component Markdown spec page for install, usage, and output details.

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 .md. The .md already records each element’s role (optional slot, fixed sub-component, content element, structural/decorative) and semantic notes from the create-component-md run, so the skill maps those onto markers rather than re-classifying. 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 the API and properties sections of the .md to recover all variant axes, boolean toggles, and instance swap properties. Variable mode collections (shape, density) are already resolved in the .md. Child component properties are rendered in-context on parent instances using live instances placed via the MCP.

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.The API section of the .md already lists every variant property, boolean toggle, and sub-component slot. 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 structure section of the .md already carries the dimensions, token references, sub-component walks, and cross-variant deltas (measured deterministically during the create-component-md run). The skill’s reasoning budget is spent on interpretation — building the section plan, writing design-intent notes, and detecting anomalies — rather than data gathering. Values are reported as token references when bound to a variable (e.g., sizing-button-lg (56)) or as plain numbers when hardcoded.

The color skill loads a single instruction file, then extracts design tokens and variable values from Figma, classifies which axes and modes affect color, chooses a rendering strategy, and renders the annotation directly in Figma.The color section of the .md records per-element token mappings using your actual token naming conventions rather than generic names. Because create-component-md enables hidden boolean toggles during extraction, the .md already captures color bindings that only appear when optional elements are visible. The strategy decision determines the output layout: Strategy A renders one section per variant for simpler components, while Strategy B uses states as table columns for components with many variant combinations.

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 pipeline captures vs. what you provide

The uSpec Extract plugin and create-component-md capture structure, tokens, and styles into the .md automatically. But some information only exists in your head — add it in the plugin’s design-intent field or in your prompt:

The pipeline captures	You need to describe
Component layers and hierarchy	States not visible in the captured variants
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 when generating the .md, the more accurate every downstream render is. A one-line prompt works, but adding states, behaviors, and edge cases produces significantly better specs.

Architecture overview

The component data, tokens, and styles a render skill needs come from the .md — not a live MCP extraction. The MCP is the render channel back into Figma, plus the occasional small whitelisted read for verification or a measurement delta. 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 let the agent render annotation frames into Figma and capture screenshots for validation. Every render skill draws 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

Out of Figma

In Figma

Resources

How It Works

The pipeline

Contract + Markdown

Figma annotations

Stage 1: compile the contract and `.md`

Stage 2: render into Figma

Triggering a skill

Inside each skill

What the pipeline captures vs. what you provide

Architecture overview

​The pipeline

Contract + Markdown

Figma annotations

​Stage 1: compile the contract and .md

​Stage 2: render into Figma

​Triggering a skill

​Inside each skill

​What the pipeline captures vs. what you provide

​Architecture overview

The pipeline

Stage 1: compile the contract and `.md`

Stage 2: render into Figma

Triggering a skill

Inside each skill

What the pipeline captures vs. what you provide

Architecture overview