يستطيع Composer في Cursor كتابة الكثير من كود واجهة المستخدم. ما لا يستطيع فعله هو قراءة ملف Figma الخاص بك. الصق لقطة شاشة وسيخمّن — تباعد خاطئ، قيم ألوان مخترعة، أسماء مكوّنات مصطنعة لا تطابق شيئاً في قاعدة كودك. المشكلة ليست النموذج. إنها السياق المنظّم المفقود.

figmascope يُصلح ذلك. يُصدِّر ملف Figma كحزمة zip: رموز تصميم، أشجار تخطيط لكل شاشة، عروض مرجعية بمقياس 2×، جرد المكوّنات، وسلاسل واجهة المستخدم — كل ما يحتاجه وكيل Cursor لتوليد كود دقيق لا كود يبدو معقولاً.

يغطّي هذا الدليل خط الأنابيب الكامل: رابط Figma ← حزمة السياق ← محث Cursor ← إخراج مراجَع.

ما تحتوي الحزمة

حين يُصدِّر figmascope ملفك، يحتوي الـ zip:

الحزمة تبقى على جهازك. لا تُرفع أبداً إلى أي مكان.

الخطوة 1: توليد الحزمة

توجَّه إلى figmascope والصق رابط ملف Figma في حقل الإدخال. يعمل المُصدِّر في متصفحك مقابل Figma REST API — ستحتاج رمز وصول شخصي في المرة الأولى (مُخزَّن في الذاكرة، لا يُرسَل أبداً إلى خوادم figmascope).

اضغط على تصدير سياق الوكيل. تعالج الصفحة كل إطار وتحل الرموز وتبني IR ثم تُنزِّل context-bundle.zip إلى جهازك.

إذا كان ملفك يحتوي إطارات كثيرة، تُدرَج فقط الإطارات عالية المستوى التي ليست مكوّنات أو صور مصغّرة. يُظهر _meta.json بالضبط أي الإطارات جُرِّدت وأي التحذيرات (تعبئات التدرج، التأثيرات غير المدعومة).

الخطوة 2: فكّ الضغط في مشروعك

ضع الحزمة حيث يمكن لـ Cursor رؤيتها — مجلد design/ في جذر مستودعك هو النمط الأنظف.

# from your project root
unzip ~/Downloads/context-bundle.zip -d ./design/

# verify the structure
ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

أضف design/ إلى .gitignore إن لم تردّ تثبيت الحزمة. أو ثبِّتها — إنها حتمية؛ نفس ملف Figma في نفس الحالة يُنتج دائماً نفس الحزمة، لذا الـ diffs ذات معنى.

الخطوة 3: أضف مقتطف .cursorrules

يقرأ Cursor ملف .cursorrules في جذر المستودع ويُلحقه بكل سياق دردشة. هنا تربط الوكيل بالحزمة.

# .cursorrules

When building UI screens:
1. Read ./design/CONTEXT.md first. It specifies the target framework and constraints.
2. Use tokens from ./design/tokens.json for all spacing, color, radius, and typography values.
3. Reference ./design/screens/<name>.json for layout structure and node hierarchy.
4. Match ./design/screens/<name>.png for visual confirmation — use it as a sanity check, not the source of truth.
5. Use string keys from ./design/strings.json rather than hardcoding UI copy.
6. Do not invent token values. If a value isn't in tokens.json, flag it.

هذه الكتلة الواحدة تمنع أكثر ثلاثة مصادر انحراف شيوعاً: الألوان المخترعة، والسلاسل المُرمَّزة، وتخمين التخطيط من لقطة الشاشة.

الخطوة 4: افتح Cursor Composer ونفِّذ شاشة

افتح Composer (Cmd+I على macOS). ثبِّت الملفات قبل المحث: انقر على أيقونة المشبك وأضف design/CONTEXT.md وdesign/tokens.json وdesign/screens/home.json. ثم اكتب المحث:

Implement the home screen from ./design/screens/home.json.

Constraints:
- Target framework and component conventions are in ./design/CONTEXT.md
- All spacing, color, and radius values must come from ./design/tokens.json
- UI strings must use keys from ./design/strings.json
- The root node is a stack (vertical). Children are declared in order in the JSON.
- Do not invent any values not present in the token or IR files.

