DEV Community: Roman Tsisyk

EAGLE-4 does not run on a Mac. I measured MTP instead: +92% on one model, -19% on another

Roman Tsisyk — Wed, 21 Oct 2026 21:24:28 +0000

A release announcement for EAGLE-4, a speculative decoding method, reported up to 3.4x faster generation for Qwen3.8-27B on four NVIDIA B300 GPUs. I run local models on a Mac Studio, and I wanted to know one thing: does it make my models faster?

The short answer: EAGLE-4 as released does not run on a Mac. But my runtime already has a related technique, MTP (multi-token prediction), and I can measure that. The result depends strongly on the model:

On a dense 27B model, MTP made code generation 92% faster (thinking off, one request).
On a 35B mixture-of-experts (MoE) model, MTP made prose generation 19% slower (thinking off, one request).
With MTP on, the output text changed at temperature 0 in 7 of 8 test cases. I did not measure quality yet.

This post covers speed only. All numbers below come from my own runs, except the EAGLE-4 numbers, which come from the EAGLE-4 README.

What EAGLE-4 is, and why I did not test it

Speculative decoding works like this. A small, fast drafter proposes several next tokens. The large model checks all of them in one forward pass and keeps the tokens that match its own choice. If most drafts are correct, you get several tokens for the cost of about one large-model pass.

EAGLE-4 is a trained drafter for this job. Facts from the official repository (github.com/eagle-hq/eagle-4, package eagle-harness):

The drafter is EAGLE-Corp/Qwen3.8-27B-EAGLE4: 3B parameters, BF16.
It runs inside SGLang, vLLM and TokenSpeed (experimental).
The quick start requires Linux, four NVIDIA GPUs with a CUDA 13 driver and about 70 GB of disk. A separate guide covers AMD Instinct MI355X.
The README does not mention Metal, MLX, llama.cpp or Apple Silicon.
The license is source-available, not OSI-approved. Read LICENSE and NOTICE in the repository for the terms.

The README reports these speedups for Qwen3.8-27B at temperature 0. Each value is EAGLE-4 throughput divided by the same engine without speculation:

Engine and hardware	1 request	8 concurrent	32 concurrent	64 concurrent
SGLang, 4x B300	3.40x	1.91x	–	1.35x
vLLM, 4x B300	2.99x	1.70x	–	1.16x
TokenSpeed (experimental)	–	2.02x	–	1.42x
SGLang, 1x AMD MI355X	–	2.07x	1.56x	–

Two notes. First, the gain falls as concurrency rises, as expected: a fuller batch leaves less idle compute for verification. Second, a news post quoted "3.59x vs vanilla MTP". I did not find that figure in the README. The README baseline is the same engine without speculation, not MTP.

Pointers to related work on Apple Silicon (I did not verify these results):

An EAGLE-3 prototype for MLX: mlx-lm discussion #890.
MTPLX (github.com/youssofal/MTPLX) and dflash-mlx (github.com/bstnxbt/dflash-mlx).
A post on aiweekly.co (aiweekly.co) says MTP makes M1 to M3 chips up to 25% slower. This report is anecdotal, and other reports disagree with it.

I found no EAGLE-4 result on a Mac or on MLX anywhere. So I tested the technique that I can run.

What I tested

Some new models ship with an MTP head: a small extra layer, trained with the model, that predicts tokens further ahead. A runtime can use this head as the drafter. You do not need a separate draft model. My runtime, oMLX, calls this feature "Lightning MTP" and turns it on per model with mtp_enabled.

Hardware and software

Mac Studio, Apple M2 Ultra (60 GPU cores), 64 GB unified memory, macOS 26.5.
oMLX 0.7.1rc1, an OpenAI-compatible server for Apple Silicon.

Models

Model	Type	Loaded size	Notes
Qwen3.8-27B oQ4e-mtp (Jundot)	Dense, 27B	16.2 GB	Hybrid Gated DeltaNet and full attention, 64 layers, mixed 4/5-bit, 4.887 bits/weight
Ornith-1.5-35B-A3B oQ4e-mtp (LookUpMark)	MoE, 35B total	20.5 GB	256 experts, 8 per token, about 3B active
Qwen3-4B-Instruct-2507 4-bit (mlx-community)	Dense, 4B	2.3 GB	Control, no MTP head

Method

One model per server process. A fresh server for each phase, in the order OFF, ON, OFF, ON.
Temperature 0, streaming, one request at a time unless stated.
Prefix cache off (--no-cache), oMLX memory guard off.
Two prompts: a Kotlin coding task and a 350-word prose explanation. Each with thinking on and thinking off.
10 runs per prompt per phase, 512 max tokens. Warm-up runs to compile kernels are not counted.
Decode tok/s = completion tokens / (time of last streamed chunk − time of first chunk). This excludes time to first token.
Prefill = the server's prompt_eval_duration for Python standard-library source code as the prompt: 2,037, 3,913, 7,875 and 16,125 tokens, 5 runs each.
A sampler recorded GPU use, memory, swap and thermal state every 2 seconds.

