/figma-use

Validation Workflow & Error Recovery

Part of the use_figma skill. How to debug, validate, and recover from errors.

Contents

• get_metadata vs get_screenshot
• Error Recovery After Failed use_figma
• 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

Error Recovery After Failed use_figma

use_figma is atomic — failed scripts do not execute. If a script errors, no changes are made to the file. The file remains in exactly the same state as before the call. There are no partial nodes, no orphaned elements, and retrying after a fix is safe.

Recovery steps when use_figma returns an error:

1. STOP — do NOT immediately fix the code and retry. Read the error message carefully first.
2. Understand the error. Most errors are caused by wrong API usage, missing font loads, invalid property values, or referencing nodes that don't exist.
3. If the error is unclear, call get_metadata or get_screenshot to understand the current file state and confirm nothing has changed.
4. Fix the script based on the error message.
5. Retry the corrected script.

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. Read the error message carefully
   b. get_metadata / get_screenshot  →  If the error is unclear, inspect file state
   c. Fix the script based on the error
   d. Retry the corrected script (safe — failed scripts don't modify the file)