Figma-library audit: 8 checks vóór een Claude spec-agent

Het is de derde design-naar-code pilot in twee maanden. Het bureau stuurt ons een Figma-bestand, we koppelen het aan een Claude-gestuurde component-spec-agent, de agent draait, en dan kijken we de komende vier uur toe hoe de outputkwaliteit wegloopt. Componenten die één variant moeten zijn, komen er als drie uit. Een button die afgelopen dinsdag is gegenereerd, lijkt totaal niet op de button van vanochtend. De bureau-lead vraagt wat er aan de hand is. We openen het layer-paneel en wijzen.

De frames heten Frame 47, Frame 47 copy, Container / Hero / fix-FINAL. De auto-layout-richting staat goed. De padding klopt. Maar de namen die de spec-agent leest als een contract, zijn ruis. Dus produceert de agent ruis.

Dit is inmiddels de audit die we doen op de Figma-library van elk bureau, voordat we een prijs op een spec-agent-build plakken. Een junior designer is er twee uur mee bezig. Het scheelt de klant ongeveer drie weken.

Waarom de agent vastloopt op naamgeving

Een Claude-gestuurde spec-agent leest een Figma-bestand als een tree. Hij ziet niet eerst de pixels. Hij ziet de structuur: frame-namen, auto-layout-eigenschappen, varianten, variables, toegepaste stijlen. Is die tree schoon, dan schrijft de agent React- of Vue- of Svelte-componenten die eruitzien alsof een zorgvuldig mens ze heeft geschreven, omdat een zorgvuldig mens dat ook deed, eerder in het proces, door dingen goed te benoemen.

Is de tree rommelig, dan doet de agent wat taalmodellen altijd doen onder onzekerheid: hij gokt. De gokken zijn plausibel. Ze zijn ook fout op een manier waar een senior developer een hele middag voor nodig heeft om ze terug te vinden. De Hacker News-thread van deze week, getiteld I design with Claude more than Figma now, had hetzelfde thema lopen door de reacties. Het model is uitstekend in vertalen. De bron moet wel een echt document zijn, geen schets.

De audit hieronder is structureel, niet esthetisch. We beoordelen niet of het ontwerp goed is. We beoordelen of een machine die structuur leest, er iets bruikbaars uit kan halen.

Consistentie van auto-layout-labels

Dit is degene die alle drie de pilots de nek omdraaide. Figma's auto-layout is sterk en grotendeels onzichtbaar: je zet een frame op Vertical, gap 16, padding 24, fill horizontally en geeft hem nooit een andere naam dan Frame 1432. De pixels kloppen. De spec-agent heeft geen manier om Frame 1432 van Frame 1433 te onderscheiden, allebei verticale stacks met dezelfde gap, die in twee verschillende componenten zitten.

De check: open het layer-paneel op de tien meest gebruikte componenten. Tel hoeveel container-frames een betekenisvolle naam hebben. We willen boven de 80%. We zien gemiddeld 15%. Acceptabele namen zien er zo uit: card / body, nav / item-row, form / field-group. Alles wat Frame, Group of Rectangle 4 heet, valt af.

Varianten-grammatica door de hele set

Figma-varianten zijn properties op een component. Een button kan state: default | hover | disabled en size: sm | md | lg dragen. Goed gedaan is dit precies wat de agent nodig heeft om een getypte component te emitten. Slecht gedaan is het een kerkhof van half afgemaakte combinaties en losse pagina's die twee maanden geleden van de library zijn afgevallen.

Wat we checken: variant-property-namen zijn consistent door de library. state in het ene component is niet status in het andere. Waarden gebruiken hetzelfde vocabulaire: default / hover / disabled, niet default / hover / off op de ene plek en idle / hover / inactive op de andere. De agent normaliseert dit niet voor je. Heeft de library drie woorden voor "disabled", dan heeft de gegenereerde code drie woorden voor "disabled", en wordt jouw design-system-PR-review een vocabulairegevecht.

Token-dekking en het variables-dictionary

Figma variables zijn het dichtste dat de tool standaard bij design tokens komt. Kleuren, spacing, radii, type styles. Bindt de library deze goed, dan mapt de spec-agent ze in één pass op CSS custom properties of de token-engine van je keuze. Gebruikt de library rauwe hex-codes en pixelwaardes, dan verzint de agent namen, en dat zal hij doen, en die namen matchen niet door de componenten heen.

De audit: sampel tien frames door het hele bestand. Tel welk percentage van fills, strokes en spacing-waardes aan variables hangt versus hardgecodeerd is. Onder de 60% betekent dat je een token-extractie-pass quoot voordat de spec-agent draait. Boven de 90% betekent dat je volgende week met de agent kunt beginnen.

Detach-rate als gezondheidssignaal

Een instance in Figma kan worden losgekoppeld van zijn main component. De pixels blijven. De connectie breekt. Detached instances zijn de beste proxy die we hebben gevonden voor de gezondheid van een library, omdat ze je vertellen of het team de componenten echt vertrouwt of er stiekem omheen werkt.

