uSpec Design System Documentation Tool

The extract-api skill is responsible for the interpretation half of the create-component-md pipeline for API data. It processes data to produce structured JSON representations of APIs.

Out of Scope

• Extracting data from Figma (except via the Step 3-delta escape hatch).
• Importing or detaching Figma templates.
• Rendering tables or previews within Figma.
• Visual validation screenshots and iterative fix loops.
• Re-reading uspecs.config.json (the orchestrator passes mcpProvider directly to the skill).

Troubleshooting Data Quality

If the produced JSON is missing properties, has incorrect ownership, or violates the schema, check the following:

1. Reasoning Errors: The logic in this skill or create-api may be flawed.
2. Source Data Errors: The _base.json provided by the uSpec Extract plugin may be incomplete. Note: You should fix the plugin's phase code rather than duplicating extraction logic within this skill.

The create-component-md orchestrator follows a strict set of operational invariants to ensure data integrity and batch-mode execution. Developers implementing or extending this workflow must adhere to these rules:

Data Integrity & Mutation

• Figma Writing: The uSpec Extract plugin is the only Figma-writer. All interpretation skills are read-only. Any script in an interpretation skill must be < 50 lines; larger scripts require widening the _base.json schema.
• _base.json Immutability: This file is immutable after the plugin finishes, with one exception: the orchestrator's Step 4.5 may rewrite _base.json._childComposition to override classifications and resolve ambiguousChildren[].
• Mutation Safety: All Figma mutations must occur on a temporary instance and must be followed by a .remove() call on all code paths. Component sets and shipped variants must never be mutated.
• Cache Files: The .uspec-cache/ directory is gitignored. Only the sibling .json contract and .md implementation guide should be version controlled.

Execution Model

• Batch Mode: The orchestrator runs in strict batch mode from Step 1 to Step 10. Never call AskQuestion or pause for user input. If data is missing, log a _deltaExtractions[] entry (for interpretation skills) or emit a row with provenance: "not-measured" (for structure) and continue.
• Parallelism: Do not run interpretation skills in parallel within the parent's context. Instead, run them as parallel subagents (one per specialist) after extract-api completes. Each subagent must hold its own _base.json + dictionary read and write to a distinct cache file.
• Skill Hierarchy: Never call a create-* skill from this orchestrator; they are designed for Figma rendering, whereas this orchestrator targets Markdown.

Error Handling & Recovery

• Interruption Recovery: If interrupted between Step 4 and Step 9, existing JSON cache files remain valid. Re-running any single phase is safe.
• Missing Content: If rendered .md is missing content, check the four domain JSONs, then _base.json. Gaps usually reside in an interpretation skill or _base.json rather than the renderer.

When documenting accessibility for components, follow these specific rules for complex scenarios:

• Merged Labels/Hints: If a label merges into an input, do NOT list it as a separate focus order entry. Instead, document it as a property on the input's platform table using accessibilityLabel (iOS), contentDescription (Android), or <label for> (Web).
• Live Regions: Do NOT include live regions in focusOrder as they are not focus stops. Document them using liveRegion or aria-live in the platform tables.
• Decorative Elements: Exclude decorative elements from both focusOrder and platform tables.
• SLOT Nodes: Treat a SLOT as a transparent wrapper (similar to an auto-layout FRAME). Focus stops are the children of the SLOT, not the SLOT itself. If a SLOT has a boolean visibility binding (componentPropertyReferences.visible), ensure the focus order accounts for children appearing/disappearing between states.
• Disabled States: If a component is in a disabled/non-focusable state, the focus stop count is 0. Remove it from the focus order entirely, but document the state's platform properties (e.g., .notEnabled trait, disabled(), or aria-disabled).
• Merged Parents with Breakout Children: If a container uses mergeDescendants but contains one independently interactive child, list only that interactive child as a focus stop.
• Ambiguous Merges: If platform behaviors differ (e.g., iOS merges parts but Web keeps them separate), document the superset in focusOrder and explain the differences in the guidelines.

The create-api skill consumes a specific Markdown structure produced by create-component-md. It does not perform extraction; it only renders what is already authored in the following sections:

• ## API Section: Contains the source of truth for the property contract.

  • General notes: A blockquote (> ...) immediately under the confidence header.
  • Properties table: A table with columns Property | Type | Values | Default | Notes.
  • Sub-component tables: Sections starting with ### {name} containing their own property tables.
  • Configuration examples: Sections starting with ### {name} containing a description and a fenced code block.
  • Referenced components: A ### Referenced components section containing #### {displayName} headers and tables mapping props passed to the child.

• render-meta block: A fenced JSON block between <!-- render-meta:start v=1 --> and <!-- render-meta:end --> containing:

  • component.compSetNodeId: The target for live previews.
  • propertyDefs: A dictionary mapping raw component-property keys (e.g., "clear button#10225:1") to their definitions.
  • booleanDefs[]: Definitions for boolean properties.
  • slotContents[]: Information for resolving configuration-example slot insertions.
  • fileKey and nodeId: For completion links.
  • sourceHash: For drift detection.

uSpec connects AI agents and Figma through a three-stage pipeline that transforms Figma component data into machine-readable contracts and human-readable documentation, which can then be rendered back into Figma as annotations.

The Pipeline Flow

1. Extraction: The uSpec Extract Figma plugin captures component data (variants, token bindings, etc.) and produces a _base.json file.
2. Compilation: The create-component-md tool processes _base.json to compile a canonical .json component contract and a concise .md Markdown guide.
3. Rendering: create-* render skills read the .md file and its associated render-meta to draw documentation frames (annotations) directly in Figma via the Figma MCP.

Key Artifacts

• Contract + Markdown: The canonical JSON serves as the machine source of truth for automation, while the Markdown provides context for people, LLMs, code reviews, and design iterations.
• Figma Annotations: Rendered frames placed next to components in Figma, ideal for design reviews and spec handoff.

flowchart LR
    Plugin["uSpec Extract plugin (Figma Community)"] -->|"_base.json"| C["create-component-md"]
    C -->|"canonical .json"| Contract["component contract"]
    Contract -->|"concise .md"| R["create-* render skills"]
    R -->|"annotation frames"| F["Figma"]

uSpec uses the Model Context Protocol (MCP) as the render channel to move data from an AI agent into Figma. You must choose one of two providers based on your environment:

1. Figma Console MCP (by Southleft):

   • Mechanism: Connects via a Desktop Bridge plugin running inside Figma Desktop using WebSockets.
   • Capabilities: Exposes 59+ tools for design creation and variable management.
   • Use case: Best for users utilizing the Desktop Bridge workflow.

2. Native Figma MCP (by Figma):

   • Mechanism: Connects directly to Figma's API.
   • Capabilities: Provides read and write access without requiring a Desktop Bridge plugin.
   • Use case: Best for direct API-based automation.

Regardless of the provider, the agent uses the .md file as the source of truth for component data, tokens, and styles, using the MCP primarily to render annotation frames and perform small whitelisted reads for verification.

When building the working evidence set, tokens must be resolved following a specific priority:

1. Style Name: If styleId resolves via styles.resolvedStyles[styleId].name.
2. Variable Name: If boundVariableId resolves via variables.resolvedVariables[boundVariableId], use codeSyntax (WEB preferred) or name.
3. Hard-coded: If neither is present, token is null (must be flagged in notes).

Composite Colors: When a node has multiple visible layers (e.g., a gradient or layered fill), a fill-composite entry is used to build compositeDetail. This includes a layers[] array containing:

• Solid: { type: 'solid', hex, token, blendMode, opacity }
• Gradient: { type: 'gradient', gradientType, angleDegrees, stops: [{ position, color, token }], blendMode, opacity }
• Image: { type: 'image', blendMode, opacity }

// Example resolved colorEntry shape
colorEntry = {
  element: "Button container fill",
  path: "/fills/0",
  property: "fill",
  hex: "#FFFFFF",
  token: "token.color.white",
  opacity: 100,
  subComponentName: "Button",
  compositeDetail: {
    styleName: "Linear Gradient",
    layers: [
      { type: 'solid', hex: '#FFFFFF', token: 'token.white', blendMode: 'normal', opacity: 100 },
      { type: 'gradient', gradientType: 'linear', angleDegrees: 90, stops: [...], blendMode: 'normal', opacity: 100 }
    ]
  }
}