redongreen/uspec/extract-api

Extract API Data

Interpretation-only companion to create-api. This skill does not extract data from Figma. It reads {cachePath}/{componentSlug}-_base.json (produced by the uSpec Extract Figma plugin), applies the same reasoning layer as create-api, and writes the normalized ApiOverviewData JSON to disk for the create-component-md orchestrator to consume.

Quality contract: every reasoning step (context gathering from _base.json, override promotion pass, audit) mirrors create-api/SKILL.md. Any improvement to API-extraction quality must be made in both places.

Batch-mode contract. This skill MUST NOT call AskQuestion, prompt for confirmation, or pause for user input. On ambiguous evidence, emit the best-effort structured output (with _deltaExtractions[] logged if a delta fired). On missing evidence that cannot be resolved, abort with a single-line diagnostic pointing at the missing _base.json field. No mid-interpretation clarifications.

Invocation Contract

The orchestrator calls this skill with these inputs (already resolved — do NOT re-parse URLs or re-read uspecs.config.json):

• componentSlug — filename-safe slug
• cachePath — cache directory, typically .uspec-cache/{componentSlug}/
• optionalContext — free-form string from the user (may be "none")
• mcpProvider — figma-console or figma-mcp (only used if a Step 3-delta escape hatch fires)
• deltaAvailable — boolean derived from _base.json._meta.fileKey + nodeId. Plugin exports normally make this true; a separately-passed figmaLink is not required.
• evidenceApiPath — optional. Path to {cachePath}/{componentSlug}-evidence-api.json from uspec-skills component-md prepare. When present and _meta.baseSourceHash matches the staged _base.json, use data as the Step 3 working evidence set and skip rebuilding it from the full base file.

fileKey and nodeId are not pass-through parameters. Read them from {cachePath}/{componentSlug}-_base.json._meta.fileKey and _meta.nodeId at the start of Step 1 — _base.json is the single source of truth for them.

Output:

• Writes {cachePath}/{componentSlug}-api.json containing the full ApiOverviewData object.
• Writes {cachePath}/{componentSlug}-api-dictionary.json — a canonical vocabulary projected from the api.json, consumed by the downstream extract-structure, extract-color, and extract-voice specialists. See Step 7.5 and the ApiDictionary artifact section in api/agent-api-instruction.md.
• Returns a single-line summary to the orchestrator: "API extracted: N properties, M sub-components, K examples → {path} (+ dictionary at {dictionaryPath})".
• Never creates or mutates Figma nodes (not even during the delta escape hatch — delta is read-only).

MCP Adapter

This skill typically makes zero MCP calls — it reads _base.json from disk. The adapter table below applies only to the optional Step 3-delta escape hatch.

For figma-mcp delta scripts, always include the page-focus preamble immediately after getNodeByIdAsync:

let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);

Workflow

Task Progress:
- [ ] Step 1: Read instruction file
- [ ] Step 2: Load _base.json and optionalContext
- [ ] Step 3: Build working evidence set (from _base.json fields only)
- [ ] Step 3-delta: OPTIONAL — read-only Figma call if a fact is genuinely missing
- [ ] Step 4: Identify properties and sub-components (Override Promotion Pass)
- [ ] Step 5: Generate ApiOverviewData object
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache
- [ ] Step 7.5: Project `ApiDictionary` from the finalized data and write `{slug}-api-dictionary.json`
- [ ] Step 8: Return one-line summary

Step 1: Read Instructions

Read api/agent-api-instruction.md. This is the same instruction file used by create-api — it defines the ApiOverviewData schema, property classification rules, naming conventions, and audit checklists.

Rendering-only sections to skip

The shared instruction file describes both extraction and Figma rendering. This skill only performs interpretation — ignore guidance in the sections below. The data schema and audit checklists still apply.

• Any phrase like "passed directly into Figma template placeholders — no JSON output is needed" — inverted for this skill: we do output JSON to disk. Keep the schema; discard the "no JSON" framing.
• §Configuration Examples — prose about how `nestedOverrides`, `textOverrides`, and `slotInsertions` are applied via `setProperties()` or inserted into SLOT nodes — describes the rendering path. The fields themselves are part of ApiOverviewData and must still be populated.
• §Common Mistakes — bullets describing rendering-path failures (e.g., "preview will show an empty slot", "SKILL.md script handles the replacement automatically") — cautions for the rendering skill, not interpretation. Data-level mistakes in the same section still apply.

