Waarom raadt een AI je componenten mis?

Een AI-agent die Figma-designs omzet naar code heeft één groot probleem: hij ziet de componenten in je design, maar weet niet hoe ze in de echte codebase heten of werken. Dus gaat hij raden. Soms raadt hij goed. Vaker bouwt hij iets na van primitieven, terwijl je al een kant-en-klaar component had liggen.

Dit is iets waar ik eerlijk gezegd te lang mee heb rondgelopen. Ik werkte met Figma en Claude voor design-to-code werk, en de output was wisselend. Soms perfect, soms een handgemaakte versie van een component die we al hadden. Het probleem zat niet in het model. Het zat in de context die ik meegaf.

Code Connect is de oplossing die Figma biedt voor dit probleem. Het is een koppeling (mapping) tussen een component in Figma en zijn tegenhanger in de code. Vergelijk het met een woordenboek: de AI ziet ‘Stepper’ in het design en slaat op in het woordenboek op wat dat in jouw codebase betekent, inclusief alle properties en gebruik.

Zonder dat woordenboek gaat de agent gokken. En bij complexe componenten, zoals een Stepper met tientallen properties, levert dat bijna altijd rommel op. Met een goede design system opzetten-aanpak leg je in één tekstbestand vast hoe jouw merk eruitziet, dat is een laagdrempelig startpunt als je nog geen volledig design system hebt.

Wat leverde 22% tijdsbesparing op in de praktijk?

Coinbase testte Code Connect in een gecontroleerde opzet: hetzelfde design, dezelfde prompt, hetzelfde model, drie keer uitgevoerd. Met en zonder Code Connect. Het resultaat was consistent: elke run met Code Connect was goedkoper, sneller en nauwkeuriger dan zonder. Gemiddeld 22,5% lagere kosten en 22% kortere implementatietijd.

De testopzet was slim. Ze gebruikten een design dat niet te simpel en niet te complex was: een mix van componenten, inclusief een paar lastige gevallen zoals de Stepper (complex, veel properties) en icoon- en illustratienamen (die agents notoir slecht raden).

Dat laatste punt trof me. Agenten hallucineren icoon- en illustratienamen. Ze verzinnen namen die niet bestaan. Na het instellen van Code Connect verdween dat probleem volledig. Niet minder vaak. Verdwenen.

De verklaring is logisch: de agent hoeft niet meer te zoeken en te raden welk icoon er bedoeld wordt. De mapping vertelt het hem direct. Minder zoekwerk betekent minder tokens, en minder tokens betekent lagere kosten en kortere looptijd. Dit is precies waarom ik nu bij elk project als eerste check of het design system goed is opgezet voordat ik een AI-agent op een design loslaat. Een slordig design system is een dure agent.

Overigens controleerde de test ook voor prompt caching, een techniek waarbij eerder verwerkte context hergebruikt wordt. Dat kan resultaten vertekenen als je het niet uitschakelt. Ze deden dat wel, wat de uitkomsten betrouwbaarder maakt.

Agent skills vs. Code Connect: doen ze hetzelfde?

Nee, en dat onderscheid is belangrijk. Agent skills vertellen een AI hoe hij iets moet bouwen: welke patronen te kiezen, welke componenten te vermijden, hoe je design tokens gebruikt. Code Connect geeft de agent context over wat er beschikbaar is. De twee vullen elkaar aan, ze vervangen elkaar niet.

Dit is een inzicht dat ik zelf ook pas later begreep. Ik dacht dat goede instructies (agent skills of een systeem-prompt) genoeg waren om een AI goed te laten presteren op design-to-code taken. Dat klopt deels. Maar instructies over hoe je iets bouwt helpen niet als de agent niet weet wat er al gebouwd is.

De vergelijking die ik gebruik: agent skills zijn de werkwijze van een nieuwe collega, Code Connect is het onboarding-document met alle bestaande componenten. Je hebt beide nodig.

Interessant is ook de langetermijnvisie hierachter. Naarmate AI-modellen beter worden, hebben ze minder expliciete instructies (skills) nodig om goede keuzes te maken. Maar de kwaliteit van de context, weten welke componenten er zijn en hoe ze werken, blijft altijd relevant. Dat maakt Code Connect eigenlijk toekomstvaster dan agent skills.

