Delivery Factory · Part 3 · Figma Extract

The Figma plugin, from design link to files

The design stage needs the values, the images and a screenshot of one Figma node. The plugin that provides them is a separate pack with one operation. This page follows it from the link to the files: which tools it calls, which scripts decide, and when it passes, asks a human or stops. Repo: agentic-figma

Checked in Code

Everything on this page was read in the plugin's skill, scripts, manifest and README, not only in the README. Paths are relative to plugins/figma/ unless said otherwise.

From link to files1200 × 627

One input line in, one verdict and a folder of files out. The model calls the tools. Which frames to fetch comes from scripts reading the metadata on disk.

The parts

A plugin of its own

The Figma pack plays one role in the pipeline: design. It has its own manifest, skill, scripts and tests, and it runs no server.

pack.yaml declares the role
kind: provider, role: design, one operation: fetch_reference → fetch-reference. It also lists the four tools only the session can provide, each with a remedy for when one is missing, so the run can check them before it does any work.
.claude-plugin/plugin.json names it
Name figma, version 0.1.0, one dependency: agentic-core. The project picks it as its design source with packs.design: figma in .ai/project-config.yaml.
skills/fetch-reference/SKILL.md is the flow
A decision graph from the link to a verdict, with one section per node. Its allowed tools are exactly the four Figma tools plus ToolSearch and Skill.
Five scripts decide
classify-node.py sorts the node. viewports.py plans the targets. fetch-assets.py downloads images and icons. sniff-asset.py names a file's format. screenshot-size.py sizes the screenshot request and records what came back.
Five offline test suites
One per script, 221 assertions in total, no network. They cover the scripts. The MCP calls themselves are not exercised by them.

Four tools from the Figma plugin

Each with one job

get_metadata: confirms the node exists; its name, size and children.
get_design_context: reference code whose classes carry layout, colour and type, and the download links for images and icons.
get_variable_defs: a map of token name to value. An empty map is a normal result.
get_screenshot: a short-lived image link with rendered and original size.

Before any call

Load, then use

The skill loads the four tools through ToolSearch, then loads figma:figma-design-to-code, which get_design_context asks for.
That skill is loaded for its prerequisite only. The operation writes no application code.
It never calls authenticate. An unattended run has nobody to open the sign-in link.

The classifier

Four classes, decided by a script

classify-node.py reads the metadata file from disk. The model reads its first line and never re-decides the class from names, sizes or the ticket.

single: one target
Anything that is not one of the three below. The node itself is fetched.
variants: one target per version
Every frame-like child belongs to one group of two or more viewport versions of the same design. Each is fetched, widest first.
page: a question
The node is a page. Every frame-like child is a candidate.
multi-frame: a question
A section, or children that mix variants with other frames, or hold several variant groups. Every frame-like child is a candidate.

A child is a viewport version when its own name matches a rule, checked in this order (pattern, keyword, width), or when size alone separates same-named frames:

Pattern: Hero / Desktop, Hero - Mobile, Desktop View, @mobile.

Keyword: a name token is desktop, mobile, tablet, responsive, phone or web.

Width: a name token is 1440, 1280, 1024, 768, 375, 390 or 414, with or without px.

Size: frames with the same base name where one is wider than 900 and one is narrower than 500.

# classification.tsv, one line per frame-like child (example names)
class	variants
node	frame	1:100	Logo Row
child	1:118	1200	variant	name:pattern=desktop	Logo Row / Desktop
child	1:131	720	variant	name:pattern=tablet	Logo Row / Tablet
child	1:144	375	variant	name:pattern=mobile	Logo Row / Mobile

A page or several frames: the question lists every candidate, none dropped, reordered or marked as preferred. Not even one whose name matches the work item.

The fetch

What it writes, and what it keeps out of files

Design values and images land in .ai/figma/ in a fixed shape. Download links are short-lived and never written down.

Check the link: a figma.com/design/ URL with a node-id. For a branch URL the branch key is used as the file key.
Load the four tools. get_metadata, then write its response whole to <file>-<node>.metadata.xml.
classify-node.py writes .classification.tsv. For variants, viewports.py plan prints one target per version, widest first, and only those are fetched.
Per target: get_design_context, with the screenshot left out of it. Keep the code block and the styles line verbatim.
The code block goes to fetch-assets.py on stdin. It downloads every image and icon, names each format from its bytes, and rewrites the code to point at local files.
get_variable_defs once, for the referenced node.
screenshot-size.py max sizes the request to the node's longer edge. get_screenshot per target, downloaded before the link expires.
Write <file>-<node>.json and report pass with the list of files written.

