🏛️ Qahera UI Kit v1.6.0

• 🎯 Why Qahera UI Kit?
• 📊 System Health & Quality Scorecard
• 🖼️ Visual Showcase & Architectural Paradigm
• 🏛️ The 45 Canonical Components (v1.5 Scope)
• 🧩 The 21 Compositional UX Patterns
• 🏙️ The 12 Cairo Atlas Neighborhood Themes
• 🚀 Quick Start & Distribution Channels
  • 1. Zero-Install CLI Scaffolder via npx (shadcn-style)
  • 2. Zero-Build Global CDN Quickstart (jsDelivr & unpkg)
  • 3. PHP 8.x Plates Engine (Composer & Packagist)
  • 4. React 19 & Next.js Server Components (RSC)
  • 5. Vanilla Web Components
• 📖 Authoritative Specifications & Documentation Links
• 🛡️ The 17 Non-Negotiable Architectural Invariants
• 🗺️ Roadmap
• 🇸🇦 نظرة عامة وميثاق المنظومة باللغة العربية (README.ar.md)
• 🤝 Contributing & Community Health
• 📞 Contact & Official Links
• 📜 License

🏛️ QAHERA QUALITY ASSURANCE AUDIT (v1.5.2 Certified)
══════════════════════════════════════════════════════════════════════════════════════
  ✓ Schema & Invariants Validation : 100% Passed (45 Contracts · 45 Recipes · 21 Patterns · 46 Icons)
  ✓ TypeScript Strict Typecheck    : 100% Passed (0 Errors across all React & Template files)
  ✓ WCAG 2.1 AA Contrast Ratios    : 100% Passed (Ratios from 4.70:1 to 19.21:1)
  ✓ Performance CSS Budget         : 219.95 KB Raw / 29.57 KB Gzip (Budget: <= 30 KB)
  ✓ RSC 0kb Client Footprint       : 32 Pure Server Components (0kb JS) + 15 Leaf Client Components
  ✓ RTL/LTR Parity & Logical CSS   : 100% Clean (0 Forbidden physical margins/paddings)
  ✓ Arabic Typography Discipline   : 100% Clean (Amiri font ban enforced, Alexandria/Cairo canonical)
  ✓ Community & Governance Score   : 95/100 (Level 5: Mature Open Source Project)
══════════════════════════════════════════════════════════════════════════════════════

• 1:1 Parity Matrix: 45 Architectural Contracts (contracts/components/) = 45 Recipes (recipes/) = 21 Compositional Patterns (patterns/) = 70 Standalone Preview Playgrounds (examples/previews/).
• Living Showcase Matrix: 86 Canonical Items (45 Components + 21 Patterns + 20 Application Templates) in the Grand Interactive Hub (examples/previews/index.html).
• Production Bundles:
  • dist/qahera.css: 219.95 KB (29.57 KB gzip) production stylesheet aggregating 49 modular CSS units.
  • dist/qahera-themes.css: 38.98 KB (5.43 KB gzip) covering all 12 Cairo Atlas neighborhood themes.

