{"id":"l-ds-2-1","courseId":"design-systems","lang":"ar","kind":"lesson","summary":"نظّم الـ design tokens في ثلاث طبقات primitive وsemantic وcomponent على شكل CSS custom properties، حتى يُحدّث تغييرٌ واحد في النيّة كلَّ مكوّن يتشاركها.","html":"

كان أول ملف tokens في Northwind قائمة ألوان: --blue-600، --gray-200، --red-500. وكل مكوّن استخدمها مباشرة. بدا ذلك مرتّبًا حتى جاء الاستحواذ على Tidewater، وسأل أحدهم سؤالًا بسيطًا: «أيّ درجات الأزرق هي أزرق علامة Northwind، وأيّها مجرّد روابط؟». لم يستطع أحد الإجابة دون قراءة 300 ملف. القائمة المسطّحة من الألوان تسجّل القيم، لكنها لا تسجّل القرارات.

\n

الطبقة 1: الـ primitives

\n

الـ primitives (القيم الأولية) هي لوحة الألوان والقيم: كل قيمة خام يسمح بها النظام، مسمّاة بحسب ما هي.

\n
CSS
:root {\n  --nw-blue-600: #1f5ae0;\n  --nw-blue-700: #1848b8;\n  --nw-gray-900: #1f2933;\n  --nw-gray-200: #d9dee3;\n  --nw-white: #ffffff;\n  --nw-space-2: 0.5rem;\n  --nw-space-4: 1rem;\n}
\n

الـ primitives تجيب عن سؤال «ما القيم الموجودة؟». وهي لا تحمل أي معنى عن قصد. فـ --nw-blue-600 لا يعرف إن كان زرًا أو رابطًا أو خطًّا في رسم بياني.

\n

الطبقة 2: الـ semantic tokens

\n

الـ semantic tokens (الـ tokens الدلالية) تسمّي نيّة وتشير إلى primitive:

\n
CSS
:root {\n  --nw-color-action-bg: var(--nw-blue-600);\n  --nw-color-action-bg-hover: var(--nw-blue-700);\n  --nw-color-action-text: var(--nw-white);\n  --nw-color-text: var(--nw-gray-900);\n  --nw-color-border: var(--nw-gray-200);\n}
\n

هذه الطبقة هي الأكثر استخدامًا، وهي التي تغيّرها الـ themes. حين يصل الوضع الداكن أو علامة Tidewater، تعيد ربط هذه الأسماء بـ primitives مختلفة، ولا تلمس أي مكوّن.

\n

الطبقة 3: الـ component tokens

\n

الـ component tokens تسمّي الأجزاء القابلة للتعديل في مكوّن واحد، وتشير إلى الـ semantic tokens:

\n
CSS
.nw-button {\n  --nw-button-bg: var(--nw-color-action-bg);\n  --nw-button-text: var(--nw-color-action-text);\n  --nw-button-padding-x: var(--nw-space-4);\n\n  background: var(--nw-button-bg);\n  color: var(--nw-button-text);\n  padding: var(--nw-space-2) var(--nw-button-padding-x);\n}
\n

الآن صار لكل نوع من ثلاثة أنواع من التغيير مكان واحد واضح:

\n
\n الـ component token المسمّى button-bg يشير إلى الـ semantic token المسمّى color-action-bg، الذي يشير إلى الـ primitive المسمّى blue-600 بالقيمة 1f5ae0. كل طبقة تتغيّر لسبب مختلف.\n \n --nw-button-bg\n \n --nw-color-action-bg\n \n --nw-blue-600\n \n \n Component\n Semantic\n Primitive\n تغيير مكوّن واحد\n تغيير theme أو علامة\n تغيير لوحة الألوان\n #1f5ae0\n \n
كل طبقة تشير فقط إلى الطبقة التي تحتها
\n\n

والقاعدة التي تجعل كل هذا يعمل: المكوّنات تشير إلى الـ semantic tokens، ولا تشير إلى الـ primitives أبدًا. في اللحظة التي يستخدم فيها مكوّن --nw-blue-600 مباشرة، يتوقّف عن اتّباع الـ themes، وتكون قد أعدت بناء القائمة المسطّحة بأسماء أطول.

\n\n

كيف يحسب المتصفّح قيمة الـ token

\n

الـ custom properties تُورَّث كما تُورَّث color. حين يحسب المتصفّح أنماط زر ما، يبحث عن --nw-button-bg على الزر نفسه، فيجد var(--nw-color-action-bg)، ثم يبحث عن هذه أيضًا على الزر، حيث تكون القيمة موروثة من أقرب سلف حدّدها. ولهذا يمكنك تغيير theme جزء من الصفحة بتحديد semantic token على حاوية:

\n
CSS
.campaign-banner {\n  --nw-color-action-bg: var(--nw-green-600);\n}
\n

كل زر داخل اللافتة يصبح أخضر، وكل زر خارجها يبقى أزرق. بلا classes جديدة، وبلا تغيير في المكوّنات. وهذا السلوك في تحديد النطاق هو الأساس الذي تقوم عليه الـ themes في الدروس القادمة.

\n\n

ليست الألوان وحدها

\n

كل فئة من الـ tokens تُعامل بالطريقة نفسها. الـ primitives الخاصة بالمسافات سُلَّم (--nw-space-1 إلى --nw-space-12)؛ والمسافات الدلالية تسمّي دورًا، مثل --nw-space-inset-md للحشوة داخل البطاقة، أو --nw-space-stack-sm للفراغ بين حقول نموذج متراصّة. والـ primitives الخاصة بالطباعة هي عائلات الخطوط وأحجامها وأوزانها؛ والطباعة الدلالية تسمّي أنماطًا مثل --nw-font-body أو --nw-font-heading-lg. وتتبع أنصاف الأقطار والظلال ومُدد الحركة النمط نفسه.

\n

وللتصوّر: لدى Northwind اليوم نحو 180 primitive، و120 semantic token، و90 component token. الطبقة الدلالية هي حيث يحدث معظم التفكير التصميمي، وهي الطبقة التي يجب أن يلجأ إليها المصمّمون والمهندسون أولًا. وإن ظلّ فريق يطلب primitive بعينه، فهذا يعني عادةً أن semantic token ناقص، والإصلاح الصحيح أن تضيف الدور، لا أن تسلّم القيمة الخام.

\n

طريقة سريعة لفحص طبقاتك

\n

افتح الـ CSS الخاص بأي مكوّن وابحث عن البادئة الخاصة بالـ primitives لديك، مثل --nw-blue أو --nw-gray. في النظام السليم تظهر هذه الأسماء في مكان واحد فقط: تعريفات الـ semantic tokens. تشغّل Northwind هذا الفحص كقاعدة lint في الـ CI، وستتعرّف عليها في القسم 4. في التمرين تضيف الطبقتين الدلالية والخاصة بالمكوّن إلى زر يقفز حاليًا مباشرة إلى primitive. وبعدها تسمّي هذه الـ tokens بطريقة تبقى منطقية بعد ثلاث سنوات.

\n","toc":[{"id":"sec-1","text":"الطبقة 1: الـ primitives","level":2},{"id":"sec-2","text":"الطبقة 2: الـ semantic tokens","level":2},{"id":"sec-3","text":"الطبقة 3: الـ component tokens","level":2},{"id":"sec-4","text":"كيف يحسب المتصفّح قيمة الـ token","level":2},{"id":"sec-5","text":"ليست الألوان وحدها","level":2},{"id":"sec-6","text":"طريقة سريعة لفحص طبقاتك","level":2}],"takeaways":["الـ primitive tokens تسمّي القيم الخام (--nw-blue-600)، والـ semantic tokens تسمّي النيّة (--nw-color-action-bg)، والـ component tokens تسمّي مفاتيح التحكّم الخاصة بمكوّن واحد.","المكوّنات تشير إلى الـ semantic tokens ولا تشير إلى الـ primitives أبدًا، فيقتصر تغيير الـ theme على الطبقة الدلالية.","عرّف الـ component tokens على الـ selector الخاص بالمكوّن لا على :root، حتى تُحسب قيمتها وفق أي تخصيص في ذلك الجزء من الصفحة.","أضف الـ component tokens باقتصاد؛ فكل واحد منها API عام ستلتزم بدعمه."],"further":[{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"},{"title":"var() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/var"},{"title":"Design tokens (Material Design 3)","url":"https://m3.material.io/foundations/design-tokens"}],"quiz":[{"q":"

يريد فريق التسويق أن يتحوّل كل إجراء أساسي في الموقع إلى الأخضر خلال حملة. في نظام من ثلاث طبقات، أيّ طبقة تغيّر؟

","options":[{"text":"طبقة الـ primitives، بتغيير --nw-blue-600 إلى أخضر.","why":"هذا يحوّل كل استخدام لذلك الأزرق إلى أخضر، بما فيها الروابط وشارات المعلومات التي ليست إجراءات، ويجعل الاسم كاذبًا."},{"text":"الطبقة الدلالية، بجعل --nw-color-action-bg يشير إلى primitive أخضر.","why":"صحيح. كل مكوّن يعبّر عن «إجراء أساسي» يتبع التغيير، ولا شيء غيره."},{"text":"طبقة الـ component، بتخصيص الخلفية لكل مكوّن على حدة.","why":"هذا ينجح، لكنك ستضطر إلى إيجاد كل مكوّن فيه لون إجراء، وهي بالضبط المشكلة التي وُجدت الطبقات لحلّها."},{"text":"لا شيء منها؛ أضف class جديدًا باسم .green لكل زر.","why":"الـ classes المؤقّتة تتجاوز النظام كليًا، وتترك التنظيف لما بعد الحملة."}],"answer":1},{"q":"

لماذا يبقى الزر داخل .promo أزرق؟

\n
CSS
:root {\n  --nw-color-action-bg: var(--nw-blue-600);\n  --nw-button-bg: var(--nw-color-action-bg);\n}\n.promo { --nw-color-action-bg: var(--nw-green-600); }\n.nw-button { background: var(--nw-button-bg); }
\n","options":[{"text":"الـ custom properties لا تُورَّث إلى الأزرار.","why":"الـ custom properties تُورَّث افتراضيًا، والأزرار ضمنها؛ والتوريث هو بالضبط ما يوصل الأزرق."},{"text":"الـ specificity الخاصة بـ .promo أقل من :root.","why":"القاعدتان تستهدفان عنصرين مختلفين، فلا تُقارن الـ specificity أصلًا؛ وكل تعريف يُطبَّق حيث كُتب."},{"text":"المتصفّح يخزّن أول قيمة لكل custom property مؤقتًا.","why":"لا يوجد تخزين مؤقت؛ القيم تُحسب لكل عنصر أثناء الـ cascade العادي."},{"text":"حُسبت قيمة --nw-button-bg على :root، فورثت الأزرار الأزرق المحسوب مسبقًا.","why":"صحيح. الـ var() داخل custom property يُستبدل حيث عُرّف؛ انقل --nw-button-bg إلى .nw-button وستُحسب قيمته وفق تخصيص .promo."}],"answer":3},{"q":"

يقترح زميل component token لكل خاصية CSS في كل مكوّن. ما التكلفة الرئيسية؟

","options":[{"text":"تتباطأ المتصفّحات بوضوح مع أكثر من 100 custom property.","why":"المتصفّحات تتعامل مع آلاف الـ custom properties بلا مشكلة؛ الأداء ليس القضية بهذا الحجم."},{"text":"يصبح كل token جزءًا من API عام تعتمد عليه الفرق، فيصعب تغيير النظام.","why":"صحيح. كل مفتاح تحكّم مكشوف وعدٌ؛ وإعادة تسميته أو حذفه لاحقًا تغيير كاسر (breaking change)."},{"text":"الـ component tokens لا يمكنها الإشارة إلى الـ semantic tokens.","why":"يمكنها، ويجب أن تفعل؛ فهكذا ترتبط الطبقات ببعضها."}],"answer":1}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"
\n \n
\n
\n \n
","css":"/* Tier 1: primitives (done) */\n:root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-700: #1848b8;\n --nw-white: #ffffff;\n --nw-space-2: 0.5rem;\n --nw-space-4: 1rem;\n}\n\n/* Tier 2: add semantic tokens here */\n\n/* Tier 3: the button skips straight to primitives. Fix it. */\n.nw-button {\n background: var(--nw-blue-600);\n color: var(--nw-white);\n padding: var(--nw-space-2) var(--nw-space-4);\n border: 0;\n border-radius: 6px;\n font: inherit;\n}\n.promo { margin-top: 16px; }\n","js":""},"solution":{"html":"
\n \n
\n
\n \n
","css":"/* Tier 1: primitives (done) */\n:root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-700: #1848b8;\n --nw-white: #ffffff;\n --nw-space-2: 0.5rem;\n --nw-space-4: 1rem;\n}\n\n/* Tier 2: semantic tokens */\n:root {\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-text: var(--nw-white);\n}\n\n/* Tier 3: component tokens, declared on the component */\n.nw-button {\n --nw-button-bg: var(--nw-color-action-bg);\n --nw-button-text: var(--nw-color-action-text);\n\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n padding: var(--nw-space-2) var(--nw-space-4);\n border: 0;\n border-radius: 6px;\n font: inherit;\n}\n.promo { margin-top: 16px; }\n","js":""},"checks":[{"id":"still-blue","test":"return style('#main', 'background-color') === 'rgb(31, 90, 224)' && style('#main', 'color') === 'rgb(255, 255, 255)';"},{"id":"semantic","test":"const cs = getComputedStyle(document.documentElement); return cs.getPropertyValue('--nw-color-action-bg').trim() !== '' && cs.getPropertyValue('--nw-color-action-text').trim() !== '';"},{"id":"component","test":"const b = $('#main'); b.style.setProperty('--nw-button-bg', 'rgb(4, 5, 6)'); const ok = style(b, 'background-color') === 'rgb(4, 5, 6)'; b.style.removeProperty('--nw-button-bg'); return ok;"},{"id":"follows-semantic","test":"const p = $('.promo'); p.style.setProperty('--nw-color-action-bg', 'rgb(10, 130, 60)'); const ok = style('#promo', 'background-color') === 'rgb(10, 130, 60)' && style('#main', 'background-color') === 'rgb(31, 90, 224)'; p.style.removeProperty('--nw-color-action-bg'); return ok;"},{"id":"no-primitives","test":"const rules = [...document.styleSheets].flatMap((s) => [...s.cssRules]).filter((r) => r.selectorText); const btn = rules.filter((r) => r.selectorText.includes('nw-button')); return btn.length > 0 && btn.every((r) => !/--nw-(blue|white)/.test(r.style.cssText));"}],"title":"امنح الزر ثلاث طبقات","prompt":"

الـ primitives جاهزة، لكن .nw-button يقفز مباشرة إلى --nw-blue-600، فلا يستطيع أي theme أن يغيّره. أضف الطبقتين الناقصتين:

\n
    \n
  1. على :root، عرّف الـ semantic tokens المسمّاة --nw-color-action-bg و--nw-color-action-text، واجعلها تشير إلى الـ primitives المناسبة.
    2. \n
  2. على .nw-button، عرّف الـ component tokens المسمّاة --nw-button-bg و--nw-button-text، واجعلها تشير إلى الـ semantic tokens، واستخدمها في background وcolor.
    3. \n
\n

يجب أن يبدو الزر تمامًا كما هو الآن، ولا يجوز لأي قاعدة من قواعد .nw-button أن تذكر primitive من نوع --nw-blue-… أو --nw-white.

\n","hints":["الـ semantic tokens تبدو هكذا داخل :root: --nw-color-action-bg: var(--nw-blue-600);.","الـ component tokens توضع داخل قاعدة .nw-button { … } لا على :root، حتى تُحسب قيمتها على كل زر.","ثم غيّر background: var(--nw-blue-600) إلى background: var(--nw-button-bg)، وافعل الشيء نفسه مع color."],"explanation":"

صار الزر يحسب --nw-button-bg ← --nw-color-action-bg ← --nw-blue-600. ولأن الـ component tokens معرّفة على .nw-button، يبحث كل زر عن الـ semantic token لدى أسلافه هو، فيغيّر تحديد --nw-color-action-bg على .promo لون زر الـ promo وحده. لو عرّفت --nw-button-bg على :root لحُسبت القيمة مرة واحدة عند الجذر، ولما فعل تخصيص الـ promo شيئًا.

\n","checkLabels":{"still-blue":"ما زال الزر أزرق بنص أبيض","semantic":"يعرّف :root كلًّا من --nw-color-action-bg و--nw-color-action-text","component":"خلفية الزر تأتي من --nw-button-bg","follows-semantic":"تخصيص --nw-color-action-bg على .promo يغيّر لون زر الـ promo وحده","no-primitives":"لا توجد قاعدة من قواعد .nw-button تشير إلى primitive token"}},"words":665,"readMinutes":4}