Limits of this test

One machine, one runtime version, community quantizations of each model.

Temperature 0 only. Sampling at higher temperatures can lower draft acceptance.

Background processes (a browser, Activity Monitor, a code-indexing tool) used CPU during parts of the runs.

Qwen MTP-off phases agree within 1.4%. Ornith has more spread: a standard deviation of up to 3.9 tok/s with MTP off (one phase with four slow runs excluded, see below) and up to 10.5 tok/s with MTP on.

Prefill, long-context and concurrency tests ran in one phase only, with 3 to 5 runs each.

Swap stayed at or below 100 MB for the whole run, the CPU speed limit stayed at 100%, and the server logged zero "Prefill throttled" lines.

Results

Decode speed

Values are mean tok/s over 20 runs (2 phases × 10 runs). "Parked" counts runs in which oMLX paused MTP and used normal decoding for 128 tokens (log line: "parked for 128 standard tokens"). I did not check the exact rule that oMLX uses to decide this.

Model	Scenario	MTP off	MTP on	On / off	Parked runs
Qwen3.8-27B (dense)	Code, thinking off	33.6	64.3	1.92x	0 / 20
	Prose, thinking off	33.7	41.6	1.23x	1 / 20
	Code, thinking on	33.5	46.7	1.39x	1 / 20
	Prose, thinking on	33.6	33.9	1.01x	20 / 20
Ornith-1.5-35B-A3B (MoE)	Code, thinking off	132.5	147.9	1.12x	0 / 20
	Prose, thinking off	133.1	107.6	0.81x	0 / 20
	Code, thinking on	132.7	144.8	1.09x	0 / 20
	Prose, thinking on	118.0*	109.8	0.93x*	0 / 20

* In the second MTP-off phase, four runs dropped to 38 to 112 tok/s. During those runs, the sampler shows a background code-indexing process at high CPU use and GPU use falling well below normal. With medians, this cell is 132.7 off and 111.4 on, a ratio of 0.84x.

Three things stand out:

On the dense model, MTP helps on every task but one. The gain is largest on code without thinking.
On the MoE model, MTP helps a little on code and hurts on prose.
Parking did not protect Ornith. It parked MTP in all 20 Qwen prose-with-thinking runs, which kept that case at +1%. It never parked MTP in Ornith's 512-token runs, even when they were 19% slower.

The control model, Qwen3-4B, ran at 159.2 to 159.9 tok/s in all four scenarios. (It has no thinking mode, and its output was the same with thinking on and off.) Ornith, with 35B total parameters, decodes at 83% of the speed of this 4B dense model. With MTP off, Ornith decodes 3.95x faster than Qwen3.8-27B on a single request.

Prefill

Prefill is the time to read the prompt before the first token. Values are server-side, with MTP off.

Prompt tokens	Qwen3.8-27B time	Qwen3.8-27B tok/s	Ornith time	Ornith tok/s
2,037	8.0 s	253	1.2 s	1,771
3,913	16.6 s	236	2.3 s	1,679
7,875	33.8 s	233	4.8 s	1,641
16,125	75.2 s	215	11.9 s	1,358

With 16,125 prompt tokens, Qwen3.8-27B waits 75.2 seconds before the first token. Ornith waits 11.9 seconds. MTP does not help prefill. With MTP on, prefill was 1.7% to 6.2% slower for Qwen and 2.5% to 3.7% slower for Ornith.

Long context and concurrency

These tests used thinking off. Concurrency requests alternate between the code prompt and the prose prompt. Aggregate tok/s = all completion tokens / wall time, so it includes time to first token.

Test	Qwen off	Qwen on	On / off	Ornith off	Ornith on	On / off
Long context: 7,878-token prompt, 300 tokens out (5 runs)	32.0	37.5	1.17x	124.3	110.5	0.89x
1 request, decode only (reference from the first table)	33.6	52.9	–	132.8	127.7	–
2 concurrent requests, aggregate (3 runs)	43.3	66.7	1.54x	158.4	174.1	1.10x
4 concurrent requests, aggregate (3 runs)	49.5	85.6	1.73x	217.5	199.9	0.92x

The 1-request row is a different metric (decode only, the mean of code and prose). I show it only for scale. On the dense model, MTP still helps with four requests in parallel. On Ornith with the long prompt, oMLX parked MTP in all 5 runs, and the result was still 11% slower than MTP off.

Why the dense and MoE models differ

