الإجابة المختصرة

لتشغيل مكتبة vercel-labs ui في فريق التطوير، حدّد أولاً مالكاً يملك قرار الاعتماد ويتابع التحديثات. ثم أضف روتيناً أسبوعياً قصيراً لمراجعة التغييرات، ودرّب المطورين على فحص ما يولّده الوكيل من سلوك وإمكانية وصول. وأخيراً قِس الاستخدام الفعلي في الفروع الرئيسية، لا عدد الحزم المثبتة. وبما أن المكتبة في مرحلة بيتا، اربط القرار بموعد لإعادة التقييم.

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

يشرح المقال تشغيل vercel-labs ui في فريق التطوير بعد التجربة: تحديد المالك، وروتين المراجعة الأسبوعي، وتدريب المطورين على مراجعة مكونات يكتبها الوكيل، وطرق قياس الاستخدام الفعلي، ومعالجة السلوك غير المتوقع، ومتى يُعاد النظر في الاعتماد على المكتبة. الهدف أن يخرج القارئ بخطة عملية يطبقها فريقه.

من يملك تبنّي مكتبة vercel-labs ui داخل فريق التطوير؟

تظهر الحاجة إلى تحديد المالك عادة عند حدوث خلل. مثال توضيحي: ثبّت مطور في فريق الواجهات الحزمة في مشروع داخلي، ثم نسخ الإعداد إلى مشروعين آخرين دون أن يعلم مدير الفريق. عندما اختلف سلوك لوحة المفاتيح بين المشاريع الثلاثة، لم يكن في الفريق شخص محدد يعرف الإصدار المعتمد.

يحتاج الفريق إلى مالك المكتبة يعتمد الإصدارات، ويحدد من يملك صلاحيات التثبيت، ويشرف على مراجعة الكود. لا يلزم أن يكون أعلى المطورين خبرة، لكنه يحتاج سلطة القرار ووقتاً لمتابعة التغييرات. وتذكر صفحة المستودع أن UI SDK في مرحلة بيتا، وقد تتغيّر واجهاتها وسلوكها قبل الإصدار العام، لذلك تبقى المتابعة ضرورية. للاطلاع على مرحلة ما بعد التجربة، راجع تشغيل الوكيل الذكي بعد التجربة.

من يوافق على تثبيت الإصدار؟

القرار هنا جماعي يوثّقه المالك، لا اختيار فردي، ويشمل الإصدار والإطار والمشاريع التي تبدأ به. يوضح الـREADME أن التثبيت يضيف @ui-sdk/core مع محول الإطار، وأن مهارة الوكيل تُضاف بأمر منفصل. لذلك يُستحسن تدوين الأمرين في دليل داخلي حتى لا يختلف الإعداد بين المشاريع.

من يراجع ما يكتبه الوكيل البرمجي؟

يذكر الـREADME أن الوكلاء يكتبون المكونات، لذلك تبقى المراجعة البشرية خطوة ثابتة قبل الدمج. يتحقق المراجع من التركيز بعد فتح النوافذ المنبثقة وإغلاقها، ومن التنقل بلوحة المفاتيح، ومن التسميات، ويرجع إلى ARIA Authoring Practices Guide للأدوار المتوقعة وطريقة دعم لوحة المفاتيح.

وبحسب وصف المكتبة، تتولى @ui-sdk/core سلوكيات مثل التركيز والإغلاق والسحب والإفلات. لذلك يتحقق المراجع من أن المكون يستخدم هذه الأجزاء، بدل أن يعيد كتابتها. ويجب أن يعرف المراجع الإطار المستخدم وحزمته المعتمدة، وأن يقارن الكود بمثال README الخاص بهذا الإطار.

قبل دمج مكوّن يكتبه الوكيل

ما الروتين الأسبوعي الذي يُبقي الواجهات متسقة مع المكتبة؟

يذكر المستودع أن UI SDK ما زالت في مرحلة بيتا، وأن الإطار والواجهات البرمجية والوثائق والسلوك قد تتغيّر قبل الإصدار العام. لذلك لا يكفي أن يراجع الفريق المكونات مرة واحدة عند إدخالها. يحتاج الفريق إلى روتين أسبوعي قصير يتابع التغييرات ويحدد متى تُدمج في المشاريع.

يدان تكتبان على لوحة مفاتيح حاسوب محمول على مكتب قرب نافذة في مكتب خليجي
كتابة الكود في بيئة عمل هادئة قبل التجربة.

ماذا نفعل في بداية الأسبوع؟

تبدأ مراجعة الإصدارات بسؤال بسيط: هل تغيّر شيء يمسّ المشاريع المثبتة؟ يفتح المسؤول صفحة المستودع ويقرأ ملف README والوثائق المرتبطة به، ثم يقارن ما فيها بما هو مثبت في المشاريع. يسجل أي تغيير يمسّ أسماء المكونات أو سلوك لوحة المفاتيح أو طريقة التثبيت. لشرح عام للمكتبة، يمكن الرجوع إلى شرح مكتبة vercel-labs ui: سلوكيات لبناء واجهات يصنعها الوكلاء الذكيون.

كيف نوثّق الاستثناءات؟

عندما يخالف مكوّن ما المعيار الداخلي، يُسجَّل الاستثناء في سجل بسيط يضم اسم المكوّن وسببه ومن وافق عليه وموعد مراجعته. مثال توضيحي: يسجل فريق متجر إلكتروني استثناءً لنافذة منبثقة في صفحة الدفع، ويراجعه بعد الإصدار القادم.

يذكر ملف README أن التنقل بلوحة المفاتيح والتركيز وغيرهما من السلوكيات موجودة في @ui-sdk/core، لكن الفريق يحتاج إلى التحقق من ذلك في مشروعه. وإذا مسّ الاستثناء الوصول أو التنقل بالمفاتيح، يرجع المراجع إلى ARIA Authoring Practices Guide من W3C قبل الموافقة، لأنه يشرح كيفية تطبيق دلالات الوصول على أنماط التصميم. وإذا تسبب التغيير في توقف نظام مهم، فالأولوية لخطة الاستجابة، وهذا موضوع مرتبط في كيف يدير الفريق أول ساعة من توقف نظام مهم.

خطوات الأسبوع الأول

  1. اقرأ ما تغيّر

    يفتح المسؤول صفحة المستودع ويراجع ملف README، ثم يكتب ملاحظة قصيرة بما يحتاج إجراءً.

    يدان تكتبان على لوحة مفاتيح حاسوب محمول على مكتب قرب نافذة في مكتب خليجي
    كتابة الكود في بيئة عمل هادئة قبل التجربة.
  2. حدد المشاريع المتأثرة

    يبحث الفريق عن المشاريع التي تستخدم الحزم، ويرتب التحديثات حسب حساسية الواجهة، مثل نماذج الدفع والقوائم المنسدلة.

  3. اعرض النتائج على الفريق

    يعرض المسؤول الملاحظات في اجتماع قصير، ويتفق الفريق على ما يُدمج هذا الأسبوع وما يؤجَّل.

    زميلان في غرفة اجتماعات زجاجية، أحدهما يشير إلى ورقة مطبوعة فيها مخططات مرسومة يدوياً
    مراجعة تصميم السلوكيات قبل كتابة الكود.

كيف أدرّب المطورين على مراجعة مكونات يكتبها الوكيل؟

تدخل المكونات التي يكتبها الوكيل البرمجي إلى المشروع بسرعة، لذلك تبقى المراجعة البشرية خط الدفاع الأول. توضح صفحة المستودع أن التنقل بلوحة المفاتيح والتركيز والإغلاق وARIA موجودة في @ui-sdk/core، فيركّز تدريب المطورين على فحص هل استُخدمت هذه السلوكيات بصورة صحيحة، وهل تبقى إمكانية الوصول محفوظة؟

زميلان في غرفة اجتماعات زجاجية، أحدهما يشير إلى ورقة مطبوعة فيها مخططات مرسومة يدوياً
مراجعة تصميم السلوكيات قبل كتابة الكود.

ما الذي يتعلمه المطور الجديد أولاً؟

ابدأ بقراءة تعريف المكوّن قبل شكله. في مثال المستودع يُعرَّف عنصر البحث باسمه وحالته وأجزائه، ثم يُعرض عبر createParts. في فريق توضيحي لمتجر إلكتروني في الرياض، يبدأ المطور الجديد كل جلسة تدريب بهذا التعريف.

  • اقرأ حالة المكوّن (state) واكتب ما يتغير فيها عند كل إدخال أو ضغط زر.
  • حدّد الأجزاء التي تظهر بشرط، مثل زر المسح الذي يعتمد على وجود نص.
  • لاحظ كيف يستخدم مثال README الدالة createFocusRecovery لإعادة التركيز إلى حقل الإدخال بعد المسح، وأعد التحقق من ذلك مع كل تحديث.

كيف نختبر التركيز ولوحة المفاتيح؟

اختبر المكوّن بلوحة المفاتيح وحدها. تأكد أن Tab يصل إلى كل عنصر تفاعلي بترتيب منطقي، وأن موضع التركيز ظاهر دائماً. ثم اختبر الإغلاق والإلغاء، وتحقق من أن التركيز لا يضيع بعد اختفاء العنصر.

للمرجعية، يقدّم دليل الممارسات الصادر عن W3C أمثلة لأنماط الأدوار والحالات ولوحة المفاتيح. وبما أن المكتبة ما زالت في بيتا، أعد هذه الاختبارات مع كل تحديث.

خطوات مراجعة مكوّن جديد

  1. اقرأ التعريف

    اكتب جملة لكل جزء تصف دوره قبل فتح الواجهة.

  2. جرّب لوحة المفاتيح

    تنقّل بـTab وEnter وEscape، وسجّل كل عنصر يفقد التركيز أو لا يُغلق.

    يدان تكتبان على لوحة مفاتيح حاسوب محمول على مكتب قرب نافذة في مكتب خليجي
    كتابة الكود في بيئة عمل هادئة قبل التجربة.
  3. راجع الـARIA

    قارن الأدوار والحالات في الكود بما يراه المستخدم فعلاً، مثل فتح النافذة أو إغلاقها.

  4. ناقش النتيجة

    اعرض النتائج على زميل في جلسة قصيرة، وقرّرا معاً هل يُدمج التغيير.

    زميلان في غرفة اجتماعات زجاجية، أحدهما يشير إلى ورقة مطبوعة فيها مخططات مرسومة يدوياً
    مراجعة تصميم السلوكيات قبل كتابة الكود.

كيف أقيس أن الفريق يستخدم المكتبة فعلاً وليس مجرد تثبيتها؟

تثبيت الحزمة يظهر في ملف package.json، لكنه لا يخبرنا إن كانت الواجهات الفعلية تعتمد على المكتبة. يبدأ الإعداد بتثبيت @ui-sdk/core مع المحوّل المناسب لإطارك، ثم تُبنى المكونات من سلوكيات تُعرَّف عبر definePrimitive. لذلك نحتاج إلى قياس الكود الذي يُدمج فعلاً في الفروع الرئيسية، لا الحزم المثبتة فقط.

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

مهندس تقني سعودي يقف عند باب غرفة خوادم صغيرة وهو يحمل وثيقة مطبوعة
مراجعة قرار التبني مع فريق البنية التحتية.

ما الفرق بين التثبيت والاستخدام؟

التثبيت حدث يقع مرة واحدة في مشروع. أما الاستخدام فيعني أن مكونات الإنتاج تُعرَّف عبر definePrimitive وتُعرض عبر createParts. مثال توضيحي: فريق في الرياض ثبّت المكتبة في مشروعين تجريبيين، لكن نماذج البحث في بوابة العملاء بقيت مكتوبة يدوياً. هذا الفرق هو ما نريد أن نرصده.

متى نعتبر المؤشر مفيداً؟

المؤشر مفيد إذا قادنا إلى قرار. عدد التثبيتات وحده لا يقرر شيئاً. قبل اعتماد أي مؤشر، اسأل: هل يغيّر طريقة مراجعة الدمج؟ وهل يكشف مكاناً يحتاج تدريباً إضافياً؟

ثلاثة مؤشرات تستحق المتابعة:

  • نسبة المكونات الجديدة المبنية على المكتبة من إجمالي المكونات الجديدة، مع تحديد الفريق المسؤول عن كل منها.
  • عدد مراجعات الدمج التي أُعيدت بسبب سلوك لوحة المفاتيح أو التركيز.
  • تكرار الاستثناءات، أي المكونات التي كُتبت خارج المكتبة لأن سلوكاً معيناً لا يناسب الفريق.

التثبيت مقابل الاستخدام

مؤشرات التثبيت

  • وجود @ui-sdk/core والمحوّل المناسب في package.json
  • تشغيل أمر إضافة Skill للوكيل مرة واحدة
  • مشروع تجريبي واحد يعمل محلياً

مؤشرات الاستخدام

  • مكونات إنتاج تُعرَّف عبر definePrimitive
  • استيراد الأجزاء من createParts في الفروع الرئيسية
  • مراجعات دمج تتضمن تعديلات على primitives موجودة

ماذا نفعل عندما يظهر سلوك غير متوقع بعد الإطلاق؟

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

المكتبة ما زالت في مرحلة بيتا. تنص وثائقها على أن الإطار والواجهات البرمجية والسلوك قد تتغير قبل الإصدار العام. لذلك يجب أن يُعامل تعارض الإصدارات كاحتمال متوقع يُدار بخطة واضحة.

يبدأ كل بلاغ من قناة واحدة يتفق عليها الفريق، مثل تذكرة داخلية. ويُحفظ في هذه القناة وصف الخلل وخطوات إعادة إنتاجه ورقم الإصدار المستخدم.

كيف نصنّف البلاغ؟

قبل البحث عن الحل، يحدد المسؤول نوع المشكلة. التصنيف الصحيح يوجّه البلاغ إلى الشخص المناسب ويختصر وقت المعالجة.

  • خلل في التركيز أو لوحة المفاتيح: يُقارن السلوك بأنماط لوحة المفاتيح في دليل ARIA Authoring Practices Guide.
  • تعارض في الأنماط أو الإصدارات: يُسجَّل الإصدار المثبت في package.json ويُقارن بما تغيّر بعده.
  • ثغرة أمنية: لا يُفتح بلاغ عام. يُرسل التقرير إلى responsible.disclosure@vercel.com كما يذكر README، مع مراجعة ملف SECURITY.md الذي يُحيل إليه.

متى نرجع إلى الإصدار السابق؟

الرجوع إلى إصدار سابق مناسب عندما يعطّل الخلل وظيفة أساسية، ولا يوجد حل سريع خلال يوم العمل. يُثبَّت الإصدار السابق في ملف الحزم، ثم يُعاد اختبار الواجهة قبل النشر.

يسجّل الفريق سبب الرجوع وتاريخه، ويبقى البلاغ مفتوحاً حتى يُعالج الخلل. بهذه الطريقة تبقى معالجة المشاكل واضحة، ولا تتحول إلى تخمين في وقت الإنتاج.

مسار معالجة بلاغ سلوك غير متوقع

  1. استقبال البلاغيفتح من لاحظ الخلل تذكرة في قناة الفريق مع خطوات إعادة الإنتاج.
  2. تصنيف النوعخلل واجهة، أو تعارض إصدارات، أو ثغرة أمنية.
  3. إعادة الإنتاجتأكيد الخلل على الإصدار المثبت في المشروع.
  4. الإصلاح أو الرجوعتحديث الكود، أو تثبيت الإصدار السابق عند الضرورة.
  5. الإغلاق والتوثيقتسجيل السبب والحل، ومراجعته في الروتين الأسبوعي.

متى نعيد تقييم الاعتماد على المكتبة وهي ما زالت في مرحلة بيتا؟

أعلنت صفحة المستودع أن UI SDK ما زالت في مرحلة بيتا، وأن الإطار والواجهات البرمجية والتوثيق والسلوك قد تتغيّر قبل الإصدار العام. لذلك لا ينبغي أن يُعامل قرار الاعتماد على المكتبة كقرار دائم. الأفضل أن يُربط بموعد إعادة التقييم وبعدد محدود من نقاط المراجعة.

يعيد الفريق التقييم عند حدوث أحد الأمور التالية:

  • صدور الإصدار العام للمكتبة.
  • تغيّر في الواجهات البرمجية يؤثر على مكون مستخدم في الإنتاج.
  • ظهور سلوك جديد في مكون حرج، مثل التنقل بلوحة المفاتيح أو إدارة التركيز.
  • تغيّر شروط البيتا المنصوص عليها في المستودع.

ماذا يعني أن المكتبة في مرحلة بيتا؟

البيتا تعني أن المكتبة لم تصل بعد إلى إصدار عام. وتقول صفحة المستودع إن الإطار والواجهات البرمجية والتوثيق والسلوك قد تتغيّر قبل ذلك.

الحكم على الاستقرار يحتاج إلى مراقبة لا إلى افتراض. في شركة متوسطة، قد يُحدَّث مكون البحث بعد تغيير في الإطار فتتغيّر طريقة تمرير الخصائص. لذلك نحصر استخدام المكتبة في مكونات محددة، ونوثّق سبب اختيارها.

ما أسماء الحزم والمستودع التي يجب تثبيتها بدقة؟

سجّل هذه الأسماء في وثيقة القرار قبل تثبيت الحزم، وتأكد منها قبل النسخ، لأن أسماء الحزم المتشابهة قد تُربك المراجعة. ثبّت الإصدار المختار في ملف القفل لدى الفريق حتى لا يتغيّر السلوك دون علم أحد.

  • المستودع: vercel-labs/ui، ويُرخّص بموجب Apache-2.0.
  • الحزمة الأساسية: @ui-sdk/core.
  • حزمة الإطار: @ui-sdk/react لفريق React، أو @ui-sdk/vue أو @ui-sdk/svelte أو @ui-sdk/solid أو @ui-sdk/web لبقية الأطر.

أسئلة شائعة

هل مكتبة vercel-labs ui مناسبة للإنتاج الآن؟

لا يقدّم المصدر حكماً على جاهزيتها للإنتاج، لكنه يذكر أن UI SDK ما زالت في مرحلة بيتا، وأن الإطار والواجهات البرمجية والتوثيق والسلوك قد تتغيّر قبل الإصدار العام، وأنها تخضع لشروط بيتا الخاصة بـVercel. لذلك يُقرَّر الاعتماد عليها في الإنتاج بعد تقييم المخاطر، ووضع خطة للتعامل مع التغييرات، ومراجعة شروط البيتا.

من يجب أن يشارك في قرار تبنّي المكتبة داخل الشركة؟

يحتاج القرار إلى مالك يملك صلاحية الاعتماد ووقتاً لمتابعة التحديثات. ويُفضَّل إشراك قادة الفريق التقني لمعرفة أثر أي تغيير على المشاريع القائمة. الهدف أن يعرف الجميع من يملك القرار، وألا تبقى المكتبة في مشروع واحد دون موافقة واضحة.

هل يحتاج فريق يعرف React إلى تدريب خاص قبل استخدام المكتبة؟

يعرض المصدر أمثلة باستخدام React وdefinePrimitive وcreateParts، ويذكر أن الوكلاء يكتبون هذا الكود. لذلك قد لا يحتاج الفريق إلى كتابته يدوياً، لكنه يحتاج إلى قراءة بنية المكون وفهم أجزائه وسلوكياته، ومراجعة الناتج قبل الدمج. حجم التدريب المطلوب يقدّره الفريق بحسب خبرته الحالية.

كيف أعرف أن المكون الذي كتبه الوكيل يحترم لوحة المفاتيح والتركيز؟

راجع المكون في المتصفح: انتقل بين عناصره بلوحة المفاتيح، وتحقق من أن التركيز يعود إلى العنصر المناسب عند إغلاق نافذة منبثقة، ومن أن أزرار الإدخال والمسح تعمل كما هو متوقع. ثم تأكد من أن خصائص ARIA الظاهرة تتوافق مع السلوك الفعلي. هذه مراجعة يدوية، ويمكن إضافة اختبارات آلية لاحقاً بحسب بنية فريقك.

ماذا أفعل إذا تغيّرت واجهة برمجة المكتبة بين إصدارين؟

ثبّت الإصدار الحالي في ملف الحزم، ولا تُحدّثه تلقائياً في الفروع الرئيسية. عند صدور تحديث، اقرأ التغييرات المنشورة في التوثيق أو ملاحظات الإصدار إن وُجدت، وشغّل الواجهات المتأثرة في بيئة اختبار. وإذا تغيّرت واجهة برمجة تستخدمها، سجّل ذلك كنقطة لإعادة التقييم، ولا تنتظر حتى يظهر الخلل في الإنتاج.

خطوة عملية

الخطوة التالية

اكتب قراراً قصيراً من صفحة واحدة يحدد المالك والمراجعين وأول مشروع تجريبي وموعد إعادة التقييم. ثم شغّل الروتين الأسبوعي على هذا المشروع وحده قبل توسيع الاستخدام. تواصل معنا إذا أردت مساعدة في تبنّي هذه الأداة.

إذا كنت تهيئ هذا المسار لفريقك، أخبرنا ما الذي يحتاج إلى ترتيب.

تحدث مع أوركيد