{"id":"l-ds-2-2","courseId":"design-systems","lang":"ar","kind":"lesson","summary":"سمِّ الـ design tokens وفق قواعد مكتوبة من فئة ومفهوم وخاصية وvariant وحالة، حتى تبقى الأسماء صادقة مع الوضع الداكن والعلامات الجديدة وسنوات من النمو.","html":"

كان في ملف الـ tokens القديم في Northwind token اسمه --color-blue-new. بعد سنتين صار هناك أيضًا --color-blue-new-2 و--color-blue-newer. ولم يعرف أحد أيّها أزرق العلامة. التسمية هي الجزء من نظام التصميم الذي يبدو جدالًا على التوافه، ثم يتبيّن أنه معمارية: فالأسماء هي الـ API الذي يكتبه كل مصمّم ومهندس مئات المرات في الأسبوع.

\n

قواعد، لا قائمة

\n

الأسماء الجيدة للـ tokens تأتي من قواعد: مجموعة ثابتة من الأجزاء بترتيب ثابت. والـ semantic tokens في Northwind تتبع هذه القواعد:

\n
Text
--nw-{category}-{concept}-{property}-{variant}-{state}\n\n--nw-color-action-bg                 category=color concept=action property=bg\n--nw-color-action-bg-hover           … state=hover\n--nw-color-danger-text               concept=danger property=text\n--nw-color-text-subtle               concept=text variant=subtle\n--nw-space-inset-md                  category=space concept=inset variant=md\n--nw-radius-control                  category=radius concept=control
\n

ليس كل token يستخدم كل الأجزاء، لكن الأجزاء الموجودة تأتي دائمًا بهذا الترتيب. وهذا يمنحك أمرين. يستطيع الناس تخمين أسماء لم يروها قط: إن كان --nw-color-action-bg-hover موجودًا، فالأرجح أن --nw-color-danger-bg-hover موجود أيضًا. وحين تُرتَّب أبجديًا، تتجمّع الـ tokens المترابطة معًا في كل محرّر وفي لوحة المتغيّرات في Figma.

\n

البادئة nw نطاق أسماء (namespace). تمنع التصادم مع CSS من أطراف خارجية، وتجعل tokens النظام سهلة البحث، وهذا ما ستستخدمه لاحقًا في مقاييس التبنّي.

\n

سمِّ الغرض، لا المظهر

\n

في طبقة الـ primitives تكون تسمية المظهر صحيحة: --nw-blue-600 هو أزرق فعلًا. أما في الطبقة الدلالية فالمظهر هو بالضبط ما تغيّره الـ themes، لذا يجب أن تصف الأسماء الغرض.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
اسم هشّلماذا ينكسراسم متين
--nw-color-red-bgلون الخطأ في Tidewater برتقالي--nw-color-danger-bg
--nw-color-text-lightفي الوضع الداكن ليس فاتحًا--nw-color-text-subtle
--nw-color-header-bgمسمّى باسم أول مستخدم له--nw-color-surface-inverse
--nw-color-text-2لا يقول شيئًا--nw-color-text-muted
\n

السلالم: أرقام أم مقاسات

\n

سلالم الـ primitives تحتاج أيضًا إلى نظام تسمية. وهناك خياران شائعان:

\n\n

تستخدم Northwind السلالم الرقمية للـ primitives، ومقاسات الملابس لحفنة tokens المسافات الدلالية (--nw-space-inset-sm و-md و-lg)، لأن المصمّمين يفكّرون بالمقاسات وهذه المجموعة نادرًا ما تكبر. اختر نظامًا واحدًا لكل سُلّم والتزم به. أما الخلط بينهما داخل سُلّم واحد، مثل --nw-space-2 و--nw-space-md و--nw-space-24px، فهو أسرع طريق إلى سُلّم لا يثق به أحد، لأن الناس لم يعودوا يميّزون أيّ القيم أشقاء.

\n

افرض القواعد

\n

القواعد التي تعيش فقط في صفحة wiki تصمد حتى أول مساهم مستعجل. حوّلها إلى فحص يعمل في الـ CI:

\n
JavaScript
const grammar = /^--nw-(color|space|radius|font|shadow|motion)(-[a-z]+)+(-[0-9]+)?$/;\nconst banned = /-(red|blue|green|light|dark|new|old|[0-9]+px)(-|$)/;\n\nconst proposed = [\n  '--nw-color-action-bg-hover',\n  '--nw-color-text-light',\n  '--nw-color-blue-new',\n  '--nw-space-inset-md',\n  '--nwColorDangerText',\n  '--nw-color-danger-text',\n];\n\nfor (const name of proposed) {\n  const ok = grammar.test(name) && !banned.test(name);\n  console.log(ok ? 'ok    ' : 'reject', name);\n}
\n

قائمة banned تلتقط العادات التي تنكسر أولًا: أسماء الألوان، و«light» و«dark»، و«new» و«old»، وقيم البكسل الخام. شغّلها على كل ملف tokens في الـ pull requests، واطبع القاعدة التي فشلت حتى يتعلّم المساهمون القواعد من رسالة الخطأ لا من صفحة wiki. إنها أداة فظّة، وسترفض أحيانًا اسمًا جيدًا. لا بأس بذلك؛ فالمساهم الذي يصطدم بها يسأل فريق النواة، والحوار نفسه هو المقصود.

\n\n

إعادة التسمية دون كسر عمل الآخرين

\n

ستخطئ في بعض الأسماء؛ الجميع يخطئ. حين تعيد تسمية token، أبقِ الاسم القديم اسمًا مستعارًا (alias) للجديد لإصدار واحد على الأقل، وعلّمه كـ deprecated (مُهمَل)، وأعلن ذلك في الـ changelog. يغطّي القسم 4 مسار الـ deprecation كاملًا. في التمرين التالي تراجع دفعة من الأسماء المقترحة كما يفعل فريق النواة في Northwind كل أسبوع. وبعدها تشغّل الطبقة الدلالية: مجموعة مكوّنات واحدة، وعدّة themes.

\n","toc":[{"id":"sec-1","text":"قواعد، لا قائمة","level":2},{"id":"sec-2","text":"سمِّ الغرض، لا المظهر","level":2},{"id":"sec-3","text":"السلالم: أرقام أم مقاسات","level":2},{"id":"sec-4","text":"افرض القواعد","level":2},{"id":"sec-5","text":"إعادة التسمية دون كسر عمل الآخرين","level":2}],"takeaways":["أسماء الـ semantic tokens تصف الغرض (danger، subtle) ولا تصف المظهر (red، light) أبدًا، لأن المظهر يتغيّر مع الـ themes.","الترتيب الثابت لأجزاء الاسم، مثل category-concept-property-variant-state، يجعل الـ tokens سهلة التخمين وسهلة الترتيب.","السلالم الرقمية مثل 100 إلى 900 تترك مجالًا لإدراج قيم لاحقًا؛ أما مقاسات الملابس فأسهل قراءة لكنها تمتلئ.","اكتب قواعد التسمية وافرضها بقاعدة lint، وإلا اخترع كل مساهم قواعده الخاصة."],"further":[{"title":"Custom properties (--*) (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/--*"},{"title":"Design tokens (Material Design 3)","url":"https://m3.material.io/foundations/design-tokens"},{"title":"Design Tokens Format Module 2025.10 (source on GitHub)","url":"https://github.com/design-tokens/community-group"}],"quiz":[{"q":"

أيّ اسم semantic token سيبقى دقيقًا بعد أن تضيف Northwind الوضع الداكن؟

","options":[{"text":"--nw-color-text-subtle","why":"صحيح. كلمة «subtle» تصف الدور (نص أقل بروزًا)، وهذا يصحّ في الـ theme الفاتح والداكن على حدّ سواء."},{"text":"--nw-color-text-light","why":"في الوضع الداكن يكون النص الأقل بروزًا رماديًا متوسطًا على خلفية داكنة، فإما أن تكذب كلمة «light» أو تختلط باسم الـ theme."},{"text":"--nw-color-text-gray-500","why":"تضمين primitive في اسم دلالي يعني أن الاسم ينكسر في اللحظة التي يربطه فيها الـ theme برمادي مختلف."},{"text":"--nw-color-text-2","why":"الرقم المجرّد لا يقول شيئًا عن الغرض، فلن يستطيع أحد اختياره بشكل صحيح دون فتح التوثيق."}],"answer":0},{"q":"

أنشأ فريق الـ dispatch الـ token المسمّى --nw-color-header-bg للشريط العلوي. والآن يحتاج الشريط الجانبي إلى اللون نفسه. ما أفضل خطوة؟

","options":[{"text":"استخدام --nw-color-header-bg في الشريط الجانبي أيضًا.","why":"يصبح الشريط الجانبي معتمدًا على token مسمّى باسم الترويسة؛ وحين تتغيّر الترويسة يتغيّر الشريط الجانبي عن غير قصد."},{"text":"نسخ القيمة إلى token جديد باسم --nw-color-sidebar-bg.","why":"اثنان من الـ tokens لقرار واحد سيتباعدان، وهكذا بالضبط ظهرت الدرجات الرمادية الأربع والستون."},{"text":"إعادة تسميته إلى token مبني على الغرض مثل --nw-color-surface-inverse، وجعل الاسم القديم اسمًا مستعارًا (alias) له خلال فترة الـ deprecation.","why":"صحيح. صار الاسم يصف الدور المشترك، والاسم المستعار يمنح المستخدمين وقتًا للانتقال."}],"answer":2},{"q":"

سُلّم المسافات لديك هو --nw-space-sm و-md و-lg. يحتاج المصمّمون الآن إلى قيمة بين sm وmd. ماذا يكشف هذا؟

","options":[{"text":"أن مقاسات الملابس يجب ألا تُستخدم للـ tokens أبدًا.","why":"هي مقروءة وتعمل جيدًا مع السلالم الصغيرة المستقرّة؛ المشكلة فقط أنها يصعب توسيعها من الوسط."},{"text":"أن القيمة الجديدة يجب أن تكون قيمة بكسل منفردة داخل ذلك المكوّن.","why":"القيمة المكتوبة يدويًا تتجاوز السُلّم وتبدأ الانحراف من جديد."},{"text":"أن tokens المسافات يجب أن تكون component tokens بدلًا من ذلك.","why":"المسافات مشتركة بين المكوّنات، فمكانها السُلّم المشترك."},{"text":"أن الدرجات المسمّاة تمتلئ؛ أما السُلّم الرقمي مثل 100 و200 و300 فيترك مجالًا لإضافة 150 لاحقًا.","why":"صحيح. السلالم الرقمية تضحّي بشيء من سهولة القراءة مقابل مجال للنمو، ولهذا تستخدمها أنظمة كثيرة للـ primitives."}],"answer":3},{"q":"

لماذا تمنع صيغة DTCG وجود . داخل أسماء الـ tokens؟

","options":[{"text":"لأن النقاط غير مسموحة في مفاتيح JSON.","why":"مفاتيح JSON يمكن أن تحتوي أي نص، بما فيه النقاط."},{"text":"لأن النقطة تفصل أجزاء المسار في المراجع مثل {color.action.bg}.","why":"صحيح. النقطة داخل الاسم ستجعل مسار المرجع ملتبسًا."},{"text":"لأن الـ CSS custom properties لا يمكن أن تحتوي نقاطًا.","why":"القاعدة آتية من صيغة المراجع في تنسيق الـ tokens، لا من CSS."}],"answer":1}],"exercise":{"kind":"choice","multiple":true,"options":["success-border","orange-badge","text-inverse","modal-shadow-v2","focus-ring","dark-surface"],"correct":["success-border","text-inverse","focus-ring"],"title":"راجع اقتراحات الـ tokens لهذا الأسبوع","prompt":"

اقتُرحت ستة أسماء semantic tokens على Northwind UI هذا الأسبوع. يجب أن يدعم النظام الـ theme الفاتح والداكن وعلامتين (Northwind وTidewater)، ويتبع القواعد --nw-{category}-{concept}-{property}-{variant}-{state}. اختر كل اسم توافق عليه كما هو مكتوب.

\n","hints":["تخيّل كل اسم في الوضع الداكن وفي علامة Tidewater. هل ما زال يقول الحقيقة؟","انتبه لأسماء الألوان، وكلمات الـ theme، وأرقام الإصدارات، والأسماء التي لا تناسب إلا مكوّنًا واحدًا."],"explanation":"

الأسماء المقبولة تصف دورًا: حدّ رسائل النجاح، والنص على سطح معكوس، وحلقة التركيز. وكلٌّ منها يبقى دقيقًا في كل theme وكل علامة. أما orange-badge فيصف مظهرًا ستغيّره لوحة ألوان Tidewater، وmodal-shadow-v2 يسجّل التاريخ بدل الغرض (وإعادة التصميم القادمة ستعطيك v3)، وdark-surface ينكسر في الوضع الداكن حيث معظم الأسطح داكنة. والبديل المبني على الدور سيكون --nw-color-surface-raised أو --nw-color-surface-inverse.

\n","checkLabels":{},"optionText":{"success-border":{"text":"--nw-color-success-border","why":"موافقة. يسمّي دورًا (حدّ رسائل النجاح) ويتبع ترتيب القواعد."},"orange-badge":{"text":"--nw-color-orange-badge-bg","why":"رفض. «Orange» وصف للمظهر؛ وحين يتغيّر لون التحذير في Tidewater يصبح الاسم كاذبًا."},"text-inverse":{"text":"--nw-color-text-inverse","why":"موافقة. «Inverse» تعني النص على السطح المعاكس، وهذا يصحّ في الـ theme الفاتح والداكن."},"modal-shadow-v2":{"text":"--nw-shadow-modal-v2","why":"رفض. رقم الإصدار يسجّل التاريخ لا الغرض، ويضمن ظهور v3 لاحقًا."},"focus-ring":{"text":"--nw-color-focus-ring","why":"موافقة. كل المكوّنات التفاعلية تتشارك حلقة التركيز، والدور ثابت عبر الـ themes."},"dark-surface":{"text":"--nw-color-dark-surface","why":"رفض. في الوضع الداكن تكون معظم الأسطح داكنة، فيفقد الاسم أي معنى."}}},"words":608,"readMinutes":4}