This section is my explanation of the data. The numbers come from oMLX's own MTP log lines. The cause is an inference that I did not prove with a profiler.

Each MTP cycle drafts several tokens and verifies them in one pass of the main model. Two numbers decide the result:

Tokens per cycle: how many tokens one cycle produces.
Cycle cost: how long one cycle takes, in units of one normal decode step with MTP off.

The speedup is about tokens per cycle divided by cycle cost. This is accounting, not a model, but it shows which factor matters. Values below come from runs that were not parked.

Model	Scenario	Accept rate	Tokens per cycle	Cycle cost (normal steps)	Measured on / off
Qwen3.8-27B	Code, thinking off	93.4%	4.20	2.16	1.92x
	Prose, thinking off	69.6%	2.64	2.11	1.23x
	Code, thinking on	77.5%	3.09	2.17	1.39x
Ornith-1.5-35B-A3B	Code, thinking off	85.2%	3.12	2.73	1.12x
	Prose, thinking off	63.7%	2.13	2.58	0.81x
	Code, thinking on	83.0%	3.05	2.73	1.09x
	Prose, thinking on	65.7%	2.18	2.58	0.84x (medians)

Qwen prose with thinking on is not in the table, because MTP was parked in every run.

The acceptance rates are similar. Ornith on code accepted 85% of drafts, more than Qwen on code with thinking on (78%). The big difference is cycle cost. A Qwen cycle costs about 2.1 to 2.2 normal steps. An Ornith cycle costs about 2.6 to 2.7. So Ornith needs about 2.6 tokens per cycle only to break even, and on prose it produces about 2.1.

Why is verification more expensive for the MoE model? My explanation: in a dense model, all tokens in the verification pass use the same weights, so one read of the weights from memory serves several tokens. In an MoE model, each token selects 8 of 256 experts, and different tokens select different experts. Verifying four or five tokens therefore reads many more expert weights than one normal step does. Also, a normal Ornith step is short (7.5 ms against 29.8 ms for Qwen), so any fixed cost per cycle is a larger share. In the logs, the main model's pass takes 92% of Ornith's cycle time and 96% of Qwen's. I did not profile the kernels, so treat this as a hypothesis. It can also be a property of the oMLX implementation and not of MoE models in general.

MTP changed the output text

Speculative decoding with greedy verification is supposed to produce exactly the text the model produces alone. In my runs, it did not:

With MTP off, every scenario produced one identical text across all 20 runs.
With MTP on, the output matched the MTP-off text in only one scenario: Qwen code with thinking off (20 of 20 runs).
In the other seven scenarios, 0 of 20 runs matched. The first difference appeared between character 26 and character 423, depending on the scenario, and the texts continued differently after it. The MTP-on texts also differed from each other between runs.

In the samples I read, the differences are changes of wording, not obvious errors. But I did not measure quality, so I cannot say if they matter. One possible cause is small numerical differences between the multi-token verification pass and the normal single-token pass. Such differences can flip a near-tie between two tokens. I did not prove this. For the speed numbers, it means that MTP on and MTP off produced texts of the same length (almost all runs reached the 512-token limit), but not the same texts.

Practical takeaways

These apply to these models on oMLX 0.7.1rc1 and an M2 Ultra:

Turn MTP on for Qwen3.8-27B on code. It gave +92% with thinking off and +39% with thinking on.
Leave MTP off for Ornith-1.5-35B-A3B by default. It gave +9% to +12% on code, but −7% to −19% on prose, −11% with a long prompt and −8% with four parallel requests.
Measure each model. Dense or MoE mattered more for the result than any headline number for the technique.
For agents, prefill matters as much as decode. The dense model needs 75 seconds to read a 16k-token prompt, and MTP makes prefill slightly slower. With MTP off, Ornith reads the same prompt in 12 seconds.
Check output quality before you rely on MTP. It changed the text in 7 of 8 scenarios.

What I did not measure

Quality of any output, with MTP on or off. Ornith's 4x decode speed says nothing about whether its code is as good as Qwen's.
Temperatures above 0.
Other runtimes (llama.cpp, mlx-lm directly, LM Studio) and other drafters (EAGLE-3, DFlash).
Other Apple chips. An M1, M3 or M4 has different bandwidth and compute, and the balance can change.
Prompts longer than 16k tokens, and real agent sessions with tool calls.
Energy use.

What comes next

The next test is quality. I will use real commits from my open-source Kotlin Multiplatform app, MyEuroStatApp, as tasks. I will compare what these local models produce, with MTP on and off, against the output of my usual coding-agent workflow on the same commits. I do not have results yet, and I do not know what they will show.

Reproduce it

The scripts are here: github.com/RomanTsisyk/mtp-bench-m2ultra. The repository contains:

