تسمية الـ Tokens لتعيش طويلًا

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

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

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

--nw-{category}-{concept}-{property}-{variant}-{state}

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

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

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

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

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

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

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

• رقمي، مثل 100 إلى 900 لدرجة سطوع اللون، أو 1 إلى 12 لخطوات المسافات. يمكنك إدراج 150 لاحقًا دون إعادة تسمية أي شيء. والأرقام وحدها لا تحمل معنى كبيرًا.
• مقاسات الملابس، مثل xs وsm وmd وlg وxl. سهلة القراءة في مراجعة الكود. لكن حين يحتاج المصمّمون إلى خطوة بين sm وmd تعلق بأسماء مثل sm-plus.

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

افرض القواعد

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

const grammar = /^--nw-(color|space|radius|font|shadow|motion)(-[a-z]+)+(-[0-9]+)?$/;
const banned = /-(red|blue|green|light|dark|new|old|[0-9]+px)(-|$)/;

const proposed = [
  '--nw-color-action-bg-hover',
  '--nw-color-text-light',
  '--nw-color-blue-new',
  '--nw-space-inset-md',
  '--nwColorDangerText',
  '--nw-color-danger-text',
];

for (const name of proposed) {
  const ok = grammar.test(name) && !banned.test(name);
  console.log(ok ? 'ok    ' : 'reject', name);
}

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

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

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