من Figma إلى Claude Code — سياق تصميم منظم لواجهة سطر أوامر Anthropic

التعليمة "لا تُعيد تطبيق المكونات الموجودة بالفعل" مهمة عندما يكون مخزون المكونات مشتركاً. يمكن لـ Claude Code قراءة design/components/inventory.json لتحديد المكونات المطبّقة بالفعل واستيرادها بدلاً من إعادة توليدها.

ربط tokens التصميم

تستخدم tokens.json المُصدَّرة من figmascope هيكلاً متداخلاً شبيهاً بـ W3C مع حقلي $value و$type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

اطلب من Claude Code توليد كتلة توسيع theme الخاصة بـ tailwind.config.ts من هذا الملف كخطوة أولى، قبل تطبيق أي شاشات. بهذه الطريقة يمكن لجميع تطبيقات الشاشات اللاحقة استخدام أسماء مستعارة لـ tokens في Tailwind باتساق:

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

راجع تصدير tokens التصميم لعملاء AI للتعمق في تنسيق tokens والاستنتاج القائم على التكرار الذي يستخدمه figmascope عند عدم إعداد متغيرات Figma Variables.

معالجة طبقة النصوص

كل عقدة نصية في ملف Figma تحصل على خانة في strings.json. تستخدم المفاتيح النقطة المشتقة من تدرج الإطار:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

وجّه Claude Code لاستخدام هذه المفاتيح كمعرّفات i18n. بدلاً من ترميز النص "Everything you need" مباشرة في JSX، يستدعي المكوّن المولّد t('home.hero.title') (أو ما يعادله في مكتبة i18n الخاصة بك). ملف المورد موجود بالفعل في strings.json — تحتاج فقط إلى استيراده أو ربطه بإعداد i18n الخاص بك.

إذا اكتشف figmascope تصادماً — عقدتان تُنتجان نفس المفتاح — يُصدر تحذير strings-collision في _meta.json ويضيف لاحقة رقمية للتمييز. تحقق من _meta.json قبل بدء جلسة حتى تعرف ما تتوقعه.

التكامل مع CLAUDE.md

إذا كنت تستخدم ملف سياق CLAUDE.md للمشروع، أضف قسماً قصيراً يوجّه الوكيل إلى مجلد التصميم. هذا يتماشى جيداً مع النهج الموصوف في تسليم تصميم AI ويكمّل سبب اختلاف figmascope عن إضافات فحص Figma.

أضف قسم تصميم مثل هذا:

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

هذا يعني أن كل جلسة Claude Code في المشروع ستمتلك تلقائياً سياق التصميم كجزء من معرفتها العاملة، دون الحاجة إلى تكراره في كل طلب.

ما يجيده الوكيل فعلاً

مع السياق المنظم، يحصل Claude Code بشكل موثوق على:

• قيم المسافات — لأنها في tokens.json كـ spacing.4 → 16px، وليس مقدّرة من لقطة شاشة
• الألوان — قيم hex دقيقة، وليس "يبدو كأنه برتقالي دافئ"
• الطباعة — عائلة الخط والحجم والوزن وارتفاع السطر، كلها مكتوبة
• اتجاه التخطيط — عقد stack لها حقلا direction وgap صريحان
• تسمية المكونات — inventory.json هو المصدر الرسمي، لذا لا توجد أسماء مخترعة
• النصوص — يمنع strings.json الوكيل من إعادة الصياغة أو اختراع نصوص مؤقتة

ما يحتاج مراجعة بشرية: حالات التفاعل (تمرير الماوس، التركيز، النشاط) غير المرئية في إطارات Figma الثابتة، توقيت الحركات، ونقاط الفصل المتجاوبة التي لم تُصمّم صراحة في الملف. يلتقط التمثيل الوسيط التخطيط الثابت؛ السلوك الديناميكي خارج النطاق.

استخدام --dangerously-skip-permissions في البيئات المتحكم بها

لأنابيب آلية حيث تريد تشغيل Claude Code دون مطالبات موافقة تفاعلية — مثلاً في خطوة CI تولّد كعب مكونات بعد تحديث التصميم — يمكنك استخدام --dangerously-skip-permissions. مناسب فقط في بيئات معزولة بلا بيانات اعتماد للإنتاج.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

في سير عمل المطور الإنتاجي، اترك الصلاحيات تفاعلية. المطالبات موجودة لسبب وجيه — يمكن لـ Claude Code كتابة الملفات وسيفعل ذلك، وتريد معرفة أيها قبل أن يفعل.

التحقق من تحذيرات التصدير قبل الطلب

يُصدر figmascope تحذيرات إلى _meta.json للظروف التي قد تؤثر على جودة المخرجات. تحقق منها قبل بدء جلسة Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

تحذيران يستحقان الانتباه:

• layout-mode-none-inferred — إطار لم يكن له تخطيط تلقائي محدد. استنتج figmascope التخطيط من المواضع المطلقة للأبناء، وهو أقل موثوقية. علّم الشاشة ذات الصلة في طلبك: "تستخدم هذه الشاشة تموضعاً مطلقاً؛ ولّد الكود وفقاً لذلك."
• strings-collision — عقدتا نص أنتجتا نفس مفتاح المورد. يميّز figmascope بلاحقة رقمية، لكن يجب عليك التحقق من أن النصوص في strings.json صحيحة قبل أن يولّد الوكيل استدعاءات i18n.

سير عمل Android وiOS

Claude Code ليس مقيداً بأُطر الويب. حزمة السياق محايدة للإطار — التمثيل الوسيط للتخطيط والـ tokens هي بيانات وليست CSS. لـ Jetpack Compose:

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

عقد stack في التمثيل الوسيط تتناسب طبيعياً مع Column (الاتجاه: رأسي) وRow (الاتجاه: أفقي) في Compose. عقد leaf ذات type: "text" تصبح composables من نوع Text؛ وtype: "image" تصبح Image أو عنصراً نائباً. راجع Jetpack Compose من Figma للنمط الكامل.

إدارة إصدارات حزمة التصميم

عامل مجلد design/ مثل أي تبعية أخرى في المشروع. عندما يتغير التصميم بشكل ملحوظ، أعد التصدير من figmascope.dev، أودعه، وسجّل التغيير في طلب السحب:

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

الحزمة القديمة تعني أن الوكيل يعمل من تصميم متقادم. فحص الطابع الزمني يكتشف هذا قبل أن تقضي وقتاً في جلسة توليد كود مبنية على مواصفات منسوخة.