suite.py: the benchmark. It starts one oMLX server per phase, runs the warm-up, decode, prefill, long-context and concurrency tests, and writes summary.json, outputs.jsonl and server.log for each phase.
sampler.py: records GPU use, memory, swap, CPU speed limit and the top processes every 2 seconds.
run_all.sh: runs the full plan in the order I used.
verify_numbers.py: recomputes every number in this post from the raw files.

To repeat the test:

Install oMLX 0.7.1rc1 and download the three models from Hugging Face.
Close other heavy applications. Background CPU load affected some of my runs.
Run ./run_all.sh. The full plan took about 1 hour 43 minutes on my machine.
Run python3 -I verify_numbers.py <results folder> and compare its output with the tables above.

If you run it on a different Mac, I want to see your numbers, especially for MoE models on M3 and M4 chips.

Claude Code + Figma: A Deterministic Design Handoff Pipeline

Roman Tsisyk — Mon, 10 Aug 2026 15:47:36 +0000

Screenshot prompting has a ceiling. You paste the design, the model makes a plausible approximation, you correct it, and on the next turn it drifts again. Nothing is anchored. The model has no source of truth to check itself against between turns.

A context bundle changes the contract. Instead of a pixel reference the model has to interpret every time, you get a structured, referenceable set of files — design tokens, layout IR, component inventory, UI strings — that stay in the session and stay consistent. Claude Code can read them, implement from them, and check its own output against them on demand. This post walks the full pipeline, from bundle export to a reviewed, token-verified implementation, using figmascope, a browser tool that turns any Figma file into exactly that bundle.

What makes this deterministic

Three things make the bundle referenceable rather than interpretable:

Tokens are typed and keyed. tokens.json maps semantic names (spacing.16, color.7f5cfe) to exact values. The model can check its output against the file without re-processing the design.
The IR is a tree, not pixels. screens/home.json describes the layout in terms of stack/overlay/absolute/leaf nodes — the same abstraction the implementation target (Compose, React, etc.) uses. There's no visual interpretation step.
The bundle is stable across turns. Once it's in the repo, every prompt in the session can reference the same files. Token drift is detectable: ask the model to compare its output against tokens.json and it can do it mechanically.

Step 1: Generate the bundle

Open figmascope.dev in your browser. Paste your Figma file URL. The exporter runs client-side using the Figma REST API — your Figma personal access token is stored in localStorage and never sent to figmascope's servers.

Click Export Agent Context. The page exports top-level frames, resolves design tokens, builds the IR, and downloads context-bundle.zip.

Step 2: Unzip into your project

# from your project root
unzip ~/Downloads/context-bundle.zip -d ./design/

# confirm what you have
find design/ -type f | sort
# design/CONTEXT.md
# design/_meta.json
# design/components/inventory.json
# design/screens/home.json
# design/screens/home.png
# design/screens/settings.json
# design/screens/settings.png
# design/strings.json
# design/tokens.json

The directory name doesn't matter — design/ is just a convention. What matters is that Claude Code can read the files from the working directory.

Step 3: Start Claude Code in your repo

cd my-app
claude

Claude Code starts in your repo root with full file access. It can read, write, and reference any file in the tree across the entire session — this is the key capability that makes the bundle pattern work.

Step 4: Orient the agent

Start with a reading prompt before any implementation. This loads the spec into the session context and lets you verify the export looks right before writing any code.

Read ./design/CONTEXT.md and tell me:
1. What target framework is this bundle for?
2. What token files does it reference?
3. Are there any warnings I should know about before implementing?

Claude will report back the target (Jetpack Compose by default), the token source, and any warnings from the CONTEXT.md header — gradient fills, missing token mappings, unsupported effects. You catch these now, not after generating 200 lines of code.

Follow up with a quick token check:

List the top 10 color tokens from ./design/tokens.json.
Then list the spacing tokens.

This confirms the token file parsed correctly and gives you a mental model of the palette before implementation.

Step 5: Implement a screen

Now the implementation prompt. Be explicit about which files are authoritative for which decisions:

Implement ./design/screens/home.json as a Jetpack Compose screen.

Rules:
- CONTEXT.md constraints apply. Read it if you haven't already.
- All spacing, color, and radius values must come from ./design/tokens.json.
  Map token keys to the appropriate Compose primitives (e.g. spacing.16 → 16.dp).
- UI strings must use keys from ./design/strings.json via stringResource().
  Fall back to the "fallback" field value if no resource ID is available yet.
- The IR node kinds map as follows:
    stack (axis:vertical)   → Column
    stack (axis:horizontal) → Row
    overlay                 → Box
    absolute                → Box with Modifier.offset
    leaf (text)             → Text with TextStyle
    leaf (rectangle)        → Box with Modifier.background