De Figma REST API geeft dit direct terug. Trek het bestand op, loop door de tree, tel nodes van type INSTANCE tegenover frames die er visueel uitzien alsof het instances zouden zijn. We verwachten minder dan 5% detached door het hele bestand. We hebben 40% gezien. Op 40% is de library decoratief. Het team rolt alles handmatig uit. De spec-agent reproduceert getrouw de handmatige output, niet de library-intentie, want de handmatige output is wat er daadwerkelijk op de pagina's staat.

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

Draai dat, en dezelfde telling voor COMPONENT-nodes. De verhouding is je gezondheidsscore. Als detached pagina-frames de component-instances overtreffen op een echte productie-frame, faalt de audit op deze as alleen al en verschuift het gesprek van "prijs de spec-agent" naar "prijs de migratie".

Component-documentatie die de vertaling overleeft

De meeste bureaus hebben een Notion-pagina of een README waarin staat "gebruik de primary button voor de primaire actie". De spec-agent leest geen Notion. Hij leest wél het description-veld op een Figma-component, als dat is ingevuld. We willen korte, structurele beschrijvingen: "Primary action. Pairs with secondary on right. Disabled state forbids hover."

De audit: dump component-beschrijvingen via de API. Tel hoeveel er inhoud hebben. Onder de 30% en de agent verzint prop-documentatie die zelfverzekerd klinkt en deels fout is. Boven de 80% en de gegenereerde TypeScript-types komen er bij de eerste pass al bijna reviewbaar uit. Dit is de goedkoopste check om op te falen. Het is ook de goedkoopste om te fixen: een designer schrijft de beschrijvingen op een middag, en de kwaliteit van de spec-output gaat de volgende dag meetbaar omhoog.

Pagina-trouw versus library-trouw

Dit is de subtiele. Een team kan een schone library hebben en alsnog een chaotische site live hebben staan, omdat de pagina's gebouwd zijn voordat de library bestond en niemand ze ooit gemigreerd heeft. De spec-agent wijst naar de pagina, ziet een button-vormig ding van drie rechthoeken, en schrijft een button-vormig ding van drie divs. De library is irrelevant als de pagina hem nooit heeft gebruikt.

De check: pak drie productiepagina's at random. Tel het percentage visuele elementen dat library-instances zijn versus losse frames. Onder de 70% en de spec-build vraagt om een pagina-migratie-pass voordat de agent de moeite waard is om te draaien. We hebben dit getal op 35% zien staan op een site waarvan de Figma-library boven de 90% scoorde op elke andere metric. De library was prachtig. Niemand gebruikte hem.

Naamgevings-hiërarchie en slot-patronen

Slot-componenten, degene die children accepteren, zijn voor een agent het lastigst om te speccen. Het patroon in Figma is meestal een frame met de naam slot of children met fill container-sizing. Zijn die frames aanwezig en consistent benoemd, dan emit de agent een verstandige {children}-prop. Ontbreken ze, of zijn ze inconsistent benoemd (sommige slot, sommige content, sommige naamloos), dan codeert de agent hard wat er op designmoment in de master stond.

De audit: zoek in het layer-paneel op slot. Tel resultaten. Kruis-check tegen de componenten die visueel children accepteren (cards, modals, list rows). Alles wat een slot zou moeten hebben en geen heeft, valt af.

De vijf-minuten pre-quote-triage

Kan het bureau je geen twee uur geven voor een volledige audit, draai dan deze triage. Hij vangt ongeveer 80% van de faalmodi.

1. Open het bestand. Druk op Ctrl/Cmd-/ en zoek op "Frame". Komen er meer dan twintig top-level resultaten terug binnen het library-bestand, dan is naamgeving stuk.
2. Open het variables-paneel. Is het leeg, dan zijn tokens niet gebonden. Quoot eerst een token-pass.
3. Open één productiepagina. Hover over de eerste tien elementen. Tel hoeveel er het paarse diamant-icoon van een instance laten zien. Minder dan zeven en de library is decoratief.
4. Open de meest-gebruikte component. Kijk naar zijn description. Leeg betekent geen docs. Gedocumenteerd betekent doorgaan.

Vijf minuten. Dan weet je of het volgende gesprek over prijs gaat of over voorwaarden.

Na de audit

Toen we eerder dit jaar de spec-agent bouwden voor een architectuurstudio in Rotterdam, slaagde de library op elke check behalve die van de variables. We quootten vooraf twee dagen aan token-binding-werk, draaiden de agent op het opgeschoonde bestand, en leverden in drie werkdagen 47 React-componenten op uit de Figma-library. Toen we dezelfde pipeline probeerden op een library die de audit niet had gehaald en het team de schoonmaak wilde overslaan, waren we twaalf dagen bezig en herschreven we de helft van de output met de hand. Dat tweede project is de reden dat deze checklist bestaat.

Wil je hulp bij de audit op je eigen library of bij het bouwen van een spec-agent die er rekening mee houdt, dan doet onze AI-agents-praktijk beide als fixed-scope opdracht.

Open je eigen library nu. Druk op Ctrl/Cmd-/ en zoek op "Frame". Welk getal er ook terugkomt, dat is het gesprek dat je moet hebben voordat iemand een prijs op een spec-agent plakt.