منتجات docs

المسار: dist/docs/

هذا هو الهدف الخامس لـ codegen (docsTarget)، وهو الهدف الوحيد الذي لا يستخدم قوالب handlebars — بل يبني السلاسل مباشرةً بالكود.

المنتجات الثلاثة

tokens.md — جدول المرجع السريع للرموز

تقسيم أقسام ## وفق مساحة الأسماء العلوية (button / cell / checkbox / color / dialog / icon / input / loading / motion / navbar / picker / radio / radius / shadow / spacing / switch / tag / text / textarea / toast / typography / zIndex)، لكل قسم جدول من خمسة أعمدة:

## button

| الرمز | النوع | الوضع الفاتح | الوضع الداكن | الوصف |
| --- | --- | --- | --- | --- |
| `button.borderRadius` | dimension | 2px | — | زاوية انحناء الزر تتبع زاوية الانحناء العامة |
| `button.height.medium` | dimension | 40px | — | إضافة أصلية؛ ارتفاع الزر المتوسط (الافتراضي) |
| `color.primary.default` | color | #2B4C7C ← #2b4c7c | #3D649E ← #3d649e | اللون الأساسي (نيلي — أزرق 青花瓷 (الخزف الأزرق)) |

الخصائص:

• عمود الرمز هو مسار النقاط الكامل
• يعمل عمود اللون على عرض نسختين «القيمة الأصلية ← الصيغة الموحَّدة بأحرف صغيرة»
• تُوسم عناصر nativeOnly في عمود الوصف بـ «إضافة أصلية»
• يُملأ عمود الوضع الداكن بـ — عند عدم وجود تغطية (الوضع الداكن الحالي لا يغطي color.* سوى)

tokens.light.json — لقطة مسطَّحة للوضع الفاتح

{
  "button.borderRadius": "2px",
  "button.fontWeight": 400,
  "button.height.medium": "40px",
  "color.primary.default": "#2B4C7C"
}

مراسلة مسطحة { path ← القيمة بعد الخَبز }، للاستهلاك الآلي.

tokens.dark.json — جدول تغطية الوضع الداكن

{
  "color.focus": "#7FA6D9",
  "color.selected": "#B1C1D8",
  …
}

لا يحتوي سوى المفاتيح المغطاة (جميعها color.*، ويتغير العدد الدقيق بين الإصدارات)، مرتبة حسب path.

المستهلكون

المستهلك	ماذا يستخدم
موقع التوثيق هذا	لا يستهلك dist/docs/ مباشرةً — فصفحة مرجع الرموز تُعرض في الوقت الحقيقي عبر خط الأنابيب loadTokenFiles + resolveTokens نفسه الذي تشغله صفحات .astro، وهي متزامنة مع المصدر
موقع توثيق العائلة	تضمين tokens.md كمرجع سريع للرموز
المحاذاة بين الأطراف	استخدام tokens.light.json / tokens.dark.json للمقارنة في وقت البناء
تصفية وثيقة خط الأساس	تُستخدم وسوم nativeOnly لاستخراج قائمة «الرموز الأصلية المُضافة»

حارس الرأس

بداية tokens.md:

<!-- هذا الملف مُولَّد تلقائيًا بواسطة @lh-ui/core، يُمنع التعديل يدويًا. المصدر: @lh-ui/core tokens -->

وهو مماثل في الغرض للافتة «يُمنع التعديل يدويًا» في منتجات كل طرف (الخط الأحمر 6).

الفرق عن الصفحات المرجعية لموقع التوثيق

	dist/docs/tokens.md	الصفحة المرجعية للرموز في موقع التوثيق
وقت التوليد	pnpm codegen	pnpm docs:build / docs:dev
مصدر البيانات	tokenSet في ذاكرة codegen	تعيد صفحات .astro تشغيل loadTokenFiles + resolveTokens من frontmatter
الشكل	جداول markdown ثابتة	جداول Astro تفاعلية (تصفية، معاينة عينات الألوان)
الموقع	dist/ (مُتجاهَل في gitignore، لا يدخل المستودع)	صفحة في الموقع (منتجات البناء في docs/dist/)

يمرّ الاثنان بخط الأنابيب نفسه للتحليل، لذا القيم متطابقة دائمًا؛ ولا يختلفان إلا في شكل العرض ومدخل البناء.