Qahera Logo Qahera Logo
قاهرة بوابة التوثيق والمعايير
CLI Tooling v1.5.3 Zero Runtime Overhead

التثبيت وإعداد بيئة العمل

تعمل منظومة قاهرة بنموذج النسخ والامتلاك (Copy & Own) بأسلوب shadcn المعماري. أنت تمتلك الكود في مشروعك بنسبة 100% دون حزم تشغيلية معقدة في وقت التشغيل.

1. فلسفة النسخ والامتلاك (Copy & Own vs Runtime Lock-in)

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

ملكية تامة للكود (Zero Black Box)
المكونات تستقر داخل مجلد مشروعك مباشرة. يمكنك تخصيص الأنماط والسلوك ودمج مكتباتك الخاصة دون قيود من حزم خارجية مغلقة.
حجم صفري في وقت التشغيل (0kb Bloat)
لا يتم تحميل أي مكتبات إدارة حالة معقدة أو runtime dependencies. ما يخرج للمتصفح هو CSS دلالي نقي و HTML فائق السرعة.

2. تهيئة المشروع التفاعلية (Quickstart)

أمر التهيئة التفاعلي يقوم بإنشاء ملف الإعدادات واستيراد الرموز والسمات المناسبة لمشروعك:

Terminal / NPX 
npx qahera-ui init

خلال أمر التهيئة، سيطرح عليك الـ CLI الأسئلة الأساسية لتخصيص بيئتك:

1
تحديد مسار ومكتبة التصيير: React (Next.js / Vite), PHP Monolith, HTML Native, أو HTMX.
2
مسار مجلد المكونات: مثل components/ui أو app/views/components.
3
الحي المعماري الافتراضي: مثل الزمالك (Zamalek)، مصر الجديدة (Heliopolis)، أو وسط البلد (Downtown).

تشريح ملف الإعدادات qahera.config.json

qahera.config.json 
{
  "$schema": "https://qahera.alwkala.com/schema/qahera.config.json",
  "style": "native",
  "rsc": true,
  "theme": "zamalek",
  "typography": {
    "heading": "Alexandria",
    "body": "Cairo",
    "mono": "JetBrains Mono"
  },
  "aliases": {
    "components": "@/components/ui",
    "tokens": "@/styles/tokens",
    "themes": "@/styles/themes"
  }
}

3. استيراد المكونات حسب الطلب (Selective Add)

يمكنك إضافة المكونات التي تحتاجها فقط لمنع أي تضخم في حجم الحزمة البرمجية:

Terminal / Bash 
npx qahera-ui add button card modal navbar

أو إضافة كافة المكونات الـ 46 والأنماط الـ 20 دفعة واحدة:

Terminal / Bash 
npx qahera-ui add --all

4. أدلة التكامل التفاعلية حسب بيئة العمل

اختر بيئة التطوير الخاصة بمشروعك لمعاينة خطوات الإعداد الدقيقة:

قاعدة الـ 0kb Client Boundary
كافة مكونات قاهرة في Next.js هي Server Components بنسبة 0 بايت جافاسكريبت على المتصفح. تُحصر تعليمة 'use client' فقط في الأطراف التفاعلية مثل Modal أو Dropdown.
app/layout.tsx (تضمين الرموز والخطوط) 
import "@/styles/tokens.css";
import "@/styles/themes.css";
import "@/styles/qahera.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ar" dir="rtl" data-theme="zamalek" data-mode="dark">
      <body className="font-cairo bg-surface-page text-primary">
        {children}
      </body>
    </html>
  );
}
app/page.tsx (استخدام المكونات الخادمة RSC) 
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";

export default function HomePage() {
  return (
    <main className="p-8 max-w-4xl mx-auto">
      <Card variant="elevated" padding="lg">
        <h1 className="font-alexandria text-2xl font-bold mb-4">منظومة قاهرة المعمارية</h1>
        <p className="text-secondary mb-6">مكون خادم نقي 0kb RSC مع دعم كامل للاتجاه المنطقي.</p>
        <Button variant="primary" size="md">ابدأ الآن</Button>
      </Card>
    </main>
  );
}
تطابق المسميات دون انحراف المفردات ودعم حزم Composer
دوال تصيير PHP تقبل نفس مسميات الـ Props تماماً: $variant, $size, $tone، وتتوفر رسمياً كحزمة Composer مع دعم لمحرك قوالب League/Plates و WordPress و Laravel.
تثبيت حزمة Composer الرسمية 
composer require alwkala/qahera-ui
views/home.php (استدعاء دوال التصيير أو إضافة Plates) 
<?php
require_once __DIR__ . '/vendor/autoload.php';