- Do not invent any value not present in the token or IR files.
  If something is missing, leave a TODO comment with the token key you expected.

Claude Code will read the IR, walk the node tree, map each node to its Compose primitive, and pull token values by key. The output is traceable: every .dp value should correspond to a spacing token, every Color(0xFF...) should match a color token.

Step 6: Detect and fix token drift

After the first implementation pass, run a drift check before reviewing visually. This is the key advantage of the bundle over screenshot prompting — you can ask the model to verify its own output mechanically.

Compare every color value in the generated HomeScreen.kt against ./design/tokens.json.
List any hex values in the output that don't correspond to a color token key.
For each one, identify the correct token and replace the hardcoded value.

Do the same for spacing:

Compare every .dp value in HomeScreen.kt against the spacing tokens in ./design/tokens.json.
Flag any value that doesn't match a spacing token. Replace with the correct token reference.

This loop — implement, check drift, fix — converges fast. By the second or third pass, the output is fully token-referenced.

Tip: include `_meta.json` warnings in your first prompt

design/_meta.json contains a warnings array. These are things the exporter couldn't fully resolve: gradient fills, embedded images, effects without a token equivalent. Read them before implementing:

cat design/_meta.json

If the output includes something like:

{
  "warnings": [
    "node 'hero-background': gradientFill not fully supported — background fill omitted",
    "node 'avatar': imageFill — reference only, no pixel data"
  ]
}

Add these explicitly to your implementation prompt: "Skip the hero background fill and leave a // TODO: gradient. For the avatar node, use a placeholder AsyncImage with a grey background."

This prevents Claude from silently approximating — it'll do what you told it instead of guessing.

Why this beats screenshot prompting

Multi-turn safe. The token file and IR don't change between turns. You can ask "did you use the right spacing for the card padding?" in turn 12 and get an accurate answer, because the source of truth is still on disk.

Diff-friendly. When you re-export after a design change, the new bundle produces a diff against the old one. You can ask Claude to review the diff and update only the affected components — no full reimplementation required.

No re-upload. The bundle lives in your repo. You don't re-paste screenshots for every new screen. Each new screen is just design/screens/<name>.json — one more file to reference in the next prompt.

Honest about gaps. CONTEXT.md and _meta.json explicitly list what the bundle doesn't cover. Screenshot prompting has no equivalent — the model just guesses through the gaps.

The main figmascope app handles the export in your browser — paste your Figma URL, export the bundle, and you're ready to run Claude Code against a deterministic spec. The same bundle pattern also works with Cursor and Aider if you want to compare agent outputs on identical input.

Structured Context vs Pixel Context: What Coding Agents Actually Need

Roman Tsisyk — Sun, 09 Aug 2026 23:00:43 +0000

Context is becoming the bottleneck in AI-assisted development. Not model capability — models are improving fast enough that they're regularly not the constraint. What limits the quality of AI-generated code is the quality of context those models receive.

For Figma-to-code workflows, context comes in two fundamentally different forms: pixel context (screenshots, rendered images) and structured context (typed IR, tokens, semantic relationships). These aren't just different formats for the same information. They're different categories of input, with different properties, different loss characteristics, and different ceilings on what an agent can produce from them.

The industry is still largely using pixel context. That's a mistake. figmascope exports structured context — the right input from the start. Here's how the two categories compare, and why the difference determines whether your generated code composes, diffs, and survives contact with a real design system.

What pixel context is

Pixel context is any rasterized representation of a design: a screenshot exported from Figma, a PNG from "Export frame", a render from a design tool. It's what you get when you press Cmd+Shift+4 over your Figma canvas.

Vision-capable LLMs process pixel context impressively well. They recognize UI patterns, identify layout regions, infer component types from visual appearance, and generate plausible code from images alone. If you've used Claude or GPT-4V for screenshot-to-code, you've seen this. The outputs look right more often than you'd expect.

But "looks right" and "is right" are not the same thing — and the gap between them is where design system compliance, token fidelity, component identity, and reproducibility all live.

What structured context is

Structured context is a typed, machine-readable representation that preserves the semantics of the design: what each element is, not just what it looks like. It includes:

Typed nodes: every element has a kind (FRAME, TEXT, INSTANCE, VECTOR) that carries semantic meaning about its role in the layout
Named values: colors are token references, not hex strings; spacings are token keys, not pixel values
Spatial relationships: layout direction, gap, padding, alignment — preserved as properties, not inferred from position
Identity links: component instances carry their source component ID; strings carry cross-reference keys
Hierarchy: the full node tree, with parent-child relationships intact

A structured IR is the design tree made explicit: each node has kind, name, absoluteBoundingBox, children, fills resolved to token references where available, auto-layout properties if applicable, and componentId on instances.

