Figma library audit: what to check before a spec agent

It is the third design-to-code pilot in two months. The agency sends us a Figma file, we wire it to a Claude-driven component-spec agent, the agent runs, and then we sit and watch the output quality bleed for the next four hours. Components that should be one variant come out as three. A button generated last Tuesday looks nothing like the button generated this morning. The agency lead asks what is going on. We open the layer panel and point.

The frames are named Frame 47, Frame 47 copy, Container / Hero / fix-FINAL. The auto-layout direction is set correctly. The padding is right. But the names that the spec agent reads as a contract are noise. So the agent produces noise.

This is now the audit we run on any agency's Figma library before we put a number on a spec-agent build. It takes a junior designer two hours. It saves the client about three weeks.

Why the agent stalls on naming

A Claude-driven spec agent reads a Figma file like a tree. It does not see the pixels first. It sees the structure: frame names, auto-layout properties, variants, variables, applied styles. When that tree is clean, the agent writes React or Vue or Svelte components that look like a careful human wrote them, because a careful human did, upstream, by naming things well.

When the tree is messy, the agent does what language models always do under uncertainty: it guesses. The guesses are plausible. They are also wrong in ways that take a senior developer a full afternoon to track down. The Hacker News thread this week titled I design with Claude more than Figma now had the same theme running through the comments. The model is excellent at translation. The source has to be a real document, not a sketch.

The audit below is structural, not aesthetic. We are not judging whether the design is good. We are judging whether a machine that reads structure can produce something usable from it.

Auto-layout label consistency

This is the one that killed all three pilots. Figma's auto-layout is powerful and largely invisible: you can set a frame to Vertical, gap 16, padding 24, fill horizontally and never bother to name it anything other than Frame 1432. The pixels look correct. The spec agent has no way to tell Frame 1432 from Frame 1433, both of which are vertical stacks with the same gap, sitting inside two different components.

The check: open the layer panel on the ten most-used components. Count how many container frames have meaningful names. We want above 80%. We see 15% on average. Acceptable names look like card / body, nav / item-row, form / field-group. Anything called Frame, Group, or Rectangle 4 fails the line.

Variant grammar across the set

Figma variants are properties on a component. A button might carry state: default | hover | disabled and size: sm | md | lg. Done well, this is exactly what the agent needs to emit a typed component. Done badly, it is a graveyard of half-finished combinations and one-off pages that broke away from the library two months ago.

What we check: variant property names are consistent across the library. state in one component is not status in another. Values use the same vocabulary: default / hover / disabled, not default / hover / off in one place and idle / hover / inactive in another. The agent will not normalise this for you. If the library has three words for "disabled", the generated code has three words for "disabled", and your design system PR review meeting becomes a vocabulary fight.

Token coverage and the variable dictionary

Figma variables are the closest thing to design tokens that the tool ships natively. Colours, spacing, radii, type styles. If the library binds these properly, the spec agent maps them onto CSS custom properties or your token engine of choice in one pass. If the library uses raw hex codes and pixel values, the agent invents names, and it will, and the names will not match across components.

The audit: sample ten frames across the file. Count what percentage of fills, strokes, and spacing values are bound to variables versus hard-coded. Below 60% means you are quoting a token-extraction pass before the spec agent runs. Above 90% means you can start the agent next week.

Detach rate as a health signal

An instance in Figma can be detached from its main component. The pixels stay. The connection breaks. Detached instances are the single best proxy we have found for library health, because they tell you whether the team actually trusts the components or quietly works around them.

The Figma REST API surfaces this directly. Pull the file, walk the tree, count nodes of type INSTANCE against frames that visually look like instances would have. We expect under 5% detach across the file. We have seen 40%. At 40%, the library is decorative. The team is hand-rolling everything. The spec agent will faithfully reproduce the hand-rolled output, not the library intent, because the hand-rolled output is what actually sits on the pages.

curl -H "X-Figma-Token: $FIGMA_PAT" \
  "https://api.figma.com/v1/files/$FILE_KEY" \
  | jq '[.. | objects | select(.type == "INSTANCE")] | length'

Run that, and the equivalent count for COMPONENT nodes. The ratio is your health score. If detached pages outnumber component instances on a real production frame, the audit fails on this axis alone and the conversation moves from "price the spec agent" to "price the migration".

Component documentation that survives translation

Most agencies have a Notion page or a README that explains "use the primary button for the primary action". The spec agent does not read Notion. It does read the description field on a Figma component, if it is set. We want short, structural descriptions: "Primary action. Pairs with secondary on right. Disabled state forbids hover."

The audit: dump component descriptions via the API. Count how many have content. Below 30% and the agent will invent prop documentation that sounds confident and is partially wrong. Above 80% and the generated TypeScript types come out almost reviewable on the first pass. This is the cheapest check to fail. It is also the cheapest to fix: a designer can write the descriptions in an afternoon, and the quality of the spec output rises measurably the next day.

Page-level versus library-level fidelity

This is the subtle one. A team can have a clean library and still ship a chaotic site, because the pages were built before the library existed and nobody ever migrated them. The spec agent points at the page, sees a button-shaped thing made of three rectangles, and writes a button-shaped thing made of three divs. The library is irrelevant if the page never used it.

The check: pick three production pages at random. Count the percentage of visual elements that are library instances versus one-off frames. Under 70% and the spec build needs a page migration pass before the agent is worth running. We have seen this number sit at 35% on a site whose Figma library scored above 90% on every other metric. The library was beautiful. Nobody used it.

Naming hierarchy and slot patterns

Slot components, the ones that accept children, are the trickiest for an agent to spec. The pattern in Figma is usually a frame named slot or children with fill container sizing. If those frames are present and consistently named, the agent emits a sensible {children} prop. If they are missing or inconsistently named (some slot, some content, some unnamed), the agent hard-codes whatever happened to be inside the master at design time.

The audit: search the layer panel for slot. Count results. Cross-reference against the components that visually accept children (cards, modals, list rows). Anything that should have a slot and does not, fails.

The five-minute pre-quote triage

If the agency cannot give you two hours for a full audit, run this triage instead. It catches around 80% of the failure modes.

1. Open the file. Hit Ctrl/Cmd-/ and search for "Frame". If more than twenty top-level results return inside the library file, naming is broken.
2. Open the variables panel. If it is empty, tokens are not bound. Quote a token pass first.
3. Open one production page. Hover the first ten elements. Count how many show the purple diamond instance icon. Less than seven and the library is decorative.
4. Open the most-used component. Look at its description. Empty means no docs. Documented means proceed.

Five minutes. You will know whether the next conversation is about pricing or about prerequisites.

After the audit

When we built the spec agent for an architecture studio in Rotterdam earlier this year, the library passed every check except the variable one. We quoted two days of token-binding work upfront, ran the agent on the cleaned file, and shipped 47 React components from the Figma library in three working days. When we tried the same pipeline against a library that had failed the audit and the team insisted on skipping the cleanup, we spent twelve days and rewrote half the output by hand. That second project is the reason this checklist exists.

If you want help running the audit on your own library or wiring a spec agent that respects it, our AI agents practice does both as a fixed-scope engagement.

Open your own library now. Press Ctrl/Cmd-/ and search for "Frame". Whatever number comes back is the conversation you should be having before anyone quotes a spec agent against it.