كل تصدير من figmascope يبدأ بملف .zip يحتوي سبعة مصنوعات. CONTEXT.md هو الملف الذي يُقرأ أولاً — بتصميم مقصود. إنه ليس README ولا وثائق مُولَّدة. بل هو عقد من طراز المحوِّل بين التصميم والوكيل الذي سيحوّله إلى كود.

يستعرض هذا المقال ما يحتويه، ولماذا بُنيَ بهذه الطريقة، وماذا يحدث حين تتخطّاه.

الفرق بين العقد والوثائق

الوثائق تصف ما هو موجود. العقد يحدد ما يجب أن يكون صحيحاً. يهمّ هذا الفرق حين يكون قارئك LLM يمكنه باطمئنان اختراع قيم تباعد، وتسوية تسلسلات التخطيط، أو ترميز ألوان hex ما إن لا يجد خياراً أفضل.

يفتح CONTEXT.md بإعلان الهدف:

# 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" ليست زينة. يستخدمها الوكيل لاختيار العناصر الأوّلية للمكوّنات، ومعالجة وحدات dp مقابل sp، ومعرفة أن Modifier.padding() هو التجريد الصحيح للتباعد، وفهم أن Box مع Alignment هو طريقة التعامل مع تخطيطات overlay. الهدف React/Tailwind يُولِّد CONTEXT.md مختلفاً بعناصر أوّلية مختلفة في القيود.

التعليمات "اقرأ هذا أولاً" مقصودة أيضاً. تعالج نوافذ سياق LLM الرموز من اليسار لليمين. يستغل هيكل CONTEXT.md هذا الأمر. إذا ظهرت قاعدة رمز بعد أن بدأ الوكيل فعلاً في التفكير بمكوّن، يصل القيد متأخراً. تحميل العقد مسبقاً يعني أن القواعد نشطة من أول رمز في التوليد.

قسم القيود الصارمة

الجزء الأكثر أهمية في CONTEXT.md هو كتلة القيود:

## 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

كل قيد موجود لأننا رأينا وكلاء يخرقونه. قاعدة ±2dp هي الأوضح. بدونها، وكيل يواجه gap: 14 على عقدة stack سيكتب Arrangement.spacedBy(14.dp). بالقاعدة، يعرف التحقق مما إذا كان spacing.16 أو spacing.12 في حدود 2dp واستخدام الرمز بدلاً من ذلك. هذا إخراج مختلف — إخراج يبقى متماسكاً حين تتغير قيمة الرمز، ومتسق لا يتفكك.

قاعدة التسلسل موجودة لأن Compose هو شجرة تخطيط. حين يُسطِّح وكيل stack متداخلة إلى قائمة مسطحة من العناصر الموضعية، يُدمّر السلوك المتجاوب الضمني في البنية الأصلية. يحتفظ IR بكل مستوى من مستويات التداخل لسبب — انظر Per-Screen IR — Stack, Overlay, Absolute, Leaf لكيفية ترميز هذا التداخل للنية التصميمية.

القيد ليس "استخدم الرموز إن أحببت." بل هو "لا تُرمِّز إن وُجد رمز." هذا نهي لا اقتراح. تستجيب النماذج اللغوية الكبيرة بشكل مختلف للنواهي مقارنةً بالاقتراحات.

تهمّ قاعدة stringRef للتعريب. إذا أدرج وكيل "Speed Test" مُضمَّنةً بدلاً من مرجع مفتاح المورد، فقد خلقت ثغرة في التعريب. يشير القيد صراحةً إلى strings.json.

كيف يقرأ الوكيل CONTEXT.md بشكل تسلسلي

نوافذ سياق LLM تعالج الرموز من اليسار لليمين. هيكل CONTEXT.md يستغل هذا. الترتيب هو:

  1. إعلان الهدف (يحدد إطار التوليد بأكمله)
  2. القيود الصارمة (النواهي التي تنطبق على كل قرار)
  3. خريطة الحزمة (الملفات الموجودة وما يحتويه كل منها)
  4. قواعد استخدام الرموز (كيفية حل التباعد واللون ونصف القطر والطباعة)
  5. ملاحظات النطاق (الفجوات الصادقة — ما تغطيه الحزمة وما لا تغطيه)

يُخبر قسم خريطة الحزمة الوكيل بالملفات التي يجب قراءتها وبأي ترتيب:

## 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

بدون هذه الخريطة، قد لا يعرف وكيل أن components/inventory.json موجود، أو قد يعامل _meta.json كالمواصفة الرئيسية. يُرشد التعداد الصريح ترتيب القراءة.

ملاحظات النطاق — ما لا يغطيه الإصدار v0.4 بصدق