Pixel context tells an agent what a design looks like. Structured context tells it what a design means. A coding agent needs meaning to write code, not appearance. Appearance is what visual tests are for.

What gets lost in the pixel-to-structured direction

The core failure mode of pixel context is irreversible information loss. When Figma renders a frame to PNG, it discards exactly the information that matters most for code generation:

The layer tree collapses. There is no longer a "group of three items with 8px gaps." There is a region of pixels that suggests a group. The agent has to reconstruct the tree structure from visual evidence, and reconstruction is approximate. It will be wrong some percentage of the time — and that percentage grows as designs get more complex.

Token bindings disappear. The orange background that maps to color/action/primary becomes #FF6B00. The agent generates a hardcoded hex. If your color ever changes, or you support dark mode, or you need to audit token usage, that hardcoded value is a liability.

Component identity is gone. Four instances of the same card component are four similar-looking rectangles. The agent may generate one reusable component or four similar-but-not-identical blocks, depending on how much structural similarity it infers. You want predictable output; you get probabilistic output.

Layout intent is ambiguous. Is this a flex row or a grid? Is the spacing between items a gap, a margin, or padding on each item? The pixels don't say. The agent picks — and the picks differ between runs.

The Figma → React pipeline, with and without structure

Consider the path from Figma to production React.

With pixel context: Export PNG. Paste into Claude. Get JSX. Review JSX for correctness. Notice hardcoded values. Notice wrong component structure. Prompt for corrections. Iterate. Eventually get something plausible. Hand-edit to match the design system. Ship. Next screen: repeat from scratch because the previous run's outputs don't compose.

With structured context: Export a bundle (one click, runs in browser). Pass CONTEXT.md + screen IR to Claude with a system prompt specifying framework and design system conventions. Get JSX that uses your token names, your component names, and correct layout structure. Review for correctness. Ship. Next screen: same bundle, same agent, composable outputs because the inputs are consistent.

The work savings are real but secondary. The primary gain is composability. Structured context enables outputs that compose across screens and agents. Pixel context doesn't — each screen's output is an island generated from a fresh inference pass.

Structure means: typed

Every node in the IR has a kind. This matters immediately. A TEXT node generates a text element. A FRAME with auto-layout generates a container. An INSTANCE of Button/Primary/Large generates a button component call with the right props. A VECTOR generates an icon reference.

The agent doesn't guess. It maps kinds to code primitives — rules specified in CONTEXT.md for the target framework: "For INSTANCE nodes, use the component name to determine the React component. For FRAME with layoutMode HORIZONTAL, use a flex row. For TEXT with style typography/heading.lg, use the Heading component." These are compiler-style rules, not inference tasks.

Structure means: spatial

The absoluteBoundingBox on each node gives position and size in the Figma coordinate space. Combined with auto-layout properties — layoutMode, itemSpacing, paddingLeft/Right/Top/Bottom, alignment — the agent has everything it needs to generate correct layout code without pixel-counting.

The bounding boxes also let the agent verify its own output: if a generated component has different dimensions than the IR specified, something went wrong. That's a testable property of structured context with no equivalent in pixel context.

Structure means: identity-aware

When four nodes in the IR share a componentId, the agent knows they're instances of the same component. It generates the component definition once, derives props from the variants, and renders four calls. This is the correct output — and it's not achievable from pixel context without significant prompt engineering that essentially asks the agent to re-derive structure the design file already had.

String cross-references work the same way. When multiple text nodes reference stringRef.key: "action.continue", the agent knows to use a single i18n lookup, not three hardcoded strings. The identity information is in the IR; the agent just reads it.

Structure means: version-controllable

Plain JSON files diff cleanly. A changed padding value shows up as a one-line change in the per-screen IR. A renamed token shows up as a find-replace diff across the tokens file. A new component instance shows up as an added object in the children array.

This is design version history that's actually useful for engineers. Not "the design was updated on Tuesday" but "here are the three properties that changed between the v2 and v3 exports of this screen." You can put that in your PR description, run automated checks on it, and audit whether the code change matches the design change.

Where this leads: design context infrastructure

The tooling category forming here isn't "Figma export, but better." It's a new layer in the stack: design context infrastructure. Its job is to transform design source (Figma files, component libraries, token systems) into structured, agent-readable, version-controlled artifacts that feed the code generation layer.

This layer sits between the design tool and the coding agent, with responsibilities neither side currently owns: snapshot management, semantic extraction, token resolution, component inventory, cross-screen string indexing, bundle versioning. Treating it as infrastructure means it's automated, versioned, CI-runnable, defined-format, and inspectable — the same way a build system is infrastructure for code: not the code, not the binary, but the reliable, reproducible pipeline that converts one to the other.

Honest: pixels still matter

