@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/skill-candidates/v0.0.10/figma-use/references/text-style-patterns.md

@@ -1,203 +1,203 @@
-# Text Style API Patterns
-
-> Part of the [use_figma skill](../SKILL.md). How to create, apply, and inspect text styles using the Plugin API.
->
-> For design system context (when to create text styles, how they relate to tokens, headless limitations), see [wwds-text-styles](working-with-design-systems/wwds-text-styles.md).
-
-## Contents
-
-- Listing Text Styles
-- Creating a Text Style
-- Probing Font Styles
-- Creating a Type Ramp (Multi-Step)
-- Applying Text Styles to Nodes
-
-## Listing Text Styles
-
-```javascript
-/**
- * Lists all local text styles with their key properties.
- *
- * @returns {Promise<Array<{id: string, name: string, key: string, fontSize: number, fontName: FontName, lineHeight: LineHeight, letterSpacing: LetterSpacing}>>}
- */
-async function listTextStyles() {
-  const styles = await figma.getLocalTextStylesAsync();
-  return styles.map(s => ({
-    id: s.id,
-    name: s.name,
-    key: s.key,
-    fontSize: s.fontSize,
-    fontName: s.fontName,
-    lineHeight: s.lineHeight,
-    letterSpacing: s.letterSpacing
-  }));
-}
-```
-
-Full runnable script:
-
-```javascript
-(async () => {
-  try {
-    const results = await listTextStyles();
-    figma.closePlugin(JSON.stringify(results));
-  } catch(e) { figma.closePluginWithFailure(e.toString()); }
-})()
-```
-
-## Creating a Text Style
-
-Font **MUST** be loaded before setting `fontName`. `lineHeight` and `letterSpacing` must be `{value, unit}` objects — bare numbers throw.
-
-```javascript
-/**
- * Creates a text style with all typographic properties set.
- * Font MUST be loaded before calling.
- *
- * @param {string} name - Slash-delimited name, e.g. "body/base"
- * @param {{ family: string, style: string }} fontName
- * @param {number} fontSize - In pixels
- * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' } | { unit: 'AUTO' }} lineHeight
- * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' }} [letterSpacing]
- * @param {string} [description] - e.g. the CSS variable name "CSS: var(--font-body-base)"
- * @returns {TextStyle}
- */
-function createTextStyleFull(name, fontName, fontSize, lineHeight, letterSpacing, description) {
-  const style = figma.createTextStyle();
-  style.name = name;
-  style.fontName = fontName;
-  style.fontSize = fontSize;
-  style.lineHeight = lineHeight; // { unit: 'AUTO' } | { value, unit: 'PIXELS'|'PERCENT' }
-  if (letterSpacing) style.letterSpacing = letterSpacing;
-  if (description) style.description = description;
-  return style;
-}
-```
-
-## Probing Font Styles
-
-Font style names vary per provider and per file (`"SemiBold"` vs `"Semi Bold"`). Always probe before hardcoding:
-
-```javascript
-/**
- * Probes available font styles for a given family.
- * Useful when font style names are unknown (e.g. "SemiBold" vs "Semi Bold").
- *
- * @param {string} family - Font family name, e.g. "Inter"
- * @param {string[]} stylesToTest - Candidate style names to probe
- * @returns {Promise<string[]>} - Style names that loaded successfully
- */
-async function probeAvailableFontStyles(family, stylesToTest) {
-  const available = [];
-  for (const style of stylesToTest) {
-    try {
-      await figma.loadFontAsync({ family, style });
-      available.push(style);
-    } catch (_) {}
-  }
-  return available;
-}
-```
-
-## Creating a Type Ramp (Multi-Step)
-
-Handles font loading, deduplication, and idempotency. Each entry: `[name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]`.
-
-**HEADLESS NOTE:** `setBoundVariable` on `TextStyle` is not supported in `use_figma`. This function sets raw values. To bind variables, do it interactively in Figma after creation.
-
-```javascript
-/**
- * Creates a full type ramp from a token definition array.
- * Handles font loading, deduplication, and idempotency.
- *
- * Each entry: [name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]
- *   - lineHeight: { unit: 'AUTO' } or { value: number, unit: 'PIXELS' | 'PERCENT' }
- *
- * @param {Array} defs - Array of [name, fontFamily, fontStyle, fontSize, lineHeight, cssVar] tuples
- * @returns {Promise<{ created: string[], skipped: string[] }>}
- */
-async function createTypeRamp(defs) {
-  const uniqueFonts = new Set();
-  for (const [, family, style] of defs) {
-    uniqueFonts.add(JSON.stringify({ family, style }));
-  }
-  await Promise.all(
-    [...uniqueFonts].map(f => figma.loadFontAsync(JSON.parse(f)))
-  );
-
-  const existing = new Set(
-    (await figma.getLocalTextStylesAsync()).map(s => s.name)
-  );
-
-  const created = [];
-  const skipped = [];
-
-  for (const [name, family, style, fontSize, lineHeight, cssVar] of defs) {
-    if (existing.has(name)) {
-      skipped.push(name);
-      continue;
-    }
-    const ts = figma.createTextStyle();
-    ts.name = name;
-    ts.fontName = { family, style };
-    ts.fontSize = fontSize;
-    ts.lineHeight = lineHeight ?? { unit: 'AUTO' };
-    if (cssVar) ts.description = `CSS: var(${cssVar})`;
-    created.push(name);
-  }
-
-  return { created, skipped };
-}
-```
-
-Full runnable script:
-
-```javascript
-(async () => {
-  try {
-    const defs = [
-      ['heading/xl', 'Inter', 'Bold',      48, { unit: 'PIXELS', value: 56 }, '--font-heading-xl'],
-      ['heading/lg', 'Inter', 'Bold',      36, { unit: 'PIXELS', value: 44 }, '--font-heading-lg'],
-      ['body/base',  'Inter', 'Regular',   16, { unit: 'AUTO' },              '--font-body-base'],
-      ['body/sm',    'Inter', 'Regular',   14, { unit: 'AUTO' },              '--font-body-sm'],
-      ['code/base',  'Roboto Mono', 'Regular', 14, { unit: 'AUTO' },          '--font-code-base'],
-    ];
-    const result = await createTypeRamp(defs);
-    figma.closePlugin(JSON.stringify(result));
-  } catch(e) { figma.closePluginWithFailure(e.toString()); }
-})()
-```
-
-## Applying Text Styles to Nodes
-
-```javascript
-/**
- * Applies a text style to all TEXT nodes on the current page that match a given name pattern.
- *
- * @param {string} styleId - The ID of a TextStyle.
- * @param {string} nodeNamePattern - Substring match against node names.
- * @returns {Promise<number>} - Number of nodes the style was applied to.
- */
-async function applyTextStyleToMatchingNodes(styleId, nodeNamePattern) {
-  const textNodes = figma.currentPage.findAllWithCriteria({ types: ['TEXT'] });
-  let applied = 0;
-  for (const node of textNodes) {
-    if (node.name.includes(nodeNamePattern)) {
-      await node.setTextStyleIdAsync(styleId);
-      applied++;
-    }
-  }
-  return applied;
-}
-```
-
-Full runnable script:
-
-```javascript
-(async () => {
-  try {
-    const applied = await applyTextStyleToMatchingNodes('STYLE_ID', 'Heading');
-    figma.closePlugin(JSON.stringify({ applied }));
-  } catch(e) { figma.closePluginWithFailure(e.toString()); }
-})()
-```
+# Text Style API Patterns
+
+> Part of the [use_figma skill](../SKILL.md). How to create, apply, and inspect text styles using the Plugin API.
+>
+> For design system context (when to create text styles, how they relate to tokens, headless limitations), see [wwds-text-styles](working-with-design-systems/wwds-text-styles.md).
+
+## Contents
+
+- Listing Text Styles
+- Creating a Text Style
+- Probing Font Styles
+- Creating a Type Ramp (Multi-Step)
+- Applying Text Styles to Nodes
+
+## Listing Text Styles
+
+```javascript
+/**
+ * Lists all local text styles with their key properties.
+ *
+ * @returns {Promise<Array<{id: string, name: string, key: string, fontSize: number, fontName: FontName, lineHeight: LineHeight, letterSpacing: LetterSpacing}>>}
+ */
+async function listTextStyles() {
+  const styles = await figma.getLocalTextStylesAsync();
+  return styles.map(s => ({
+    id: s.id,
+    name: s.name,
+    key: s.key,
+    fontSize: s.fontSize,
+    fontName: s.fontName,
+    lineHeight: s.lineHeight,
+    letterSpacing: s.letterSpacing
+  }));
+}
+```
+
+Full runnable script:
+
+```javascript
+(async () => {
+  try {
+    const results = await listTextStyles();
+    figma.closePlugin(JSON.stringify(results));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+## Creating a Text Style
+
+Font **MUST** be loaded before setting `fontName`. `lineHeight` and `letterSpacing` must be `{value, unit}` objects — bare numbers throw.
+
+```javascript
+/**
+ * Creates a text style with all typographic properties set.
+ * Font MUST be loaded before calling.
+ *
+ * @param {string} name - Slash-delimited name, e.g. "body/base"
+ * @param {{ family: string, style: string }} fontName
+ * @param {number} fontSize - In pixels
+ * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' } | { unit: 'AUTO' }} lineHeight
+ * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' }} [letterSpacing]
+ * @param {string} [description] - e.g. the CSS variable name "CSS: var(--font-body-base)"
+ * @returns {TextStyle}
+ */
+function createTextStyleFull(name, fontName, fontSize, lineHeight, letterSpacing, description) {
+  const style = figma.createTextStyle();
+  style.name = name;
+  style.fontName = fontName;
+  style.fontSize = fontSize;
+  style.lineHeight = lineHeight; // { unit: 'AUTO' } | { value, unit: 'PIXELS'|'PERCENT' }
+  if (letterSpacing) style.letterSpacing = letterSpacing;
+  if (description) style.description = description;
+  return style;
+}
+```
+
+## Probing Font Styles
+
+Font style names vary per provider and per file (`"SemiBold"` vs `"Semi Bold"`). Always probe before hardcoding:
+
+```javascript
+/**
+ * Probes available font styles for a given family.
+ * Useful when font style names are unknown (e.g. "SemiBold" vs "Semi Bold").
+ *
+ * @param {string} family - Font family name, e.g. "Inter"
+ * @param {string[]} stylesToTest - Candidate style names to probe
+ * @returns {Promise<string[]>} - Style names that loaded successfully
+ */
+async function probeAvailableFontStyles(family, stylesToTest) {
+  const available = [];
+  for (const style of stylesToTest) {
+    try {
+      await figma.loadFontAsync({ family, style });
+      available.push(style);
+    } catch (_) {}
+  }
+  return available;
+}
+```
+
+## Creating a Type Ramp (Multi-Step)
+
+Handles font loading, deduplication, and idempotency. Each entry: `[name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]`.
+
+**HEADLESS NOTE:** `setBoundVariable` on `TextStyle` is not supported in `use_figma`. This function sets raw values. To bind variables, do it interactively in Figma after creation.
+
+```javascript
+/**
+ * Creates a full type ramp from a token definition array.
+ * Handles font loading, deduplication, and idempotency.
+ *
+ * Each entry: [name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]
+ *   - lineHeight: { unit: 'AUTO' } or { value: number, unit: 'PIXELS' | 'PERCENT' }
+ *
+ * @param {Array} defs - Array of [name, fontFamily, fontStyle, fontSize, lineHeight, cssVar] tuples
+ * @returns {Promise<{ created: string[], skipped: string[] }>}
+ */
+async function createTypeRamp(defs) {
+  const uniqueFonts = new Set();
+  for (const [, family, style] of defs) {
+    uniqueFonts.add(JSON.stringify({ family, style }));
+  }
+  await Promise.all(
+    [...uniqueFonts].map(f => figma.loadFontAsync(JSON.parse(f)))
+  );
+
+  const existing = new Set(
+    (await figma.getLocalTextStylesAsync()).map(s => s.name)
+  );
+
+  const created = [];
+  const skipped = [];
+
+  for (const [name, family, style, fontSize, lineHeight, cssVar] of defs) {
+    if (existing.has(name)) {
+      skipped.push(name);
+      continue;
+    }
+    const ts = figma.createTextStyle();
+    ts.name = name;
+    ts.fontName = { family, style };
+    ts.fontSize = fontSize;
+    ts.lineHeight = lineHeight ?? { unit: 'AUTO' };
+    if (cssVar) ts.description = `CSS: var(${cssVar})`;
+    created.push(name);
+  }
+
+  return { created, skipped };
+}
+```
+
+Full runnable script:
+
+```javascript
+(async () => {
+  try {
+    const defs = [
+      ['heading/xl', 'Inter', 'Bold',      48, { unit: 'PIXELS', value: 56 }, '--font-heading-xl'],
+      ['heading/lg', 'Inter', 'Bold',      36, { unit: 'PIXELS', value: 44 }, '--font-heading-lg'],
+      ['body/base',  'Inter', 'Regular',   16, { unit: 'AUTO' },              '--font-body-base'],
+      ['body/sm',    'Inter', 'Regular',   14, { unit: 'AUTO' },              '--font-body-sm'],
+      ['code/base',  'Roboto Mono', 'Regular', 14, { unit: 'AUTO' },          '--font-code-base'],
+    ];
+    const result = await createTypeRamp(defs);
+    figma.closePlugin(JSON.stringify(result));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+## Applying Text Styles to Nodes
+
+```javascript
+/**
+ * Applies a text style to all TEXT nodes on the current page that match a given name pattern.
+ *
+ * @param {string} styleId - The ID of a TextStyle.
+ * @param {string} nodeNamePattern - Substring match against node names.
+ * @returns {Promise<number>} - Number of nodes the style was applied to.
+ */
+async function applyTextStyleToMatchingNodes(styleId, nodeNamePattern) {
+  const textNodes = figma.currentPage.findAllWithCriteria({ types: ['TEXT'] });
+  let applied = 0;
+  for (const node of textNodes) {
+    if (node.name.includes(nodeNamePattern)) {
+      await node.setTextStyleIdAsync(styleId);
+      applied++;
+    }
+  }
+  return applied;
+}
+```
+
+Full runnable script:
+
+```javascript
+(async () => {
+  try {
+    const applied = await applyTextStyleToMatchingNodes('STYLE_ID', 'Heading');
+    figma.closePlugin(JSON.stringify({ applied }));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```

package/docs/skill-candidates/v0.0.10/figma-use/references/validation-and-recovery.md

@@ -1,109 +1,109 @@
-# Validation Workflow & Error Recovery
-
-> Part of the [use_figma skill](../SKILL.md). How to debug, validate, and recover from errors.
-
-## Contents
-
-- `get_metadata` vs `get_screenshot`
-- Error Recovery After Failed `use_figma`
-- Cleanup Pattern
-- Recommended Workflow
-
-
-## `get_metadata` vs `get_screenshot`
-
-After each `use_figma` call, validate results using the right tool for the job. Do NOT reach for `get_screenshot` every time — it is expensive and should be reserved for visual checks.
-
-### `get_metadata` — Use for intermediate validation (preferred)
-
-`get_metadata` returns an XML tree of node IDs, types, names, positions, and sizes. Use it to confirm:
-
-- **Structure & hierarchy**: correct parent-child relationships, component nesting, section contents
-- **Node counts**: expected number of variants created, children present
-- **Naming**: variant property names follow the `property=value` convention
-- **Positioning & alignment**: x/y coordinates, width/height values match expectations
-- **Layout properties**: auto-layout direction, sizing mode, padding, spacing
-- **Component set membership**: all expected variants are inside the ComponentSet
-
-```
-Example: After creating a ComponentSet with 120 variants, call get_metadata on the
-ComponentSet node to verify all 120 children exist with correct names, sizes, and positions
-— without waiting for a full render.
-```
-
-**When to use `get_metadata`:**
-- After creating/modifying nodes — to verify structure, counts, and names
-- After layout operations — to verify positions and dimensions
-- After combining variants — to confirm all components are in the ComponentSet
-- After binding variables — to verify node properties (use use_figma to read bound variables if needed)
-- Between multi-step workflows — to confirm step N succeeded before starting step N+1
-
-### `get_screenshot` — Use after each major creation milestone
-
-`get_screenshot` renders a pixel-accurate image. It is the only way to verify visual correctness (colors, typography rendering, effects, variable mode resolution). It is slower and produces large responses, so don't call it after every single `use_figma` — but do call it after each major milestone to catch visual problems early.
-
-**When to use `get_screenshot`:**
-- **After creating a component set** — verify variants look correct, grid is readable, nothing is collapsed or overlapping
-- **After composing a layout** — verify overall structure and spacing
-- **After binding variables/modes** — verify colors and tokens resolved correctly
-- **After any fix or recovery** — verify the fix didn't introduce new visual issues
-- **Before reporting results to the user** — final visual proof
-
-**What to look for in screenshots** — these are the most commonly missed issues:
-- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
-- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
-- **Placeholder text** still showing ("Title", "Heading", "Button") instead of actual content
-
-## CRITICAL: Error Recovery After Failed `use_figma`
-
-> **THIS IS NOT OPTIONAL.** Every `use_figma` error MUST trigger the recovery steps below. Skipping these steps leaves orphaned nodes in the file that will cause duplicates and inconsistencies on retry.
-
-**Scripts can partially execute before hitting an error.** A failed `use_figma` does NOT roll back — nodes created before the error line persist in the file. This leaves the file in an **inconsistent, partially-modified state**.
-
-**Mandatory recovery steps when `use_figma` returns an error (DO NOT SKIP):**
-1. **STOP — do NOT immediately fix the code and retry.** The file has partial state that must be inspected first.
-2. **Immediately call `get_metadata`** on the parent node (section, page, or ComponentSet) to see what was partially created.
-3. **If `get_metadata` doesn't make the damage clear** (e.g. positions look fine but visual state is uncertain), call `get_screenshot` to assess visual damage.
-4. **Write a cleanup script** to remove orphaned/incomplete nodes before retrying. Use `page.findChildren()` to locate stray nodes.
-5. **Only after cleanup is confirmed**, fix the original script and retry.
-6. **Never retry the failed script blindly** — the partial state means a retry will create duplicates or hit new errors.
-
-```
-Example: A script creating 8 components fails on component #5.
-Components 1-4 exist on the page. A naive retry creates components 1-8 again,
-leaving 12 components total (4 orphaned duplicates). Always clean up first.
-```
-
-### Cleanup Pattern
-
-```js
-// Cleanup pattern: find and remove orphaned nodes from a failed run
-(async () => {
-  try {
-    const page = figma.currentPage;
-    // Find orphaned components that weren't combined into a ComponentSet
-    const orphans = page.findChildren(n =>
-      n.type === 'COMPONENT' && n.name.includes('variant=')
-    );
-    for (const orphan of orphans) orphan.remove();
-    figma.closePlugin('Cleaned up ' + orphans.length + ' orphaned nodes');
-  } catch(e) { figma.closePluginWithFailure(e.toString()); }
-})()
-```
-
-## Recommended Workflow
-
-```
-1. use_figma  →  Create/modify nodes
-2. get_metadata     →  Verify structure, counts, names, positions (fast, cheap)
-3. use_figma  →  Fix any structural issues found
-4. get_metadata     →  Re-verify fixes
-5. ... repeat as needed ...
-6. get_screenshot   →  Visual check after each major milestone
-
-⚠️ ON ERROR at any step:
-   a. get_metadata    →  Inspect partial state (always do this first)
-   b. get_screenshot  →  Only if metadata doesn't make the damage clear
-   c. use_figma →  Clean up orphaned/incomplete nodes
-   d. THEN retry the failed operation
-```
+# Validation Workflow & Error Recovery
+
+> Part of the [use_figma skill](../SKILL.md). How to debug, validate, and recover from errors.
+
+## Contents
+
+- `get_metadata` vs `get_screenshot`
+- Error Recovery After Failed `use_figma`
+- Cleanup Pattern
+- Recommended Workflow
+
+
+## `get_metadata` vs `get_screenshot`
+
+After each `use_figma` call, validate results using the right tool for the job. Do NOT reach for `get_screenshot` every time — it is expensive and should be reserved for visual checks.
+
+### `get_metadata` — Use for intermediate validation (preferred)
+
+`get_metadata` returns an XML tree of node IDs, types, names, positions, and sizes. Use it to confirm:
+
+- **Structure & hierarchy**: correct parent-child relationships, component nesting, section contents
+- **Node counts**: expected number of variants created, children present
+- **Naming**: variant property names follow the `property=value` convention
+- **Positioning & alignment**: x/y coordinates, width/height values match expectations
+- **Layout properties**: auto-layout direction, sizing mode, padding, spacing
+- **Component set membership**: all expected variants are inside the ComponentSet
+
+```
+Example: After creating a ComponentSet with 120 variants, call get_metadata on the
+ComponentSet node to verify all 120 children exist with correct names, sizes, and positions
+— without waiting for a full render.
+```
+
+**When to use `get_metadata`:**
+- After creating/modifying nodes — to verify structure, counts, and names
+- After layout operations — to verify positions and dimensions
+- After combining variants — to confirm all components are in the ComponentSet
+- After binding variables — to verify node properties (use use_figma to read bound variables if needed)
+- Between multi-step workflows — to confirm step N succeeded before starting step N+1
+
+### `get_screenshot` — Use after each major creation milestone
+
+`get_screenshot` renders a pixel-accurate image. It is the only way to verify visual correctness (colors, typography rendering, effects, variable mode resolution). It is slower and produces large responses, so don't call it after every single `use_figma` — but do call it after each major milestone to catch visual problems early.
+
+**When to use `get_screenshot`:**
+- **After creating a component set** — verify variants look correct, grid is readable, nothing is collapsed or overlapping
+- **After composing a layout** — verify overall structure and spacing
+- **After binding variables/modes** — verify colors and tokens resolved correctly
+- **After any fix or recovery** — verify the fix didn't introduce new visual issues
+- **Before reporting results to the user** — final visual proof
+
+**What to look for in screenshots** — these are the most commonly missed issues:
+- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
+- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
+- **Placeholder text** still showing ("Title", "Heading", "Button") instead of actual content
+
+## CRITICAL: Error Recovery After Failed `use_figma`
+
+> **THIS IS NOT OPTIONAL.** Every `use_figma` error MUST trigger the recovery steps below. Skipping these steps leaves orphaned nodes in the file that will cause duplicates and inconsistencies on retry.
+
+**Scripts can partially execute before hitting an error.** A failed `use_figma` does NOT roll back — nodes created before the error line persist in the file. This leaves the file in an **inconsistent, partially-modified state**.
+
+**Mandatory recovery steps when `use_figma` returns an error (DO NOT SKIP):**
+1. **STOP — do NOT immediately fix the code and retry.** The file has partial state that must be inspected first.
+2. **Immediately call `get_metadata`** on the parent node (section, page, or ComponentSet) to see what was partially created.
+3. **If `get_metadata` doesn't make the damage clear** (e.g. positions look fine but visual state is uncertain), call `get_screenshot` to assess visual damage.
+4. **Write a cleanup script** to remove orphaned/incomplete nodes before retrying. Use `page.findChildren()` to locate stray nodes.
+5. **Only after cleanup is confirmed**, fix the original script and retry.
+6. **Never retry the failed script blindly** — the partial state means a retry will create duplicates or hit new errors.
+
+```
+Example: A script creating 8 components fails on component #5.
+Components 1-4 exist on the page. A naive retry creates components 1-8 again,
+leaving 12 components total (4 orphaned duplicates). Always clean up first.
+```
+
+### Cleanup Pattern
+
+```js
+// Cleanup pattern: find and remove orphaned nodes from a failed run
+(async () => {
+  try {
+    const page = figma.currentPage;
+    // Find orphaned components that weren't combined into a ComponentSet
+    const orphans = page.findChildren(n =>
+      n.type === 'COMPONENT' && n.name.includes('variant=')
+    );
+    for (const orphan of orphans) orphan.remove();
+    figma.closePlugin('Cleaned up ' + orphans.length + ' orphaned nodes');
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+## Recommended Workflow
+
+```
+1. use_figma  →  Create/modify nodes
+2. get_metadata     →  Verify structure, counts, names, positions (fast, cheap)
+3. use_figma  →  Fix any structural issues found
+4. get_metadata     →  Re-verify fixes
+5. ... repeat as needed ...
+6. get_screenshot   →  Visual check after each major milestone
+
+⚠️ ON ERROR at any step:
+   a. get_metadata    →  Inspect partial state (always do this first)
+   b. get_screenshot  →  Only if metadata doesn't make the damage clear
+   c. use_figma →  Clean up orphaned/incomplete nodes
+   d. THEN retry the failed operation
+```