آلية المراجع

ما هو ref

يجوز للرمز الطرفي ألا يكتب value بل يكتب ref، مشيرًا إلى المسار الكامل لرمز آخر:

"selected": { "ref": "color.primary.active", "description": "لون النص في الحالة المحددة، ويتبع نمط الضغط للون الأساسي" }

في وقت البناء يُحلَّل ref ساكنيًا ويُخبَز إلى قيمة حرفية — ما تراه في منتجات كل طرف هو القيمة محلَّلة فعلًا، بلا أي وساطة في وقت التشغيل.

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

الدالة المضمَّنة resolveRef(path, chain) في resolve.ts:

1. مسار الهدف غير موجود ← يُطلق الرمز المُشار إليه غير موجود: <path>
2. الهدف نفسه هو ref ← تكرار يتبع السلسلة (يدعم سلاسل غير مباشرة بأي طول)
3. السلسلة تحتوي بالفعل على المسار الحالي ← يُطلق تم اكتشاف حلقة في مراجع الرموز: a -> b -> a
4. الوصول إلى قيمة حرفية ← تُعاد { value, type }

السلسلة غير المباشرة

"a": { "ref": "b" },
"b": { "ref": "c" },
"c": { "value": "#2B4C7C" }

يحلَّل a على طول السلسلة ليصل إلى القيمة الحرفية في c.

الكشف عن الحلقات

"a": { "ref": "b" },
"b": { "ref": "a" }

عند التحليل يتحقق chain.includes(path) ويُطلق تم اكتشاف حلقة في مراجع الرموز: a -> b -> a، فيفشل codegen مباشرةً.

نتيجة الخَبز

تُكتب نتيجة التحليل في token.value، ويُسجَّل refChain (ResolvedToken.refChain، مثل ["color.primary.active"]). لا توجد في منتجات كل طرف سوى القيم الحرفية، ولا تظهر مراجع ref:

// يشير button.borderRadius إلى radius.base (2px)، وبعد الخَبز:
val borderRadius = 2.dp  // زاوية انحناء الزر تتبع زاوية الانحناء العامة

النوع يتبع المصدر الأصلي

عندما لا يُعلِن رمز ref عن type خاص به، يُؤخذ النوع من نوع الهدف المُشار إليه (الطبقة الثانية من أولويات الطبقات الثلاث، راجع نظام الأنواع).

refMap

يسجّل refMap الذي يُعيده resolveTokens جميع علاقات المراجع التي تم حلها (path ← سلسلة ref الأصلية، مع بادئة dark: للمفاتيح الداكنة)، لاستخدامه في التوثيق وpnpm verify:tokens.

الاستخدامات الفعلية

السيناريوهات النموذجية لـ ref في tokens/:

السيناريو	مثال
تبعُّع المكوّن لكميات عامة	button.borderRadius → radius.base
تبعُّع الحالة للون دلالي	color.selected → color.primary.active
تبعُّع حجم خط المكوّن للطباعة	button.fontSize.small → typography.fontSize.small

يجب كتابة أي ref بالمسار الكامل (مساحة الأسماء + المسار المتداخل)، راجع مساحات الأسماء.