تنسيق الرموز

كل ملف tokens/*.json هو مصدر محايد تجاه المنصات، يفرض تنسيقه tokens/schema.json بشدة.

الخصائص الوصفية على مستوى الملف

المفاتيح التي تبدأ بـ $ هي خصائص وصفية، ولا تُنتج رموزًا:

الخاصية	الوظيفة
$schema	تشير إلى ./schema.json (إكمال تلقائي + تحقق في المحرر)
$description	وصف الملف، يظهر في هدف docs وفي وثيقة خط الأساس
$type	النوع الافتراضي على مستوى الملف، يرثه كل لفافة (leaf) حرفية لم تُعلِن عن type خاص بها
$dark	true تعني أن هذا الملف هو ملف تغطية الوضع الداكن (لا يُعلَن سوى المفاتيح التي تحتاج تغطية)
$namespace	بادئة مساحة الأسماء، تحدد مسار النقاط العام (راجع مساحات الأسماء)

{
  "$schema": "./schema.json",
  "$namespace": "color",
  "$type": "color",
  "$description": "لوحة الألوان والألوان الدلالية",
  "primary": { "default": { "value": "#2B4C7C" } }
}

الحقول الخمسة للرمز الطرفي

الحقل	الإلزام	الوظيفة
value	واحد من اثنين مع ref	قيمة حرفية
ref	واحد من اثنين مع value	المسار الكامل لرمز آخر يُشار إليه (تحليل ساكن وخَبز في وقت البناء)
type	اختياري	نوع الرمز، وعند عدم الإعلان عنه يُورَّث من $type على مستوى الملف
description	اختياري	وصف، يُعرض في تعليقات المنتجات وجداول التوثيق لكل طرف
nativeOnly	اختياري	true = مُضاف حديثًا في السلالة الأصلية، بلا مقابل في سلالة الويب

يستخدم schema الصيغة anyOf: [{required: [value]}, {required: [ref]}] + additionalProperties: false لضمان أن كل رمز طرفي يمتلك value أو ref ولا غيرهما، مع منع الحقول الزائدة.

سبعة أنواع

يسمح لـ type / $type بقيم سبع فقط:

النوع	شكل القيمة	مثال
color	#RGB / #RRGGBB / #AARRGGBB / rgba(r,g,b,a)	"#2B4C7C"، "rgba(61, 100, 158, 0.25)"
dimension	سلسلة نصية مع وحدة فقط "12px" / "50%" (يُلزم assertTypedValue بأن تكون سلسلة نصية؛ والقيم العددية الصافية مشروعة فقط تحت نوع number)	"40px"، "50%"
number	قيمة عددية صافية	400، 1000
string	سلسلة نصية	"PingFang SC"
shadow	سلسلة ظل مفصولة بمسافات (x y blur [spread] color)	"0px 2px 12px 0px rgba(26, 26, 26, 0.08)"
duration	"200ms" / "0.2s" (تُوحَّد إلى ملي ثانية)	"200ms"
cubicBezier	مصفوفة رباعية	[0.4, 0, 0.2, 1]

يُرفض عدم تطابق النوع مع القيمة (مثل type: color مع 40px) في مرحلة resolve عبر assertTypedValue، راجع نظام الأنواع.

قيود القيمة المحايدة (الخط الأحمر 5)

لا يُسمح لقيم الرموز سوى بالتعبيرات المحايدة:

• ✅ الألوان السداسية عشرية، rgba()، السلاسل النصية مع وحدة مثل "12px" / "50%"، القيم العددية الصافية تحت نوع number
• ❌ var() وrem وsp وdp وأي وحدات أو مراجع خاصة بأي منصة

التحويل بين وحدات المنصات من مسؤولية قوالب كل هدف:

المنصة	التحويل
Android	تحكم usesSp() باستخدام sp لأحجام الخطوط، وdp لغيرها
iOS	الأبعاد CGFloat، وتُحوَّل المدد إلى ثوانٍ ((ms/1000)، لأن رسوم SwiftUI المتحركة تعمل بالثواني)
HarmonyOS	قيم vp صافية للأبعاد
C	قيم عددية صافية، مع شرح للوحدات في التعليقات (الألوان 0xAARRGGBB، والأبعاد بالبكسل المنطقية، والمدد بالملي ثانية)

التداخل في المجموعات

يمكن تداخل المجموعات على أي مستوى، ويمكن للمجموعة كذلك أن تُعلِن عن $type خاص بها يغطي النوع الافتراضي للمجموعة بأكملها:

"fontSize": {
  "$type": "dimension",
  "base": { "value": "14px" },
  "small": { "value": "13px" }
}

لا يمتلك typography.json قيمة $type على مستوى الملف، ويعتمد على $type على مستوى المجموعة أو على type ذاتي في كل رمز طرفي.

علامة nativeOnly

تُعلَّم بها الرموز المُضافة حديثًا في السلالة الأصلية بلا مقابل في سلالة الويب (غالبيتها أبعاد جديدة للأجهزة المحمولة). وظيفتها:

• column الوصف في dist/docs/tokens.md يُعلَّم بـ «إضافة أصلية»
• تستخرج وثيقة خط أساس العائلة منها قائمة «الرموز الأصلية المُضافة»
• لا يتم فلترتها في أهداف الأطراف الأصلية، بل تُولَّد كما هي

قائمة الملفات

الملف	$namespace	$type	الوصف
color.json	color (مشتق من اسم الملف)	color	لوحة الألوان والألوان الدلالية
color-dark.json	color (صريح، يجب أن يطابق مساحة أسماء الوضع الفاتح)	color	تجاوزات تدريجية للوضع الداكن
components.json	""	dimension	رموز على مستوى المكوّن
typography.json	typography	لا شيء (يعلن كل مجموعة / رمز عن نفسه)	الطباعة
spacing.json	spacing	dimension	مقياس المسافات
radius.json	radius	dimension	زوايا الانحناء
shadow.json	shadow	shadow	الظلال
motion.json	motion	لا شيء (يعلن كل مجموعة / رمز عن نفسه)	المدد والتخفيف
z-index.json	zIndex (صريح)	number	الترتيب الطبقي