Wil je begrijpen hoe Figma Skills werken als herbruikbare AI-instructies? Lees dan hoe Figma Skills designers helpen met AI-workflows als goed startpunt om het verschil voelbaar te maken.

Wat moet je nu doen als je een design system hebt?

Check of je componenten in Figma gekoppeld zijn aan de code via Code Connect. Zijn ze dat niet, of zijn de mappings verouderd? Dan geef je elke AI-agent die je gebruikt een slechte startpositie. Updaten hoeft niet per hand: je kunt een agent de mappings laten schrijven op basis van een lijst componenten.

Het Coinbase-team had hetzelfde probleem: bestaande mappings waren verouderd en nieuwe componenten hadden helemaal geen template. Ze losten dat op door een agent in te zetten die de mappings parallel bijwerkte. In vier uur hadden ze volledige dekking voor hun design system.

Dat is de aanpak die ik zou volgen. Niet handmatig elke component doorlopen, maar een gestructureerde lijst maken en een agent het werk laten doen. Let op: de output moet je nog wel controleren. Een agent die mappings schrijft kan fouten maken, zeker bij complexe componenten.

Heb je nog geen design system? Dan is dit een goed moment om na te denken over hoe je dat opzet. Niet als luxe voor grote teams, maar als fundament voor alles wat je met AI bouwt. Met een DESIGN.md leg je in één tekstbestand vast hoe jouw merk eruitziet, dat is een laagdrempelig startpunt als je geen volledig design system hebt.

Voor wie WordPress gebruikt en wil weten hoe AI past in het bredere plaatje van webdesign en development: AI inzetten voor WordPress-code begrijpen en verbeteren laat zien hoe je AI als sparringpartner gebruikt in plaats van als schrijfmachine.

Het probleem: AI-tools missen context van jouw merk

Je laat een AI een banner of UI maken en krijgt drie keer iets anders terug. Andere kleur, ander gevoel. Niet jouw stijl. Dat is geen bug. AI-tools werken op basis van wat je ze geeft. Zonder merkinformatie gokken ze op iets generieks.

Bij mijn klanten zie ik dit elke week. Vorige week kwam een klant in de hospitality bij me met drie social-posts uit een AI-tool: drie keer dezelfde prompt, drie keer een ander oranje. Hij dacht eerst dat het aan zijn ogen lag , tot ik de hex-codes naast elkaar zette en hij het verschil zwart-op-wit zag.

De fout zit niet in de tool, hij zit in het gebrek aan context. Bij Midjourney, Claude, ChatGPT en Figma AI werkt het allemaal zo. Geen merkinformatie? Dan gokken ze. DESIGN.md vult die context in één keer in en houdt hem voor elke volgende prompt vast.

Wat DESIGN.md is en waarom het werkt

DESIGN.md is een tekstbestand met je merkinfo in een formaat dat AI direct begrijpt. Geen formeel document. Geen technische specificatie. Kleuren als hex-codes, fontnamen, een paar stijlsteekwoorden, korte componentbeschrijvingen. Eén tot twee pagina's max.

Ik gebruik dit zelf voor elk klantproject sinds een half jaar. Het scheelt me makkelijk een uur per ontwerpronde aan corrigeren en herhalen. Werkt in elke AI-tool die tekst als input accepteert: ChatGPT, Claude, Midjourney, Figma AI, Cursor, Lovable.

Het bestand zelf hoef je nergens te uploaden. Je plakt de inhoud aan het begin van je prompt, daarna pas komt je opdracht. Resultaat: consistente output die er elke keer hetzelfde uitziet.

De vier basissecties die je opschrijft

