Elke export van figmascope begint met een .zip met zeven artefacten. CONTEXT.md is het artefact dat als eerste wordt gelezen — met opzet. Het is geen README. Het is geen gegenereerde documentatie. Het is een compilercontract tussen het ontwerp en de agent die het in code zal omzetten.

Dit artikel doorloopt wat erin staat, waarom het zo is gestructureerd en wat er misgaat als je het overslaat.

Hoe een contract eruitziet versus hoe documentatie eruitziet

Documentatie beschrijft wat bestaat. Een contract specificeert wat waar moet zijn. Dat onderscheid is belangrijk als je lezer een LLM is dat vrolijk afstandswaarden verzint, lay-outhiërarchieën afvlakt of hexkleuren hardcoded als het geen betere optie heeft.

CONTEXT.md opent met een doelverklaring:

# CONTEXT.md — Jetpack Compose-doel

Dit bestand is de gezaghebbende specificatie voor het genereren van UI-code uit deze bundel.
Lees het voordat je andere bestanden leest.

Het "Jetpack Compose-doel" is geen decoratie. De agent gebruikt het om composable primitieven te kiezen, dp- versus sp-eenheden af te handelen, te weten dat Modifier.padding() de juiste abstractie voor afstand is en te begrijpen dat Box met Alignment de manier is om overlaylayouts te verwerken. Een React/Tailwind-doel genereert een andere CONTEXT.md met andere primitieven in de beperkingen.

De instructie "lees dit eerst" is ook opzettelijk. Agents verwerken context van links naar rechts. Als een tokenregel na het begin van het redeneren over een component verschijnt, komt de beperking te laat. Het vooraf laden van het contract zorgt ervoor dat de regels actief zijn vanaf de eerste token van de generatie.

De sectie met strikte beperkingen

Het meest draagkrachtige deel van CONTEXT.md is het beperkingsblok:

## Strikte beperkingen (moet worden gevolgd)

- Hardcode nooit dp-waarden als er een token bestaat binnen ±2dp
- Verplat nooit de lay-outhiërarchie — bewaar elk stack/overlay/absolute-knooppunt
- Gebruik stringRef-waarden uit strings.json, nooit inline letterlijke tekst
- Behandel ontbrekende velden als afwezig, niet als nul
- Verzin geen componentnamen die niet voorkomen in components/inventory.json

Elke beperking bestaat omdat we agents deze hebben zien overtreden. De ±2dp tokenregel is het duidelijkste voorbeeld. Zonder deze regel schrijft een agent die een gap: 14 op een stack-knooppunt tegenkomt Arrangement.spacedBy(14.dp). Met de regel weet het dat het moet controleren of spacing.16 of spacing.12 binnen 2dp valt en in plaats daarvan het token moet gebruiken. Dat is een andere uitvoer — één die coherent blijft wanneer de tokenwaarde verandert, niet één die dat niet doet.

De hiërarchieregel bestaat omdat Compose een layoutboom is. Wanneer een agent een geneste stack afvlakt tot een platte lijst van gepositioneerde elementen, vernietigt het het responsieve gedrag dat door de oorspronkelijke structuur wordt geïmpliceerd. De IR bewaart elk niveau van nesting om een reden — zie Per-scherm IR — Stack, Overlay, Absolute, Leaf voor hoe die nesting lay-outintentie codeert.

De beperking is niet "gebruik de tokens als je dat wilt." Het is "hardcode nooit als er een token bestaat." Dat is een verbod, geen suggestie. LLM's reageren anders op verboden dan op suggesties.

De stringRef-regel is belangrijk voor i18n. Als een agent "Snelheidstest" inline hardcoded in plaats van naar de resourcesleutel te verwijzen, heb je een lokalisatiegat gecreëerd. De beperking wijst de agent expliciet naar strings.json.

Hoe de agent CONTEXT.md sequentieel leest

LLM-contextvensters verwerken tokens van links naar rechts. De structuur van CONTEXT.md maakt hier gebruik van. De volgorde is:

  1. Doelverklaring (stelt het volledige generatiekader in)
  2. Strikte beperkingen (verboden die van toepassing zijn op elke beslissing)
  3. Bundelkaart (welke bestanden bestaan en wat elk bevat)
  4. Tokengebruiksregels (hoe afstand, kleur, straal en typografie op te lossen)
  5. Scope-opmerkingen (eerlijke hiaten — wat deze bundel wel en niet dekt)

De bundelkaartensectie vertelt de agent welke bestanden te lezen en in welke volgorde:

## Bundelinhoud

