Každý export figmascope začíná souborem .zip obsahujícím sedm artefaktů. CONTEXT.md je ten, který se čte jako první — záměrně. Není to README. Nejsou to generované dokumenty. Je to smlouva ve stylu kompilátoru mezi návrhem a agentem, který z něj vytvoří kód.

Tento příspěvek rozebírá, co v něm je, proč je strukturován tak, jak je, a co se pokazí, když ho přeskočíte.

Jak vypadá smlouva vs. jak vypadá dokumentace

Dokumentace popisuje, co existuje. Smlouva specifikuje, co musí být pravda. Tento rozdíl záleží, když vaším čtenářem je LLM, který ochotně vymýšlí hodnoty mezer, zploští hierarchie rozvržení nebo hardkóduje hex barvy v okamžiku, kdy nemá lepší možnost.

CONTEXT.md začíná deklarací cíle:

# CONTEXT.md — cíl Jetpack Compose

Tento soubor je autoritativní specifikací pro generování UI kódu z tohoto balíčku.
Čtěte ho před čtením jakéhokoli jiného souboru.

"Cíl Jetpack Compose" není dekorace. Agent ho používá k výběru composable primitiv, ke zpracování jednotek dp vs sp, k pochopení, že Modifier.padding() je správná abstrakce pro mezery, a k porozumění, že Box s Alignment je způsob, jak zacházet s overlay rozvržením. Cíl React/Tailwind generuje jiný CONTEXT.md s různými primitivy v omezeních.

Instrukce "přečtěte to jako první" je také záměrná. Agenti zpracovávají kontext zleva doprava. Pokud se pravidlo tokenu objeví poté, co agent již začal uvažovat o komponentě, omezení přichází příliš pozdě. Upřednostnění smlouvy znamená, že pravidla jsou aktivní od prvního tokenu generování.

Sekce striktních omezení

Nejzatíženější část CONTEXT.md je blok omezení:

## Striktní omezení (je nutné dodržovat)

- Nikdy nepoužívejte hardkódované hodnoty dp, pokud existuje token v rozsahu ±2dp
- Nikdy nezploštěte hierarchii rozvržení — zachovejte každý uzel stack/overlay/absolute
- Používejte hodnoty stringRef z strings.json, nikdy nevkládejte doslovný text
- Považujte chybějící pole za nepřítomná, ne za nulová
- Nevymýšlejte názvy komponent, které nejsou uvedeny v components/inventory.json

Každé omezení existuje, protože jsme viděli agenty ho porušovat. Pravidlo ±2dp je nejjasnějším příkladem. Bez něj agent narazí na gap: 14 na uzlu stack a napíše Arrangement.spacedBy(14.dp). S tímto pravidlem ví, že má zkontrolovat, zda je spacing.16 nebo spacing.12 v rozsahu 2dp, a použít token. To je jiný výstup — takový, který zůstane koherentní, když se hodnota tokenu změní.

Pravidlo hierarchie existuje, protože Compose je strom rozvržení. Když agent zploští vnořený stack do plochého seznamu umístěných prvků, zničí responsivní chování implikované původní strukturou. IR zachovává každou úroveň vnoření z důvodu — viz IR pro jednotlivé obrazovky — Stack, Overlay, Absolute, Leaf pro to, jak toto vnoření kóduje záměr rozvržení.

Omezení není "používejte tokeny, pokud se vám chce." Je to "nikdy nepoužívejte hardkód, pokud token existuje." To je zákaz, ne doporučení. LLM reagují na zákazy jinak než na doporučení.

Pravidlo stringRef záleží pro i18n. Pokud agent vloží "Speed Test" místo odkazu na klíč zdroje, vytvořili jste lokalizační díru. Omezení explicitně nasměruje agenta na strings.json.

Jak agent čte CONTEXT.md sekvenčně

Kontextová okna LLM zpracovávají tokeny zleva doprava. Struktura CONTEXT.md toho využívá. Pořadí je:

  1. Deklarace cíle (nastavuje celý rámec generování)
  2. Striktní omezení (zákazy, které platí pro každé rozhodnutí)
  3. Mapa balíčku (jaké soubory existují a co každý obsahuje)
  4. Pravidla použití tokenů (jak rozlišovat mezery, barvy, poloměry, typografii)
  5. Poznámky k rozsahu (poctivé mezery — co tento balíček pokrývá a co ne)

Sekce mapy balíčku říká agentovi, které soubory číst a v jakém pořadí:

## Obsah balíčku