Vier secties zijn genoeg. Kleuren als hex-codes (niet "donkerblauw" maar #0A1F44). Fonts met gewicht ("Inter Regular 400"). Drie tot vijf stijlsteekwoorden. Korte componentbeschrijvingen voor je terugkerende UI-elementen.

Concrete waarden zijn het belangrijkst. Niet “warm oranje” maar #F5821F. Niet “modern blauw” maar #0A1F44. AI vertaalt jouw woorden naar pixels, en die vertaling werkt alleen voorspelbaar bij exacte waarden.

Mijn eigen fout in het begin: te veel willen vastleggen. Ik schreef pagina’s vol met uitzonderingen, edge cases en gedragsregels per component. De AI raakte juist meer in de war en mengde regels door elkaar. Sinds ik me beperk tot een halve A4 met alleen de essentials, werkt het tien keer beter.

Voor componenten geef je één regel per type: “Primaire knop: oranje achtergrond, witte tekst, 4px border-radius, geen schaduw.” Dat is genoeg. Te veel detail laat de AI dwalen.

Werkend voorbeeld: DESIGN.md voor een bouwbedrijf

Dit is de DESIGN.md die ik gebruik voor een klant in de bouw. Concreet, in dezelfde structuur die ik altijd hanteer. Gebruik 'm als template: vervang de waarden door die van jou en je hebt binnen tien minuten een werkend bestand.

De fictieve klant heet “Bouwbedrijf Janssen”. De structuur hieronder werkt 1-op-1 voor elke andere branche, alleen de waarden verschillen.

# DESIGN.md ,  Bouwbedrijf Janssen

## Kleuren
- Primair: #1B3A57 (donkerblauw, voor headers en knoppen)
- Accent: #E8A33D (warm geel-oranje, voor CTA's en hover-states)
- Tekst: #1A1A1A op #FFFFFF
- Achtergrond licht: #F5F2ED (gebroken wit, geen plat wit)
- Lijnen en borders: #D4CFC4

## Typografie
- Headings: Montserrat SemiBold 600
- Body: Inter Regular 400
- Captions: Inter Light 300, 14px
- Knoppen: Montserrat Medium 500, all caps

## Stijl in steekwoorden
Solide, ambachtelijk, betrouwbaar, ruime witregels, geen schaduwen, foto's altijd warm-getint.

## Componenten
- Primaire knop: #1B3A57 achtergrond, witte tekst, 4px border-radius, hover #E8A33D
- Secundaire knop: transparant, 1px border #1B3A57, blauwe tekst
- Kaart: #FFFFFF achtergrond, 8px border-radius, 1px border #D4CFC4, geen schaduw
- Foto's: altijd 16:9, warme tint via 5% sepia-overlay

## Tone of voice
Direct, geen jargon, jij/je-vorm, korte zinnen. Vermijd: "innovatief", "passie", "kwaliteit". Gebruik: "we bouwen", "we leveren op tijd".

Plak deze inhoud aan het begin van je prompt en je AI-tool weet direct wat hij wel en niet moet doen. Een UI-generator levert nu een knop op met #1B3A57, niet met een willekeurig blauw.

Hoe je DESIGN.md in de praktijk gebruikt

In de praktijk: open je AI-tool, plak de DESIGN.md, daarna pas je opdracht. Werkt voor afbeeldingen, UI, code en zelfs teksten als je een tone of voice-sectie toevoegt. Maak twee versies: een korte voor snelle prompts, een complete voor diepere opdrachten.

Voorbeeld voor een UI-generator: “[DESIGN.md inhoud] Maak nu een contactformulier met deze stijl. Velden: naam, e-mail, bericht.” Je krijgt een formulier in jouw kleuren, met jouw font, met de juiste border-radius. Geen willekeur meer.

Voor afbeeldingsgeneratoren werk je met een ingedikte versie. Niet de hele DESIGN.md, alleen de relevante regels: primaire en accent-kleur, drie stijl-steekwoorden, eventuele foto-stijl. Vier regels meegeven werkt vaak beter dan twintig.

Voor AI-codeertools zoals Cursor of Claude Code sla je het bestand op in je projectmap. Tools die met repositorybestanden werken pikken het automatisch op als context. Wat ik bij klanten doe: bouw DESIGN.md in de eerste week van een project en sla hem op naast de README. Geen overleg meer over kleuren, geen “welk geel was het ook alweer?”. Het bestand is de bron van waarheid.