كيف يُبنى Tanrei
مصدران للحقيقة، وسير عمل يبدأ بالمواصفة، وفحوص انحراف تُبقي خمس منصات والوثائق ومصفوفة الحالة متفقة.
يقدّم Tanrei نظام تصميم واحدًا لخمس منصات من مستودع واحد. ولا ينجح ذلك إلا إذا كان المستودع نفسه يجعل الخطأ صعبًا: التغيير الذي يُجرى في موضع واحد يجب أن ينتشر في كل مكان، أو أن يفشل فشلًا صريحًا. تصف هذه الصفحة الآلية التي تحقق ذلك.
مجلدان فقط يحتويان على قرارات:
| المجلد | ما يحمله | الصيغة |
|---|---|---|
tokens/ |
كل قيمة تصميم | صيغة Design Tokens Community Group، الإصدار 2025.10 |
specs/ |
عقد كل مكوّن | JSON، يتحقق منه specs/component.schema.json |
كل ما عدا ذلك مشتق: ملفات الرموز (tokens) المولَّدة لكل منصة، وتنفيذات المنصات، والجداول في هذه الوثائق، ومصفوفة الحالة. حين يخالف شيء مشتق مصدر الحقيقة، فالمشتق هو المخطئ بحكم التعريف.
مواصفة المكوّن محايدة تجاه المنصات. تسجّل بنية المكوّن وخصائصه ومنافذه (slots) وأحداثه وحالاته؛ وسلوكه في صورة متطلبات مرقَّمة؛ وعقد إمكانية الوصول فيه، ومنه الدور وجدول لوحة المفاتيح والتسمية؛ ومجموعة الرموز التي يرتبط بها؛ ومجموعة من نماذج الاختبار (fixtures)، وهي عروض معيارية تلتقط لها كل منصة لقطة تحت المعرّف نفسه؛ وقسم platforms الذي يقابل الأسماء المحايدة بأسلوب كل منصة.
يُكتب السلوك بصيغة EARS، وهي نمط جمل مقيَّد يسهل الاختبار وفقه:
WHEN the user activates the button by pointer, touch, Enter or Space
THE button SHALL emit click exactly once.لكل متطلب معرّف مثل BTN-1، والاختبارات على كل منصة تشير إلى هذه المعرّفات.
- اقترح. اكتب المواصفة أو غيِّرها، والرموز إن لزم. المكوّنات الجديدة والتغييرات الكاسرة يقرّرها المشرفون على المشروع، قبل أن تتغيّر المواصفة.
- تحقق. يفحص
pnpm validateالمخططات (schemas)، ويدقّق الرموز، ويتأكد من ثوابت التباين لكل سمة ومستوى تباين. - ولِّد. يعيد
pnpm generateبناء مخرجات الرموز والهياكل الأولية ومصفوفة الحالة. - نفِّذ على كل منصة تسردها المواصفة، مع اختبارات وحدة ولقطات وإمكانية وصول.
- افحص. يشغّل
pnpm checkكل شيء بالترتيب، ومنه فحص الانحراف، ويجب أن ينجح كله. - سجِّل. أضف changeset. تُرقَّم إصدارات الحزم كلها معًا، لأن التكافؤ هو المنتج.
لا يجوز أن يتغير السطح العام لمنصة من دون التغيير نفسه في المواصفة في الإيداع نفسه.
- فرق إعادة التوليد. يعيد CI توليد كل ملف مشتق، ويفشل إذا اختلفت النتيجة عما هو مودَع. التعديل اليدوي على ملف مولَّد لا يمكن أن يبقى.
- فحص التكافؤ. لكل منصة تعلنها المواصفة، يشترط الفاحص تنفيذًا، واختبارًا، ولقطة لكل نموذج اختبار، وصفحة توثيق المكوّن بالإنجليزية وباليابانية. أما الصفحات التي يجب أن تكون لكل لغة من لغات الموقع الأخرى فيتحقق منها فحص منفصل خاص بموقع التوثيق. ومصفوفة الحالة محسوبة من الحقائق نفسها، فلا تستطيع أن تدّعي أكثر مما هو موجود.
- ثوابت التباين. المخطط اللوني الذي يخفق في التباين لا يُصدَر أبدًا.
- انضباط اللقطات. اختلاف اللقطة نتيجة تستحق النظر. ولا تتغير الصور المرجعية إلا حين يكون التغيير البصري هو النتيجة المقصودة لتغيير في مواصفة أو رمز.
التكافؤ يعني الرموز نفسها، ونتيجة بصرية متكافئة، والحالات نفسها، ودلالات إمكانية الوصول نفسها. ولا يعني واجهة برمجية متطابقة. يأخذ Compose الخاصية enabled، ويعطّل Flutter الزر بقيمة null للخاصية onPressed، ويستخدم SwiftUI المعدِّل .disabled(_:). كل مقابلة مدوَّنة في قسم platforms من المواصفة ومعروضة في صفحة كل مكوّن.
القواعد نفسها تُلزم البشر ووكلاء الذكاء الاصطناعي، وأكبر قدر ممكن منها تفرضه الأدوات لا الثقة.
- قواعد متراكبة. ملف
AGENTS.mdقصير في الجذر ينص على دستور المشروع؛ والملفات الداخلية تضيف قواعد محلية للرموز والمواصفات ولكل حزمة. تستطيع القواعد الداخلية أن تزيد على قواعد الجذر، ولا تُضعفها أبدًا. - المسارات. عمل المنصة محصور في حزمة تلك المنصة. الوكيل الذي ينفّذ SwiftUI لا سبب لديه ليمسّ Compose.
- الخطّافات (hooks). التعديلات على المجلدات المولَّدة، والخيار
--no-verify، وتحديثات الصور المرجعية للّقطات تُحجب على مستوى الأدوات، ويعمل فحص الانحراف عند انتهاء الجلسة. - المهارات (skills). الإجراءات المتكررة، مثل إضافة مكوّن أو رمز، مدوَّنة مهاراتٍ خطوة بخطوة، فتُنفَّذ بالطريقة نفسها كل مرة.
- لا نشر. الإصدار إلى سجل حزم قرار المشرفين على المشروع. ولا يجوز لأي فاعل آلي أن يقوم به.
ملاحظة
هذه الوثائق تتبع القواعد نفسها. الحالة ومراجع الرموز وجداول مواصفات المكوّنات تُعرض من بيانات المستودع عند البناء. والنصوص وحدها مكتوبة باليد.