سيقرأ Cursor الملفات المُثبَّتة ويُعيِّن عقد IR إلى العناصر الأوّلية في إطار عملك ويُولِّد التنفيذ. الإخراج مُشار إلى الرموز — إذا فحصت الكود المُولَّد، يجب أن تتتبع كل قيمة تباعد إلى مفتاح في tokens.json.

الخطوة 5: المراجعة والتكرار

افتح design/screens/home.png جانباً مع الإخراج المُصيَّر. الـ PNG هو تصدير بمقياس 2× من Figma — يُظهر بالضبط كيف يجب أن يبدو التصميم. الاختلافات ذات معنى: تُشير إما إلى فجوات في تعيين IR أو قيم رموز لم تُطبَّق.

مشكلات شائعة ومحثات متابعة:

انحراف الرموز — استخدم الوكيل hex مُرمَّزة بدلاً من رمز:

Compare every color value in the generated component against ./design/tokens.json.
List any colors that don't match a token key. Replace them with the correct token reference.

مكوّن مفقود — يُشير IR إلى معرّف مكوّن لم يحلّه الوكيل:

The IR references componentId "btn-primary-01". Check ./design/components/inventory.json
for its name and type, then implement a placeholder with that name and the correct token values.

التخطيط خاطئ — التباعد أو المحاذاة لا يطابق الـ PNG:

The vertical gap between the header and the card list should be spacing.24 from tokens.json (24dp).
Your output uses 16px. Fix it.

ما يعمل وما لا يعمل

يعمل جيداً: الشاشات المسطّحة بتخطيطات stack، التباعد واللون المدفوع بالرموز، النص مع مراجع السلاسل، أنماط البطاقات والقوائم البسيطة. يتعامل Cursor مع هذه جيداً بمجرد وجود IR في السياق — يتوقف عن التخمين ويبدأ التعيين.

يعمل أقل جيداً: طبقات التراكب المُوضَعة بشكل مطلق المعقدة (قد يقرأ Cursor إحداثيات الإزاحة بشكل خاطئ أحياناً)، تعبئات التدرج (مُشار إليها كتحذيرات في _meta.json — سيقرّب Cursor)، وأيقونات المتجهات (يخزّن IR معرّف مرجعي فقط، لا بيانات المسار).

لقطة الشاشة فقط مقابل الحزمة: المضيّ بلقطة الشاشة فقط أسرع للبدء لكنه غير حتمي. كل جلسة تبدأ من جديد. قد ينجح النموذج في التباعد مرة ويُخطئ في الدور التالي. الحزمة قابلة للإسناد عبر الجلسة بالكامل — يمكن لـ Cursor التحقق من إخراجه مقابل ملف الرموز في أي وقت دون إعادة رفع أي شيء.

نصيحة: تحقق من تحذيرات _meta.json قبل المحث

قبل محث التنفيذ الأول، اقرأ design/_meta.json. تسرد مصفوفة warnings أي شيء لم يستطع المُصدِّر حلّه بالكامل: تعبئات التدرج، تعيينات الرموز المفقودة، الإطارات بالصور المضمّنة. أضف ملاحظة عن هذه إلى محثك حتى لا يحاول الوكيل تنفيذها ثم يتراجع بصمت إلى قيم مُرمَّزة.

cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'

إذا أظهر الإخراج "gradientFill: not fully supported" على عقدة محددة، أخبر Cursor بتخطّي خلفية تلك العقدة وترك تعليق // TODO: gradient بدلاً من ذلك.

الخلاصة

سير العمل هو: صدِّر مرة، أسنِد في كل مكان. الحزمة مواصفة ثابتة وقابلة للقراءة آلياً يمكن لـ Cursor الرجوع إليها عبر أدوار متعددة دون إعادة معالجة التصميم. تحصل على كود دقيق في الرموز ومُشار إلى السلاسل وصحيح التخطيط بدلاً من تقريب لقطة شاشة — وحين ينحرف شيء، يمكنك توجيه الوكيل مجدداً إلى مصدر الحقيقة في سطر واحد.

جرِّب هذا بنفسك على figmascope.dev — الصق رابط Figma، اضغط على تصدير سياق الوكيل، وفكّ ضغط الحزمة في مساحة عمل Cursor في أقل من دقيقتين.