# 🏛️ قاهرة لتصميم الواجهات `v1.5.5` (Qahera UI Kit)
### نظام التصميم العربي البرمجـي والهندسة المعمارية متعددة المسارات لعصر الذكاء الاصطناعي
**المعجم البصري المعياري، وسجل المكونات الحي، والأساس متعدد البيئات من تطوير استوديو الوكالة**
امنح وكلاء الذكاء الاصطناعي البرمجيين (**Google Antigravity, Claude Code, Cursor, OpenAI Codex, Windsurf**) عقداً بصرياً حتمياً ومقروءاً آلياً لبناء تطبيقات ويب عربية وإنجليزية متماسكة، متوافقة مع معايير الوصولية، وفائقة الجمال عبر **React, PHP Plates, Native HTML, Web Components, HTMX** — مع ملكية برمجية كاملة للكود وصفر تبعيات تشغيلية مغلقة.
[](https://www.npmjs.com/package/qahera-ui)
[](https://www.jsdelivr.com/package/npm/qahera-ui)
[](https://www.npmjs.com/package/qahera-ui)
[](https://github.com/alwkala/Qahera-UI-Kit/stargazers)
[](LICENSE)
[](https://github.com/alwkala)
[](https://github.com/TidyFactor)
[-success.svg?style=for-the-badge)](#بطاقة-الجودة-وصحة-المنظومة)
[-61DAFB.svg?style=for-the-badge&logo=react)](renderers/react/)
[-777BB4.svg?style=for-the-badge&logo=php)](renderers/php/plates/)
[](tsconfig.json)
[-10B981.svg?style=for-the-badge)](#بطاقة-الجودة-وصحة-المنظومة)
[](#المحددات-المعمارية-الـ-17-غير-القابلة-للتفاوض)
[-DC2626.svg?style=for-the-badge)](#المحددات-المعمارية-الـ-17-غير-القابلة-للتفاوض)
[](#أطلس-أحياء-القاهرة-المعماري-12-ثيما)
**[ 🌐 مركز المعارض الحية ](examples/previews/index.html) • [ 🏛️ المكونات الـ 45 ](#المكونات-المعمارية-الـ-45) • [ 🧩 الأنماط الـ 21 ](#الأنماط-التركيبية-الـ-21) • [ 🏙️ أطلس القاهرة (12 ثيماً) ](#أطلس-أحياء-القاهرة-المعماري-12-ثيما) • [ 🚀 البدء السريع ](#دليل-البدء-السريع-وقنوات-التوزيع) • [ 🗺️ خارطة الطريق ](#خارطة-الطريق-roadmap) • [ 📄 English ](README.md)**
---
## 📚 فهرس المحتويات
- [🎯 لماذا منظومة قاهرة؟](#لماذا-منظومة-قاهرة)
- [📊 بطاقة الجودة وصحة المنظومة](#بطاقة-الجودة-وصحة-المنظومة)
- [🖼️ النموذج المعماري ومسارات الإنتاج](#النموذج-المعماري-ومسارات-الإنتاج)
- [🏛️ المكونات المعمارية الـ 45](#المكونات-المعمارية-الـ-45)
- [🧩 الأنماط التركيبية الـ 21](#الأنماط-التركيبية-الـ-21)
- [🏙️ أطلس أحياء القاهرة المعماري (12 ثيماً)](#أطلس-أحياء-القاهرة-المعماري-12-ثيما)
- [🚀 دليل البدء السريع وقنوات التوزيع](#دليل-البدء-السريع-وقنوات-التوزيع)
- [1. أداة سطر الأوامر عبر `npx` (بنمط shadcn المعاصر)](#1-أداة-سطر-الأوامر-عبر-npx-بنمط-shadcn-المعاصر)
- [2. التضمين الفوري عبر شبكات التوزيع (CDN Quickstart)](#2-التضمين-الفوري-عبر-شبكات-التوزيع-cdn-quickstart-بدون-أي-أدوات-بناء)
- [3. محرك قوالب PHP Plates (حزمة Packagist / Composer)](#3-محرك-قوالب-php-plates-حزمة-packagist--composer)
- [4. بيئة React ومكونات الخادم 0kb RSC](#4-بيئة-react-ومكونات-الخادم-0kb-rsc)
- [5. عناصر الويب المعيارية (Web Components)](#5-عناصر-الويب-المعيارية-web-components)
- [📖 وثائق المواصفات المعمارية التفصيلية](#وثائق-المواصفات-المعمارية-التفصيلية)
- [🛡️ المحددات المعمارية الـ 17 غير القابلة للتفاوض](#المحددات-المعمارية-الـ-17-غير-القابلة-للتفاوض)
- [🗺️ خارطة الطريق (Roadmap)](#خارطة-الطريق-roadmap)
- [🤝 المساهمة وصحة المجتمع](#المساهمة-وصحة-المجتمع)
- [📞 قنوات التواصل والروابط الرسمية](#قنوات-التواصل-والروابط-الرسمية)
- [📜 الترخيص](#الترخيص)
---
## 🎯 لماذا منظومة قاهرة؟
> [!IMPORTANT]
> **المعادلة المعمارية المحورية:**
> $$\mathbf{\text{Qahera UI Kit v1.5.2}} = \mathbf{\text{Design System}} + \mathbf{\text{Registry}} + \mathbf{\text{AI Decision Layer}}$$
>
> منظومة قاهرة ليست مجرد مكتبة مكونات مكررة؛ بل هي **نظام تصميم موجه للذكاء الاصطناعي (AI-Native)** يدمج لغة تصميمية دقيقة، وسجلاً معمارياً موثقاً، وطبقة اتخاذ قرار واضحة تخبر الوكلاء البرمجيين **ماذا** يستخدمون، **متى** يستخدمونه، و**لماذا يحظر** اختراع خصائص عشوائية خارج المنظومة.
| البعد التقني | مكتبات المكونات التقليدية | التوليد العشوائي بالذكاء الاصطناعي | منظومة قاهرة (Qahera UI Kit) |
|---|---|---|---|
| **مصدر الحقيقة** | فئات CSS صلبة ومغلقة | تخمينات إحصائية ونصوص عشوائية | **عقود YAML معيارية ومحددة حتمياً** |
| **ملكية الكود** | ارتهان لحزم `npm` المعقدة | نسخ ولصق هش لـ Tailwind | **ملكية برمجية كاملة** (بنمط shadcn عبر `qahera add`) |
| **دعم RTL واللغة العربية** | حلول ترقيعية ثانوية | أخطاء اتجاهية كارثية (`mr-*`, `ml-*`) | **بنية تحتية أصيلة:** خصائص منطقية 100% وخطوط معيارية |
| **كفاءة النماذج البرمجية** | قراءة آلاف فئات الـ CSS | تلوث بصري ورموز إيموجي مشتتة | **سياق ذكاء اصطناعي تصاعدي** (`ai/components.yaml`) |
| **التوافق متعدد البيئات** | محصورة في React أو CSS فقط | صعوبة النقل وإعادة الهيكلة | **تطابق دلالي تام عبر 6 مسارات** (React, PHP, HTML, HTMX, JS) |
| **الهوية البصرية والأيقونات** | خطوط أيقونات قديمة أو عشوائية | رموز إيموجي طفولية (🗑️, 🚀, ✕) | **حظر تام للإيموجي (`QAHERA-VISUAL-001`):** 46 أيقونة SVG معيارية |
---
## 📊 بطاقة الجودة وصحة المنظومة
```text
🏛️ فحص وضمان الجودة المعمارية الصارم (معتمد للإصدار v1.5.2)
══════════════════════════════════════════════════════════════════════════════════════
✓ التحقق من المخططات والمحددات : 100% بنجاح (45 عقداً · 45 وصفة · 21 نمطاً · 46 أيقونة)
✓ فحص الأنواع الصارم TypeScript : 100% بنجاح (0 أخطاء لكافة ملفات React والقوالب)
✓ تباين الألوان معايير WCAG AA : 100% بنجاح (نسب التباين من 4.70:1 إلى 19.21:1)
✓ ميزانية الأداء لحزم الـ CSS : 219.95 KB خام / 29.57 KB مضغوطة (الحد: <= 30 KB)
✓ بصمة سيرفرية 0kb RSC : 32 مكون خادم نقي (0kb JS) + 15 مكون عميل معتمد
✓ التكافؤ الاتجاهي والقواعد المنطقية: 100% نظيف (0 خصائص فيزيائية محظورة)
✓ الانضباط الطباعي العربي : 100% نظيف (حظر تام لخط Amiri، واعتماد Alexandria/Cairo)
✓ درجة الحوكمة والمجتمع السحابي : 95 / 100 (المستوى الخامس: مشروع مفتوح المصدر ناضج)
══════════════════════════════════════════════════════════════════════════════════════
```
---
## 🖼️ النموذج المعماري ومسارات الإنتاج
كل مكون في المنظومة يبدأ كعقد دلالي موثق وينساب برمجياً عبر محول قاهرة إلى جميع بيئات التشغيل دون أي تراجع أو اختلاف:
```text
مصدر الحقيقة المعماري (YAML)
┌─────────────────────────────────────────────────┐
│ contracts/components/*.yaml (مفردات العقود) │
│ tokens/*.yaml (متغيرات التصميم)│
│ recipes/*.yaml (الوصفات البصرية)│
│ icons/registry.yaml (أيقونات SVG) │
└────────────────────────┬────────────────────────┘
│
⚡ محول قاهرة المعماري الموحد
┌────────────────────────┴────────────────────────┐
│ المرحلة 1: اكتشاف الملفات وفحص الأنساب │
│ المرحلة 2: التدقيق الصارم للمخططات والمحددات │
│ المرحلة 3: دمج وحل مصفوفة المتغيرات التراكمية │
│ المرحلة 4: توليد سجلات الـ JSON والمانيفست │
└────────────────────────┬────────────────────────┘
│
┌───────────────────┬───────────────────┼───────────────────┬───────────────────┐
▼ ▼ ▼ ▼ ▼
⚛️ React 19 / RSC 🐘 PHP 8.x Plates 🌐 Native HTML/CSS 🧩 Alpine Behaviors ⚙️ أداة الـ CLI
32 مكون خادم نقي 20 قالباً ومساعداً 49 ملف CSS ذري 11 وحدة تفاعلية `qahera add`
0kb جافاسكريبت عميل توافق PHP 8.2+ خصائص منطقية 100% ربط الأحداث المباشر ملكية الكود
```
---
## 🏛️ المكونات المعمارية الـ 45
تلتزم المكونات الـ 45 بميثاق الجودة الصارم ومسارات العرض المتكاملة:
| # | المكون المعماري | التصنيف | ملف العقد المرجعي | الغرض المعماري الأساسي |
|---|---|---|---|---|
| 1 | **Accordion** | `disclosure` | [`Accordion.yaml`](contracts/components/Accordion.yaml) | تنظيم البيانات العميقة في ألواح رأسية قابلة للطي والفتح. |
| 2 | **Alert** | `feedback` | [`Alert.yaml`](contracts/components/Alert.yaml) | عرض رسائل وتنبيهات سياقية بارزة داخل تخطيط الصفحات. |
| 3 | **Avatar** | `media` | [`Avatar.yaml`](contracts/components/Avatar.yaml) | تمثيل بصري للمستخدم أو الفريق مع مؤشر الحالة اللحظي. |
| 4 | **BackToTop** | `navigation` | [`BackToTop.yaml`](contracts/components/BackToTop.yaml) | زر عائم يتتبع عمق التمرير للعودة السلسة لأعلى الصفحة. |
| 5 | **Badge** | `feedback` | [`Badge.yaml`](contracts/components/Badge.yaml) | وسوم مدمجة للمعلومات الوصفية والحالات العددية والتصنيفية. |
| 6 | **Breadcrumb** | `navigation` | [`Breadcrumb.yaml`](contracts/components/Breadcrumb.yaml) | مسار تصفح هرمي يوضح عمق الصفحة والانتقال للآباء. |
| 7 | **Button** | `actions` | [`Button.yaml`](contracts/components/Button.yaml) | أزرار الإجراءات مع 6 أنماط و 5 مقاسات وحالات التحميل. |
| 8 | **Callout** | `feedback` | [`Callout.yaml`](contracts/components/Callout.yaml) | كتل إرشادية وتأملية بارزة للملاحظات المعمارية والتحريرية. |
| 9 | **CanvasSparks** | `media` | [`CanvasSparks.yaml`](contracts/components/CanvasSparks.yaml) | مؤثرات بصرية حية لجسيمات مضيئة تتفاعل مع حركة الفأرة. |
| 10 | **Card** | `containers` | [`Card.yaml`](contracts/components/Card.yaml) | حاويات محتوى مع رأس وجسم وتذييل وحالات رفع بصري متعددة. |
| 11 | **Carousel** | `media` | [`Carousel.yaml`](contracts/components/Carousel.yaml) | شريط تمرير وسائط متجاوب يدعم اللمس ومؤشرات الترقيم. |
| 12 | **Checkbox** | `forms` | [`Checkbox.yaml`](contracts/components/Checkbox.yaml) | صندوق اختيار متعدد نفاذ يدعم الحالة غير المحددة. |
| 13 | **Chip** | `forms` | [`Chip.yaml`](contracts/components/Chip.yaml) | شرائح ترشيح واختيار مدمجة قابلة للإزالة والتفعيل. |
| 14 | **Divider** | `layout` | [`Divider.yaml`](contracts/components/Divider.yaml) | خط فاصل دلالي أفقي أو رأسي مع دعم إدراج عنوان مركزي. |
| 15 | **Dock** | `navigation` | [`Dock.yaml`](contracts/components/Dock.yaml) | شريط تنقل سفلي للهواتف المحمولة يسهل الوصول باللمس. |
| 16 | **Drawer** | `overlay` | [`Drawer.yaml`](contracts/components/Drawer.yaml) | درج جانبي ينزلق من حافة الشاشة للفلاتر والتصفح الإضافي. |
| 17 | **Dropdown** | `navigation` | [`Dropdown.yaml`](contracts/components/Dropdown.yaml) | قائمة عائمة تكشف إجراءات وروابط سياقية منبثقة. |
| 18 | **FileUpload** | `forms` | [`FileUpload.yaml`](contracts/components/FileUpload.yaml) | منطقة سحب وإفلات لرفع الملفات مع شريط تقدم وحالات تحقق. |
| 19 | **Input** | `forms` | [`Input.yaml`](contracts/components/Input.yaml) | حقل إدخال نصوص أحادي مع أيقونات بداية ونهاية وحالات الخطأ. |
| 20 | **Kbd** | `data-display`| [`Kbd.yaml`](contracts/components/Kbd.yaml) | وسوم دلالية لاختصارات لوحة المفاتيح وأزرار النظام. |
| 21 | **Megamenu** | `navigation` | [`Megamenu.yaml`](contracts/components/Megamenu.yaml) | لوحة تصفح عريضة متعددة الأعمدة للبوابات والمتاجر الكبرى. |
| 22 | **Menu** | `navigation` | [`Menu.yaml`](contracts/components/Menu.yaml) | قائمة روابط رأسية للأشرطة الجانبية والبطاقات والأدراج. |
| 23 | **Modal** | `overlay` | [`Modal.yaml`](contracts/components/Modal.yaml) | حوار تركيبي يحصر التركيز لتأكيد الإجراءات والعمليات الحرجة. |
| 24 | **Navbar** | `navigation` | [`Navbar.yaml`](contracts/components/Navbar.yaml) | شريط علوي للهوية وروابط التصفح الأساسية ودرج المحمول. |
| 25 | **Pagination** | `navigation` | [`Pagination.yaml`](contracts/components/Pagination.yaml) | تحكم في تقسيم صفحات الجداول والكتالوجات مع منتقي الحجم. |
| 26 | **Preloader** | `feedback` | [`Preloader.yaml`](contracts/components/Preloader.yaml) | شاشة تحميل تمهيدية غامرة مع شريط تقدم ونسبة مئوية رقمية. |
| 27 | **Progress** | `feedback` | [`Progress.yaml`](contracts/components/Progress.yaml) | شريط تقدم بصري يدعم الحالات المحددة وغير المحددة. |
| 28 | **Radio** | `forms` | [`Radio.yaml`](contracts/components/Radio.yaml) | أزرار خيارات أحادية حصرية مع ملصقات وصفية نفاذة. |
| 29 | **Rating** | `feedback` | [`Rating.yaml`](contracts/components/Rating.yaml) | تقييم تفاعلي بالنجوم يدعم وضع القراءة ووضع التعديل الحي. |
| 30 | **Ribbon** | `data-display`| [`Ribbon.yaml`](contracts/components/Ribbon.yaml) | شريط زاوية مائل يثبت على أطراف البطاقات لتمييز الحالة. |
| 31 | **Select** | `forms` | [`Select.yaml`](contracts/components/Select.yaml) | قائمة اختيار منسدلة أنيقة تدعم المجموعات والتعطيل. |
| 32 | **Skeleton** | `feedback` | [`Skeleton.yaml`](contracts/components/Skeleton.yaml) | هيكل تحميل رمادي يحاكي أبعاد المكون أثناء جلب البيانات. |
| 33 | **Spinner** | `feedback` | [`Spinner.yaml`](contracts/components/Spinner.yaml) | مؤشر دوران نقي بتقنية CSS يعبر عن المعالجة اللحظية. |
| 34 | **Stepper** | `navigation` | [`Stepper.yaml`](contracts/components/Stepper.yaml) | شريط خطوات متسلسل يوضح مراحل إتمام المعاملات والنماذج. |
| 35 | **Switch** | `forms` | [`Switch.yaml`](contracts/components/Switch.yaml) | مفتاح تبديل ثنائي سلس بانتقالات فيزيائية ووصولية تامة. |
| 36 | **Table** | `data-display`| [`Table.yaml`](contracts/components/Table.yaml) | جدول بيانات متقدم يدعم الصفوف المخططة والحدود والرؤوس الثابتة. |
| 37 | **Tabs** | `navigation` | [`Tabs.yaml`](contracts/components/Tabs.yaml) | تبويبات تنقل متوافقة مع اتجاه أسهم لوحة المفاتيح في LTR و RTL. |
| 38 | **Textarea** | `forms` | [`Textarea.yaml`](contracts/components/Textarea.yaml) | حقل إدخال نصوص متعدد الأسطر مع عداد أحرف وتكيف الارتفاع. |
| 39 | **Timeline** | `data-display`| [`Timeline.yaml`](contracts/components/Timeline.yaml) | شريط أحداث زمني يربط المحطات والأنشطة بروابط بصرية. |
| 40 | **Toast** | `feedback` | [`Toast.yaml`](contracts/components/Toast.yaml) | إشعارات حية عائمة تختفي تلقائياً مع دعم النغمات الدلالية. |
| 41 | **Tooltip** | `overlay` | [`Tooltip.yaml`](contracts/components/Tooltip.yaml) | بالون تلميح سياقي يظهر عند التحويم والتركيز بالاتجاهات الأربعة. |
| 42 | **Treeview** | `navigation` | [`Treeview.yaml`](contracts/components/Treeview.yaml) | مستعرض هرمي للمجلدات والتصنيفات العميقة مع إمكانية الطي والفتح. |
| 43 | **Cartouche** | `heritage` | [`cartouche.yaml`](contracts/components/cartouche.yaml) | خرطوشة ملكية مصرية لإبراز العناوين والنصوص الملكية والنقوش الهيروغليفية. |
| 44 | **Frieze** | `heritage` | [`frieze.yaml`](contracts/components/frieze.yaml) | شريط إفريز معماري تراثي بزخارف هندسية وزهور لوتس متكررة للفواصل والإطارات. |
| 45 | **Seal** | `heritage` | [`seal.yaml`](contracts/components/seal.yaml) | ختم رسمي وميدالية ملكية مصرية بنقش بارز ونصوص دائرية للاعتماد والتوثيق. |
---
## 🧩 الأنماط التركيبية الـ 21
أنماط واجهة مركبة مبنية حصراً من المكونات المعمارية الأساسية لضمان التناسق:
1. **ConfirmationDialog** (`patterns/confirmation.yaml`): حوار تأكيد مركب لحماية العمليات غير القابلة للتراجع.
2. **DataTableToolbar** (`patterns/data-table-toolbar.yaml`): شريط أدوات الجداول (بحث، إجراءات جماعية، ومبدل الكثافة).
3. **FilterBar** (`patterns/filter-bar.yaml`): شريط فلاتر متعدد الأبعاد مع شرائح قابلة للإزالة.
4. **SearchToolbar** (`patterns/search-toolbar.yaml`): شريط بحث ذكي لحظي مع إشارات اختصارات المفاتيح (`⌘K`).
5. **DashboardStat** (`patterns/dashboard-stat.yaml`): بطاقة إحصائية لمؤشرات الأداء مع نسب التغير ومخطط بياني مصغر.
6. **ChatStream** (`patterns/chat-stream.yaml`): موجز رسائل تفاعلي يدعم مؤشرات التدفق اللحظي للذكاء الاصطناعي.
7. **EmptyState** (`patterns/empty-state.yaml`): واجهة إرشادية جذابة للقوائم الفارغة مع زر دعوة للإجراء.
8. **FormActions** (`patterns/form-actions.yaml`): شريط إجراءات النماذج الثابت أو المضمن (حفظ، إلغاء، وإعادة تعيين).
9. **KanbanBoard** (`patterns/kanban-board.yaml`): لوحة كانبان متعددة الأعمدة لإدارة تقدم المهام بالسحب والإفلات.
10. **LuxuryProductCard** (`patterns/luxury-product-card.yaml`): بطاقة منتج فاخرة للمتاجر الإلكترونية الراقية.
11. **MetricComparisonGrid** (`patterns/metric-comparison-grid.yaml`): شبكة مقارنة المؤشرات للأنظمة السحابية والشركات.
12. **DatePaginator** (`patterns/date-paginator.yaml`): شريط تنقل زمني يومي لجدولة العمليات والمواعيد.
13. **EditorialStory** (`patterns/editorial-story.yaml`): تخطيط مجلات وصحافة رقمية مع نصوص استهلالية واقتباسات.
14. **FileManagerGrid** (`patterns/file-manager-grid.yaml`): شبكة مستعرض الملفات والمجلدات مع القوائم السياقية.
15. **Questionnaire** (`patterns/questionnaire.yaml`): تدفق استبيان وتأهيل متعدد الخطوات للمستخدمين.
16. **SortableList** (`patterns/sortable-list.yaml`): قائمة صفوف تفاعلية قابلة لإعادة الترتيب.
17. **StoreLocator** (`patterns/store-locator.yaml`): مستكشف فروع تفاعلي مع بطاقات المتاجر والتفاصيل.
18. **UserCard** (`patterns/user-card.yaml`): بطاقة مستخدم مدمجة تلخص المؤشرات الاجتماعية وإجراءات المتابعة.
19. **VipMembership** (`patterns/vip-membership.yaml`): بطاقة عضوية فاخرة تبرز المزايا والمستويات الحصرية.
20. **PaginationPattern** (`patterns/pagination.yaml`): شريط ترقيم صفحات متكامل للجداول مع التحكم في القفز بين الصفحات.
21. **HeroSkylinePanorama** (`patterns/hero-skyline-panorama.yaml`): بانوراما أفق القاهرة السينمائية مع تدرجات لونية، شارات مميزة، وأزرار إجراء مزدوجة.
---
## 🏙️ أطلس أحياء القاهرة المعماري (12 ثيماً)
تنفرد المنظومة بمعمارية **التضاريس الثيمية (`QAHERA-THEME-001`)** حيث يجسد كل ثيم حركة تصميم عالمية ممزوجة بسياق عمراني وثقافي مصري أصيل:
| ثيم الحي المعماري | الحركة التصميمية العالمية | الأساسي النهاري | الأساسي الليلي | نصف قطر الحواف | الطابع والسمة البصرية |
|---|---|---|---|---|---|
| **جاردن سيتي (Garden City)** | Belle Époque الكلاسيكية الأوروبية | `#1E3A8A` | `#3B82F6` | `12px` (هادئ) | هدوء استعماري عريق، وظلال ناعمة مرتفعة |
| **الزمالك (Zamalek)** | النيو-كلاسيكية وفخامة الجزيرة | `#D4AF37` | `#F59E0B` | `10px` (ملكي) | ذهب الشمبانيا، أسطح أوبسيديان سوداء، وعمق فاخر |
| **وسط البلد (Downtown)** | آرت ديكو وعمارة الخديوي إسماعيل | `#B45309` | `#C29B38` | `0px` (حواف حادة) | حواف معمارية حادة تماماً، نحاس أثري، وتباين صلب |
| **هليوبوليس (Heliopolis)** | طراز البارون إمبان ومصر الجديدة | `#C2410C` | `#EA580C` | `10px` (دافئ) | دفء التراكوتا والرمال الصحراوية، وأقواس متزنة |
| **المعادي (Maadi)** | ضاحية الحدائق والتناغم العضوي | `#15803D` | `#22C55E` | `18px` (انسيابي) | خضرة وارفة، زوايا انسيابية طبيعية، وألوان مهدئة |
| **روكسي (Roxy)** | حداثة منتصف القرن التجارية | `#7C3AED` | `#8B5CF6` | `10px` (حيوي) | حداثة تجارية مبهجة، وتباين جريء باللون البنفسجي |
| **السكاكيني (Sakakini)** | قصر السكاكيني وفخامة الروكوكو | `#BE185D` | `#F43F5E` | `14px` (روكوكو) | انعكاسات نيون مضيئة، وزجاج منكسر دافئ |
| **الحسين (El Hussein)** | القاهرة الفاطمية والتاريخ الإسلامي | `#991B1B` | `#DC2626` | `8px` (أرابيسك) | كستنائي دافئ، وذهب فاطمي عتيق، ووقار هندسي |
| **شبرا (Shubra)** | النيو-بروتاليزم المصري الشعبي | `#374151` | `#6B7280` | `0px` (كتلي) | إطارات داكنة صلبة، وظلال كتلية غير مموهة |
| **الزيتون (El Zaytoun)** | الهندسة الوظيفية المتوازنة | `#0284C7` | `#38BDF8` | `8px` (عملي) | أزرق كلاسيكي نقي، وحسابات هندسية واضحة |
| **المرج (El Marg)** | واحة النخيل والتراث الريفي | `#047857` | `#10B981` | `14px` (نخيل) | خضرة النخيل العتيق، وإطارات مذهبة ناعمة |
| **القاهرة الجديدة (New Cairo)** | الحداثة التقنية والواجهات الزجاجية | `#06B6D4` | `#22D3EE` | `22px` (زجاجي) | زجاج مضبب (Blur 22px)، وهالات سيان نيون مشعة |
*تفعيل أي ثيم فورياً عبر وسوم الـ HTML:*
```html
```
---
## 🚀 دليل البدء السريع وقنوات التوزيع
توفر منظومة القاهرة 3 قنوات توزيع متكاملة تمنحك الملكية الكاملة للكود المصدري دون أي ارتباط تشغيلي:
### 1. أداة سطر الأوامر عبر `npx` (بنمط shadcn المعاصر)
تهيئة ملفات الـ Tokens والـ CSS وتضمين مهارة الذكاء الاصطناعي تلقائياً في مشروعك:
```bash
# 1. تهيئة المشروع (إنشاء qahera.json و tokens.css ودمج مهارة .agents/skills/qahera-ui)
npx qahera-ui init --target=react
# 2. إضافة المكونات مباشرة إلى شجرة كود مشروعك
npx qahera-ui add button modal card --target=react
# 3. إضافة المكونات إلى مشاريع PHP Plates / Monolith
npx qahera-ui add button alert navbar --target=php --dest=./views/qahera
# 4. إضافة الأنماط التركيبية أو القوالب الجاهزة
npx qahera-ui add pattern:dashboard-stat --target=react
npx qahera-ui add template:admin --target=react
# 5. استعراض قائمة الـ 45 مكوناً و 21 نمطاً و 20 قالباً
npx qahera-ui list
# 6. توليد كود البدء السريع المعتمد على الـ CDN لأي ثيم فوري
npx qahera-ui cdn zamalek
# 7. توليد خرائط الرموز وعناصر HTML الذكية لمحررات الأكواد
npx qahera-ui build:ide-data
```
> [!TIP]
> **التهيئة الصفرية لبيئة التطوير (Zero-Touch IDE Configuration):** تشغيل أمر `npx qahera-ui init` يقوم تلقائياً بتهيئة محررك المفضّل (**VS Code, Cursor, Google Antigravity**) عن طريق إنشاء `.vscode/settings.json` و `.vscode/extensions.json`، ونسخ ملفات الإكمال التلقائي (`qahera.css-data.json` و `qahera.html-data.json`)، ودمج مهارة الذكاء الاصطناعي السيادية `.agents/skills/qahera-ui` ليصبح وكيلك البرمجي خبيراً فورياً بالأمر `/qahera-ui`.
#### أوامر وكيل الذكاء الاصطناعي البرمجي (`/qahera-ui`)
| الأمر / المدخل | مسار العمل في المهارة | الوصف والمخرجات |
|---|---|---|
| `/qahera-ui compose [screen]` | `compose-screen.md` | توليد شاشات إنتاجية متكاملة اعتماداً حصرياً على المكونات والأنماط المعيارية. |
| `/qahera-ui pattern [name]` | `patterns-catalog.md` | بناء وتركيب أي نمط من الأنماط الـ 20 التركيبية (مثل `DataTableToolbar`, `ChatStream`). |
| `/qahera-ui theme [neighborhood]` | `tokens/themes/*.yaml` | تفعيل ومعاينة أي ثيم من ثيمات أطلس القاهرة الـ 12 (مثل `zamalek`, `downtown`). |
| `/qahera-ui audit` | `audit-kit.md` | فحص الالتزام المعماري الصارم بالمحددات الـ 17 غير القابلة للتفاوض. |
| `/qahera-ui scaffold [name]` | `author-component.md` | إنشاء وتوليد مكون جديد عبر دورة العقود الصارمة لكافة المسارات الستة. |
### 2. التضمين الفوري عبر شبكات التوزيع (CDN Quickstart - بدون أي أدوات بناء)
لصفحات الهبوط الثابتة، أو قوالب ووردبريس، أو مشاريع PHP التقليدية، أو التجارب السريعة دون الحاجة لتثبيت Node.js أو أدوات التحزيم، يمكنك تضمين قاهرة مباشرة عبر شبكات الـ CDN العالمية الفائقة السرعة.
#### الطبقات المعمارية الثلاث لملفات الـ CSS
يتم توزيع ملفات قاهرة عبر ثلاث طبقات معمارية دلالية مستقلة:
| حزمة التوزيع | رابط jsDelivr السريع | رابط unpkg المباشر | الوظيفة المعمارية |
|---|---|---|---|
| **رموز التصميم (Tokens)** | `https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera-tokens.min.css` | `https://unpkg.com/qahera-ui@1.5.5/dist/qahera-tokens.min.css` | الرموز الأولية الشاملة (سلم الألوان، الخطوط، المسافات، الظلال). |
| **سمات أحياء القاهرة (Themes)** | `https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera-themes.min.css` | `https://unpkg.com/qahera-ui@1.5.5/dist/qahera-themes.min.css` | أطلس السمات الـ 12 المستوحاة من أحياء القاهرة وتراثها (`[data-theme="..."]`). |
| **المكونات المعمارية (Components)** | `https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera.min.css` | `https://unpkg.com/qahera-ui@1.5.5/dist/qahera.min.css` | كافة أنماط المكونات الـ 45 الذرية المعيارية بأصناف `qhr-*`. |
> [!TIP]
> **تثبيت الإصدار مقابل التحديث التلقائي:** يُوصى بتثبيت الإصدار `@1.5.5` لضمان الاستقرار التام في الإنتاج، أو استخدام `@latest` لتلقي التحسينات والإصلاحات الطفيفة تلقائياً.
#### كود البداية المتكامل الجاهز للتشغيل المباشر (HTML5 Boilerplate)
انسخ هذا الكود بالكامل وضعه في أي ملف `.html` وافتحه مباشرة في متصفحك (أو ولّده عبر أمر `npx qahera-ui cdn zamalek`):
```html
البدء الفوري مع قاهرة عبر CDN
تضمين فوري v1.5.5
منظومة قاهرة عبر شبكة الـ CDN العالمية
واجهة عربية معمارية أصيلة تعمل فورياً دون أي تثبيت لحزم Node.js. يمكنك التبديل بين اللغات والاتجاهات (dir="rtl" / dir="ltr") والسمات المعمارية الـ 12 (data-theme="zamalek") بمرونة مطلقة.
```
### 3. محرك قوالب PHP Plates (حزمة Packagist / Composer)
التثبيت المباشر في مشاريع PHP (Laravel, FlightPHP, Slim, WordPress):
```bash
composer require alwkala/qahera-ui
```
تسجيل الإضافة المعيارية في محرك Plates:
```php
use League\Plates\Engine;
use Qahera\Renderers\Plates\QaheraPlatesExtension;
$templates = new Engine(__DIR__ . '/views');
$templates->loadExtension(new QaheraPlatesExtension());
// داخل قالب العرض:
echo $this->qhrButton([
'label' => 'تأكيد الحجز',
'variant' => 'primary',
'size' => 'lg',
'icon' => 'check'
]);
echo $this->qhrModal([
'id' => 'checkoutDialog',
'title' => 'إتمام الطلب',
'body' => '
