بعد أن صارت الـ tokens مخزّنة كـ JSON بصيغة DTCG، يجب أن يحوّلها شيء ما إلى ما تستهلكه كل منصّة: CSS custom properties لتطبيق الويب والموقع التسويقي، وSwift لتطبيق السائقين على iOS، وKotlin أو XML لـ Android. هذا الشيء هو خط إنتاج الـ tokens (token pipeline). إنه قطعة كود صغيرة ينتهي كل فريق نظام تصميم بامتلاكها، وإتقانها مبكرًا يوفّر شهورًا من الانحراف لاحقًا.
\n{color.blue.600}، ويرفض المراجع المكسورة أو الدائرية.color.action.bg هو --nw-color-action-bg في CSS وcolorActionBg في Swift؛ ويصبح 1rem هو 16 نقطة على iOS.هذا قلب جانب CSS، وهو صغير بما يكفي لتقرأه دفعة واحدة:
\nconst tokens = {\n color: {\n $type: 'color',\n blue: { 600: { $value: { colorSpace: 'srgb', components: [0.122, 0.353, 0.878], hex: '#1f5ae0' } } },\n white: { $value: { colorSpace: 'srgb', components: [1, 1, 1], hex: '#ffffff' } },\n action: {\n bg: { $value: '{color.blue.600}' },\n text: { $value: '{color.white}' },\n },\n },\n space: { $type: 'dimension', 4: { $value: { value: 1, unit: 'rem' } } },\n};\n\n// Walk the tree and collect every token with its path.\nfunction flatten(node, path = [], type) {\n const t = node.$type ?? type;\n if ('$value' in node) return [{ path, type: t, value: node.$value }];\n return Object.entries(node)\n .filter(([key]) => !key.startsWith('$'))\n .flatMap(([key, child]) => flatten(child, [...path, key], t));\n}\n\nconst cssName = (path) => `--nw-${path.join('-')}`;\nfunction cssValue({ type, value }) {\n if (typeof value === 'string' && value.startsWith('{')) {\n return `var(${cssName(value.slice(1, -1).split('.'))})`; // keep the reference\n }\n if (type === 'color') return value.hex;\n if (type === 'dimension') return `${value.value}${value.unit}`;\n return String(value);\n}\n\nconst lines = flatten(tokens).map((t) => ` ${cssName(t.path)}: ${cssValue(t)};`);\nconsole.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).
\nيمكنك أن تطوّر السكربت أعلاه إلى أداة كاملة، لكن أغلب الفرق تستخدم Style Dictionary، وهو أكثر أنظمة بناء الـ tokens مفتوحة المصدر انتشارًا. إصداراته الحديثة تقرأ ملفات DTCG مباشرة وتكتشف الصيغة تلقائيًا. وإعداد على طريقة Northwind يبني الـ theme الفاتح داخل :root والـ theme الداكن تحت الـ attribute selector الخاص به:
import StyleDictionary from 'style-dictionary';\n\nconst themes = {\n light: ':root',\n dark: '[data-theme=\"dark\"]',\n};\n\nfor (const [name, selector] of Object.entries(themes)) {\n const sd = new StyleDictionary({\n include: ['tokens/primitives.tokens.json'],\n source: [`tokens/semantic-${name}.tokens.json`],\n platforms: {\n css: {\n transformGroup: 'css',\n prefix: 'nw',\n buildPath: 'dist/css/',\n files: [{\n destination: `theme-${name}.css`,\n format: 'css/variables',\n filter: name === 'light' ? undefined : (token) => token.isSource,\n options: { selector, outputReferences: true },\n }],\n },\n },\n });\n await sd.buildAllPlatforms();\n}الأفكار الأساسية: الـ 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 قبل أن يراه أي مصمّم.
\nفي التمرين تكمل إعداد بناء الـ theme الداكن. وبهذا تكتمل معمارية الـ tokens؛ والقسم التالي يبني المكوّنات فوقها.
\n","toc":[{"id":"sec-1","text":"ماذا يفعل خط الإنتاج","level":2},{"id":"sec-2","text":"احتفظ بالمراجع","level":2},{"id":"sec-3","text":"خط إنتاج حقيقي مع Style Dictionary","level":2},{"id":"sec-4","text":"فحوص تعمل مع البناء","level":2}],"takeaways":["خط إنتاج الـ tokens يحلّل ملفات المصدر، ويحلّ الأسماء المستعارة، ويحوّل الأسماء والقيم لكل منصّة، ويكتب صيغة إخراج واحدة لكل منصّة.","احتفظ بالمراجع في إخراج CSS (outputReferences) حتى تبقى الـ semantic tokens تشير إلى الـ primitives وقت التشغيل، ويستمرّ تغيير الـ theme على الأشجار الفرعية في العمل.","ابنِ كل theme من الـ primitives المشتركة مع الملف الدلالي الخاص بذلك الـ theme، وأخرج الـ tokens الخاصة بالـ theme وحدها تحت الـ selector الخاص به.","الملفات المولَّدة مخرجات بناء؛ لا يعدّلها أحد يدويًا، والـ CI يعيد بناءها مع كل تغيير."],"further":[{"title":"Style Dictionary (official repository and docs)","url":"https://github.com/style-dictionary/style-dictionary"},{"title":"Design Tokens Community Group repository","url":"https://github.com/design-tokens/community-group"},{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"}],"quiz":[{"q":"يكتب خط الإنتاج --nw-color-action-bg: #1f5ae0; بدل --nw-color-action-bg: var(--nw-color-blue-600);. ما الذي ينكسر؟
لماذا يستخدم بناء الـ theme الداكن include للـ primitives وsource للملف الدلالي الداكن، ثم يصفّي على isSource؟
[data-theme="dark"] سيكرّر مئات الأسطر دون أن يغيّر شيئًا."},{"text":"لأن الملفات في include تُحمَّل أسرع.","why":"السرعة ليست المقصود؛ الفرق هو هل تُعدّ الـ tokens tokens مصدرية لأغراض التصفية أم لا."},{"text":"لأن Style Dictionary لا يستطيع قراءة ملفين في source.","why":"المصفوفة source تقبل ملفات كثيرة وأنماط glob."}],"answer":0},{"q":"عدّل مهندس منتج الملف dist/css/theme-dark.css مباشرة ليصلح خللًا في التباين، فاختفى الإصلاح بعد الإصدار التالي. ماذا كان يجب أن تكون العملية؟
املأ إعداد Style Dictionary الذي يولّد الـ theme الداكن في Northwind. يجب أن يحقّق الإخراج ما يلي:
\nnw (--nw-…)،include،var() بدل القيم المحلولة.source تُعلَّم بشكل مختلف عن المحمّلة عبر include. أيّ خاصية تميّز بينها؟","الـ selector هو نفسه من درس الـ themes: attribute selector وحده، دون html."],"explanation":"prefix: 'nw' يضيف نطاق الأسماء إلى كل اسم. وcss/variables تكتب الـ custom properties داخل الـ selector المحدّد. والتصفية على token.isSource تُبقي الـ semantic tokens الداكنة وتُسقط الـ primitives التي حُمّلت فقط لكي تُحلّ المراجع. و[data-theme="dark"] يسمح لأي عنصر ببدء شجرة فرعية داكنة، وoutputReferences: true يُبقي أسطرًا مثل --nw-color-action-bg: var(--nw-color-blue-400); حتى تصل بنية الطبقات سليمة إلى المتصفّح.