/figma-generate-library

Part of the figma-generate-library skill.

Error Recovery Reference

Protocol for handling failures, partial state, and incomplete runs across a 20–100+ call design system build.

1. Core Protocol: STOP → Inspect → Identify → Clean → Fix → Retry

Never retry a failed script without cleanup first. A failed script may have created partial state — frames, components, or variables that are half-built. Retrying on top of partial state compounds the problem and can make recovery impossible.

The mandatory recovery sequence:

1. STOP   — Do not run any more use_figma writes.
2. INSPECT — Call get_metadata on the current page. Optionally call get_screenshot.
3. IDENTIFY — Find artifacts from the failed attempt using dsb_run_id pluginData tags.
4. CLEAN   — Run a targeted cleanup script to remove orphaned nodes (pluginData-based, never name-based).
5. VERIFY  — Run get_metadata again to confirm cleanup was complete.
6. FIX     — Correct the script that failed.
7. RETRY   — Re-run the corrected script from the last clean checkpoint.
8. PERSIST — Update the state ledger with the outcome.

Do not skip step 4 even if the failure seems minor. Partial frames and components accumulate and cause confusing results in later steps.

2. pluginData-Based Cleanup: Why Name Matching is Dangerous

Why name-prefix matching fails

A cleanup script that deletes "all nodes whose name starts with Button" will also delete nodes the user may have created manually with that name, or nodes from a previous approved phase. Name-based cleanup has no way to distinguish "orphan from a failed attempt" from "intentional user node."

Furthermore, variant names (Size=Medium, Style=Primary, State=Default) do not have consistent prefixes that are safe to target without also hitting legitimate nodes.

How setPluginData / getPluginData works

pluginData is a key-value store attached to individual nodes. It persists across sessions and is invisible to the user in the Figma UI. Only plugins with the same pluginId can read/write data scoped to that plugin. Use three keys:

node.setPluginData('dsb_run_id', 'ds-build-2024-001'); // identifies the build run
node.setPluginData('dsb_phase',  'phase3');             // which phase created this node
node.setPluginData('dsb_key',    'componentset/button');// unique logical key

// Reading:
const runId = node.getPluginData('dsb_run_id'); // returns '' if never set
const key   = node.getPluginData('dsb_key');

getPluginData returns '' (empty string, not null) for unset keys. Always check for !== ''.

Tag every created node immediately after creation — before any further operations that might fail. If a failure happens between createComponent() and the tagging line, the node will be an untagged orphan. To minimize this window, tag in the same statement sequence as creation:

const comp = figma.createComponent();
comp.setPluginData('dsb_run_id', RUN_ID);  // tag immediately
comp.setPluginData('dsb_key', key);         // tag immediately
// ... then do the rest of the setup

Complete cleanupOrphans script using dsb_run_id

This script finds all nodes tagged with a given dsb_run_id and optionally a dsb_phase filter, then removes them. Run it on the specific page where the failure occurred.

