Style Dictionary: تحويل الرموز وإنشاؤها

Style Dictionary هي أداة بناء، أنشأتها Amazon، تأخذ تعريفات رموز التصميم بتنسيق JSON وتُخرجها بأي تنسيق مستهدف: خصائص CSS المخصّصة، ووحدات JavaScript ES، ومتغيرات Sass، وثوابت iOS بلغة Swift، وموارد Android بصيغة XML، وأي تنسيق مخصّص تحدده. مصدر واحد للحقيقة، ومخرجات متعددة.

ثبّت الحزمة باستخدام npm install --save-dev style-dictionary. وابدأ بهيكل المشروع باستخدام npx style-dictionary init، الذي ينشئ config.json (أو config.js) ودليل tokens/. ويحدد ملف الإعدادات مكان العثور على ملفات الرموز ومكان كتابة المخرجات.

تستخدم Style Dictionary بنية JSON متداخلة تكون للعُقد الطرفية فيها خاصية value. على سبيل المثال: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. ويصبح المسار إلى القيمة (color, primary, 500) اسم الرمز بعد التحويل، ويُنسّق عادةً على شكل color-primary-500 أو --color-primary-500.

شغّل npx style-dictionary build --config config.json (أو style-dictionary build إذا أعددته ضمن scripts في package.json). تقرأ Style Dictionary جميع ملفات الرموز من المصدر المُعدّ، وتطبّق التحويلات، ثم تكتب المخرجات في الوجهات المُعدّة. ويُبلّغ عن أخطاء تنسيق الرموز مع اسم الملف والمسار.

يعرّف config.json المنصات: css (يُخرج ملف CSS يتضمن خصائص مخصّصة)، وjs (يُخرج كائن JS)، وscss (يُخرج متغيرات Sass). وتحدد كل منصة دليل الإخراج، واسم الملف، والتنسيق (القالب)، والتحويلات (دوال معالجة الاسم والقيمة) التي يجب تطبيقها.

تتضمن Style Dictionary تحويلات مضمّنة: يحوّل name/cti/kebab المسار المتداخل إلى color-primary-500، وينتج name/cti/camel القيمة colorPrimary500، ويحوّل size/rem قيم البكسل إلى rem، ويوحّد color/hex الألوان بتنسيق hex. ويمكن تركيب التحويلات، كما تُطبّق بالترتيب.

يمكنك تسجيل تحويلات مخصّصة باستخدام StyleDictionary.registerTransform(). فمثلًا، يمكنك إنشاء تحويل يحوّل قيم البكسل إلى نقاط iOS، أو تحويل يضيف بادئة خاصة بالشركة إلى جميع أسماء الرموز. تمنحك التحويلات المخصّصة تحكمًا كاملًا في طريقة معالجة القيم قبل إخراجها.

تحدد التنسيقات المخصّصة قالب ملف الإخراج. تستقبل StyleDictionary.registerFormat() قاموس الرموز المحوّلة وتُعيد سلسلة نصية تمثل محتوى الملف. ويمكنك إخراج الرموز على شكل أنواع TypeScript، أو كائن سمة لـ React، أو امتداد لإعدادات Tailwind، أو أي تنسيق آخر يتطلبه المكدس التقني لديك.

بعد البناء، استورد مخرجات CSS في ورقة الأنماط العامة: @import './tokens/tokens.css'. واستورد مخرجات JS في المكوّنات أو إعدادات Tailwind: import tokens from './tokens/tokens.js'. تمنحك CSS خصائص مخصّصة لتطبيق السمات أثناء التشغيل، بينما تمنحك JS ثوابت ذات أنواع لاستخدامها مع Tailwind ومنطق JavaScript.

تدعم Style Dictionary مراجع الرموز باستخدام الأقواس المعقوفة: { "value": "{color.primary.500}" }. وينشئ ذلك أسماء مستعارة لرموز دلالية؛ إذ يشير الرمز الدلالي إلى رمز أولي. وأثناء البناء، تحل Style Dictionary المراجع وتُخرج القيمة النهائية المحلولة (أو مرجعًا إلى متغير CSS، وفقًا للتنسيق المستخدم).

شغّل Style Dictionary باعتبارها نصًا برمجيًا من نوع prebuild في npm، حتى تُعاد توليد الرموز دائمًا قبل بناء التطبيق. أضف "prebuild": "style-dictionary build" إلى package.json. ويضمن ذلك انعكاس أي تغيير في ملفات JSON الخاصة بالرموز على مخرجات CSS وJS قبل أن تعالجها عملية بناء React.

ما الغرض من التحويلات في Style Dictionary؟

تحوّل Style Dictionary ملفات JSON للرموز إلى أي تنسيق إخراج: متغيرات CSS، ووحدات JS، وSass، وiOS، وAndroid. تستخدم ملفات JSON للرموز كائنات متداخلة تتضمن عُقدًا طرفية بخاصية value. وتعالج التحويلات الأسماء والقيم (مثل camelCase والتحويل من px إلى rem)، بينما تحدد التنسيقات قالب الإخراج. وتتيح مراجع الرموز ({color.primary.500}) إنشاء أسماء مستعارة دلالية. ويمكنك أتمتة العملية باستخدام نص برمجي من نوع prebuild لضمان تحديث الرموز دائمًا قبل بناء React.