Every component begins as an authoritative semantic contract and flows deterministically into all consuming targets without semantic drift:

                                  AUTHORITATIVE YAML SOURCE
                      ┌─────────────────────────────────────────────────┐
                      │   contracts/components/*.yaml  (Vocabulary)     │
                      │   tokens/*.yaml                (Design Tokens)  │
                      │   recipes/*.yaml               (Normalized CSS) │
                      │   icons/registry.yaml          (Semantic SVGs)  │
                      └────────────────────────┬────────────────────────┘
                                               │
                                 ⚡ QAHERA CANONICAL COMPILER
                      ┌────────────────────────┴────────────────────────┐
                      │   Stage 1: Discover & Lineage Resolution        │
                      │   Stage 2: Strict Schema & Invariant Audit      │
                      │   Stage 3: Token Resolution & Cascade Flatten   │
                      │   Stage 4: JSON & Manifest Registry Generation  │
                      └────────────────────────┬────────────────────────┘
                                               │
       ┌───────────────────┬───────────────────┼───────────────────┬───────────────────┐
       ▼                   ▼                   ▼                   ▼                   ▼
 ⚛️ React 19 / RSC     🐘 PHP 8.x Plates   🌐 Native HTML/CSS   🧩 Alpine Behaviors  ⚙️ CLI Scaffolder
 29 Server Components  20 Engine Partials  42 Atomic CSS Units  11 Zero-Dep Modules  `qahera add`
 0kb Client Footprint  PHP 8.2+ Strict     100% Logical CSS     Event-Driven Bridge  Source Ownership

<!-- ❌ TYPICAL RAW AI LLM GENERATION (Fragile, Hardcoded, Inaccessible) -->
<button class="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded ml-3 flex items-center gap-2">
  <span>Delete Item</span>
  <span>🗑️</span> <!-- VIOLATION: Arbitrary Emoji Slop -->
</button>
<!-- Flaws: Breaks in RTL (ml-3); Unverified contrast; Emoji slop; Hardcoded arbitrary blue -->

<!-- ✅ QAHERA CANONICAL COMPONENT (100% Token-Driven, Native RTL, Accessible) -->
<button class="qhr-btn qhr-btn--danger qhr-btn--md" type="button">
  <span class="qhr-btn__label">حذف العنصر / Delete Item</span>
  <svg class="qhr-icon qhr-icon--delete" aria-hidden="true" viewBox="0 0 24 24">
    <path d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
  </svg>
</button>
<!-- Strengths: Governed by --qhr-color-danger; Logical CSS margins; Registered SVG icon; Full 8-state matrix -->

All 45 components strictly satisfy the Definition of Done (DoD) with matching contracts, recipes, multi-target renderers, and interactive previews:

Higher-order compositional patterns constructed strictly from canonical primitives:

1. ConfirmationDialog (patterns/confirmation.yaml): Modal paired with FormActions for irreversible operations.
2. DataTableToolbar (patterns/data-table-toolbar.yaml): Search input, bulk actions, and density switcher.
3. FilterBar (patterns/filter-bar.yaml): Multi-dimensional facet selection bar with removable chips.
4. SearchToolbar (patterns/search-toolbar.yaml): Live fuzzy search input with shortcut indicators (⌘K).
5. DashboardStat (patterns/dashboard-stat.yaml): KPI statistic card with trend percentage and sparkline.
6. ChatStream (patterns/chat-stream.yaml): Conversational message feed with streaming text indicators.
7. EmptyState (patterns/empty-state.yaml): Illustrated placeholder with call-to-action for blank lists.
8. FormActions (patterns/form-actions.yaml): Sticky or embedded form submission, reset, and cancel bar.
9. KanbanBoard (patterns/kanban-board.yaml): Multi-column drag-and-drop task progression board.
10. LuxuryProductCard (patterns/luxury-product-card.yaml): High-end e-commerce card with image hover zooms.
11. MetricComparisonGrid (patterns/metric-comparison-grid.yaml): Multi-tenant metric comparison matrix.
12. DatePaginator (patterns/date-paginator.yaml): Timeline date stepper for operational day views.
13. EditorialStory (patterns/editorial-story.yaml): Rich magazine layout with drop caps and callouts.
14. FileManagerGrid (patterns/file-manager-grid.yaml): Asset folder cards with metadata and context menus.
15. Questionnaire (patterns/questionnaire.yaml): Multi-step survey and onboarding assessment flow.
16. SortableList (patterns/sortable-list.yaml): Reorderable list rows with handle indicators.
17. StoreLocator (patterns/store-locator.yaml): Interactive location finder with branch cards.
18. UserCard (patterns/user-card.yaml): User profile summary badge with social metrics and actions.
19. VipMembership (patterns/vip-membership.yaml): Tiered luxury subscription badge and perk list.
20. PaginationPattern (patterns/pagination.yaml): Composite table pagination bar with page jump control.
21. HeroSkylinePanorama (patterns/hero-skyline-panorama.yaml): Cinematic panorama hero banner with gradient overlays, kicker badges, and dual CTA actions.

Qahera UI Kit features Thematic Topography (QAHERA-THEME-001): every theme synthesizes a recognized global design movement with an authentic Egyptian cultural, architectural, or urban context:

Activate any theme seamlessly via HTML attributes:

<html data-theme="zamalek"> <!-- Switches all tokens dynamically -->

Qahera UI Kit provides 3 seamless distribution channels giving you 100% source ownership with zero runtime lock-in:

Initialize tokens, CSS, and automatically embed the AI Agent Skill into your project:

# 1. Initialize project (creates qahera.json, tokens.css, and .agents/skills/qahera-ui)
npx qahera-ui init --target=react

# 2. Add individual components directly to your project source tree
npx qahera-ui add button modal card --target=react

# 3. Add to PHP Plates / Monolith projects
npx qahera-ui add button alert navbar --target=php --dest=./views/qahera

# 4. Add composite patterns or full templates
npx qahera-ui add pattern:dashboard-stat --target=react
npx qahera-ui add template:admin --target=react

# 5. List all 45 components, 21 patterns, and 20 templates
npx qahera-ui list

# 6. Generate instant CDN HTML5 boilerplate for any Cairo theme
npx qahera-ui cdn zamalek

# 7. Audit template compliance (Zero Custom CSS & Canonical qhr-* check)
npx qahera-ui audit:template templates/fintech-wealth

# 8. Build VS Code / Cursor / Antigravity smart CSS and HTML custom data
npx qahera-ui build:ide-data

For static sites, landing pages, WordPress child themes, legacy PHP, or rapid prototyping without Node.js or build tools, load Qahera directly from global edge CDNs.

Qahera's distribution separates design tokens, themes, and component styles into clean semantic layers:

Copy and paste this complete boilerplate into any .html file and open it directly in your browser (or generate it instantly via npx qahera-ui cdn zamalek):

<!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>Qahera CDN Quickstart</title>

  <!-- Google Fonts: Alexandria (Headings) & Cairo (Body) -->
  <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">

  <!-- 1. Design Tokens & Elevation Matrix -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera-tokens.min.css">

  <!-- 2. The 12 Cairo Neighborhood Themes -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera-themes.min.css">

  <!-- 3. The 45 Canonical Components Stylesheet -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/qahera-ui@1.5.5/dist/qahera.min.css">

  <!-- Optional: Alpine.js for Interactive Components (Dropdown, Modal, Accordion) -->
  <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.8/dist/cdn.min.js"></script>
</head>
<body style="background-color: 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: 640px; margin: 0 auto; padding: 2rem;">
    <span class="qhr-badge qhr-badge--primary qhr-badge--pill">CDN Quickstart v1.5.5</span>
    
    <h1 style="font-family: var(--qhr-font-heading, 'Alexandria', sans-serif); margin-block: 1rem 0.5rem; font-size: 1.75rem;">
      منظومة قاهرة عبر شبكة التوزيع السريعة
    </h1>
    
    <p style="color: var(--qhr-text-secondary); line-height: 1.7; margin-block-end: 1.5rem;">
      تجربة فورية تعمل بـ 0kb أدوات بناء أو تجميع. يمكنك التبديل بين اللغات والاتجاهات (<code style="font-family: monospace;">dir="rtl"</code> / <code style="font-family: monospace;">dir="ltr"</code>) والسمات المعمارية الـ 12 (<code style="font-family: monospace;">data-theme="zamalek"</code>) بسلاسة تامة.
    </p>

    <div style="display: flex; gap: 0.75rem; flex-wrap: wrap;">
      <button class="qhr-btn qhr-btn--primary qhr-btn--md" type="button">
        زر رئيسي / Primary Action
      </button>
      <button class="qhr-btn qhr-btn--outline qhr-btn--md" type="button">
        زر ثانوي / Outline
      </button>
    </div>
  </div>

</body>
</html>

Install via Composer into your PHP project:

composer require alwkala/qahera-ui

Register the official Qahera extension with your Plates engine instance:

use League\Plates\Engine;
use Qahera\Renderers\Plates\QaheraPlatesExtension;

$templates = new Engine(__DIR__ . '/views');
$templates->loadExtension(new QaheraPlatesExtension());

// Inside your template:
echo $this->qhrButton([
    'label'   => 'تأكيد الحجز',
    'variant' => 'primary',
    'size'    => 'lg',
    'icon'    => 'check'
]);

echo $this->qhrModal([
    'id'    => 'checkoutDialog',
    'title' => 'إتمام الطلب',
    'body'  => '<p>تفاصيل الفاتورة المعمارية...</p>'
]);

Preserve a 0kb client JavaScript footprint using pure Server Components:

import { Button } from '@/components/qahera/Button';
import { Card } from '@/components/qahera/Card';
import { Modal } from '@/components/qahera/Modal'; // Client Leaf Component

export default function DashboardPage() {
  return (
    <Card elevation="elevated">
      <Card.Header title="لوحة التحكم المعمارية" subtitle="إصدار قاهرة 1.5.0" />
      <Card.Body>
        <Button variant="primary" size="md">
          إصدار التقرير
        </Button>
      </Card.Body>
    </Card>
  );
}

Import the autonomous bundle to self-register all 42 Custom Elements:

<script type="module" src="renderers/js/index.js"></script>

<qhr-button variant="primary" size="md">
  إجراء معياري
</qhr-button>

<qhr-badge tone="success" size="sm">
  نشط الآن
</qhr-badge>

Qahera UI Kit provides native IDE intelligence via Microsoft Custom Data v1.1 specifications:

1. Smart CSS Token Map (qahera.css-data.json): Context-aware completion across all 325 canonical tokens with bilingual Markdown documentation cards.
2. Smart HTML Custom Data (qahera.html-data.json): Intelligent autocomplete for all 45 Web Component tags (<qhr-*>) and global attributes (data-theme, data-mode, dir) with full Cairo neighborhood themes and ARIA validation.

// in .vscode/settings.json (automatically configured via npx qahera-ui init)
{
  "css.customData": [
    "./dist/qahera.css-data.json"
  ],
  "html.customData": [
    "./dist/qahera.html-data.json"
  ],
  "editor.quickSuggestions": {
    "strings": true,
    "other": true,
    "comments": false
  }
}

• Typing --qhr- in CSS: Instant completion for 325 tokens, dual-mode day/night values, Egyptian heritage notes, and logical CSS warnings.
• Typing <qhr- in HTML: Instant Web Component suggestions (<qhr-button>, <qhr-card>, etc.) with canonical props and slot definitions.
• Typing data-theme="...": Instant dropdown of all 13 authentic Cairo neighborhood themes with design movement descriptions.

To regenerate both custom data maps after updating YAML tokens or contracts:

npx qahera-ui build:ide-data

Qahera UI Kit is governed by its normative specification suite in docs/:

Every contribution and automated build must strictly adhere to the 17 invariants defined in AGENTS.md:

1. YAML is Authoritative: Contracts and recipes in YAML are the single source of truth; JSON is emitted for machine interchange only.
2. Generated Files Never Hand-Patched: Fix bugs in contracts/ or recipes/, then recompile.
3. Tokens Precede Styling: Hardcoded hex values or pixel margins are strictly banned; use --qhr-* custom properties.
4. Contracts Precede Implementations: No component exists without a registered contract in contracts/components/.
5. RTL is Infrastructure, Not a Theme: Built-in bidirectional parity via logical CSS (margin-inline-start, inset-inline-start).
6. Arabic Typography Discipline: Primary canonical fonts are Alexandria (headings) and Cairo (body); font Amiri is strictly prohibited.
7. Heritage Stays in Templates: Cultural motifs belong to downstream templates; core components remain universally portable.
8. Zero Vocabulary Drift: Semantic prop names remain identical across all 6 renderer tracks.
9. Source Ownership over Runtime Lock-in: Consuming projects copy and own their source code.
10. AI Metadata Required: Every component exposes WHAT (purpose), WHEN (use cases), and WHY NOT (anti-patterns).
11. Icons are Semantic Architecture, Never Emoji (QAHERA-VISUAL-001): Emojis (🚀, 🗑️, ✕) are strictly banned in UI components; all icons reference the 46 SVGs in icons/registry.yaml.
12. Modular Stylesheet Architecture & RSC 0kb Boundary: Atomic component CSS files; React preserves a 0kb client footprint via Server Components.
13. Dogfooding & Canonical Composition (QAHERA-COMP-001): Showcases are built exclusively from registered canonical primitives.
14. Alpine.js Hydration Protocol (QAHERA-ALPINE-001): No large inline attributes; unique template keys; no nested x-for.
15. Thematic Topography (QAHERA-THEME-001): All 12 themes map to authentic Egyptian urban contexts and architectural movements.
16. Script Tokenizer Immunity (QAHERA-SCRIPT-001): No unescaped </script> tags in string literals; code copying extracts directly from DOM nodes.
17. Disambiguated Barrel Exports (QAHERA-BARREL-001): Primitives and patterns sharing identical names (e.g. Pagination) must use explicit named re-exports.

منظومة قاهرة (Qahera UI Kit) هي أول نظام تصميم برمجـي عربي هجين مخصص لعصر الذكاء الاصطناعي (AI-Native Design System):

• المعادلة المعمارية: نظام تصميم + سجل معياري موثق + طبقة اتخاذ قرار ذكية للوكلاء البرمجيين (Antigravity, Claude, Cursor).
• حفظ السيادة واستقلالية الكود: لا تفرض المنظومة أي حزم تشغيل مغلقة؛ بل يمتلك المطور الشفرة المصدرية لمكوناته بالكامل بنمط shadcn.
• التوافق ثنائي الاتجاه (RTL/LTR Parity): اعتماد شامل لخصائص CSS المنطقية (Logical Properties) مع انضباط طباعي صارم للخطوط العربية الأصيلة (Alexandria للعناوين و Cairo للنصوص والواجهات).
• أطلس أحياء القاهرة المعماري (12 ثيماً مصرياً): تجسيد بصري لأحياء القاهرة التاريخية والمعاصرة (الزمالك، وسط البلد، هليوبوليس، جاردن سيتي، المعادي، روكسي، السكاكيني، الحسين، شبرا، الزيتون، المرج، والقاهرة الجديدة).
• حظر تام للإيموجي (QAHERA-VISUAL-001): اعتماد 46 أيقونة معيارية فكتور SVG مع حظر أي رموز تعبيرية في مكونات الواجهة لضمان الرصانة المؤسسية.

We welcome community contributions that uphold our architectural rigor. Before opening a PR:

1. Review the Contributing Guidelines (CONTRIBUTING.md) and Architectural Invariants (AGENTS.md).
2. Read the Contributor Covenant Code of Conduct (CODE_OF_CONDUCT.md).
3. Review our Security Policy & Vulnerability Reporting (SECURITY.md).
4. Ensure all local quality audits pass cleanly:

   npm run typecheck && node bin/qahera.js test

• Studio & Architecture Owner: Alwkala
• Technical Support & Inquiries: alwkala@outlook.com
• Repository & Source: github.com/alwkala/Qahera-UI-Kit
• Official Releases: GitHub Releases
• Issue Tracker: GitHub Issues

Distributed under the MIT License. © 2026 Alwkala. All rights reserved.