> ## 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 two rendering paths and the skill pipelines behind them 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. 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. 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 ```mermaid theme={null} flowchart LR A[You] -->|Figma link| B[Agent Skill] B -->|Extract + Render| C[Figma MCP] C -->|Documentation frame| D[Figma Output] ``` 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 ```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. *** ## 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, 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. 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. 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. 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. 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. ```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 --> MCP[Figma MCP] MCP --> Extract[Extract children, layers, and properties] Instruction --> Classify[Classify elements and enrich notes] Extract --> Classify Classify --> Import[Import and detach template] Import --> Composition[Render composition markers and table] Composition --> Children[Per-child sections for eligible instances] Children --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> MCP[Figma MCP] MCP --> Extract[Extract properties and variant axes] MCP --> Modes[Detect variable mode properties] MCP --> Children[Discover child component properties] Extract --> Normalize[Normalize coupled axes and booleans] Modes --> Normalize Children --> Normalize Normalize --> Import[Import and detach template] Import --> Render[Render exhibits with instance previews] Render --> Validate[Screenshot validation] ``` 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. ```mermaid theme={null} flowchart TB Skill[SKILL.md] --> Instruction[agent-api-instruction.md] Skill --> MCP[Figma MCP] Instruction --> Analyze[Analyze properties] MCP --> Props[Extract variant properties] MCP --> Booleans[Extract boolean properties] MCP --> Slots[Extract 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] Render --> Validate[Screenshot validation] ``` 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 --> MCP[Figma MCP] MCP --> Extract["Tier 1: Deterministic extraction"] Extract --> Dims[Dimensions, tokens, sub-components] Extract --> Compare[Cross-variant comparison] Dims --> Interpret["Tier 2: AI interpretation"] Compare --> Interpret Instruction --> Interpret Interpret --> Plan[Section plan, notes, anomaly detection] Plan --> Import[Import and detach template] Import --> Render["Tier 1: Deterministic render"] Render --> Validate[Screenshot validation] ``` 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 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 --> MCP[Figma MCP] Instruction --> Analyze[Analyze color usage] MCP --> Tokens[Extract design tokens] MCP --> Variables[Extract variable values] MCP --> Styles[Extract styles] Tokens --> Enrich[Boolean enrichment: enable hidden toggles] Variables --> Enrich Styles --> Enrich Enrich --> ClassifyAxes[Classify color-relevant axes] ClassifyAxes --> DetectModes[Detect 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] Render --> Validate[Screenshot validation] ``` The agent reads token names directly from Figma variables, so the output uses your actual token naming conventions rather than generic names. Hidden boolean toggles are enabled during extraction to capture 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 --> MCP[Figma MCP] MCP --> Extract[Extract component structure] Extract --> 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] Render --> Validate[Screenshot validation] ``` The merge analysis is the critical step. It determines 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 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 ```mermaid theme={null} flowchart TB subgraph Host["Agent Host (Cursor / Claude Code / Codex)"] direction TB Prompt[Your prompt] Skill[Agent skill + reference files] Agent[AI agent] Prompt --> 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 <-->|Component data, tokens, styles| MCP Agent -->|Render documentation| MCP MCP <-->|Read + write| File File --> Output ``` 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](/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).