Structured context bundles include 2x PNGs of every exported screen. Not because the PNG drives code generation, but because visual confirmation matters. An agent should be able to cross-reference its generated output against the PNG. A developer should be able to look at the screen without opening Figma. The PNG is a sanity check, not a specification.

That distinction — pixels for confirmation, structure for specification — is the right mental model. You don't eliminate pixel context; you demote it to its correct role. It's the QA artifact, not the build input.

The same way you wouldn't give a compiler a screenshot of your source code: you give it the source, and you use screenshots for documentation. The design file is the source. The bundle is the compilation artifact. The PNG is the documentation image.

One design, multiple targets

Structured context enables a workflow pixel context can't: one design, multiple targets. The same IR can feed a React/Tailwind generator, a Jetpack Compose generator, and a SwiftUI generator. The underlying design is the same; the target-specific context (framework primitives, naming conventions, layout APIs) lives in CONTEXT.md, which is generated per-target.

This is multi-target codegen that actually scales. You export one bundle from the design, run three agents with three different CONTEXT.md files, and get three implementations that are structurally equivalent — because they were generated from the same IR, not from three separate inference passes over three screenshots.

The bottleneck for this workflow isn't model capability. It's context quality. Structured context is what makes it possible.

Export your structured context bundle from the figmascope app, then use it with Cursor, Claude Code, or Aider for multi-target, composable UI generation.

Why Pasting Figma Screenshots into Claude Fails (And What to Use Instead)

Roman Tsisyk — Sun, 09 Aug 2026 22:27:56 +0000

Here's the workflow that's become default in every design-to-code team right now: export a frame from Figma, paste the PNG into Claude or Cursor, type "build this", and iterate on the hallucinated output. It works just well enough to feel productive. It doesn't work well enough to ship from.

This isn't a model capability problem. It's an input problem. A screenshot is the worst possible representation of a Figma design for an LLM to reason about — and yet it's almost universally what teams reach for first. The structured alternative is what figmascope exports: a context bundle of typed IR, design tokens, component inventory, and UI strings that the agent can read instead of guess. Let's walk through everything a screenshot silently destroys.

The hierarchy is gone

A Figma file is a tree. Frames contain auto-layout groups, which contain component instances, which contain text and fill layers. That tree encodes the layout intent: this row is a flex container, this card is a padded box, these three items are siblings with 16px gaps between them.

A screenshot flattens that tree to a grid of pixels. The LLM sees shapes and colors. It does not see the layout structure — it infers it. And inference is lossy in both directions: the model may reconstruct structure that looks right visually but is wrong semantically (a fixed-width div instead of a flex child, absolute positioning instead of auto-layout), or it may see structural ambiguity and pick one arbitrarily.

You can't tell from a PNG whether a horizontal row of items is implemented with display: flex, CSS Grid, a custom HStack, or three absolutely-positioned divs. They're visually identical. The LLM picks one. The pick changes between runs.

Semantics don't survive rasterization

The LLM can see that a rectangle with rounded corners contains some text and an icon. What it can't see:

Is this a Button component or a custom card?
If it's a button, what variant is it — primary, secondary, ghost?
Is the icon decorative or meaningful?
Does this element have interactive states in the design system, or is it one-off?

Semantics in Figma live in the layer tree: component names, variant properties, node kinds. A Button/Primary/Large component is explicitly typed. In a screenshot, it's a rounded rectangle with a shadow and a label. The model guesses "this is probably a button" correctly most of the time — and then guesses "this is probably the primary variant" based on color, which may or may not match your design system's actual naming.

Small mismatches compound. A ghost button rendered as an outlined button. A tooltip rendered as a modal trigger. A disabled state rendered as active. Each of these is one screenshot-inference step away from the source of truth.

Spacing systems don't resolve to numbers

Look at a screenshot of a card with padding. What's the padding? You can't tell without measuring pixels, knowing the canvas scale, knowing the export resolution, and doing the math. The LLM does the math badly — it estimates, it rounds, and it has no way to know if your spacing system uses an 8px base grid or a 4px one or something custom.

So it guesses. It generates padding: 12px when the design says 16. It generates gap: 8px when the design says 12. These numbers look plausible in isolation but they're wrong — and if your design system uses spacing tokens like spacing.md or Spacing/400, the LLM doesn't know about them at all. It hardcodes literals that will drift from your system the moment anything changes.

The LLM isn't hallucinating. It's doing exactly what you'd do with only a screenshot: guessing. You're just surprised when the guesses are wrong because you could see the right answer in the Figma file all along.

Token relationships vanish

Your designer set that background to #7F5CFE. In Figma, that hex is bound to a variable: color/brand/primary. That binding is meaningful — it means the color participates in theming, it means dark mode swaps it, it means if the brand color changes you update one variable and every instance updates.

