/create-component-md

name: create-component-md
description: Generate a canonical JSON contract and a self-contained implementation Markdown specification for a Figma component covering API, structure, color, and screen-reader behavior. Reads a `_base.json` produced by the uSpec Extract plugin, runs four read-only interpretation skills in parallel, reconciles their outputs, and writes sibling `.json` and `.md` artifacts. Use when the user mentions "component md", "component markdown", "spec md", "source of truth", "create-component-md", or wants a portable component specification.

Create Component Markdown (Orchestrator)

This skill consumes a `_base.json` produced by the uSpec Extract Figma plugin (`figma-plugin/`), runs four **read-only interpretation** skills (`extract-api`, `extract-structure`, `extract-color`, `extract-voice`), and writes two sibling artifacts: a canonical `.json` contract and a polished implementation `.md`. Figma is only the source of extraction. Exhaustive `.audit.md` is an opt-in diagnostic view, not a default artifact.

**Do not call the `create-*` skills from here.** They render Figma frames that overlap and do not compose into a single file.

Why this orchestrator exists

The four `create-*` skills each cost ~100k tokens per run because the majority of their weight is Figma rendering (`setProperties`, `createInstance`, `loadFontAsync`, layout math). The `extract-*` skills strip all rendering. Because the Figma plugin produces a single shared `_base.json`, the four interpretation skills also stop calling Figma — they read that file from disk. This removes most of the Figma-side work and keeps the orchestrator's parent context small by discarding each phase's detail after its one-line summary lands.

**Token model (approximate):**

| Phase | Peak context in parent | |---|---| | extract-api (runs first, inline) | instruction + `_base.json` read + interpretation | | parallel fan-out (structure + color + voice, subagent each) | three one-line summaries (subagents hold their own context) | | reconciliation (Step 8.5) | mismatch lists + api dictionary (small) | | rendering | 4 JSON cache files + template + instruction |

`extract-api` runs first in the parent so its dictionary can steer the three downstream specialists. After the dictionary lands, the parent dispatches `extract-structure`, `extract-color`, and `extract-voice` as three **parallel subagents** (`subagent_type=generalPurpose`, single batch). Each subagent holds its own `_base.json` + dictionary context; the parent keeps only the returned one-line summaries and cache-file paths.

Inputs Expected

• **`baseJsonPath`** (required): absolute or workspace-relative path to the `_base.json` file produced by the uSpec Extract Figma plugin. Must validate against [figma-plugin/docs/base-json-schema.md]({{repo:figma-plugin/docs/base-json-schema.md}}). If this is not provided, abort and instruct the user to run the uSpec Extract plugin (see `figma-plugin/README.md`).
• **`figmaLink`** (optional): URL to the component set or standalone component. Accept `figma.com/design/:fileKey/...` and branch URLs (`/branch/:branchKey/`). Only consulted if an interpretation skill needs a Step 3-delta MCP call.
• **`optionalContext`** (optional): free-form guidance (e.g., "this is a compact variant only", "skip error states"). If the plugin already captured it in `_meta.optionalContext`, that wins; otherwise the value passed here is used. Forwarded verbatim to every sub-skill.

No output path is required — the defaults are `./components/{componentSlug}.md` and `./components/{componentSlug}.json` in the current working directory.

Workflow

Copy this checklist and update as you progress:

Task Progress:
- [ ] Step 1: Preflight — read config, run `uspec-skills component-md prepare`, load manifest
- [ ] Step 2: Resolve componentSlug and output path (from manifest)
- [ ] Step 3: Announce the plan
- [ ] Step 3.5: Composition classification (reasoning gate — internalize before Step 4.5 review)
- [ ] Step 4: Stage _base.json into cachePath (handled by CLI prepare — verify manifest only)
- [ ] Step 4.5: Post-extract review — confirm _childComposition (user-selected classifications skip override pass)
- [ ] Step 5: Run extract-api (reads _base.json, no Figma), flush, verify cache + api-dictionary.json
- [ ] Step 6: Parallel fan-out — dispatch extract-structure, extract-color, extract-voice as three subagents in a single batch; join on all three summaries
- [ ] Step 8.5: Reconciliation — typed disagreement handling with bounded serial retries
- [ ] Step 9: Build the canonical JSON contract, then render the implementation Markdown
- [ ] Step 9.5: Integrity check — validate all cache files and reconciliation artifact before rendering
- [ ] Step 10: Audit output and return a one-line summary
- [ ] Step 10.5: Emit recursion manifest (constitutive children only)

Step 1: Preflight (CLI prepare)

Read `uspecs.config.json` at the project root. Extract:

• `mcpProvider` (`figma-console` or `figma-mcp`). Only used if `figmaLink` is also provided AND an interpretation skill's Step 3-delta triggers.
• `environment` (`cursor` | `claude-code` | `codex`) — used to resolve the skills directory for subagent dispatch (see Step 6).

**`baseJsonPath` is required.** If it is missing, abort with a one-line diagnostic: "run the uSpec Extract plugin in Figma and rerun with `baseJsonPath=<path>` — see `figma-plugin/README.md`."

**Run the deterministic prepare stage first.** Resolve the CLI executable **before** shelling out — do not assume `npx uspec-skills` is new enough to expose `component-md prepare`.

**CLI resolution order** (try each; stop at the first that works):

1. **Local dev checkout** — when `packages/cli/dist/index.js` exists in the project root:

   node packages/cli/dist/index.js component-md prepare --base "<baseJsonPath>" --json

If missing but `packages/cli/` exists, run `npm run build:cli` from the project root onc