Note: Fields that look like rendering config but are part of the output schema (e.g., slotInsertions, textOverrides, nestedOverrides, variantProperties) must still be populated.

Step 2: Load _base.json

Read {cachePath}/{componentSlug}-_base.json with the Read tool. If the file is missing, or if any of the sections listed in Step 3 below are null / missing, abort with a clear diagnostic asking the user to re-run the uSpec Extract plugin.

The file schema is defined in figma-plugin/docs/base-json-schema.md. Familiarize yourself with the top-level keys:

• component — component name + is-set flag
• variantAxes — [{ name, options, defaultValue }]
• defaultVariant — { id, name, variantProperties }
• propertyDefinitions.rawDefs / booleans / instanceSwaps / slots
• variables.localCollections / resolvedVariables
• variants[] — per variant: dimensions, treeHierarchical, treeFlat, colorWalk, revealedTree
• ownershipHints[] — pre-built hints from the plugin
• _extractionNotes.warnings — surface to the user if any warnings are present

Also: absorb optionalContext from the orchestrator as authoritative user guidance.

Step 3: Build Working Evidence Set

Evidence fast path (preferred). When evidenceApiPath is provided, read it first. If the file exists, parses as JSON, has _meta.domain === "api", and _meta.baseSourceHash matches the hash recorded in {cachePath}/{componentSlug}-prepare-manifest.json (or recomputed from the staged base bytes), treat data as the completed Step 3 ComponentEvidence projection and proceed directly to Step 4. Still load {cachePath}/{componentSlug}-_base.json for Step 4 reasoning that needs fields outside the evidence slice (variant walks, revealed trees, etc.) — but do not re-derive the Step 3 table from scratch.

Populate the ComponentEvidence structure (defined in the instruction file) by reading only from _base.json when the fast path is unavailable. The mapping:

No Figma calls are needed for Step 3. Any field you cannot derive from the table above means either (a) the _base.json schema needs widening — file a note for a follow-up — or (b) you need a Step 3-delta extraction.

Step 3-delta (optional, read-only)

If during Step 4 you discover a fact that is genuinely missing from _base.json (e.g., a rare property description, a variable collection mode value not present in variables.resolvedVariables), you MAY issue a tiny figma_execute / use_figma call scoped to exactly that missing fact. Rules:

• Read-only. No createInstance, setProperties, appendChild, or remove. If you need mutation, file a bug against the uSpec Extract plugin instead.
• < 50 lines of JS. If your script is longer than 50 lines, the _base.json schema needs widening — do that instead of a large delta.
• Audit every call. Append one entry to data._deltaExtractions[] per delta script you run:

{
  "purpose": "<why the fact was missing from _base.json>",
  "script": "<first 200 chars of the script>",
  "byteCount": <returned bytes>,
  "timestamp": "<ISO 8601>"
}

An empty array (zero delta calls) is the expected default. Multiple entries across components signal pressure to widen the _base.json schema in the plugin; treat the escape hatch as a diagnostic channel, not a regular path.

When a needed delta cannot run, emit the complete unavailable shape: { purpose, script: null, byteCount: 0, timestamp, unavailable: "mcp-unavailable" }. Use "no-figma-target" only when _meta.fileKey or _meta.nodeId is genuinely absent.

Step 4: Identify Properties

Using the working evidence set from Step 3, identify:

A. Variant properties from variantAxes

• If a broad axis mixes transient and persistent states, decompose it into engineer-friendly API properties instead of copying the axis verbatim.
• Drop transient interaction visuals (hovered, pressed, focused) unless the component exposes them as persistent configuration.

B. Boolean toggles from booleanProps

• Separate simple modifiers (isDisabled, showBadge) from slot-selection booleans that should become enums with none.
• Check whether a child-level toggle actually changes the parent component contract. If it does, promote it to the parent API.

Mandatory: Override Promotion Pass

For each entry in composableChildren, walk every key in contextualOverrides and classify it: