خطوط إنتاج الـ Tokens: من JSON إلى كل منصّة

بعد أن صارت الـ tokens مخزّنة كـ JSON بصيغة DTCG، يجب أن يحوّلها شيء ما إلى ما تستهلكه كل منصّة: CSS custom properties لتطبيق الويب والموقع التسويقي، وSwift لتطبيق السائقين على iOS، وKotlin أو XML لـ Android. هذا الشيء هو خط إنتاج الـ tokens (token pipeline). إنه قطعة كود صغيرة ينتهي كل فريق نظام تصميم بامتلاكها، وإتقانها مبكرًا يوفّر شهورًا من الانحراف لاحقًا.

ماذا يفعل خط الإنتاج

1. التحليل (parse): يقرأ كل ملفات المصدر ويدمجها دمجًا عميقًا في شجرة واحدة.
2. حلّ المراجع (resolve): يحلّ الأسماء المستعارة مثل {color.blue.600}، ويرفض المراجع المكسورة أو الدائرية.
3. التحويل (transform): يحوّل الأسماء والقيم لكل منصّة: يصبح color.action.bg هو --nw-color-action-bg في CSS وcolorActionBg في Swift؛ ويصبح 1rem هو 16 نقطة على iOS.
4. التنسيق (format): يكتب النتيجة في ملف: كتلة custom properties، أو enum في Swift، أو ملف موارد Android.

هذا قلب جانب CSS، وهو صغير بما يكفي لتقرأه دفعة واحدة:

const tokens = {
  color: {
    $type: 'color',
    blue: { 600: { $value: { colorSpace: 'srgb', components: [0.122, 0.353, 0.878], hex: '#1f5ae0' } } },
    white: { $value: { colorSpace: 'srgb', components: [1, 1, 1], hex: '#ffffff' } },
    action: {
      bg: { $value: '{color.blue.600}' },
      text: { $value: '{color.white}' },
    },
  },
  space: { $type: 'dimension', 4: { $value: { value: 1, unit: 'rem' } } },
};

// Walk the tree and collect every token with its path.
function flatten(node, path = [], type) {
  const t = node.$type ?? type;
  if ('$value' in node) return [{ path, type: t, value: node.$value }];
  return Object.entries(node)
    .filter(([key]) => !key.startsWith('
    
  

))
    .flatMap(([key, child]) => flatten(child, [...path, key], t));
}

const cssName = (path) => `--nw-${path.join('-')}`;
function cssValue({ type, value }) {
  if (typeof value === 'string' && value.startsWith('{')) {
    return `var(${cssName(value.slice(1, -1).split('.'))})`; // keep the reference
  }
  if (type === 'color') return value.hex;
  if (type === 'dimension') return `${value.value}${value.unit}`;
  return String(value);
}

const lines = flatten(tokens).map((t) => `  ${cssName(t.path)}: ${cssValue(t)};`);
console.log(`/* Generated from tokens. Do not edit. */\n:root {\n${lines.join('\n')}\n}`);

انظر إلى الإخراج. المسار يصبح الاسم، فيخرج color.blue.600 بالشكل --nw-color-blue-600. في الدروس السابقة اختصرنا الـ primitives إلى --nw-blue-600 لتسهيل القراءة، لكن في نظام مولَّد يكون الاسم هو ما تقوله بنية المجموعات، وهذا سبب إضافي لتصمّم المجموعات والأسماء معًا. والأهم أن الـ semantic tokens تخرج بالشكل var(--nw-color-blue-600) لا كقيمة hex. وهذا الاختيار مهمّ بما يكفي ليستحقّ قسمًا خاصًا به.

احتفظ بالمراجع

يمكن لخط الإنتاج إما أن يحلّ الأسماء المستعارة إلى قيمها النهائية، أو أن يُبقيها مراجع في الإخراج. في CSS، أبقِها. الإخراج المحلول يسطّح طبقاتك: يرى المتصفّح --nw-color-action-bg: #1f5ae0، فلا يفعل تخصيص الـ primitive وقت التشغيل شيئًا، ولا يستطيع مطوّر يفحص زرًا في DevTools أن يرى من أي primitive جاء لونه. أما الإخراج بالمراجع فيحفظ البنية التي صمّمتها بالضبط، بما فيها تغيير الـ theme على الأشجار الفرعية من درس الـ themes.

المنصّات الأصلية مختلفة. الثوابت في Swift وKotlin تُحلّ عادةً إلى قيمها النهائية، لأن هذه المنصّات تتعامل مع الـ themes بآلياتها الخاصة (asset catalogs، وcolor schemes في Compose).

خط إنتاج حقيقي مع Style Dictionary

يمكنك أن تطوّر السكربت أعلاه إلى أداة كاملة، لكن أغلب الفرق تستخدم Style Dictionary، وهو أكثر أنظمة بناء الـ tokens مفتوحة المصدر انتشارًا. إصداراته الحديثة تقرأ ملفات DTCG مباشرة وتكتشف الصيغة تلقائيًا. وإعداد على طريقة Northwind يبني الـ theme الفاتح داخل :root والـ theme الداكن تحت الـ attribute selector الخاص به:

import StyleDictionary from 'style-dictionary';

const themes = {
  light: ':root',
  dark: '[data-theme="dark"]',
};

for (const [name, selector] of Object.entries(themes)) {
  const sd = new StyleDictionary({
    include: ['tokens/primitives.tokens.json'],
    source: [`tokens/semantic-${name}.tokens.json`],
    platforms: {
      css: {
        transformGroup: 'css',
        prefix: 'nw',
        buildPath: 'dist/css/',
        files: [{
          destination: `theme-${name}.css`,
          format: 'css/variables',
          filter: name === 'light' ? undefined : (token) => token.isSource,
          options: { selector, outputReferences: true },
        }],
      },
    },
  });
  await sd.buildAllPlatforms();
}

الأفكار الأساسية: الـ primitives تدخل عبر include حتى يمكن حلّ المراجع، بينما يدخل الملف الدلالي الخاص بالـ theme عبر source. وفي الـ theme الداكن يُبقي الـ filter الـ tokens المصدرية وحدها، فيحتوي الملف الداكن على الـ semantic tokens المعاد ربطها لا على نسخة ثانية من كل primitive. وoutputReferences: true يُبقي مراجع var() في الإخراج. وقد يحذّرك Style Dictionary من أن الملف الداكن يشير إلى tokens استبعدها الـ filter؛ وهذا مقصود هنا، لأن الملف الفاتح يعرّف الـ primitives على :root أصلًا.

فحوص تعمل مع البناء

حين تصبح الـ tokens بيانات، يستطيع الـ CI أن يختبر قرارات التصميم كما يختبر الكود. يشغّل خط الإنتاج في Northwind ثلاثة فحوص على كل pull request: فحص التسمية (lint) الذي رأيته سابقًا، وفحص مراجع يفشل عند الأسماء المستعارة المكسورة أو الدائرية، وفحص تباين يحلّ كل زوج موثّق من النص والخلفية في كل theme ويفشل تحت 4.5:1. وهذا الأخير التقط تراجعًا في الوضع الداكن لعلامة Tidewater قبل أن يراه أي مصمّم.

في التمرين تكمل إعداد بناء الـ theme الداكن. وبهذا تكتمل معمارية الـ tokens؛ والقسم التالي يبني المكوّنات فوقها.