قسم ملاحظات النطاق هو المكان الذي توثّق فيه figmascope قيودها الخاصة. هذا مقصود وغير قابل للتفاوض. وكيل لا يعرف أن المواصفة غير مكتملة سيملأ الفجوات بثقة بالاختراع. هذا أسوأ من معرفة الفجوة.

## 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.

تحذير التدرج مهم بشكل خاص. يدعم Figma تعبئات تدرجية معقدة لا مكافئ مباشر لها في Compose بدون رسم مخصص. بدلاً من إسقاط التدرجات بصمت أو توليد كود مكسور، تُصدر figmascope تحذير background-gradient-not-supported:<name> في _meta.json وتُشير إليه هنا حتى يعرف الوكيل معالجة العقد المتأثرة كفجوة معروفة لا كخطأ في إخراجه.

ملاحظة الطباعة تتصل بحقل tokensSource في _meta.json. حين لا يحتوي ملف Figma على Variables، تستنتج figmascope الرموز من التكرار — القيم الشائعة تصبح رموزاً والنادرة لا. تُخبر ملاحظة النطاق الوكيل أن هذا الاستنتاج غير مثالي ولا يفترض تغطية طباعة كاملة. انظر شرح tokens.json لكيفية عمل الاستنتاج الاحتياطي.

أمثلة WRONG / RIGHT

لنجعل هذا ملموساً. بعقدة stack مع gap: 16 وملف رموز يحتوي spacing.16: 16:

بدون قيود CONTEXT.md (WRONG):

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

مع قيود CONTEXT.md (RIGHT):

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

الإخراج الصحيح يُشير إلى الرموز. حين يغيّر نظام التصميم spacing.16 من 16dp إلى 14dp، يبقى الكود صحيحاً دون بحث واستبدال في قاعدة الكود بالكامل.

مثال آخر — معالجة السلاسل. بعقدة leaf مع text: "Speed Test" وstringRef: "speed.test":

WRONG:

Text(text = "Speed Test")

RIGHT:

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

يُشير القيد إلى strings.json، المفتاح هو speed.test، ويعرف الوكيل كيفية تحويل ترميز النقطة إلى معرفات موارد Android. هذا ممكن فقط إذا قرأ الوكيل القيد قبل توليد المكوّن.

لماذا لا تكتب المحثات بنفسك؟

يمكنك كتابة هذه التعليمات يدوياً في محثك. تُخرجها figmascope إلى ملف لأن:

الهدف ليس هندسة المحثات حول الإعدادات الافتراضية للوكيل. بل هو شحن مواصفة تجعل الإعدادات الافتراضية غير ذات صلة.

مقارنة الهيكل بالبدائل

يُخرج Dev Mode في Figma قياسات ومتغيرات ومقتطفات كود. لا يُنتج مواصفة. الوكيل الذي يستخدم إخراج Dev Mode يجب استنتاج القواعد من الأمثلة — مما يعني استنتاج قواعد خاطئة للحالات الحدية.

أدوات مثل Locofy تُولِّد الكود مباشرةً. لا يوجد مكافئ CONTEXT.md لأنها لا تتوقع أن يقرأ وكيل مواصفة — بل تتوقع أن تكون هي الوكيل. يعمل هذا حين يطابق توليد كود الأداة كدّتك بالضبط. لا يعمل حين لديك اتفاقيات تسمية خاصة بالمشروع، أو مكتبة مكوّنات مخصصة، أو نظام تصميم برموز الأداة لا تعرفها.

CONTEXT.md هو موجز تصميم قابل للقراءة آلياً. إنه الشيء الذي وُجد كصفحة Confluence أو وثيقة Notion في كل تسليم تصميم قبل عصر LLM، مُهيكَل فقط لجمهور يتّبع القواعد فعلاً.

ماذا تفعل به

حين تفتح تصدير figmascope في Cursor أو Claude Code:

  1. أضف @CONTEXT.md إلى سياقك قبل أي محث عن التصميم.
  2. أشر إلى JSON الشاشة التي تعمل عليها: @screens/home.json.
  3. إذا كنت تتعامل مع الرموز، أضف @tokens.json.
  4. إذا كنت تعمل مع السلاسل، أضف @strings.json.

تنطبق قيود CONTEXT.md عبر الجلسة بالكامل بمجرد تحميلها. لا تُعيد إضافتها لكل محث — تُضيفها مرة واحدة في البداية وتدع إطارها يشمل كل توليد لاحق.

المصنوعات الأخرى في الحزمة مغطاة في بقية هذه السلسلة. ابدأ بـ شرح tokens.json لكيفية تعامل نظام الرموز مع الملفات مع أو بدون Figma Variables، أو Per-Screen IR لكيفية تحويل تخطيطات Figma إلى عقد stack/overlay/absolute/leaf. مستعد للتجربة؟ الصق رابط Figma على figmascope.dev وصدِّر حزمتك الأولى.