// أو استدعاء مباشر لملفات التصيير النواة
require_once __DIR__ . '/vendor/alwkala/qahera-ui/renderers/php/renderers/button.php';
require_once __DIR__ . '/vendor/alwkala/qahera-ui/renderers/php/renderers/card.php';
?>

<!DOCTYPE html>
<html lang="ar" dir="rtl" data-theme="zamalek" data-mode="dark">
<head>
  <link rel="stylesheet" href="/assets/dist/qahera-tokens.css">
  <link rel="stylesheet" href="/assets/dist/qahera-themes.css">
  <link rel="stylesheet" href="/assets/dist/qahera.css">
</head>
<body>
  <?= qhr_card([
    'variant' => 'elevated',
    'content' => '
      <h2>مرحبا بك في قاهرة</h2>
      <p>تصيير PHP نقي مع أعلى كفاءة أداء في الخادم.</p>
    ' . qhr_button(['variant' => 'primary', 'label' => 'متابعة'])
  ]) ?>
</body>
</html>
جاهز للإنتاج فوراً بدون أدوات بناء (Zero Build Step & CDN)
يمكنك استخدام المكونات مباشرة عبر كود HTML نقي والاعتماد على أصناف الـ CSS القياسية qhr-* مع استدعاء ملفات التوزيع محلياً أو عبر شبكات الـ CDN العالمية (jsDelivr / unpkg).
التضمين الفوري عبر CDN (jsDelivr) 
<!-- Design Tokens & 12 Cairo Themes -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-tokens.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-themes.min.css">
<!-- Core Components -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera.min.css">
index.html (استخدام محلي) 
<!DOCTYPE html>
<html lang="ar" dir="rtl" data-theme="zamalek" data-mode="dark">
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="dist/qahera-tokens.css">
  <link rel="stylesheet" href="dist/qahera-themes.css">
  <link rel="stylesheet" href="dist/qahera.css">
  <script src="dist/behavior/alpine.min.js" defer></script>
</head>
<body>
  <div class="qhr-card qhr-card--elevated">
    <h2 class="qhr-card-title">واجهة سريعة وخفيفة</h2>
    <button type="button" class="qhr-btn qhr-btn--primary qhr-btn--md">زر قياسي</button>
  </div>
</body>
</html>
واجهات هايبرميديا تفاعلية دون تعقيدات SPA
خوادمك ترجع أجزاء HTML دلالية مباشرة مغلفة بأصناف qhr-* ليقوم HTMX بتبديلها في الصفحة بلحظة واحدة.
partials/table-row.html (استجابة الخادم) 
<tr id="order-101" class="qhr-table-row">
  <td class="qhr-table-cell">#101</td>
  <td class="qhr-table-cell">أحمد الشناوي</td>
  <td class="qhr-table-cell"><span class="qhr-badge qhr-badge--success">مكتمل</span></td>
  <td class="qhr-table-cell">
    <button hx-delete="/orders/101" hx-target="#order-101" hx-swap="outerHTML" class="qhr-btn qhr-btn--ghost qhr-btn--xs qhr-btn--danger">حذف</button>
  </td>
</tr>

5. التضمين الفوري عبر شبكات التوزيع (Zero-Build CDN Quickstart)

إذا كنت تبني صفحة هبوط مستقلة، أو موقع ووردبريس، أو مشروع PHP لا يعتمد على Node.js أو أدوات التحزيم، يمكنك استدعاء ملفات قاهرة مباشرة عبر شبكات الـ CDN العالمية الفائقة السرعة (jsDelivr و unpkg):

