components/inventory.json — AI Agents के लिए Component Identity

Design file और component library के बीच का फ़र्क identity है। Design file में shapes होती हैं। Component library में named, reusable parts होते हैं जिनके stable identifiers होते हैं। components/inventory.json इस सवाल का figmascope का जवाब है: "इस design में कौन से parts components meant हैं, और instances उनसे कैसे connect होते हैं?"

Schema

components/inventory.json objects का एक array है:

[
  {
    "id": "789:012",
    "name": "PrimaryButton",
    "type": "COMPONENT"
  },
  {
    "id": "789:013",
    "name": "SecondaryButton",
    "type": "COMPONENT"
  },
  {
    "id": "890:100",
    "name": "Button",
    "type": "COMPONENT_SET"
  },
  {
    "id": "890:101",
    "name": "Button/Primary/Default",
    "type": "COMPONENT"
  },
  {
    "id": "890:102",
    "name": "Button/Primary/Pressed",
    "type": "COMPONENT"
  }
]

हर entry में तीन fields होते हैं:

• id: Figma node ID, same file के लिए sessions में stable।
• name: Figma से component name। COMPONENT_SET में variants के लिए, Figma slash-notation use करता है: Button/Primary/Default।
• type: या तो "COMPONENT" (single component definition) या "COMPONENT_SET" (variants का group)।

यह पूरा schema है। यह जानबूझकर minimal है।

Instances कैसे link back करते हैं

Instances से inventory तक का link per-screen IR में है। कोई भी node जो किसी component का INSTANCE है वह componentId और componentName carry करता है:

// screens/home.json
{
  "kind": "stack",
  "id": "555:201",
  "componentId": "789:012",
  "componentName": "PrimaryButton",
  "axis": "horizontal",
  ...
}

componentId inventory.json में किसी id से match करता है। componentName name से match करता है। दोनों fields present हैं ताकि agent को name पाने के लिए inventory.json load न करना पड़े — लेकिन अगर उसे जानना हो कि यह component किसी COMPONENT_SET का हिस्सा है, तो वह inventory cross-reference करता है।

इस तरह एक coding agent जानता है कि screen पर button node एक bespoke layout नहीं है जिसे उसे detail में reproduce करना है — यह PrimaryButton का एक instance है, और उसे IR की structural details से नया generate करने की बजाय existing PrimaryButton() composable call करनी चाहिए।

Component identity के बिना, agent हर screen पर scratch से same button generate करता है। इसके साथ, agent existing composable call करता है और structural codegen पूरी तरह skip करता है। फ़र्क यह है कि आपको 40 Row { Text(...) Surface { ... } } blocks मिलते हैं या 40 PrimaryButton(...) calls।

Refactor safety के लिए यह क्यों मायने रखता है

Design systems refactor होते हैं। Button को नई shape, नई padding, अलग color मिलती है। अगर आपका generated code structurally literal था, तो refactor का मतलब है हर screen को touch करना जिसमें button है। अगर generated code PrimaryButton composable reference use करता था, तो refactor एक file है।

Inventory इसे generation time पर contract establish करके possible बनाता है: "यह node custom layout नहीं है, यह एक known component का instance है।" Agent जो इस contract का सम्मान करता है वह ऐसा code generate करता है जो component-level refactoring के लिए already structured है।

COMPONENT vs. COMPONENT_SET

Figma के component system में दो levels हैं। COMPONENT एक single definition है। COMPONENT_SET variants के लिए container है — जिसे Figma "variants" कहता है (जैसे Primary/Secondary/Destructive और Default/Hovered/Pressed states वाला button)।

Practice में, screen में एक instance हमेशा COMPONENT (एक specific variant) reference करेगा, COMPONENT_SET नहीं। COMPONENT_SET इसलिए है ताकि agent को पूरी variant surface पता हो जब उसे component का state machine implement करना हो।

// Button set के लिए Inventory entries
{ "id": "890:100", "name": "Button", "type": "COMPONENT_SET" }
{ "id": "890:101", "name": "Button/Primary/Default", "type": "COMPONENT" }
{ "id": "890:102", "name": "Button/Primary/Pressed", "type": "COMPONENT" }
{ "id": "890:103", "name": "Button/Secondary/Default", "type": "COMPONENT" }

// Screen IR में instance एक specific variant reference करता है
{ "componentId": "890:101", "componentName": "Button/Primary/Default" }

300-entry cap

figmascope inventory.json को 300 entries पर cap करता है। Scale पर Figma files — खासकर exhaustive component libraries वाले design systems — में हज़ारों components हो सकते हैं। उन सभी को उस context bundle में include करना जो LLM को भेजना है, उन definitions से context window pad कर देगा जो agent implemented screens के लिए use नहीं करेगा।

जब cap hit होती है, inventory में एक _truncated field appear होता है:

[
  { "id": "...", "name": "...", "type": "COMPONENT" },
  ...
  { "_truncated": true, "totalCount": 847, "included": 300 }
]

Inventory में क्या नहीं है

Inventory identity list है, implementation spec नहीं। यह बताता है कि ID 789:012 के साथ PrimaryButton नाम का component exist करता है। यह नहीं बताता:

• Component कौन से props accept करता है
• इसके कौन से states हैं
• Component internally कैसे structured है (वह IR nodes में है जो INSTANCEs हैं)
• Component का source Figma file क्या है (अगर यह linked library से है)

सही workflow: agent एक componentId: "789:012" देखता है, inventory में इसे PrimaryButton के रूप में look up करता है, फिर actual function signature समझने के लिए आपके Kotlin codebase में PrimaryButton search करता है। Inventory design और code के बीच bridge है, code का replacement नहीं। आप figmascope.dev पर किसी भी Figma file से inventory export कर सकते हैं।

IR में Component identity वह है जो "इस design से code generate करो" को "existing codebase में fit होने वाला code generate करो" से अलग करती है। पहला toy है। दूसरा असली काम है।

Screenshot-only handoff से comparison

Same screen के PNG से काम करने वाले agent के पास कोई component identity नहीं होती। वह एक blue rounded rectangle with centered text देखता है और generate करता है:

Box(
    modifier = Modifier
        .background(Color(0xFF7F5CFE), RoundedCornerShape(24.dp))
        .padding(horizontal = 32.dp, vertical = 16.dp)
) {
    Text("Start", color = Color.White, fontWeight = FontWeight.SemiBold)
}

IR with inventory से काम करने वाला agent componentId: "789:012" देखता है, PrimaryButton look up करता है, codebase में existing composable find करता है, और generate करता है:

PrimaryButton(
    label = stringResource(R.string.start),
    onClick = { /* TODO */ }
)

दूसरा output आपके design system के साथ integrate होता है। पहला divergence create करता है। Inventory वह है जो दूसरे output को possible बनाती है। Screenshots के handoff artifacts के रूप में क्यों fail होते हैं, इसके लिए Screenshots क्यों Fail होते हैं देखें।

Per-screen IR जिसमें componentId references हैं उसे Per-Screen IR — Stack, Overlay, Absolute, Leaf में detail में cover किया गया है। दोनों artifacts वाले full context bundle structure का परिचय CONTEXT.md की संरचना के ज़रिए है। अपना component inventory पाने के लिए, figmascope को अपनी Figma file पर run करें।