(async () => {
  try {
    const TARGET_RUN_ID = 'ds-build-2024-001'; // run ID to clean
    const TARGET_PHASE  = 'phase3';            // optionally filter by phase ('' = all phases)
    const PAGE_NAME     = 'Button';            // page to clean (or null for all pages)

    const pagesToSearch = PAGE_NAME
      ? [figma.root.children.find(p => p.name === PAGE_NAME)].filter(Boolean)
      : figma.root.children;

    const removed = [];
    const skipped = [];

    for (const page of pagesToSearch) {
      await figma.setCurrentPageAsync(page);

      const orphans = page.findAll(node => {
        const runId = node.getPluginData('dsb_run_id');
        if (runId !== TARGET_RUN_ID) return false;
        if (TARGET_PHASE && node.getPluginData('dsb_phase') !== TARGET_PHASE) return false;
        return true;
      });

      // Remove leaf-first to avoid removing parents before children
      // Sort by depth (deepest first) to avoid double-remove errors
      const sorted = orphans.slice().sort((a, b) => {
        let depthA = 0, depthB = 0;
        let n = a; while (n.parent) { depthA++; n = n.parent; }
        n = b; while (n.parent) { depthB++; n = n.parent; }
        return depthB - depthA;
      });

      for (const node of sorted) {
        try {
          if (node.removed) continue; // already removed (was a child of removed parent)
          node.remove();
          removed.push({ id: node.id, name: node.name, key: node.getPluginData('dsb_key') });
        } catch (e) {
          skipped.push({ id: node.id, name: node.name, error: e.message });
        }
      }
    }

    figma.closePlugin(JSON.stringify({ removed: removed.length, skipped: skipped.length, details: removed }));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

After running cleanup, call get_metadata on the target page to confirm the orphaned nodes are gone before retrying.

3. Idempotency Patterns: Check-Before-Create

Run an idempotency check at the start of every create operation. If the entity already exists (tagged with the expected dsb_key), skip creation and return the existing ID.

Check-before-create for a variable collection

(async () => {
  try {
    const KEY = 'collection/color';
    const RUN_ID = 'ds-build-2024-001';
    const COLLECTION_NAME = 'Color';

    // Check: does a collection tagged with this key already exist?
    const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
    // Variables/collections support pluginData too — check by name as fallback
    // Note: VariableCollection pluginData is set via collection.setPluginData(...)
    const existing = allCollections.find(c =>
      c.getPluginData('dsb_key') === KEY
    );

    if (existing) {
      figma.closePlugin(JSON.stringify({
        collectionId: existing.id,
        modeIds: existing.modes.map(m => ({ name: m.name, id: m.modeId })),
        alreadyExisted: true,
      }));
      return;
    }

    // Create fresh
    const collection = figma.variables.createVariableCollection(COLLECTION_NAME);
    collection.setPluginData('dsb_run_id', RUN_ID);
    collection.setPluginData('dsb_key', KEY);

    // Rename default mode, add second mode
    collection.renameMode(collection.modes[0].modeId, 'Light');
    const darkModeId = collection.addMode('Dark');

    figma.closePlugin(JSON.stringify({
      collectionId: collection.id,
      modeIds: [
        { name: 'Light', id: collection.modes[0].modeId },
        { name: 'Dark',  id: darkModeId },
      ],
    }));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

Check-before-create for a page

(async () => {
  try {
    const KEY = 'page/button';
    const PAGE_NAME = 'Button';
    const RUN_ID = 'ds-build-2024-001';

    // Check by pluginData key first, then by name as fallback
    let page = figma.root.children.find(p => p.getPluginData('dsb_key') === KEY);
    if (!page) {
      page = figma.root.children.find(p => p.name === PAGE_NAME);
    }

    if (page) {
      // Ensure it's tagged if it was found by name only
      if (!page.getPluginData('dsb_key')) {
        page.setPluginData('dsb_run_id', RUN_ID);
        page.setPluginData('dsb_key', KEY);
      }
      figma.closePlugin(JSON.stringify({ pageId: page.id, alreadyExisted: true }));
      return;
    }

    page = figma.createPage();
    page.name = PAGE_NAME;
    page.setPluginData('dsb_run_id', RUN_ID);
    page.setPluginData('dsb_key', KEY);

    figma.closePlugin(JSON.stringify({ pageId: page.id, alreadyExisted: false }));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

Check-before-create for a component set

(async () => {
  try {
    const KEY = 'componentset/button';
    const PAGE_ID = 'PAGE_ID_FROM_STATE';
    const RUN_ID = 'ds-build-2024-001';

    const page = await figma.getNodeByIdAsync(PAGE_ID);
    await figma.setCurrentPageAsync(page);

    const existing = page.findAll(n =>
      n.type === 'COMPONENT_SET' && n.getPluginData('dsb_key') === KEY
    );

    if (existing.length > 0) {
      figma.closePlugin(JSON.stringify({
        componentSetId: existing[0].id,
        alreadyExisted: true,
      }));
      return;
    }

    // ... proceed with creation
    figma.closePlugin(JSON.stringify({ componentSetId: null, alreadyExisted: false }));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

4. State Ledger

JSON Schema

Maintain a state ledger in your context (not in the Figma file) across calls. This is your source of truth for node IDs, completed steps, and pending validations.

{
  "runId": "ds-build-2024-001",
  "phase": "phase3",
  "step": "component-button/combine-variants",
  "completedSteps": [
    "phase0",
    "phase1/collections",
    "phase1/primitives",
    "phase1/semantics",
    "phase2/pages",
    "phase2/foundations-docs",
    "phase3/component-avatar",
    "phase3/component-icon"
  ],
  "entities": {
    "collections": {
      "primitives": "VariableCollectionId:1234:5678",
      "color":      "VariableCollectionId:1234:5679",
      "spacing":    "VariableCollectionId:1234:5680"
    },
    "variables": {
      "color/bg/primary":         "VariableId:2345:1",
      "color/bg/secondary":       "VariableId:2345:2",
      "color/bg/disabled":        "VariableId:2345:3",
      "color/text/on-primary":    "VariableId:2345:4",
      "color/text/on-secondary":  "VariableId:2345:5",
      "color/text/disabled":      "VariableId:2345:6",
      "spacing/sm":               "VariableId:2345:7",
      "spacing/md":               "VariableId:2345:8",
      "spacing/lg":               "VariableId:2345:9",
      "radius/md":                "VariableId:2345:10"
    },
    "modes": {
      "color/light": "2345:1",
      "color/dark":  "2345:2"
    },
    "pages": {
      "Cover":       "0:1",
      "Foundations": "0:2",
      "Button":      "0:3"
    },
    "components": {
      "Icon":        "3456:1",
      "Avatar":      "3456:2",
      "Button":      "3456:3"
    },
    "componentSets": {
      "Button": "4567:1"
    }
  },
  "pendingValidations": [
    "Button:metadata",
    "Button:screenshot"
  ],
  "userCheckpoints": {
    "phase0": "approved-2024-01-15",
    "phase1": "approved-2024-01-15",
    "phase2": "approved-2024-01-15",
    "component-avatar": "approved-2024-01-15"
  }
}

Persisting between calls

After every successful use_figma call:

1. Extract all IDs from the closePlugin return value
2. Add them to the appropriate entities section of the ledger
3. Add the completed step to completedSteps
4. Remove from pendingValidations if this call validated something
5. Update phase and step to the current position

Rehydrating at session start

If a conversation is interrupted and resumed, read the state ledger and verify key entities still exist:

(async () => {
  try {
    // Verify that critical nodes from the ledger still exist
    const toVerify = {
      'color-collection':  'VariableCollectionId:1234:5679',
      'button-page':       '0:3',
      'button-componentset': '4567:1',
    };

    const results = {};
    for (const [label, id] of Object.entries(toVerify)) {
      const node = await figma.getNodeByIdAsync(id)
        .catch(() => null);
      results[label] = node ? { found: true, name: node.name } : { found: false };
    }

    figma.closePlugin(JSON.stringify(results));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

If any entity is missing, treat the phase that created it as incomplete and re-run from that checkpoint.

5. Resume Protocol

Step 1: Inspect the file for dsb_run_id tags

(async () => {
  try {
    const TARGET_RUN_ID = 'ds-build-2024-001';
    const inventory = { pages: [], variables: [], componentSets: [], frames: [] };

    // Scan pages
    for (const page of figma.root.children) {
      if (page.getPluginData('dsb_run_id') === TARGET_RUN_ID) {
        inventory.pages.push({ id: page.id, name: page.name, key: page.getPluginData('dsb_key') });
      }
    }

    // Scan variables
    const allVars = await figma.variables.getLocalVariablesAsync();
    for (const v of allVars) {
      if (v.getPluginData('dsb_run_id') === TARGET_RUN_ID) {
        inventory.variables.push({ id: v.id, name: v.name, key: v.getPluginData('dsb_key') });
      }
    }

    // Scan all component sets and frames on each page
    for (const page of figma.root.children) {
      await figma.setCurrentPageAsync(page);
      const nodes = page.findAll(n => n.getPluginData('dsb_run_id') === TARGET_RUN_ID);
      for (const n of nodes) {
        if (n.type === 'COMPONENT_SET') {
          inventory.componentSets.push({ id: n.id, name: n.name, key: n.getPluginData('dsb_key') });
        } else if (n.type === 'FRAME') {
          inventory.frames.push({ id: n.id, name: n.name, key: n.getPluginData('dsb_key') });
        }
      }
    }

    figma.closePlugin(JSON.stringify(inventory));
  } catch (e) { figma.closePluginWithFailure(e.toString()); }
})();

Step 2: Reconstruct state from inventory

Map the inventory keys back to the state ledger schema. For each entity found with a dsb_key, add its ID to the appropriate section. Mark the corresponding step as completedSteps.

Example mapping:

key: 'collection/color'        → entities.collections.color
key: 'variable/color/bg/primary' → entities.variables['color/bg/primary']
key: 'page/button'             → entities.pages.Button
key: 'componentset/button'     → entities.componentSets.Button

Step 3: Identify the resume point

The resume point is the first step in the workflow that is NOT in completedSteps. If the inventory shows the Button component set exists but the pending validations list shows 'Button:screenshot', the resume point is the screenshot validation call, not re-creation.

Use the checkpoint table from the workflow to determine which phase to continue from:

Phase 0 complete: all planned pages listed in entities.pages
Phase 1 complete: all planned variables listed in entities.variables with correct scopes
Phase 2 complete: all structural pages + foundations doc frames present
Phase 3 complete (per component): componentSet exists + no pending validations + user checkpoint recorded

6. Failure Taxonomy

Recoverable Errors

These can be fixed and retried without affecting already-created entities:

Structural Corruption (Requires Rollback or Restart)

These errors leave the file in a state where continuing forward is unreliable:

Recovery from structural corruption: run cleanupOrphans for the entire run ID, then restart from the affected phase. Do NOT attempt to patch corrupted structure in-place.

7. Common Error Table

8. Per-Phase Recovery Guidance

Phase 1 fails mid-execution (variable creation)

Symptoms: partial variable collections exist; some variables are missing; some have wrong values.

Recovery steps:

1. Run inspection script to find all variables tagged with your dsb_run_id
2. For each variable with dsb_key matching the plan, verify its valuesByMode and scopes are correct
3. If a variable is malformed, call variable.remove() and recreate it
4. If the collection itself is malformed, remove the entire collection and recreate from scratch
5. Do NOT proceed to Phase 2 until ALL planned variables exist with correct scopes and code syntax

The most common Phase 1 failure: running out of time in a single use_figma call when creating many variables. Fix: batch variable creation — create at most 20–30 variables per call.

Phase 2 fails mid-execution (page/file structure)

Symptoms: some pages exist, others are missing; foundations doc frames are incomplete.

Recovery steps:

1. Identify which pages were successfully created (check for dsb_key tags)
2. Mark remaining pages as pending and create them in subsequent calls
3. If a foundations doc frame is malformed, run cleanupOrphans for dsb_phase: 'phase2' on that page, then recreate

Phase 2 failures rarely require Phase 1 rollback unless the page structure itself is corrupted (which is unusual).

Phase 3 fails mid-execution (component creation)

This is the most common failure mode in long builds. Handle by component:

If failure in Call 1 (page creation):
  → Idempotency check will handle on retry. Safe to re-run.

If failure in Call 2 (doc frame):
  → cleanupOrphans for dsb_key='doc/{component}', then re-run.

If failure in Call 3 (base component):
  → Remove the partial base component node, re-run from Call 3.

If failure in Call 4 (variant creation):
  → cleanupOrphans for dsb_phase='phase3' on the component page (scoped by page).
  → Re-run from Call 3 (base) or Call 4 if base was successfully tagged.

If failure in Call 5 (combineAsVariants + layout):
  → Remove the malformed component set.
  → Remove all variant ComponentNodes for this component (by dsb_key pattern).
  → Re-run from Call 3.

If failure in Call 6 (component properties):
  → The component set already exists and is structurally sound.
  → Re-run Call 6 only — addComponentProperty is safe to retry if
    you first check componentPropertyDefinitions for existing properties.
  → Idempotency check: if 'Label' property already exists, skip addComponentProperty.

Idempotency for component properties (Call 6 retry):

const existingDefs = cs.componentPropertyDefinitions;
const labelKey = existingDefs['Label']
  ? Object.keys(existingDefs).find(k => k.startsWith('Label'))
  : cs.addComponentProperty('Label', 'TEXT', 'Button');

Phase 4 fails mid-execution (QA / Code Connect)

Phase 4 is non-destructive. Failures here do not corrupt Phase 3 work. Common failures:

• Accessibility audit finds contrast failures: do not attempt auto-fix. Report the specific variable IDs and token names that fail, then ask the user which value to update.
• Naming audit finds duplicates: list all duplicates with their dsb_key values, ask user which to keep, then remove the duplicates.
• Code Connect mapping fails: treat as incomplete, not broken. Continue and leave as pending.