Your Figma file looks great and the AI still writes generic UI. Agents read structure, not pixels, and most of what makes a file legible to them is invisible on the canvas. Eight checks, cheapest first.
The first scorer we built was useless. Every file we ran it on came back in the same band, because we'd weighted it toward the easy things: descriptions, token coverage. Tidiness was all it could see.
A tidy file is not a design system. Neat pages, consistent naming and a full component library can all be true while the structure an agent needs isn't there at all. So we rebalanced toward the parts that are hard to reach, and those weights are what's below. You can run every check by hand.
Start here. Free, no visual risk, and hardly anyone does it.
Tokens are the usual starting point, and they need a review cycle and a chunk of your week. Descriptions cost nothing, can't break a layout, and change what an agent builds more directly than any colour variable. We'd do these first.
Check: open your components page. How many sets have a description?
Why: the description is the only place you can say when to use something. The name says what it's called. The properties say what can change. Neither tells an agent to pick Banner over Toast, so it guesses from the name, and name similarity is a terrible way to choose a component.
Fix: one line per set. What it is, then the boundary.
Inline validation message shown under a field. For page-level errors use Alert.
The second sentence is the one that changes behaviour. Write that part even if you skip the rest.
Every set should expose something. Three or more is the target.
Check: select a component set. Does the properties panel show anything at all?
How we score it: 60% of this axis is just exposing any property, the other 40% scales up to an average of three per set. One variant property on everything gets you the first half and none of the second.
Fix: add the things you already change by hand: size, state, icon on/off, label.
Text that changes between variants but isn't a property.
Check: look at a set's variants. Does a text layer say something different in each one, with no TEXT property exposed?
That's the flag. The content obviously varies, but there's no supported way to vary it, so the next person detaches.
Not a problem: text that's identical across every variant. A keyboard key, a fixed code sample. Those are meant to be fixed. We deliberately don't penalise them. The check reads whether the string actually changes rather than guessing from layer names.
Fix: expose it as a TEXT property.
The heaviest single axis. A value is either bound or it's a magic number.
Check: click any fill. Variable, or hex code?
Priority: fills and text carry four times the weight of strokes, radius and spacing. A hardcoded radius gives you slightly-off code. A hardcoded fill breaks theming outright, because there's nothing for dark mode to swap.
Fix: look for values that repeat: the same grey in nine places, the same 12px gap. Mint a token, bind it.
One warning about coverage as a metric: bound isn't the bar. Plenty of audits stop at "is this attached to something," which is how a file scores well and still collapses the moment you add a second theme. What it's bound to is the part that matters, and that's the next check.
Where most systems stop one step short.
grey/900 is a primitive. It names a value. text/primary is semantic. It names a role and points at the primitive.
Check: what are your components bound to? If it's a colour name, dark mode won't work. The component asked for that specific grey, so that's what it gets, in every theme you build.
Fix: components bind to semantic tokens only. Semantic tokens point at primitives. That indirection is the entire mechanism behind theming. There's no way to get it without the second tier.
But don't extend this to spacing and radius. Flat scales are correct there, and spacing/comfortable pointing at space/16 is ceremony, a rename that adds a lookup and buys nothing. We deliberately don't score it. Semantic layers earn their keep on colour, where theming actually happens.
Detached copies count against you twice.
Check: how many detached copies are floating around your product files?
We count instances against detached ones and weight each detached copy double. It stopped receiving updates and stopped carrying your tokens the moment someone hit detach. It left the system.
A detach is the component's fault, not the designer's. Nobody detaches for fun. They do it because they needed one change the component wouldn't allow. Governance rules and "please stop detaching" messages treat the symptom. Fix checks 2 and 3 and most of it stops on its own.
The quickest check on this page.
Check: are your variants named Prop=Value? Size=Large, not Large.
Figma groups them properly when they are, and the naming carries through to generated code. Loose names produce a set that looks fine in the panel and falls apart on the other side.
Fix: rename. Nothing else changes.
Five capabilities. Each is binary: you have it or you don't.
This is the axis we added when we rebalanced, and it's what lets a mature system pull away from a merely tidy one.
We went with five yes/no capabilities rather than maturity levels on purpose. Being told you're at "Level 2 of 5" is a horoscope. It describes you without telling you what to do on Monday. A failed checkbox names the work.
Three of the five are the same piece of work: build the semantic layer. That also settles check 5 and unlocks theming, which makes it the highest-leverage thing on this page.
All five is rare. Three is already strong.
Full points where you're near-complete, half where you're partway, zero where you haven't started.
You can approximate the same thing by hand.
Token coverage 18 fills + text bound
Semantic structure 15 components bind roles, not values
Maturity 15 how many of the five
Component reuse 14 instances vs detached
Prop richness 10 varying text is a prop
Exposed props 10 every set configurable
Descriptions 10 every set documented
Variant structure 8 Prop=Value naming
---
100
90+ A 80+ B 70+ C
Low score with good coverage usually means descriptions and props, both cheap, both fixable this week. Stuck just below an A is almost always maturity, and that's a project rather than an afternoon.
Decisions encoded as data, not just drawn. Values bound to tokens, components bound to a semantic layer, properties instead of layers you have to detach, and descriptions saying when to use what.
Not primarily. Through MCP an agent walks the structure: node names, component properties, bound variables. Anything you expressed only visually doesn't reach it.
Raw hex values instead of tokens, components with no exposed properties, no descriptions. With nothing specific to read, the agent falls back on its training defaults.
Both, in two tiers. Primitives name values (grey/900), semantic tokens name roles (text/primary) and point at primitives. Components bind only to semantic. Spacing and radius are fine flat.
It's the only place intent lives. Names say what a component is called, properties say what can change, but nothing says when to use one over a similar one. Without it an agent picks by name similarity.
Score what survives being read as data: token coverage, semantic structure, reuse versus detached copies, exposed properties, prop richness, variant naming, descriptions, and theming capability. All of it is readable through Figma's Plugin API.
We skip the stage labels. Score five capabilities you either have or don't: a semantic layer, theming that resolves, responsive tokens, 99%+ semantic binding, and APIs averaging 3+ properties. That gives you a next move instead of a label.
Instances versus detached copies, first. Detached instances are the real failure: no updates, no tokens. Then share of values bound to tokens, and share of sets with descriptions.
It doesn't need to. Every signal here is available through the Plugin API locally. Ours makes no network call and uses no model.
The AMPLIFAI Masterclass
This makes your file legible to an agent. The course is what you do next: feeding it your system as context, generating whole screens from it, and shipping the result.
Module 1 is free: Figma × Claude CodeFull course: $399 · $299 until Sep 13