redongreen/uspec/extract-structure

Extract Structure Data

Interpretation-only companion to create-structure. 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-structure, and writes the normalized StructureSpecData JSON to disk for the create-component-md orchestrator to consume.

Quality contract: every reasoning step (section planning, ownership resolution, override promotion, design-intent notes, anomaly detection) mirrors create-structure/SKILL.md. Any improvement to structure-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. When a value cannot be resolved from _base.json (and a Step 3-delta doesn't recover it), emit a row with provenance: "not-measured" and values: ["—", …] instead of asking. 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.
• apiDictionaryPath — absolute or workspace-relative path to {cachePath}/{componentSlug}-api-dictionary.json. Optional. When present, this file is the canonical vocabulary for axis/value/sub-component/state naming (see Step 2.5). When absent, the skill continues with _dictionaryUnavailable: true in its output envelope and the renderer treats the produced cache as lower-confidence.
• evidencePath — optional. Path to {cachePath}/{componentSlug}-evidence-structure.json from CLI prepare. When present and hash-valid, use data as the Step 3 working evidence set.

fileKey and nodeId are not pass-through parameters anymore. Read them from {cachePath}/{componentSlug}-_base.json._meta.fileKey and _meta.nodeId at the start of Step 1.

Output:

• Writes {cachePath}/{componentSlug}-structure.json containing the full StructureSpecData object.
• Returns a single-line summary to the orchestrator: "Structure extracted: N sections, M sub-components, K slot contents → {path}".
• Never creates or mutates Figma nodes.

MCP Adapter

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

For figma-mcp delta scripts, include the page-focus preamble 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 2.5: Load API dictionary (canonical vocabulary) — optional
- [ ] 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: AI interpretation layer — section plan, ownership, design-intent notes, anomalies
- [ ] Step 5: Generate StructureSpecData object
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache and return one-line summary

Step 1: Read Instructions

Read agent-structure-instruction.md. This is the same instruction file used by create-structure. Treat it as the single source of truth for the StructureSpecData schema, row emission rules, 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.

• §Role — "render structure documentation directly into Figma" — framing only; this skill writes JSON to disk instead.
• §Inputs — the `figma_execute` row's "render sections" phrasing — this skill does not render.
• §Data Structure Reference — "The data is passed directly into Figma template placeholders — no JSON output is needed" — inverted: we do output JSON. Keep the schema; discard the "no JSON" framing.
• §Field Rules — "Render order: first column → values[0..n] → Notes", "Renders between Spec and Notes columns", "Always renders in the final Notes column" — rendering-order prose. The spec / values[] / notes shape is still the authoritative schema.
• §Common Mistakes — "Overriding preview frame layout" and any bullet about `#Preview` frame behavior — rendering concerns. Data-level mistakes (missing sub-component sections, wrong axis grouping, bad display strings) still apply.
• §Pre-Render Validation Checklist — "Sub-component preview sourcing" and "Preview frame untouched" rows — do not apply. All other checks (shape of sections, correctness of rows, column counts, measurement labels) DO still apply.
• §Inputs → "Authoritative `.md`" (including the child "What the `.md` already tells you (Mode B extraction scope)" subsection) — Mode-B-only concepts for the downstream create-structure skill. extract-structure produces the data that becomes the .md; it never consumes a .md as input and never runs Mode B. Ignore the entire ### Authoritative .md block.

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

Step 2: Load _base.json

Read {cachePath}/{componentSlug}-_base.json. If missing, or if required sections are null / missing, abort with a diagnostic asking the user to re-run the uSpec Extract plugin.

See figma-plugin/docs/base-json-schema.md for the full schema. Top-level keys this skill consumes:

• component, variantAxes, defaultVariant
• propertyDefinitions.rawDefs / booleans / slots
• variables.localCollections + resolvedVariables (for mode detection)
• variants[] — each has dimensions, layoutTree, treeHierarchical, revealedTree
• crossVariant.axisDiffs / stateComparison / axisClassification / sizeAxis / stateAxis / dimensionAxes
• slotHostGeometry.swapResults
• subComponentVariantWalks (optional, Phase I; absent on legacy fixtures) — per-subCompSetId walks across a constitutive child's own variant cross-product
• _extractionNotes.warnings

Also absorb optionalContext as authoritative user guidance.

Step 2.5: Load API dictionary (canonical vocabulary)

The create-component-md orchestrator writes {cachePath}/{componentSlug}-api-dictionary.json alongside _base.json after extract-api finishes. When present, this file is the canonical vocabulary for axis names, value names, sub-component names, and state runtime conditions. See the `ApiDictionary` artifact section in api/agent-api-instruction.md for the schema.

Resolution order:

1. If the orchestrator passed apiDictionaryPath, read that file.
2. Otherwise look for {cachePath}/{componentSlug}-api-dictionary.json on disk.
3. If neither path resolves (e.g., the skill is being run standalone outside the orchestrator), continue with existing behavior but set data._dictionaryUnavailable = true on the output envelope. The orchestrator's Step 9.5 integrity check uses this flag to mark the produced cache as lower confidence.

How this skill uses the dictionary (keep it in scope through Steps 3–5):

• Sub-component section names. When emitting sections[].sectionName for a sub-component section (Rule 2d) or a slotContent section (Rule 6), prefer the dictionary's canonical subComponents[].name over the raw Figma name. Example: the dictionary says "Input" but the revealed tree walks a node named "input-container" — the section name is "Input".
• State column headers. When a section's columns correspond to a decomposed Figma state axis (dictionary.states[].figmaAxis matches the section axis), replace Figma option columns with the dictionary's runtimeCondition values in matching order. Do not substitute when the mapping is partial — leave every column as the raw Figma value and emit a _dictionaryMismatch entry (see below).
• Visual-only axis delta columns (Step 4.D.1). Same rule: the renderer already resolves column headers via stateAxisMapping[], but when you emit visualOnlyAxisDeltas[].columns[], keep them as the raw Figma values — the renderer relabels. Never pre-substitute.

Mismatch protocol — do NOT silently rename, do NOT silently keep.

When your evidence (from _base.json) contradicts the dictionary — for example, the dictionary names a sub-component the revealed tree does not contain, or you measured a value the dictionary does not list — emit the observed value AND attach a _dictionaryMismatch annotation to that row/section with shape:

{
  "observed": "<what you measured / observed in _base.json>",
  "dictionary": "<what the dictionary named; null when the dictionary listed a value you couldn't find>",
  "kind": "value-missing" | "value-extra" | "name-drift",
  "note": "<short rationale; ≤160 chars>"
}

`value-extra` guard — only vocabulary-controlled fields can mismatch. Resolve an observed axis/value/component identity against the full dictionary: axes[], booleanProps[], states[], subComponents[], referencedComponents[], and slots[]. Measurements, layer names, dimensions, tokens, and topology are specialist evidence and MUST NOT produce dictionary mismatches. A runtime substate such as “disclosure (expanded)” is also not an extra when it is explicitly linked to its parent dictionary value (for example type=disclosure); document the parent API assignment on the section. Emit value-extra only for an API-facing name/value that resolves nowhere.

Aggregate every mismatch into data._extractionArtifacts.dictionaryMismatches[]. The orchestrator's Step 8.5 reconciliation pass consumes this list and decides whether to auto-rewrite vocabulary, re-dispatch a specialist, or surface a semantic conflict.

Retry semantics — the orchestrator may re-dispatch this skill.

When optionalContext begins with the literal prefix create-component-md retry: , the rest of the string is an authoritative scope expansion from the orchestrator's Step 8.5 reconciliation step. Parse it as a comma-separated list of items the dictionary exposed but this skill previously did not cover. The retry run MUST emit evidence for every listed item — either a real section/row citing evidence from _base.json, or an explicit _dictionaryMismatch entry explaining why no evidence could be gathered. Never silently drop a listed item.

Step 3: Build Working Evidence Set

Evidence fast path (preferred). When evidencePath is provided, read it first. If the file exists, parses as JSON, has _meta.domain === "structure", and _meta.baseSourceHash matches {cachePath}/{componentSlug}-prepare-manifest.json, treat data as the Step 3 evidence set and proceed to Step 4 without rebuilding mappings from the full _base.json. Still read _base.json for coverage-matrix recounts and any facts missing from the slice.