CONTEXT.md की संरचना — वह Spec जो आपका Coding Agent पहले पढ़ता है

हर figmascope export एक .zip से शुरू होती है जिसमें सात artifacts होते हैं। CONTEXT.md वह फ़ाइल है जो सबसे पहले पढ़ी जाती है — जानबूझकर। यह README नहीं है। यह generated docs नहीं हैं। यह design और उस agent के बीच एक compiler-style contract है जो इसे code में बदलेगा।

यह post इसमें क्या है, इसे इस तरह क्यों structure किया गया है, और इसे skip करने पर क्या गलत होता है — यह सब cover करता है।

Contract बनाम docs — फ़र्क क्या है?

Documentation बताता है कि क्या मौजूद है। Contract specify करता है कि क्या होना चाहिए। यह फ़र्क तब मायने रखता है जब आपका reader एक LLM है जो किसी बेहतर option के न होने पर खुशी-खुशी spacing values गढ़ लेगा, layout hierarchies को flatten कर देगा, या hex colors को hardcode कर देगा।

CONTEXT.md एक target declaration से शुरू होता है:

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

"Jetpack Compose target" सिर्फ decoration नहीं है। Agent इसका उपयोग composable primitives चुनने, dp बनाम sp units handle करने, यह जानने के लिए करता है कि spacing के लिए Modifier.padding() सही abstraction है, और overlay layouts के लिए Box with Alignment का उपयोग होता है। React/Tailwind target के लिए एक अलग CONTEXT.md generate होता है जिसमें अलग primitives होते हैं।

"पहले इसे पढ़ें" instruction भी जानबूझकर है। Agents context को left-to-right process करते हैं। अगर token rule agent के किसी component के बारे में reasoning शुरू करने के बाद आती है, तो constraint बहुत देर से पहुंचती है। Contract को front-load करने से rules generation के पहले token से ही active हो जाती हैं।

Strict constraints section

CONTEXT.md का सबसे महत्वपूर्ण हिस्सा constraints block है:

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

हर constraint इसलिए है क्योंकि हमने agents को इसे violate करते देखा है। ±2dp token rule सबसे स्पष्ट उदाहरण है। इसके बिना, एक agent जो stack node पर gap: 14 देखता है, वह Arrangement.spacedBy(14.dp) लिखेगा। इस rule के साथ, वह check करेगा कि spacing.16 या spacing.12 2dp के भीतर है या नहीं और token use करेगा। यह एक अलग output है — जो token value बदलने पर भी coherent रहता है।

Hierarchy rule इसलिए है क्योंकि Compose एक layout tree है। जब agent nested stack को flat positioned elements की list में flatten करता है, तो original structure से implied responsive behavior नष्ट हो जाता है। IR हर nesting level को preserve करता है — देखें Per-Screen IR — Stack, Overlay, Absolute, Leaf कि यह nesting layout intent को कैसे encode करता है।

Constraint यह नहीं है कि "tokens use करें अगर मन चाहे।" यह है कि "कभी hardcode मत करो अगर token मौजूद है।" यह एक prohibition है, suggestion नहीं। LLMs prohibitions पर suggestions से अलग react करते हैं।

stringRef rule i18n के लिए ज़रूरी है। अगर agent "Speed Test" inline कर देता है बजाय resource key reference करने के, तो आपने एक localization gap बना दिया। Constraint agent को explicitly strings.json की तरफ point करता है।

Agent CONTEXT.md को sequentially कैसे पढ़ता है

LLM context windows tokens को left-to-right process करते हैं। CONTEXT.md की structure इसका फायदा उठाती है। Order है:

1. Target declaration (पूरा generation frame set करता है)
2. Strict constraints (हर decision पर लागू prohibitions)
3. Bundle map (कौन सी files मौजूद हैं और हर एक में क्या है)
4. Token usage rules (spacing, color, radius, typography कैसे resolve करें)
5. Scope notes (honest gaps — यह bundle क्या cover करती है और क्या नहीं)

Bundle map section agent को बताता है कि कौन सी files पढ़नी हैं और किस order में:

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

इस map के बिना, agent को पता नहीं चल सकता कि components/inventory.json मौजूद है, या वह _meta.json को main spec मान सकता है। Explicit enumeration reading order guide करती है।

Scope notes — v0.4 ईमानदारी से क्या cover नहीं करता

Scope notes section वह जगह है जहाँ figmascope अपनी limitations document करता है। यह जानबूझकर और non-negotiable है। एक agent जो नहीं जानता कि spec incomplete है, वह gaps को invention से भर देगा। यह gap जानने से बुरा है।

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

