figma-known-pitfalls

# Figma Known Pitfalls ## Overview The ten most common mistakes when integrating with the Figma REST API and Plugin API, with correct alternatives for each. ## Prerequisites - Working Figma integration to audit - Access to codebase ## Instructions ### Pitfall 1: Fetching Full File Trees **Problem:** `GET /v1/files/:key` without `depth` returns the entire document tree. Large files can be 10-100 MB of JSON. ```typescript // BAD -- downloads entire file tree const file = await figmaFetch(`/v1/files/${fileKey}`); // GOOD -- only get metadata and page names const file = await figmaFetch(`/v1/files/${fileKey}?depth=1`); // GOOD -- fetch only the nodes you need const nodes = await figmaFetch(`/v1/files/${fileKey}/nodes?ids=${ids}`); ``` ### Pitfall 2: Ignoring Rate Limit Headers **Problem:** Blasting requests and crashing on 429 without reading `Retry-After`. ```typescript // BAD -- no rate limit handling for (const id of nodeIds) { await figmaFetch(`/v1/files/${fileKey}/nodes?ids=${id}`); // 429! } // GOOD -- batch IDs and honor Retry-After const ids = nodeIds.join(','); const res = await fetch(`https://api.figma.com/v1/files/${fileKey}/nodes?ids=${ids}`, { headers: { 'X-Figma-Token': token }, }); if (res.status === 429) { const wait = parseInt(res.headers.get('Retry-After') || '60'); await new Promise(r => setTimeout(r, wait * 1000)); } ``` ### Pitfall 3: Caching Image Export URLs Too Long **Problem:** Figma image URLs expire after 30 days. Storing them perm...