> ## Documentation Index > Fetch the complete documentation index at: https://docs.uspec.design/llms.txt > Use this file to discover all available pages before exploring further. # How It Works > Understand the uSpec pipeline: extract a component, generate its Component Markdown spec, then render that spec into Figma uSpec connects your AI agent and Figma into a single pipeline. The **uSpec Extract** plugin captures a component, `create-component-md` turns that capture into a single self-contained `.md` specification, and the `create-*` skills render sections of that `.md` back into Figma as annotation frames. ## The pipeline ```mermaid theme={null} flowchart LR Plugin["uSpec Extract plugin (Figma Community)"] -->|"_base.json"| C["create-component-md"] C -->|"components/componentSlug.md"| R["create-* render skills"] R -->|"annotation frames"| F["Figma"] ``` Everything flows through the Component Markdown file. It is the required input for every `create-*` render skill — there is no longer a path that points a render skill straight at a raw Figma link. The source of truth, written to disk by `create-component-md`. Best for feeding specs to any LLM (Cursor, Claude Design, GPT), committing alongside code, or diffing across design iterations. 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: generate the `.md` ```mermaid theme={null} flowchart LR A[You] -->|"Select component"| Plugin[uSpec Extract Plugin] Plugin -->|"_base.json"| Skill[create-component-md] Skill -->|"Parallel specialists"| Cache[".uspec-cache/"] Cache -->|"Render"| MD["components/componentSlug.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 `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](/specs/component-md#how-it-works) for the full pipeline diagram. ### Stage 2: render into Figma ```mermaid theme={null} flowchart LR A[You] -->|"component .md"| B[Agent Skill] B -->|"Read .md + render-meta"| Plan[Plan annotations] Plan -->|"Render"| C[Figma MCP] C -->|"Documentation frame"| D[Figma Output] ``` 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 Skills are triggered by typing `@` followed by the skill name in Cursor's chat. In Cursor's chat, type `@`. Cursor shows an autocomplete menu of available skills. 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`. 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. 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. 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. 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. 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 (one serial, three in parallel), reconciles typed disagreements, then renders a single `.md` file to disk. ```mermaid theme={null} flowchart TB Pre["Steps 1-4.5 (preflight)"] --> API["Step 5: extract-api (parent, solo)"] API --> Dict[(api-dictionary.json)] Dict --> FanOut["Parallel fan-out (1 batch of 3 Task calls)"] FanOut -->|subagent| Struct[extract-structure] FanOut -->|subagent| Color[extract-color] FanOut -->|subagent| Voice[extract-voice] Struct --> Join Color --> Join Voice --> Join Join --> Recon["Step 8.5: Reconciliation (typed, deterministic)"] Recon -->|"typed gap + retries available"| SerialRetry["Re-dispatch ONE specialist
via Task (serial, not parallel)"] SerialRetry --> Recon Recon -->|"no gaps or budget exhausted"| Integ["Step 9.5: integrity"] Integ --> Render["Step 9: render .md"] ``` 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](/specs/component-md) 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-anatomy-instruction.md] Skill --> MD[component .md] MD --> Read[Read anatomy section + render-meta] Instruction --> Classify[Map elements to markers and notes] Read --> Classify Classify --> Import[Import and detach template] Import --> Composition[Render composition markers and table] Composition --> Children[Per-child sections for eligible instances] Children --> MCP[Figma MCP] MCP --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> MD[component .md] MD --> Props[Read properties and variant axes] MD --> Modes[Read variable mode properties] MD --> Children[Read child component properties] Props --> Normalize[Normalize coupled axes and booleans] Modes --> Normalize Children --> Normalize Normalize --> Import[Import and detach template] Import --> Render[Render exhibits with instance previews] Render --> MCP[Figma MCP] MCP --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-api-instruction.md] Skill --> MD[component .md] Instruction --> Analyze[Analyze properties] MD --> Props[Read variant properties] MD --> Booleans[Read boolean properties] MD --> Slots[Read sub-component slots] Props --> Analyze Booleans --> Analyze Slots --> Analyze Analyze --> Classify[Classify transient vs persistent] Classify --> MainTable[Generate main property table] Analyze --> SubTables[Generate sub-component tables] MainTable --> Examples[Generate configuration examples] SubTables --> Examples Examples --> Checklist[Audit against checklist] Checklist --> Render[Render in Figma via MCP] Render --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-structure-instruction.md] Skill --> MD[component .md] MD --> Read["Read structure section"] Read --> Dims[Dimensions, tokens, sub-components] Read --> Compare[Cross-variant deltas] Dims --> Interpret["AI interpretation"] Compare --> Interpret Instruction --> Interpret Interpret --> Plan[Section plan, notes, anomaly detection] Plan --> Import[Import and detach template] Import --> Render["Deterministic render via MCP"] Render --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-color-instruction.md] Skill --> MD[component .md] Instruction --> Analyze[Analyze color usage] MD --> Tokens[Read design tokens] MD --> Variables[Read variable values] MD --> Styles[Read styles] Tokens --> ClassifyAxes[Classify color-relevant axes] Variables --> ClassifyAxes Styles --> ClassifyAxes ClassifyAxes --> DetectModes[Read variable mode collections] DetectModes --> Strategy{Strategy A or B?} Strategy -->|"6 or fewer sections"| StratA[Strategy A: one section per variant] Strategy -->|"More than 6 sections"| StratB[Strategy B: states as columns] Analyze --> Strategy StratA --> Checklist[Audit against checklist] StratB --> Checklist Checklist --> Render[Render in Figma via MCP] Render --> Validate[Screenshot validation] ``` 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 screen reader skill loads four reference files, one for general instructions and one per platform, then runs a merge analysis to determine focus stops before rendering per-platform tables directly in Figma. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-screenreader-instruction.md] Skill --> VO[voiceover.md] Skill --> TB[talkback.md] Skill --> AR[aria.md] Instruction --> MD[component .md] MD --> Read[Read voice section + structure] Read --> Merge[Merge analysis] Merge --> Focus[Identify focus stops] VO --> Gen[Generate platform tables] TB --> Gen AR --> Gen Focus --> Gen Gen --> Checklist[Audit against checklist] Checklist --> Render[Render in Figma via MCP] Render --> Validate[Screenshot validation] ``` The voice section of the `.md` already records the focus order and merge analysis — which visual parts become independent focus stops and which get merged into a parent announcement. The three platform files provide the exact property names and announcement patterns for iOS, Android, and Web. 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. ```mermaid theme={null} flowchart TB AE[After Effects] -->|"Run export-timeline.jsx"| JSON[JSON on clipboard] JSON -->|Paste or file ref| Skill[SKILL.md] Skill --> Instruction[agent-motion-instruction.md] Skill --> MCP[Figma MCP] Instruction --> Parse[Parse and validate JSON] JSON --> Parse Parse --> Layout[Compute track width and tick spacing] Layout --> Import[Import and detach template] Import --> Ruler[Render time ruler] Ruler --> Timeline[Render timeline layers and bars] Timeline --> Table[Render detail table rows] Table --> Validate[Screenshot validation] ``` 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 ```mermaid theme={null} flowchart TB subgraph Host["Agent Host (Cursor / Claude Code / Codex)"] direction TB Prompt[Your prompt] MD[component .md] Skill[Agent skill + reference files] Agent[AI agent] Prompt --> Skill MD --> Skill Skill --> Agent end subgraph Figma["Figma"] direction TB File[Figma file] Output[Documentation frames] end subgraph MCP["Figma MCP"] direction TB Console["Console MCP + Desktop Bridge"] Native["Native Figma MCP"] end Agent -->|"Render documentation"| MCP Agent <-->|"Verify + small whitelisted reads"| MCP MCP <-->|Read + write| File File --> Output ``` 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](/getting-started#2-set-up-figma-mcp) for setup instructions. MCP providers update their capabilities and setup instructions frequently. For the latest details, see the [Figma Console MCP docs](https://docs.figma-console-mcp.southleft.com/) or the [native Figma MCP docs](https://github.com/figma/figma-mcp).