- tokens.json — ontwerptokens (afstand, straal, kleur, typografie)
- screens/*.json — per-scherm IR in stack/overlay/absolute/leaf-formaat
- components/inventory.json — componentidentiteitslijst
- strings.json — i18n-resourcesleutels
- _meta.json — generatiemetadata en waarschuwingen

Zonder deze kaart weet een agent misschien niet dat components/inventory.json bestaat, of behandelt het _meta.json als de hoofdspecificatie. De expliciete opsomming begeleidt de leesvolgorde.

Scope-opmerkingen — wat v0.4 eerlijk niet dekt

De sectie scope-opmerkingen is waar figmascope zijn eigen beperkingen documenteert. Dit is opzettelijk en niet onderhandelbaar. Een agent die niet weet dat een specificatie onvolledig is, zal vol vertrouwen de hiaten opvullen met verzinsels. Dat is erger dan weten dat het gat bestaat.

## Scope-opmerkingen (v0.4)

- Verloopvullingen worden niet ondersteund. Knooppunten met verloopvullingen geven een waarschuwing
  in _meta.json onder warnings. Behandel als een effen vullingbenadering of TODO.
- Typografietokens vereisen Figma Variables om te worden ingevuld. Als tokensSource
  "inferred-from-frequency" of "none" is, kan de typografiedekking gedeeltelijk zijn.
- Deze bundel dekt alleen UI-structuur. Navigatie, statusbeheer
  en netwerkoproepen vallen buiten het bereik.
- Componentinstanties worden geïdentificeerd door componentId. Volledige componentbronprops
  zijn niet opgenomen — de inventaris geeft identiteit, geen implementatie.

De verloopwaarschuwing is bijzonder belangrijk. Figma ondersteunt complexe verloopvullingen zonder direct Compose-equivalent zonder aangepast tekenen. In plaats van verlopende kleurvullingen stilletjes te laten vallen of gebroken code te genereren, geeft figmascope een background-gradient-not-supported:<name>-waarschuwing in _meta.json en vermeldt het hier zodat de agent weet aangetaste knooppunten te behandelen als een bekend hiaat in plaats van een bug in zijn eigen uitvoer.

De typografienotitie verbindt zich met het veld tokensSource in _meta.json. Wanneer een Figma-bestand geen Variables heeft, leidt figmascope tokens af op basis van frequentie — veelvoorkomende waarden worden tokens, zeldzame waarden niet. De scope-opmerking vertelt de agent dat deze inferentie onvolmaakt is en niet te veronderstellen dat er volledige typografiedekking is. Zie tokens.json uitgelegd voor hoe het inferentieterugvalplan werkt.

FOUT / GOED-voorbeelden

Laten we dit concreet maken. Gegeven een stack-knooppunt met gap: 16 en een tokenbestand met spacing.16: 16:

Zonder CONTEXT.md-beperkingen (FOUT):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Met CONTEXT.md-beperkingen (GOED):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

De GOEDE uitvoer is tokengerefereerd. Wanneer het ontwerpsysteem spacing.16 van 16dp naar 14dp verandert, blijft de code correct zonder een zoek-en-vervang in de codebase.

Nog een voorbeeld — tekenreeksverwerking. Gegeven een leaf-knooppunt met text: "Snelheidstest" en stringRef: "speed.test":

FOUT:

Text(text = "Snelheidstest")

GOED:

Text(text = stringResource(R.string.speed_test))

De beperking wijst naar strings.json, de sleutel is speed.test en de agent weet hoe puntnotatie moet worden omgezet naar Android-resource-ID's. Dat is alleen mogelijk als de agent de beperking heeft gelezen vóór het genereren van de component.

Waarom niet gewoon zelf de agent aansturen?

Je kunt deze instructies handmatig in je prompt schrijven. figmascope externaliseert ze naar een bestand omdat:

Het doel is niet om prompt-engineering te doen rondom de standaardinstellingen van de agent. Het doel is om een specificatie te leveren die de standaardinstellingen irrelevant maakt.

Structuur vergeleken met alternatieven

Figma's Dev Mode levert metingen, variabelen en codefragmenten. Het produceert geen specificatie. De agent die Dev Mode-uitvoer gebruikt, moet regels uit voorbeelden afleiden — wat betekent dat het verkeerde regels zal afleiden voor randgevallen.

Locofy en soortgelijke tools genereren direct code. Ze hebben geen CONTEXT.md-equivalent omdat ze niet verwachten dat een agent een specificatie leest — ze verwachten zelf de agent te zijn. Dat werkt wanneer de codegeneratie van de tool precies overeenkomt met je stack. Het werkt niet wanneer je projectspecifieke naamgevingsconventies, een aangepaste componentbibliotheek of een ontwerpsysteem met tokens hebt die de tool niet kent.

CONTEXT.md is een machine-leesbaar ontwerpbriefing. Het is het ding dat als een Confluence-pagina of Notion-document bestond in elke pre-LLM-ontwerpoverdracht, alleen gestructureerd voor een publiek dat daadwerkelijk regels volgt.

Wat er mee te doen

Wanneer je een figmascope-export opent in Cursor of Claude Code:

  1. Voeg @CONTEXT.md toe aan je context vóór elke prompt over het ontwerp.
  2. Refereer naar de scherm-JSON waaraan je werkt: @screens/home.json.
  3. Als je tokens aanraakt, voeg @tokens.json toe.
  4. Als je met tekenreeksen werkt, voeg @strings.json toe.

De CONTEXT.md-beperkingen gelden voor de hele sessie zodra ze zijn geladen. Je voegt het niet per prompt opnieuw toe — je voegt het eenmalig aan het begin toe en laat het elke volgende generatie inkaderen.

De andere artefacten in de bundel worden behandeld in de rest van deze serie. Begin met tokens.json uitgelegd voor hoe het tokensysteem omgaat met bestanden met en zonder Figma Variables, of Per-scherm IR voor hoe Figma-layouts worden toegewezen aan stack/overlay/absolute/leaf-knooppunten. Klaar om het te proberen? Plak je Figma URL op figmascope.dev en exporteer je eerste bundel.