- tokens.json — design tokeny (mezery, poloměry, barvy, typografie)
- screens/*.json — IR pro každou obrazovku ve formátu stack/overlay/absolute/leaf
- components/inventory.json — seznam identit komponent
- strings.json — klíče i18n zdrojů
- _meta.json — metadata generování a varování

Bez této mapy by agent možná nevěděl, že components/inventory.json existuje, nebo by mohl považovat _meta.json za hlavní specifikaci. Explicitní výčet řídí pořadí čtení.

Poznámky k rozsahu — co v0.4 poctivě nepokrývá

Sekce poznámek k rozsahu je místo, kde figmascope dokumentuje vlastní omezení. To je záměrné a nezpochybnitelné. Agent, který neví, že specifikace je neúplná, bude sebevědomě vyplňovat mezery vymýšlením. To je horší než znát mezeru.

## Poznámky k rozsahu (v0.4)

- Přechodové výplně nejsou podporovány. Uzly s přechodovými výplněmi emitují varování
  v _meta.json pod warnings. Považujte je za přibližnou plnou výplň nebo TODO.
- Tokeny typografie vyžadují naplnění Figma Variables. Pokud je tokensSource
  "inferred-from-frequency" nebo "none", pokrytí typografie může být neúplné.
- Tento balíček pokrývá pouze strukturu UI. Navigace, správa stavu
  a síťová volání jsou mimo rozsah.
- Instance komponent jsou identifikovány pomocí componentId. Úplné zdrojové
  props komponent nejsou zahrnuty — inventář dává identitu, ne implementaci.

Varování o přechodu je obzvláště důležité. Figma podporuje složité přechodové výplně, které nemají přímý ekvivalent v Compose bez vlastního kreslení. Místo tichého přeskočení přechodů nebo generování nefunkčního kódu figmascope emituje varování background-gradient-not-supported:<name> v _meta.json a poznamenává to zde, aby agent věděl, že má s postiženými uzly nakládat jako se známou mezerou, ne jako s chybou ve vlastním výstupu.

Poznámka k typografii se vztahuje na pole tokensSource v _meta.json. Když Figma soubor nemá Variables, figmascope odvozuje tokeny z frekvence — běžné hodnoty se stávají tokeny, vzácné ne. Poznámka k rozsahu říká agentovi, že toto odvození je nedokonalé a nemá předpokládat úplné pokrytí typografie. Viz tokens.json vysvětlen pro to, jak záložní odvozování funguje.

Příklady ŠPATNĚ / SPRÁVNĚ

Udělejme to konkrétní. Daný uzel stack s gap: 16 a soubor tokenů obsahující spacing.16: 16:

Bez omezení CONTEXT.md (ŠPATNĚ):

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

S omezeními CONTEXT.md (SPRÁVNĚ):

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

Výstup SPRÁVNĚ odkazuje na tokeny. Když design systém změní spacing.16 z 16dp na 14dp, kód zůstane správný bez prohledávání a nahrazování celé kódové základny.

Další příklad — zacházení s řetězci. Daný listový uzel s text: "Speed Test" a stringRef: "speed.test":

ŠPATNĚ:

Text(text = "Speed Test")

SPRÁVNĚ:

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

Omezení ukazuje na strings.json, klíč je speed.test a agent ví, jak mapovat tečkovou notaci na Android resource ID. To je možné pouze tehdy, pokud agent přečetl omezení před generováním komponenty.

Proč si prompt nepsat sami?

Tyto instrukce si můžete napsat ručně do promptu. figmascope je externalizuje do souboru, protože:

Cílem není prompt-engineerovat kolem výchozích nastavení agenta. Je to dodat specifikaci, která výchozí nastavení učiní irelevantní.

Porovnání struktury s alternativami

Figma Dev Mode výstupuje měření, proměnné a úryvky kódu. Nevytváří specifikaci. Agent používající výstup Dev Mode musí pravidla odvodit z příkladů — což znamená, že pro hraniční případy odvodí špatná pravidla.

Locofy a podobné nástroje generují kód přímo. Nemají ekvivalent CONTEXT.md, protože neočekávají, že agent bude číst specifikaci — očekávají, že budou agenti sami. To funguje, když generování kódu nástroje přesně odpovídá vašemu stacku. Nefunguje to, když máte konvence pojmenování specifické pro projekt, vlastní knihovnu komponent nebo design systém s tokeny, o kterých nástroj neví.

CONTEXT.md je strojově čitelný design brief. Je to věc, která existovala jako stránka Confluence nebo Notion doc v každém pre-LLM předávání návrhu, jen strukturovaná pro publikum, které skutečně dodržuje pravidla.

Co s ním dělat

Když otevřete export figmascope v Cursor nebo Claude Code:

  1. Přidejte @CONTEXT.md do svého kontextu před jakýmkoli promptem o návrhu.
  2. Odkazujte na JSON obrazovky, na které pracujete: @screens/home.json.
  3. Pokud se dotýkáte tokenů, přidejte @tokens.json.
  4. Pokud pracujete s řetězci, přidejte @strings.json.

Omezení CONTEXT.md platí pro celé sezení po načtení. Nepřidáváte ho znovu pro každý prompt — přidáte ho jednou na začátku a necháte ho rámovat každé následné generování.

Ostatní artefakty v balíčku jsou pokryty ve zbytku této série. Začněte s tokens.json vysvětlen pro to, jak systém tokenů zpracovává soubory s Figma Variables i bez nich, nebo s IR pro jednotlivé obrazovky pro to, jak se rozvržení Figma mapují na uzly stack/overlay/absolute/leaf. Chcete to vyzkoušet? Vložte URL Figma na figmascope.dev a exportujte svůj první balíček.