Turn a Figma ready for dev version into a Jira handoff ticket

When a designer publishes a named version in Figma that signals the work is ready for engineering, I want an agent to assemble the whole handoff for me. Trigger this from a Figma webhook on file version updates (FILE_VERSION_UPDATE), which fires when someone deliberately names a version rather than on ordinary autosaves. Only continue when the version name contains my handoff keyword. Make that keyword configurable, default it to "Ready for dev", and match it case-insensitively. If the version name does not contain the keyword, stop without doing anything.

Before touching the file, confirm it is a Figma Design file. The file and dev resource endpoints only support Design files, so a FigJam board (/board/) or a Slides deck (/slides/) should be skipped cleanly instead of failing with a file type error.

Use Get File Versions to identify the newly named version and the version immediately before it. Use Get File Nodes to inspect the frames that changed between those two versions. Keep the scope to just those top level frames rather than pulling the whole document tree, because Get File and Render Images are the most expensive Figma endpoints and the most likely to hit rate limits. Node IDs also need converting in both directions: Figma URLs use hyphens (node-id=1-2) but the API expects colons (1:2), so send colons to the API and build hyphens back into any link you create.

Before creating anything, call Get Dev Resources for those frames. This decides the path for each frame. A frame with no linked ticket gets a brand new Jira issue. A frame that already has a linked ticket must not get a duplicate issue, so use Update Dev Resources to refresh the name or URL of the existing resource instead.

For the frames that need a new ticket, use Render Images of File Nodes to capture a PNG preview of each changed frame, and use Get Comments to pull in any designer notes sitting on those frames. Ignore comments that have already been resolved, since the point is to surface what is still open.

Then draft a plain-language handoff spec covering three things: what changed between the two versions, which screens and states are affected, and what is still an open question based on the unresolved comments. Write it for an engineer who has not been following the design work, so skip the design jargon and be specific about states such as empty, loading, and error wherever the frames show them.

Create the ticket with the Jira Create Issue operation. Put the handoff spec in the description, include the rendered frame previews, and include a deep link back to the exact Figma frame. Note that the Jira integration creates the issue and its description in one step and has no separate file upload operation, so the previews go into the description as image links rather than as uploaded attachments. Jira's description field uses Atlassian Document Format, so structure the spec as real paragraphs and headings. Figma render URLs expire after 30 days, so label the preview links with that expiry and treat the Figma deep link as the permanent reference for the ticket.

Once the issue exists, use Create Dev Resources to attach the new Jira ticket URL onto that frame inside Figma, so designers see the linked ticket in Dev Mode. Figma caps dev resources at 10 per node, so if a frame is already at the cap, update the least relevant existing resource rather than trying to add an eleventh.

Finally, post to my engineering channel using the Slack Send a Message operation. The message should name the file and the version, summarize what changed in a couple of lines, call out anything still open, and link both the Jira ticket and the Figma frame.

This needs Figma permissions for file contents, version history, comments, and dev resources, including write access to dev resources so the ticket link can be written back into the file.