دمج الوضع الداكن

التغطية التدريجية

لا يُعلِن ملف الوضع الداكن ("$dark": true) سوى المفاتيح المختلفة عن الوضع الفاتح، وتحتفظ المفاتيح غير المغطاة بقيمها من الوضع الفاتح:

color-dark.json

{
  "$namespace": "color",
  "$dark": true,
  "$description": "لا يُعلَن سوى المفاتيح المختلفة عن الوضع الفاتح، وتحافظ المفاتيح غير المغطاة على قيمها من color.json",
  "primary": { "default": { "value": "#3D649E" } }
}

تحتفظ المفاتيح غير المذكورة مثل color.primary.hover و.active بقيمها من الوضع الفاتح. ومبدأ التقليم هو المقارنة مفتاحًا بمفتاح: يُحذف كل مفتاح تطابقت قيمته تمامًا مع قيمته في الوضع الفاتح (مثلًا، onPrimary يساوي #FFFFFF في الوضعين، وdisabled.* يشير إلى نفس مجموعة المراجع في الوضعين في الوضعين، ولذلك لا يظهر أي منهما في ملف الوضع الداكن).

يجب أن تتطابق مساحة الأسماء

يجب أن يُعلِن ملف الوضع الداكن نفس $namespace الخاص بملف الوضع الفاتح (يكتب color-dark.json صراحةً "$namespace": "color")، كي تقع المفاتيح المغطاة على المسار نفسه.

تحليل مراجع الوضع الداكن بالأقرب

تُحلَّل مراجع ref داخل ملف الوضع الداكن عبر resolveDarkRef، وقواعدها مختلفة عن الوضع الفاتح:

1. الهدف داخل مساحة أسماء الوضع الداكن وهو ref ← تتبع السلسلة بشكل متداخل داخل الوضع الداكن (فقط عندما يشير الداكن إلى الداكن تُؤخذ القيمة من النمط نفسه)
2. الهدف داخل مساحة أسماء الوضع الداكن وهو قيمة حرفية ← تُعاد قيمة الوضع الداكن
3. الهدف ليس داخل مساحة أسماء الوضع الداكن ← التراجع إلى مساحة أسماء الوضع الفاتح لأخذ القيمة

// داكن يشير إلى داكن: تُؤخذ قيمة primary.active من الوضع الداكن
"selectedDark": { "ref": "color.primary.active" }

تجري مراجع الوضع الداكن كذلك الكشف عن الحلقات (تم اكتشاف حلقة في مراجع الرموز الداكنة)، ويجب أن يكون الهدف موجودًا في مجموعة الوضع الفاتح أو مجموعة الوضع الداكن، وإلّا يُطلق مرجع الرمز الداكن X غير موجود.

الحساب المسبق لـ color-mix

يستخدم الوضع الداكن في سلالة الويب بكثرة color-mix()، وليس لدى الأطراف الأصلية هذه القدرة في وقت التشغيل، لذلك يتم حسابه مسبقًا إلى قيم ألوان مسطحة في وقت البناء، مع تدوين أساس الحساب في الوصف:

"selected": {
  "value": "#B1C1D8",
  "description": "محسوب مسبقًا من color-mix(primary 40%, #fff)، تباين اللوحة الداكنة 5.2:1"
},
"primary": {
  "bg": {
    "value": "rgba(61, 100, 158, 0.25)",
    "description": "محسوب مسبقًا من color-mix(primary 25%, transparent)"
  }
}

شكل المنتجات

ينتج resolveTokens القيمة TokenSet.dark: وهي Map<path, TokenValue> مسطحة، لا تحتوي إلا على المفاتيح المغطاة. ثم يقرر كل هدف كيفية إصدارها:

المنصة	آلية الوضع الداكن
Android	object LhDarkTokens مستقل
iOS	public enum LhDarkTokens مستقل
HarmonyOS	export class LhDarkTokens مستقل
C	إعادة تعريف الماكرو بالاسم نفسه —— يُضمَّن ملف رأس الوضع الداكن بعد ملف الوضع الفاتح، فيغطي مباشرةً تعريف #define بالاسم نفسه

المسارات الداكنة اليتيمة

يُسجَّل نوعان من الحالات الشاذة في orphanDarkPaths (دون إيقاف codegen، ويُبلَّغ عنها عبر pnpm verify:tokens):

• مفتاح داكن يفتقر إلى النوع (لا يملك نوعًا ذاتيًا، ولا يوجد مفتاح مماثل في مجموعة الوضع الفاتح يرث منه) ← يُتخطى هذا المفتاح، ولا يُكتب في جدول التغطية
• مفتاح داكن غير موجود في مجموعة الوضع الفاتح (يتيم) ← يبقى مكتوبًا في جدول التغطية، لكن يُبلَّغ عنه

نطاق تغطية الوضع الداكن

لا يغطي الوضع الداكن حاليًا سوى مساحة أسماء color.* (العدد الدقيق للمفاتيح يتغير بين الإصدارات، راجع عمود الوضع الداكن في صفحة مرجع الرموز). تحافظ مساحات الأسماء غير اللونية (المسافات، الزوايا، أحجام الخطوط وغيرها) على قيمها من الوضع الفاتح في الوضع الداكن — وهذا هو السبب في أن عمود الوضع الداكن للصفوف غير اللونية في dist/docs/tokens.md يكون —.

يمكن الاطلاع على قيمة كل رمز في الوضعين الفاتح والداكن معًا في صفحة مرجع الرموز.