In the screenshot: it's purple. The LLM generates background-color: #7F5CFE. The token relationship is gone. Your codebase now has a hardcoded hex that will never track with your design system. Multiply this by every component on the screen.

The same applies to typography scales, border radii, and shadow definitions. Every value in a well-maintained Figma file is potentially a named token. Every value in a screenshot is just a number.

Component reuse is invisible

A well-composed screen reuses components. The four product cards are four instances of the same ProductCard component. The avatar in the nav and the avatar in the comment thread are both instances of Avatar/Medium. This matters for code: you want one React component, not four hand-rolled variations that will diverge.

From a screenshot, the LLM sees four visually similar rectangles. It may generate one reusable component — or it may generate four nearly-identical blocks of JSX because it didn't notice they were the same. There's no signal in the image to tell it which is correct.

Structured context carries componentId on every instance node. The agent knows: these four nodes are all ProductCard. Generate it once, render it four times with different props. That's the output you want. That's the output you can't get from pixels.

String identity is lost

You have a "Continue" button on three different screens. Are those three instances the same string, or did a designer write them independently? In a well-structured Figma file, they reference the same string key. That means one i18n entry, one change propagates everywhere.

In three screenshots: three times the LLM generates a hardcoded string. If you're building an internationalised app, you now have three strings to find and replace instead of one to look up. Small thing. Compounds across a real codebase.

Why the LLM hallucinates: it re-derives structure every time

The model has no memory of previous runs. Every time you paste the same screenshot, it reconstructs the structure from scratch. The reconstruction is probabilistic — which means the same screenshot + same prompt + same model can produce measurably different outputs on different runs. Same design, different code. Different component names, different className patterns, different layout choices.

This is not a model bug. It's the expected behavior of a probabilistic model given insufficient constraints. The screenshot provides insufficient constraints. The model fills the gaps — and the gaps are filled differently each time.

You can partially work around this with longer, more detailed prompts — "use Tailwind, use 8px grid, use these component names..." — but then you've manually specified the structure that should have been in the design file all along. You're doing the extraction work the tool should do.

The reproducibility problem

Teams that use screenshots for design-to-code handoff hit the same wall: the output is not reproducible. Two developers, same Figma screenshot, independently prompt Claude — they get different component structures, different className patterns, different nesting decisions. Now you have two codebases that look the same visually but are architecturally inconsistent.

This makes code review harder. It makes refactoring harder. It makes design system compliance auditing impossible. You can't diff "what did the agent generate from this design" if the answer changes every run.

Structured context fixes reproducibility because it fixes the inputs. A deterministic input bundle — the same JSON with the same node IDs, component names, token values, and spatial relationships — produces much more consistent output across runs, agents, and developers. Not perfectly deterministic: the model is still probabilistic. But the variance drops dramatically when the structure is specified rather than inferred.

What a screenshot gives you vs. what the IR gives you

Take a product card: image, title, subtitle, price, an "Add to cart" button. Here's what each input gives the agent:

Screenshot input: A rectangle with an image at the top, two lines of text, a number, and a button. Colors are inferred. Padding is estimated. Whether this is a component or one-off is unknown. The button variant is inferred from color. The spacing system is unknown.

IR input: Node kind FRAME, name ProductCard, component ID linking to the component definition. Auto-layout with vertical direction, 16px gap, 16px horizontal padding, 12px vertical padding. Child nodes: IMAGE (fills width, fixed height), TEXT with stringRef.key: "product.title" and style typography/heading.sm, TEXT with stringRef.key: "product.subtitle" and style typography/body.md, TEXT with fill color/price, INSTANCE of Button/Primary/Medium. Background fill color/surface.card. Border radius radius/card.

The IR gives the agent a spec. The screenshot gives it a suggestion.

The frame: this is the documentation problem

We solved this exact problem for source code decades ago. You don't give an agent a screenshot of your codebase and ask it to reason about architecture. You give it the code — the structured, parseable, semantically-meaningful representation. The abstract syntax tree, not a picture of the editor.

Figma designs are structured data. They have a well-defined tree structure with typed nodes and named values, and the Figma API exposes it completely. The only reason the screenshot workflow persists is that extracting the structure and formatting it as context has friction.

Reducing that friction is what figmascope does. You paste the Figma URL, the export runs in your browser, and you get a ZIP with structured context: CONTEXT.md, tokens.json, per-screen IR, component inventory, strings manifest. Everything the agent needs, none of it inferred from pixels.

Keep the screenshots for visual confirmation — the bundle includes 2x PNGs for exactly that. Use the structure for everything else. If you're on Claude Code, the full handoff pipeline walkthrough shows the pattern end-to-end; there are also variants for Cursor and Aider.