Agent skill · software engineering · jeremylongshore
figma-known-pitfalls
Avoid the most common Figma API integration mistakes and anti-patterns.
Why this skill is useful
Provides specific integration patterns and anti-patterns for the Figma API that the AI wouldn't reliably generate on its own.
What it needs
Requires figma account access. About 5k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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. Pitfall 2: Ignoring Rate Limit Headers Problem: Blasting requests and crashing on 429 without reading Retry-After. Pitfall 3: Caching Image Export URLs Too Long Problem: Figma image URLs expire after 30 days. Storing them permanently breaks. Pitfall 4: Hardcoded PATs Problem: Personal access tokens committed to source code. Pitfall 5: Using Deprecated files:read Scope Problem: The files:read scope is deprecated. New tokens should use granular scopes. Pitfall 6: Forgetting Color Format Conversion Problem: Figma returns colors as 0-1 floats, not 0-255 integers. Pitfall 7: Not Handling null Image Renders Problem: The images endpoint returns null for nodes that cannot be rendered (invisible, deleted, empty). Pitfall 8: Polling Instead of Webhooks Problem: Polling GET /v1/files/:key every 30 seconds wastes rate limit quota. Pitfall 9: SVG Export with Scale Parameter Problem: Figma ignores the scale parameter for SVG exports. SVGs always export at 1x. Pitfall 10: Webhook Without Passcode Verification Problem: Anyone can POST to your webhook endpoint if you don't verify the passcode. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/figma-known-pitfalls