Formats from bytes. sniff-asset.py recognises png, jpg, gif, webp and svg from the first bytes of the file. The name or the URL is never trusted. Bytes of no known format stop the operation.

Files named by content. Each asset is written as the first 16 hex digits of its SHA-256 plus the extension. Identical bytes are one file. A name already holding different bytes is refused, so no earlier file is replaced.

No URL on disk. The asset links and the screenshot link exist only in the tool response and in the command that uses them. The script refuses a result that still contains one.

## Result
verdict: pass
summary: <node name> from <Figma file>
artifacts:
  - .ai/figma/<file>-<node>.json
  - .ai/figma/<file>-<node>.png
  - .ai/figma/<file>-<node>.metadata.xml
  - .ai/figma/<file>-<node>.classification.tsv
  - .ai/figma/<file>-<node>.context.txt
next_action: none
metrics: variables=<n> design_context=code
  node_class=single downscaled=0 assets=<n>

A design context returned as structure only, or cut short by the tool's size cap, is recorded as structure_only. It is a pass, not an error: metadata, tokens and the screenshot still cover the node.

Pass, ask, stop

Three verdicts, and the class behind a fail

The operation ends in exactly one of three verdicts. A fail always carries an error class, read off what the tool actually returned.

Pass
The link is one frame, or the viewport versions of one design. Every target is fetched, the files are written, the result lists them.
Question
The link has no node-id, or the node is a page or holds several frames. The question comes verbatim from classify-node.py --question, with one option per candidate from --options. No error class: it is a clarification the ticket's author can answer.
Fail · VALIDATION
The reference itself is wrong: not a figma.com/design/ URL (/file/, /board/, /slides/ and /make/ are not supported), or the file or node is not found, or the node id is malformed. Re-running it unchanged cannot succeed.
Fail · PERMANENT
The plugin is not installed, or installed but not authenticated, or the sign-in was rejected (401), or this session has no access (403). Also any error nothing else matches, because an unrecognised error is not evidence that retrying is safe. A script exit of 2 is here too: unreadable metadata, bytes of no known image format, an asset link that would be written.
Fail · TRANSIENT
A rate limit, a quota or a plan's call limit, a timeout, or an image download that failed. The only class that is retried: twice, after 2 seconds and then 4. If the third attempt fails, the operation reports a fail. It does not ask a question of its own, because only the stage that called it knows whether another source exists.

## Result
verdict: fail
summary: Figma is not authenticated: run /plugin,
  select figma, choose Authenticate, finish
  sign-in in the browser, then re-run.
artifacts: []
next_action: none
error_class: PERMANENT

The shape of a fail, with the exact summary the plugin uses when authentication is what is missing. The text tells the person what to do, not only that it failed.

The authentication remedy is also declared in pack.yaml for each of the four session tools, so the run can name it before any work starts.

What it doesn't cover

It reads the design as drawn

The plugin gets the values and the picture. It does not judge them.

Needs
The Figma plugin installed and signed in, and the network. The five test suites cover the scripts; the tool calls and the skill's own branching are not covered by them.
Scope
/design/ URLs only. One reference per call: the operation takes one reference: line and fetches that node and, when it holds viewport versions, each of them.
Next
Building the prototype against these files, and checking it in a real browser.

The Figma plugin, from design link to files

A plugin of its own

`pack.yaml` declares the role

`.claude-plugin/plugin.json` names it

`skills/fetch-reference/SKILL.md` is the flow

Five scripts decide

Five offline test suites

Each with one job

Load, then use

Four classes, decided by a script

`single`: one target

`variants`: one target per version

`page`: a question

`multi-frame`: a question

What it writes, and what it keeps out of files

Three verdicts, and the class behind a fail

It reads the design as drawn

The Figma plugin, from design link to files

A plugin of its own

pack.yaml declares the role

.claude-plugin/plugin.json names it

skills/fetch-reference/SKILL.md is the flow

Five scripts decide

Five offline test suites

Each with one job

Load, then use

Four classes, decided by a script

single: one target

variants: one target per version

page: a question

multi-frame: a question

What it writes, and what it keeps out of files

Three verdicts, and the class behind a fail

It reads the design as drawn

`pack.yaml` declares the role

`.claude-plugin/plugin.json` names it

`skills/fetch-reference/SKILL.md` is the flow

`single`: one target

`variants`: one target per version

`page`: a question

`multi-frame`: a question