1# Validation Workflow & Error Recovery
2 
3> Part of the [use_figma skill](../SKILL.md). How to debug, validate, and recover from errors.
4 
5## Contents
6 
7- `get_metadata` vs `get_screenshot`
8- Error Recovery After Failed `use_figma`
9- Recommended Workflow
10 
11 
12## `get_metadata` vs `get_screenshot`
13 
14After 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.
15 
16### `get_metadata` — Use for intermediate validation (preferred)
17 
18`get_metadata` returns an XML tree of node IDs, types, names, positions, and sizes. Use it to confirm:
19 
20- **Structure & hierarchy**: correct parent-child relationships, component nesting, section contents
21- **Node counts**: expected number of variants created, children present
22- **Naming**: variant property names follow the `property=value` convention
23- **Positioning & alignment**: x/y coordinates, width/height values match expectations
24- **Layout properties**: auto-layout direction, sizing mode, padding, spacing
25- **Component set membership**: all expected variants are inside the ComponentSet
26 
27```
28Example: After creating a ComponentSet with 120 variants, call get_metadata on the
29ComponentSet node to verify all 120 children exist with correct names, sizes, and positions
30— without waiting for a full render.
31```
32 
33**When to use `get_metadata`:**
34- After creating/modifying nodes — to verify structure, counts, and names
35- After layout operations — to verify positions and dimensions
36- After combining variants — to confirm all components are in the ComponentSet
37- After binding variables — to verify node properties (use use_figma to read bound variables if needed)
38- Between multi-step workflows — to confirm step N succeeded before starting step N+1
39 
40### `get_screenshot` — Use after each major creation milestone
41 
42`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.
43 
44**When to use `get_screenshot`:**
45- **After creating a component set** — verify variants look correct, grid is readable, nothing is collapsed or overlapping
46- **After composing a layout** — verify overall structure and spacing
47- **After binding variables/modes** — verify colors and tokens resolved correctly
48- **After any fix or recovery** — verify the fix didn't introduce new visual issues
49- **Before reporting results to the user** — final visual proof
50 
51**What to look for in screenshots** — these are the most commonly missed issues:
52- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
53- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
54- **Placeholder text** still showing ("Title", "Heading", "Button") instead of actual content
55 
56## Error Recovery After Failed `use_figma`
57 
58**`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.
59 
60**Recovery steps when `use_figma` returns an error:**
611. **STOP — do NOT immediately fix the code and retry.** Read the error message carefully first.
622. **Understand the error.** Most errors are caused by wrong API usage, missing font loads, invalid property values, or referencing nodes that don't exist.
633. **If the error is unclear**, call `get_metadata` or `get_screenshot` to understand the current file state and confirm nothing has changed.
644. **Fix the script** based on the error message.
655. **Retry** the corrected script.
66 
67## Recommended Workflow
68 
69```
701. use_figma  →  Create/modify nodes
712. get_metadata     →  Verify structure, counts, names, positions (fast, cheap)
723. use_figma  →  Fix any structural issues found
734. get_metadata     →  Re-verify fixes
745. ... repeat as needed ...
756. get_screenshot   →  Visual check after each major milestone
76 
77⚠️ ON ERROR at any step:
78   a. Read the error message carefully
79   b. get_metadata / get_screenshot  →  If the error is unclear, inspect file state
80   c. Fix the script based on the error
81   d. Retry the corrected script (safe — failed scripts don't modify the file)
82```
83