Gradient warning विशेष रूप से महत्वपूर्ण है। Figma complex gradient fills support करता है जिनका Compose में कोई direct equivalent नहीं है बिना custom drawing के। Gradients को silently drop करने या broken code generate करने के बजाय, figmascope _meta.json में background-gradient-not-supported:<name> warning emit करता है।

Typography note _meta.json में tokensSource field से जुड़ा है। जब Figma file में Variables नहीं होते, figmascope frequency से tokens infer करता है। Scope note agent को बताता है कि यह inference imperfect है। देखें tokens.json Explained कि inference fallback कैसे काम करता है।

WRONG / RIGHT उदाहरण

इसे concrete बनाते हैं। एक stack node जिसमें gap: 16 है और token file में spacing.16: 16 है:

CONTEXT.md constraints के बिना (WRONG):

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

CONTEXT.md constraints के साथ (RIGHT):

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

RIGHT output token-referenced है। जब design system spacing.16 को 16dp से 14dp में बदले, code बिना codebase search-and-replace के सही रहता है।

एक और उदाहरण — string handling। एक leaf node जिसमें text: "Speed Test" और stringRef: "speed.test" है:

WRONG:

Text(text = "Speed Test")

RIGHT:

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

Constraint strings.json की तरफ point करता है, key speed.test है, और agent जानता है कि dot-notation को Android resource IDs में कैसे map करें। यह तभी possible है जब agent ने component generate करने से पहले constraint पढ़ी हो।

Agent को खुद prompt क्यों नहीं करते?

आप ये instructions manually अपने prompt में लिख सकते हैं। figmascope इन्हें एक file में externalize करता है क्योंकि:

• Constraints actual bundle से derived हैं। ±2dp rule तभी meaningful है जब tokens.json मौजूद हो। CONTEXT.md जानते हुए generate होता है कि कौन से tokens present हैं।
• Per-project scope notes हर file के लिए बदलती हैं। Full Variables coverage वाली Figma file को अलग typography note मिलती है बनाम inferred tokens वाली file को।
• File zip में है। आप इसे copy-paste किए बिना context में reference कर सकते हैं। Cursor, Claude Code, और similar tools सभी @-file references support करते हैं।
• यह reproducible है। Same Figma file से हर export में same CONTEXT.md generate होता है। आपकी team का agent हर बार same contract पढ़ता है।

Goal यह नहीं है कि agent के defaults के आसपास prompt-engineer करें। Goal यह है कि एक ऐसा spec ship करें जो defaults को irrelevant बना दे।

Alternatives से comparison

Figma का Dev Mode measurements, variables, और code snippets output करता है। यह spec produce नहीं करता। Dev Mode output से काम करने वाले agent को examples से rules infer करनी पड़ती हैं — जिसका मतलब है वह edge cases के लिए गलत rules infer करेगा।

Locofy और similar tools directly code generate करते हैं। उनके पास CONTEXT.md equivalent नहीं है क्योंकि वे expect नहीं करते कि agent spec पढ़े — वे खुद agent बनना चाहते हैं। यह तब काम करता है जब tool का code generation आपके stack से exactly match करे। यह तब काम नहीं करता जब आपके project-specific naming conventions हों, custom component library हो, या design system हो जिसके tokens tool को पता नहीं।

CONTEXT.md एक machine-readable design brief है। यह वह चीज़ है जो pre-LLM design handoff में Confluence page या Notion doc के रूप में मौजूद थी, बस उस audience के लिए structured है जो actually rules follow करती है।

इसके साथ क्या करें

जब आप Cursor या Claude Code में figmascope export खोलें:

1. Design के बारे में किसी भी prompt से पहले @CONTEXT.md अपने context में add करें।
2. जिस screen JSON पर काम कर रहे हैं उसे reference करें: @screens/home.json।
3. अगर tokens touch कर रहे हैं, @tokens.json add करें।
4. अगर strings के साथ काम कर रहे हैं, @strings.json add करें।

CONTEXT.md constraints एक बार load होने पर पूरे session में apply होती हैं। आपको इसे हर prompt में re-add नहीं करना — इसे एक बार शुरू में add करें और हर subsequent generation को frame करने दें।

Bundle के अन्य artifacts इस series के बाकी हिस्सों में cover हैं। Token system Figma Variables के साथ और बिना files को कैसे handle करता है, इसके लिए tokens.json Explained से शुरू करें, या Figma layouts stack/overlay/absolute/leaf nodes में कैसे map होते हैं इसके लिए Per-Screen IR देखें। Try करना चाहते हैं? figmascope.dev पर अपना Figma URL paste करें और अपना पहला bundle export करें।