/create-property

name: create-property
description: Generate a visual property annotation in Figma showing each configurable property axis with component instance previews. Use when the user mentions "property", "properties", "property annotation", "create property", or wants to document a component's configurable properties visually.

Create Property Annotation

Generate a visual property annotation directly in Figma — one exhibit per variant axis and boolean toggle, each showing the available options as component instances with a summary table.

**Execution contract (read first).**

• This file is instructions to RUN, not a document to edit. Invoking the skill = render the property 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.

| Operation | `figma-console` | `figma-mcp` | |-----------|-----------------|-------------| | Verify connection | `figma_get_status` | Skip — implicit. If first `use_figma` call fails, guide user to check MCP setup. | | Navigate to file | `figma_navigate` with URL | Extract `fileKey` from URL (`figma.com/design/:fileKey/...`). No navigate needed. | | Take screenshot | `figma_take_screenshot` | `get_screenshot` with `fileKey` + `nodeId` | | Execute Plugin JS | `figma_execute` with `code` | `use_figma` with `fileKey`, `code`, `description`. **Core logic is identical** — see font loading note below for the one API difference (`getRangeAllFontNames` → `tn.fontName`). | | Search components | `figma_search_components` | `search_design_system` with `query` + `fileKey` + `includeComponents: true` | | Get file/component data | `figma_get_file_data` / `figma_get_component` | `get_metadata` or `get_design_context` with `fileKey` + `nodeId` | | Get variables (file-wide) | `figma_get_variables` | `use_figma` script: `return await figma.variables.getLocalVariableCollectionsAsync();` | | Get token values | `figma_get_token_values` | `use_figma` script reading variable values per mode/collection | | Get styles | `figma_get_styles` | `search_design_system` with `includeStyles: true`, or `use_figma`: `return figma.getLocalPaintStyles();` | | Get selection | `figma_get_selection` | `use_figma` script: `return figma.currentPage.selection.map(n => ({id: n.id, name: n.name, type: n.type}));` |

**`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 at the **start** of every script that references a previously-created node:

const pages = figma.root.children;
const targetPage = pages.find(p => p.name === '__PAGE_NAME__');
if (targetPage) await figma.setCurrentPageAsync(targetPage);

Replace `__PAGE_NAME__` with the actual page name (determined during Step 7 when the template is placed). This loads the page content so child nodes are accessible.

**`figma-mcp` font loading:** `getRangeAllFontNames` is not available in the `use_figma` sandbox and will throw `TypeError`. Replace it with `tn.fontName` (returns `{ family, style }` for single-font text, or `figma.mixed` for mixed-font text). `findAll` and `findOne` work normally after `setCurrentPageAsync` — they do not need replacement.

Replace the font-collection loop in every script from:

const fonts = tn.getRangeAllFontNames(0, tn.characters.length);
for (const f of fonts) {
  const key = f.family + '|' + f.style;
  if (!fontSet.has(key)) { fontSet.add(key); fontsToLoad.push(f); }
}

to:

try {
  const fn = tn.fontName;
  if (fn && fn !== figma.mixed && fn.family) {
    const key = fn.family + '|' + fn.style;
    if (!fontSet.has(key)) { fontSet.add(key); fontsToLoad.push(fn); }
  }
} catch {}

And add `.catch(() => {})` to the batch load: `await Promise.all(fontsToLoad.map(f => figma.loadFontAsync(f).catch(() => {})));`

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 rebuilds its property model from the `.md`'s `render-meta` block; it does NOT re-extract the property surface from Figma. `fileKey`, `nodeId`, and `compSetNodeId` come from `render-meta`, never from a Figma link.
• **Figma link** (optional) — placement hint only (which page/frame to drop the rendered annotation on, including a cross-file destination) and the target for the two whitelisted minimal live reads in Steps 4a/4b. Never the source of the property contract.

**Asymmetry from the other consumers.** Unlike the Structure / Color / Voice consumers, the `.md` ha