البدء السريع

متطلبات البيئة

• Node.js >= 22.12 (موقع التوثيق يستخدم Astro 7، وهو شرط إلزامي)
• pnpm 10.x (المستودع مُقفل على pnpm@10.34.5)

التثبيت

pnpm install

لا يوجد أي تبعية في وقت التشغيل في هذا المستودع (قيمة dependencies فارغة)، وكل ما يُثبَّت هو سلسلة أدوات وقت البناء (tsx، ajv، handlebars، vitest، astro وغيرها).

تشغيل codegen مرة واحدة

pnpm codegen

ينفّذ هذا الأمر tsx codegen/src/index.ts، والعملية الكاملة هي:

1. قراءة رقم الإصدار من package.json
2. تحميل tokens/*.json والتحقق منها (تحقق هيكلي عبر Ajv)
3. تحليل المراجع (ref)، ودمج الوضع الداكن (تحقق دلالي: مطابقة الأنواع، سلامة المراجع، الكشف عن الحلقات)
4. تحميل specs/*.json وcases/*.json والتحقق منهما
5. حذف مجلد dist/ بالكامل وإعادة بنائه
6. تنفيذ 5 أهداف بالترتيب (android ← ios ← harmony ← c ← docs)

تكون المخرجات في dist/:

  [android] android/top/lhgb/ui/tokens/LhTokens.kt
  [android] android/top/lhgb/ui/tokens/LhDarkTokens.kt
  ...
اكتمل codegen: 5 أهداف، N ملفًا، الإصدار v0.0.1

يتغير عدد الملفات باختلاف محتوى الرموز (عند وجود رموز ظلال يظهر ملف حامل ظل إضافي لكل من ios / harmony)، لذا يُرجَّح الرجوع إلى المخرجات الفعلية.

التحقق

pnpm verify          # = pnpm verify:tokens && pnpm verify:specs

• verify:tokens: التحقق من schema الرموز + سلامة المراجع + تباين النص الأساسي مع لون الخلفية للعناصر الحرجة ≥4.5:1 (WCAG AA) + فحص الصياغة الخاصة بالمنصات (var() / rem / sp / dp)، والإبلاغ عن المسارات الداكنة اليتيمة (مفاتيح مُعلَنة في ملف الوضع الداكن لكنها غير موجودة في مجموعة الأوضاع الفاتحة) والمفاتيح الداكنة التي تفتقر إلى النوع.
• verify:specs: التحقق من اتساق المواصفات (specs) مع الحالات (cases) (مثل: هل الـ prop / الحدث الذي تشير إليه الحالة موجودًا في المواصفات أم لا).

الاختبار

pnpm test

تعكس اختبارات اللقطات (snapshot) جميع منتجات dist/. بعد تعديل الرموز أو القوالب ستفشل اللقطات، وبعد التأكد من صحة التغييرات تُحدَّث عبر pnpm test -- -u.

موقع التوثيق

pnpm docs:dev        # معاينة محلية http://localhost:5185/lhui/core/
pnpm docs:build      # بناء للإنتاج (base هو /lhui/core/)
pnpm docs:preview    # معاينة بناء الإنتاج

تقرأ الصفحات المرجعية الثلاث في موقع التوثيق (الرموز / العقود / الحالات) المصادر الأصلية tokens/ وspecs/ وcases/ مباشرةً في وقت البناء، ولا تحتاج إلى تشغيل codegen مسبقًا.

تركيبات شائعة

السيناريو	الأمر
عُدِّلت الرموز، وتُريد المنتجات	pnpm codegen
عُدِّلت الرموز، وتُريد المنتجات + التحقق	pnpm build (= codegen + verify)
عُدِّلت القوالب، وتُريد المنتجات + اللقطات	pnpm codegen && pnpm test -- -u
الاطلاع فقط على جدول المرجع السريع للرموز	بعد pnpm codegen، راجع dist/docs/tokens.md

أين تُستهلك المنتجات

يستهلك كل طرف أصلي المنتجات الخاصة بمنصته تحت dist/:

• Android: ملفات Kotlin تحت dist/android/
• iOS: ملفات Swift تحت dist/ios/
• HarmonyOS: ملفات ArkTS تحت dist/harmony/
• Windows: ملفات C# تحت dist/windows/

آلية الربط المحلي (تعديل الرموز مع مفعول فوري دون إصدار نسخة) موضحة في الربط المحلي.