redongreen/uspec/create-api

Create API Overview

Generate an API overview directly in Figma — property tables with values, defaults, required status, sub-component tables, and configuration examples.

Execution contract (read first).

• This file is instructions to RUN, not a document to edit. Invoking the skill = render the API overview into Figma from the input .md.
• Never edit this SKILL.md or any other skill file in response, even if one is open or focused in the editor. Modify a skill only when the user explicitly asks to change the skill itself.
• The input component .md is a READ-ONLY source of truth. Never edit, append to, or "add a section" to it. The only artifact this skill produces is the Figma annotation. When the user asks to "create/add a section," "show," or "include" something, render it in the Figma annotation, never as an edit to the .md.
• Never call AskQuestion, request confirmation, or pause for input (including before Figma writes, the expected output). On ambiguity, pick the most defensible option and continue.
• Only two legal stops: (a) Step 0 fail-fast when no .md resolves; (b) one-line abort if the Figma MCP connection is dead.

MCP Adapter

Read uspecs.config.json → mcpProvider. Follow the matching column for every MCP call in this skill.

`figma-mcp` requires `fileKey` on every call. Extract it once from the user's Figma URL at the start of the workflow. For branch URLs (figma.com/design/:fileKey/branch/:branchKey/:fileName), use :branchKey as the fileKey.

`figma-mcp` page context: use_figma resets figma.currentPage to the first page on every call. When a script accesses a node from a previous step via getNodeByIdAsync(ID), the page content may not be loaded — findAll, findOne, and characters will fail with TypeError until the page is activated. Insert this page-loading block immediately after getNodeByIdAsync:

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

This walks up to the PAGE ancestor and loads its content. Console MCP does not need this — figma_execute inherits the Desktop page context.

Inputs Expected

• Component `.md` spec (required, user-provided path) — the source-of-truth component spec produced by {{skill:create-component-md}}. The user tells you where this `.md` lives — use the exact path they provide; the .md may live anywhere. This skill renders the API section from the `.md`; it does NOT re-extract anything from Figma and does NOT re-identify properties. fileKey, nodeId, and compSetNodeId come from the .md's render-meta block.
• Figma link (optional) — placement hint only (where to drop the rendered frame on the canvas) and the target for the single whitelisted TEXT-node listing in Step 5. Never the source of structural facts or the property contract.

There is no screenshot-only path. Without the component .md there is nothing to render — see Step 0's fail-fast contract.

Workflow

Copy this checklist and update as you progress:

Task Progress:
- [ ] Step 0: Require + parse the component `.md` (API body + render-meta). FAIL FAST if missing.
- [ ] Step 1: Read instruction file (only as needed for example-projection / isSubProperty prose — NOT for re-identifying the API)
- [ ] Step 2: Verify MCP connection
- [ ] Step 3: Read template key from uspecs.config.json
- [ ] Step 4: Build render inputs from the parsed .md (main table, sub-component tables, config examples, referenced components) — NO extraction
- [ ] Step 5: Re-derive light values (required, isSubProperty, example→raw-key projection, slot insertions) + the ONE whitelisted TEXT-node listing for preview text overrides
- [ ] Step 6: (folded into Step 4 — the property/sub-component tables are ALREADY authored in the .md)
- [ ] Step 7: Audit the assembled render inputs against the .md
- [ ] Step 8: Import and detach the API template
- [ ] Step 9: Fill header fields
- [ ] Step 10: Fill main API table
- [ ] Step 11: Fill sub-component tables (if any)
- [ ] Step 12: Fill configuration examples
- [ ] Step 13: Visual validation

Step 0: Require and parse the component .md (fail fast)

This skill is a consumer of the `.md` source of truth. It does not re-extract from Figma and does not re-run the property-identification reasoning layer — that work already happened in extract-api/create-component-md and is baked into the .md's API section (Properties table, sub-component tables, configuration examples, referenced-components tables). Your job is to render that section into a Figma frame.

1. Resolve the `.md` path. Use the exact path the user gave, else an attached or open .md in context. The .md may live anywhere; do NOT invent or guess a path. If neither resolves to an existing file, abort per item 2. Never pause to ask the user which file to use.
2. Require the file. If no file exists at the resolved .md path, abort immediately with this exact single-line diagnostic and stop — do NOT fall back to extraction:

> This skill requires the component's Markdown .md spec (produced by create-component-md). Provide the path to it. (create-component-md needs a _base.json from the uSpec Extract plugin.)

1. Parse the API section body (## API) from the .md. Copy these verbatim — they are already authored, do not re-derive them:

• General notes — the blockquote (> …) immediately under the confidence header, if present → GENERAL_NOTES.
• Properties table — the table with columns Property | Type | Values | Default | Notes → the main table rows. Each row carries property (the Property cell), values (the Values cell, pipe-joined verbatim), default (the Default cell), and notes (the Notes cell).
• Sub-component tables — each ### {name} sub-section (with optional description) whose body is a Property | Type | Values | Default | Notes table → one sub-component entry { name, description, properties: [...] }.
• Configuration examples — each ### {name} sub-section consisting of a description paragraph + a fenced code block → one example entry { name, description, code }. The fenced block is the example.code string; keep it intact for the Step 5 projection.
• Referenced components — the ### Referenced components sub-section (when present): each #### {displayName} lead paragraph + Prop passed to … | Value in this context | Notes table → one referenced-component entry. These render as additional sub-component tables (the .md is the source of truth for the referenced child's placement props; its full property surface lives in its own spec).

1. Parse the `render-meta` block (the fenced JSON between <!-- render-meta:start v=1 --> and <!-- render-meta:end -->):

• COMP_SET_ID = component.compSetNodeId — the target for live preview instances (Step 12) and the single whitelisted read (Step 5).
• propertyDefs — keyed by raw component-property key (e.g. "clear button#10225:1"); each entry { type, default?, values?, preferredComponentKey?, associatedLayerName?, associatedLayerId? }. This is the raw-key dictionary used to project human prop names in configuration examples to the keys setProperties expects.
• booleanDefs[] — { key, default, associatedLayerName, associatedLayerId }; key is the raw component-property key.
• slotContents[] — for resolving configuration-example slot insertions: each entry { slotName, slotNodeType, preferredComponents: [{ componentKey, componentName, componentId, … }] }. The componentId is the live node id to instantiate into a slot.
• fileKey, nodeId — for the Step 14 completion link and template placement.
• sourceHash — record it; the completion footer reports it so downstream readers can detect drift between this render and the _base.json that produced the .md.

FORBIDDEN — do NOT re-extract / do NOT re-identify. When the component .md is present (it always is past Step 0), you MUST NOT run the legacy extraction or the property-identification reasoning pass. Specifically:

• The old Step 4b extraction script (the componentPropertyDefinitions walk that rebuilt variantAxes, booleanProps, instanceSwapProps, slotProps, composableChildren, ownershipHints, textNodeMap, etc.) is deleted — it does not exist in this skill anymore. Do NOT run any figma_execute / use_figma script that walks the component tree to rebuild the property surface.
• The old Step 4 context-gathering (navigate / screenshot / figma_get_file_data / figma_get_component / figma_get_variables), the old Step 4c working-evidence-set, and the old Step 5–6 property-identification reasoning (variant decomposition, override-promotion pass, variable-mode classification, ownership/nesting decisions, sub-component pattern selection, ApiOverviewData synthesis) are all deleted/demoted. The Properties table, sub-component tables, configuration examples, and referenced-components tables are already authored in the .md — copy them verbatim; do NOT re-identify properties.
• The ONLY Figma reads this skill makes are: the single whitelisted TEXT-node listing in Step 5 (bounded below), the template import (Step 8), the header fill (Step 9), the table fills (Steps 10–11), and the configuration-example previews (Step 12). No other live reads are permitted.

Step 1: Read References (only as needed)

The property contract is already authored in the .md — you do NOT re-identify it. Read agent-api-instruction.md only if you need to reason about a narrow rendering detail while building inputs:

• the isSubProperty Notes-prose convention (the "Only meaningful when {parentProperty} = {triggerValue}. …" template) when re-deriving the hierarchy flag in Step 5;
• the configuration-example code shape when projecting human prop names to raw render-meta.propertyDefs keys in Step 5.

Skip this step entirely when the .md's configuration examples have no slot/variant overrides to project. Do NOT use the instruction file to re-run property identification — that reasoning is demoted (see Step 0 FORBIDDEN).

Step 2: Verify MCP Connection

Read mcpProvider from uspecs.config.json and verify the connection (rendering — and the single whitelisted Step 5 read — require a live Figma session):