حزمة التوزيع رابط jsDelivr المعتمد رابط unpkg المباشر الوظيفة والوصف المعماري
qahera-tokens.min.css cdn.jsdelivr.net/npm/[email protected]/dist/qahera-tokens.min.css unpkg.com/[email protected]/dist/qahera-tokens.min.css رموز التصميم الأولية، سلم الألوان، ومصفوفة الارتفاعات.
qahera-themes.min.css cdn.jsdelivr.net/npm/[email protected]/dist/qahera-themes.min.css unpkg.com/[email protected]/dist/qahera-themes.min.css أطلس سمات أحياء القاهرة الـ 12 (data-theme).
qahera.min.css cdn.jsdelivr.net/npm/[email protected]/dist/qahera.min.css unpkg.com/[email protected]/dist/qahera.min.css ورقة أنماط المكونات الـ 45 الذرية المعيارية (qhr-*).
تثبيت الإصدار في الإنتاج (Version Pinning)
يُوصى دائماً بتحديد رقم الإصدار الدقيق @1.5.3 في بيئة الإنتاج لضمان الاستقرار التام، أو استخدام @latest في بيئات التطوير لتلقي التحديثات والتحسينات التلقائية.
قالب HTML5 متكامل للبدء المباشر مع CDN 
<!DOCTYPE html>
<html lang="ar" dir="rtl" data-theme="zamalek" data-mode="dark">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>تطبيق قاهرة عبر CDN</title>

  <!-- Fonts: Alexandria & Cairo -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Alexandria:wght@600;700;800&family=Cairo:wght@400;500;600;700&display=swap" rel="stylesheet">

  <!-- Qahera CDN CSS Layers -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-tokens.min.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-themes.min.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera.min.css">

  <!-- Alpine.js for Interactive Controls -->
  <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>
</head>
<body style="background: var(--qhr-surface-page, #0A0D14); color: var(--qhr-text-primary, #F8FAFC); font-family: var(--qhr-font-body, 'Cairo', sans-serif); padding: 2rem;">
  <div class="qhr-card qhr-card--elevated" style="max-width: 600px; margin: 0 auto; padding: 2rem;">
    <span class="qhr-badge qhr-badge--primary qhr-badge--pill">CDN Quickstart</span>
    <h1 style="font-family: var(--qhr-font-heading, 'Alexandria', sans-serif); margin-block: 1rem 0.5rem;">منظومة قاهرة المعمارية</h1>
    <p style="color: var(--qhr-text-secondary); line-height: 1.7; margin-block-end: 1.5rem;">جاهزة للعمل فوراً في أي متصفح دون أدوات بناء وبكفاءة 100% Logical CSS.</p>
    <button type="button" class="qhr-btn qhr-btn--primary qhr-btn--md">زر رئيسي</button>
  </div>
</body>
</html>

6. الجدول المرجعي لأوامر الـ CLI

الأمر (Command) الخيارات الشائعة الوصف والوظيفة
npx qahera-ui init --yes, --cwd <path> تهيئة ملف الإعدادات واستيراد الرموز والسمات لمشروع جديد.
npx qahera-ui add <names...> --all, --overwrite نسخ مكونات أو أنماط محددة إلى مجلد المكونات الخاص بك.
npx qahera-ui list --components, --patterns عرض فهرس كافة المكونات والأنماط المتاحة في السجل الكنسي.
npx qahera-ui template <name> --dir <path> توليد قالب إنتاجي متكامل (من الـ 20 قالباً) مباشرة في مشروعك.
npx qahera-ui validate --strict فحص سلامة الرموز والعقود والتحقق من عدم وجود قيم صلبة.

7. الأسئلة الشائعة واستكشاف الأخطاء

كيف يتم تبديل الاتجاه بين العربية والإنجليزية دون تكسر في الواجهة؟
تعتمد المنظومة حصراً على الخصائص المنطقية (Logical CSS Properties) مثل margin-inline-start و padding-inline. تغيير وسم dir="ltr" أو dir="rtl" في جذر الصفحة يعكس التخطيط فورياً وبشكل تلقائي 100%.
ما هي الخطوط المعتمدة وهل يلزم استدعاؤها خارجياً؟
الخطوط الأساسية هي Alexandria للعناوين والشعار، و Cairo للنصوص وعناصر الواجهة، و JetBrains Mono للأكواد. يتم استدعاؤها عبر Google Fonts أو استضافتها محلياً عبر Next/Font.
لماذا تحظر المنظومة استخدام الإيموجي كأيقونات؟ (QAHERA-VISUAL-001)
لأن الرموز التعبيرية تختلف جذرياً في رسمها بين أنظمة التشغيل (iOS, Android, Windows) وتفتقر للانضباط البصري الاحترافي. تعتمد قاهرة حصراً على أيقونات SVG دلالية بمقاس 24x24 ومسار كنسي موحد.
→ الصفحة السابقة نظرة عامة والفلسفة الصفحة التالية ← رموز التصميم والسمات الـ 12