redongreen/uspec/create-anatomy

Create Anatomy Annotation

Generate a hierarchical anatomy annotation directly in Figma — a composition section showing the top-level sub-components with numbered markers and a 4-column attribute table, then per-child sections for each INSTANCE sub-component showing all its internal elements (including hidden ones).

Uses the Anatomy & Properties v2 template with #annotation-table, type indicators (#instance / #text / #slot), and #anatomy-section cloning.

Execution contract (read first).

• This file is instructions to RUN, not a document to edit. Invoking the skill = render the anatomy annotation 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 seeds its element model from the `.md`'s `render-meta` block and then runs one bounded minimal live walk; it does NOT re-run the old full extraction. The .md has no dedicated Anatomy section — identity comes from render-meta (component.compSetNodeId, variantAxes, booleanDefs, slotContents, subComponents), and the few facts render-meta cannot supply (live direct-child classification, the richest variant, slot default children, wrapper visuals) come from the Step 3' walk.
• Figma link to the destination (optional) — placement hint only: which page/frame to drop the rendered annotation on. fileKey, nodeId, and compSetNodeId always come from the .md's render-meta block, never from the link.

There is no screenshot-only path and no "extract everything from a Figma URL" path. Without the component .md there is no identity to seed — 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` render-meta block (seed identity). FAIL FAST if missing.
- [ ] Step 1: Verify MCP connection
- [ ] Step 2: Read template key from uspecs.config.json
- [ ] Step 3': Seed from render-meta + run the bounded minimal live walk (classify direct children, pick richest variant, read slot defaults, check wrapper visuals)
- [ ] Step 4: Evaluate variant selection, classify elements, and enrich notes (AI reasoning)
- [ ] Step 5: Navigate to destination (if different file)
- [ ] Step 6: Import and detach the Anatomy template
- [ ] Step 7: Fill header fields and create composition section
- [ ] Step 8: Build composition artwork with markers + fill table
- [ ] Step 8b: Per-sub-component child sections (property-aware unhide)
- [ ] Step 10: Visual validation

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

This skill is a consumer of the `.md` source of truth. Unlike the other create-* skills, the .md has no dedicated "Anatomy" body section — so create-anatomy seeds identity only from the render-meta block and supplements it with one bounded live walk (Step 3'). It does NOT parse an Anatomy section body, and it does NOT re-run the legacy full tree-walk extraction.

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 `render-meta` block (the fenced JSON between <!-- render-meta:start v=1 --> and <!-- render-meta:end -->). There is no Anatomy body section to parse — every seed value comes from this block:

• COMP_SET_ID = render-meta.component.compSetNodeId — the target node for the Step 3' walk, the Step 6 template placement, and every artwork instance in Steps 8/8b.
• IS_COMPONENT_SET = render-meta.component.isComponentSet.
• COMPONENT_NAME = render-meta.component.componentName.
• VARIANT_AXES = render-meta.variantAxes ({ axisName: [options] }) and VARIANT_AXES_DEFAULTS = render-meta.variantAxesDefaults — used by Step 4 sub-step 0 to decide whether a structurally richer variant exists. This replaces reading componentPropertyDefinitions live for variant axes.
• BOOLEAN_DEFS = render-meta.booleanDefs[] ({ key, default, associatedLayerName, associatedLayerId }) — the source for boolean-controlled hidden elements. key is the raw component-property key setProperties expects; associatedLayerName lets Step 4 bind a boolean to a Step 3'-walked element by name. This replaces parsing booleans + resolving bindings by raw key in a live walk.
• SLOT_CONTENTS = render-meta.slotContents[] ({ slotName, slotNodeType, preferredComponents: [{ componentId, componentName, componentSetId, isComponentSet, ... }] }) — resolves slot preferred instances without the old cross-page findAll search.
• SUB_COMPONENTS = render-meta.subComponents[] ({ name, mainComponentName, subCompSetId, subCompVariantAxes, subCompVariantAxesDefaults, booleanOverrides }) — the constitutive sub-components that become Step 8b child sections; subCompSetId is the child node id.
• FILE_KEY = render-meta.fileKey, NODE_ID = render-meta.nodeId — for the Step 11 completion link and template placement.
• SOURCE_HASH = render-meta.sourceHash — recorded in the Step 11 provenance footer so drift between this annotation and the underlying _base.json is detectable.

FORBIDDEN — do NOT run the full extraction. When the component .md is present (it always is past Step 0), you MUST NOT run the legacy full-tree extraction. Specifically:

• The old Step 3 extraction script — the one that parsed componentPropertyDefinitions for variantAxes / booleanProps / instanceSwapProps, resolved boolean bindings by raw key, and ran a cross-page findAll to resolve slot preferredValues — is deleted. It does not exist in this skill anymore. Do NOT reintroduce it.
• Do NOT re-derive variantAxes, variantAxesDefaults, booleanDefs, slot preferred components, or sub-component identity from a live walk — they are seeded from render-meta (Step 0.3).
• The ONLY live read of the component tree permitted before rendering is the bounded minimal walk in Step 3' below, whose scope is explicitly whitelisted. The render scripts (Steps 8 / 8b) make their own live reads of the rendered instance — those are unchanged and still allowed.

Step 1: Verify MCP Connection

Read mcpProvider from uspecs.config.json to determine which Figma MCP to use.

If `figma-console`:

• figma_get_status — Confirm Desktop Bridge plugin is active
• If connection fails: "Please open Figma Desktop and run the Desktop Bridge plugin. Then try again."

If `figma-mcp`:

• Connection is verified implicitly on the first use_figma call. No explicit check needed.
• If the first call fails: "Please verify your FIGMA_API_KEY is set correctly in your MCP configuration."

Step 2: Read Template Key

Read the file uspecs.config.json and extract:

• The anatomyOverview value from the templateKeys object → save as ANATOMY_TEMPLATE_KEY
• The fontFamily value → save as FONT_FAMILY (default to Inter if not set)

If the template key is empty, tell the user:

The anatomy template key is not configured. Run {{skill:firstrun}} with your Figma template library link first.

Step 3': Seed from render-meta + run the bounded minimal live walk

The element model is built in two parts: a `render-meta` seed (already parsed in Step 0) and a bounded minimal live walk that supplies only the facts render-meta cannot.

Seed (from `render-meta`, no Figma reads):

• SUB_COMPONENTS (render-meta.subComponents[]) — constitutive sub-components and their subCompSetId; drives the Step 8b child sections with no live identity resolution.
• SLOT_CONTENTS (render-meta.slotContents[]) — each slot's preferred components with their componentId; replaces the old cross-page findAll preferred-instance search.
• BOOLEAN_DEFS (render-meta.booleanDefs[]) — boolean properties and their associatedLayerName; replaces parsing componentPropertyDefinitions and resolving boolean bindings by raw key.