The README states what figma-edit-mcp does. This document explains why we built it that way. The exact enforcement rules live in SAFETY.md, and the evidence behind the claims here — direct quotes and links to sources — is collected in EVIDENCE.md.
The project pursues three goals:
The goals are not independent. Safer leads to Cleaner and to Faster, and Cleaner leads to Faster and back to Safer. Four insights carry this reasoning: three of them explain the connections between the goals, and the fourth acts on Faster directly. Each insight is presented below at the point where it does its work.
Safer means more errors are caught and prevented, and fewer ways exist to make one. figma-edit-mcp checks every action the AI requests, inside Figma, before the action runs. An action that fails a check is refused, with an error message that tells the AI what was wrong.
The first insight explains why the checks actually deliver safety: A programmatic check is more reliable & costs less than instructing the AI.
There are two ways to stop an AI from making a specific mistake. You can instruct the AI (“never delete a variable that is still in use”), or you can write a program that checks each action and blocks the mistake.
The two differ first in reliability. An instruction produces probable compliance: an AI follows instructions most of the time, not every time, and in a long session its attention to any single rule weakens. A check produces a guarantee: it returns the same result on every call, and it does not depend on the AI’s attention, the AI’s context length, or which AI model is connected. The checks in figma-edit-mcp run inside the Figma plugin, so the AI cannot skip them, and the guarantee holds even for an AI that never read any instructions.
The costs differ as well. An instruction consumes tokens on every request, because its text must sit in the AI’s context window every time. A check runs by itself on every call. Over any sustained use, the check is the cheaper of the two.
Two measured results support this insight. OpenAI compared the two approaches on output formatting: with instructions alone, its earlier model produced a valid complex output format in fewer than 40% of test cases; with checks, the rate was 100%. The SWE-agent research team gave a coding agent an edit command that discards any edit that introduces a syntax error and asks the agent to retry — the same pattern figma-edit-mcp uses — and the agent solved 18.0% of its benchmark tasks with that check versus 15.0% without it. (Quotes and sources.)
Reliable checks stop errors before they enter the file, and a file that receives fewer errors stays cleaner. That is the connection: Safer leads to Cleaner. Stated precisely: the checks do not make a file clean — the cleanliness comes from you and the AI doing good work — the checks stop that clean state from decaying.
This connection has been measured at scale. In 2019, memory-handling errors caused 76% of Android’s security vulnerabilities. Google then required new code to be written in languages whose compilers refuse memory-unsafe code, and left the existing code in place. By the end of 2024 the share had fallen to 24%. Preventing new errors was enough to make the whole codebase cleaner, because old errors get found and fixed over time while new ones stop arriving. (Quotes and sources.)
Two caveats keep this connection honest:
figma-edit skill and the figma-edit://guide/* resources teach the AI the rules before it starts. Their purpose is efficiency, not safety: an AI that knows the rules wastes fewer calls on actions figma-edit-mcp would refuse. Safety never depends on the AI reading them.The second insight: Preventing an error costs less than repairing it.
The cost saving comes from three places:
The variable-consumer check in figma-edit-mcp illustrates the mechanism directly. Figma lets you delete a variable that layers still use, shows no warning, and provides no complete way to list and repair the resulting broken references.
Before deletion, the figma-edit-mcp can determine whether the variable has consumers and return that diagnosis with the refused call. Without figma-edit-mcp, after an unchecked deletion, the same information is no longer readily available in Figma, and users on Figma’s own forum describe the consequences: one user found 1,548 orphaned variable references after reorganizing their variables, and users report that the “Detach deleted variables” quick action fixes only some of them. This does not quantify the average speedup of the check, but it identifies an error class for which immediate containment is predictably cheaper than reconstructing the affected state later.
Other industries recognize this insight as well, with evidence showing that early checks can produce a net time saving after their overhead is included. IBM’s original inspection study reported 23% higher coding-operation productivity after counting inspection and rework effort, together with 38% fewer errors during later equivalent testing. A field study of 30 industrial software products modeled both the direct overhead of process controls and the quality-mediated reduction in rework; at the sample average, the estimated net effect was lower cycle time and effort. An observational study of 35 industrial projects found that automated static analysis identified unique defects with comparatively low find-and-fix effort and modeled a positive operational return. (Quotes and sources.)
Stated precisely: Safer leads to Faster as an expected end-to-end effect for the failure modes the checks cover. The effect is zero in a task where no covered harmful action would otherwise occur and largest for latent, high-fan-out, or difficult-to-reverse errors.
One further check belongs to this insight because it prevents a whole class of repair at once. Batch tools validate every item before changing anything, so a batch that fails validation changes nothing — the file is never left half-modified by a detectably invalid batch. The exact guarantee and its limits are defined in SAFETY.md.
Cleaner means fewer errors and less ambiguous, duplicated, or implicit state in the work environment — the design file. Broken relationships and accidental near-duplicates are removed; shared decisions are represented through authoritative variables, styles, or components when appropriate; consumers keep explicit links to those sources; and names distinguish legitimate alternatives.
The third insight: Defects, and the inconsistencies they cause, can compound by making it more likely for additional defects & inconsistencies to occur.
A cleaner file does not make every task faster. The effect appears when a task must interpret, reuse, or modify the affected part of the file. Across repeated work, a cleaner file reduces the chance that the AI must stop to locate the right object, distinguish near-duplicate tokens, diagnose a latent defect, or repair an inherited mistake before it can make the requested change.
Three mechanisms produce the saving:
Measured evidence supports the direction of this relationship. In a counterbalanced Figma experiment, designers completed matched tasks 34% faster when they had a current, task-relevant design system instead of old design files to search. In a controlled experiment with 72 professional developers, meaningful word identifiers made finding semantic defects 19% faster than abbreviations or single letters. Studies of CAD models, production codebases, and structural antipatterns point the same way: structure that communicates intent lowers the cost of later modification, and combinations of structural problems raise it. (Quotes, methods, limitations, and sources.)
Stated precisely: Cleaner leads to Faster as an expected lifecycle effect. The effect is largest in frequently reused or high-churn structures.
The first insight explains why a programmatic check is more reliable than an instruction once a condition can be evaluated. Cleaner leads back to Safer by determining which conditions are available to evaluate: A safeguard can reliably enforce only the relationships the file makes observable.
Any design or engineering document can hold a decision in one of two forms. The decision can be recorded as structure that the software stores and can read back — a stated link from one thing to another. Or it can exist only as a convention: the author knows two things are meant to match, but nothing in the file says so. The two forms can produce the same visible result, but they are not the same to a checker. A check can read a recorded relationship and act on it, but it cannot read an intention that was never written down.
So the more of the author’s intent a file records as structure, the more of it a check can protect. A file that has been cleaned up in this sense — decisions written down rather than left implied — is a file in which more can be verified.
In Figma this same choice shows up in concrete pairs. A layer can be explicitly bound to a variable, or it can just happen to contain the same value. A reusable element can stay an instance of a component, or it can be a detached copy that people still expect to behave like the component. A colour or spacing value in current use can be the only one of its kind, or it can sit next to leftover near-duplicates from earlier work. In each pair the design can look identical. Only the first form of each records what was intended, so only the first can be checked.
A cleaner file records more of that intent, through three mechanisms. Each is a general idea with a direct Figma form:
The same pattern appears well outside design tools, which is the reason to trust it rather than treat it as a quirk of Figma:
These are different fields, but each shows the same thing: a safeguard helps when the relationship it depends on is recorded, and cannot help when that relationship exists only by convention. (Quotes, methods, limitations, and sources.)
Stated precisely: Cleaner leads to Safer when cleanup replaces duplicated or unstated decisions with recorded objects and explicit links, or removes obsolete choices that could still be selected.
Two caveats keep the claim bounded:
Faster means tasks take a shorter time to be completed correctly. This goal is where the other two pay out: Safer prevents work that would otherwise have to be diagnosed and repaired, while Cleaner reduces the search and interpretation imposed by disorder in the file. The plugin also contributes directly, by matching its tool boundaries to decision boundaries.
The fourth insight: Design tools around decisions, not operations: one model turn should express all work already determined, and one tool result should provide all information needed for the next decision.
A model turn is one reasoning cycle: the AI reads the last result, thinks, and composes its next call. A single operation does not justify another turn. Another turn is useful when the AI must see an operation’s result before it can determine what follows. If the AI can already state the remaining operations — or a rule that selects them — returning after every operation adds coordination without adding judgment.
The boundary test is: can the AI state what follows, or the rule for determining it, before seeing the result? If yes, the work can stay inside the current call. If no, the result marks a real decision, and control should return to the AI.
“Already determined” covers more than a fixed list. It includes deterministic control logic — a filter, loop, comparison, or branch — that the AI can state now and ordinary code can apply. It does not include a choice that depends on the AI interpreting an observation it has not yet seen.
The plugin applies the insight on both sides of each exchange. On the action side, batch tools let one call express many operations, and the schemas and guides make the available actions legible enough to compose that call correctly. On the observation side, success and refusal results carry the information the next decision needs.
Once the AI has determined the targets and changes, a batch lets it express them in one invocation. The plugin still validates and executes every item; what disappears is the requirement to return to the AI between items that require no new judgment.
The current batch tools implement the simplest case: the AI supplies the full list of items and arguments together. The design rule also identifies a future opportunity for higher-level tools: a filter, loop, comparison, or branch could stay inside one call when the AI can state the rule before execution. That an intermediate value selects which branch runs does not by itself require another turn; a turn becomes useful when the AI must see the value before it can decide what the value means for the task.
This is why the speed of a batch does not depend on Figma executing each operation faster. Its direct contribution is that already-determined work no longer waits for repeated model re-entry.
The primary consumer of these tools is an LLM composing calls. The contract therefore has two jobs.
Before execution, it must expose the parameters, distinctions, and constraints the AI needs to translate its current decision into a valid request. A required read discovers facts about the design; trial and error caused by an ambiguous interface merely discovers facts the tool already knew.
After execution, the result must supply what the AI needs to decide what happens next. A success response should make the outcome legible. A refusal should identify the failed condition, the observed value that failed it, and — when it can do so safely — the alternatives the plugin would have accepted. An opaque result forces another turn to reconstruct information the tool already possessed.
We call such a result decision-complete: it contains what the next decision needs, and as little else as possible. Decision-complete does not mean short. Irrelevant output consumes context, but removing an exact identifier, an edit anchor, or an accepted value can create more work than the shorter result saves. The goal is the smallest result that makes the next decision possible.
Measured evidence supports this boundary rather than a blanket preference for fewer calls. Anthropic’s programmatic tool calling — letting a model run many tool calls inside one turn — cut billed input tokens by roughly 38% with no change in accuracy on a multi-tool benchmark, yet on tasks whose every call depends on fresh model judgment it left scores unchanged and cost roughly 8% more. On the observation side, filtering results down to what the next decision needs improved benchmark performance by 11% while using 24% fewer input tokens; refusals that named the accepted alternatives raised repair success by roughly 40 percentage points over raw diagnostics; and a study that trimmed tool results too aggressively cut tokens but raised total cost and failures. Most of these results measure tokens, steps, and success rather than elapsed time. (Sources, methods, and limitations.)
That is the plugin’s direct Faster contribution: keep execution inside the tool until the AI has something new to decide; when control returns, return the facts that decision requires.
These three goals and four insights produce the system described in the README: you direct the design, the AI executes the operations, and the plugin checks each one. The full list of checks, and the conditions under which each one holds, is in SAFETY.md.