alwkala/Qahera-UI-Kit

The Authoritative Visual Vocabulary, Living Component Registry & Multi-Stack Foundation by Alwkala

Give Google Antigravity, Claude Code, Cursor, OpenAI Codex, or Windsurf a deterministic, machine-readable visual contract to build cohesive, accessible, and stunning bilingual Arabic/English web applications across React, PHP Plates, Native HTML, Web Components, and HTMX — with zero runtime lock-in and 100% source ownership.

🌐 Living Showcase Hub • 🤖 Native MCP Suite • 📚 GitHub Wiki • 🏛️ The 49 Components • 🧩 21 UX Patterns • 🏙️ Cairo Atlas (13 Themes) • 🚀 Quick Start • 🗺️ Roadmap • 📄 بالعربية (README.ar.md)

📚 Table of Contents

🎯 Why Qahera UI Kit?

Important

The Core Architectural Equation:
$$\mathbf{\text{Qahera UI Kit v1.7.0}} = \mathbf{\text{Design System}} + \mathbf{\text{Registry}} + \mathbf{\text{AI Decision Layer}}$$

Qahera is NOT just another component library or compiler. It is an AI-Native UI Kit combining a systematic design language, an authoritative canonical registry, and an explicit AI decision layer that tells coding agents WHAT to use, WHEN to use it, and WHY NOT to invent ad-hoc styles.

🤖 Sovereign AI Agent Engine & Native MCP (v1.7.0)

1. Launching the MCP Server

# Start JSON-RPC 2.0 stdio server (for IDE sidecars)
npx -y qahera-ui mcp

# Start local HTTP stream on port 3301
npx -y qahera-ui mcp --http --port=3301

2. Available AI Tools (7 Canonical Tools)

3. Automated Zero-Touch IDE Setup

npx qahera-ui setup-ide

4. Remote Web MCP Endpoint

https://alwkala.com/qahera/api/mcp.php

📚 Official GitHub Wiki & Knowledge Base

📊 System Health & Quality Scorecard

🏛️ QAHERA QUALITY ASSURANCE AUDIT (v1.7.0 Certified)
══════════════════════════════════════════════════════════════════════════════════════
  ✓ Schema & Invariants Validation : 100% Passed (49 Contracts · 49 Recipes · 21 Patterns · 47 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         : 238.06 KB Raw / 32.51 KB Gzip (Budget: <= 35 KB gzip)
  ✓ 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)
══════════════════════════════════════════════════════════════════════════════════════

🖼️ Visual Showcase & Architectural Paradigm

1. The Multi-Target Architecture Pipeline

                                  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

2. The Code-Level Difference: Raw AI UI vs. Qahera Canonical Contract

<!-- ❌ 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 -->

🏛️ The 45 Canonical Components (v1.5 Scope)

🧩 The 21 Compositional UX Patterns

🏙️ The 12 Cairo Atlas Neighborhood Themes

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

🚀 Quick Start & Distribution Channels

1. Zero-Install CLI Scaffolder via npx (shadcn-style)

# 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

Tip

Zero-Touch IDE Configuration: Running npx qahera-ui init automatically creates .vscode/settings.json and .vscode/extensions.json, copies qahera.css-data.json and qahera.html-data.json, and embeds .agents/skills/qahera-ui directly into your workspace. Coding agents in Google Antigravity, Cursor, or Claude Code immediately gain full bilingual autocomplete, hover docs, and screen composition capabilities via /qahera-ui.

AI Coding Agent Commands (/qahera-ui)

2. Zero-Build Global CDN Quickstart (jsDelivr & unpkg)

The 3 Architectural CSS Layers

Tip

Version Pinning vs. Rolling Updates: Pin to @1.6.0 for guaranteed production stability, or use @latest to automatically receive non-breaking patch updates.

Ready-to-Run HTML5 Production Boilerplate

<!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>

3. PHP 8.x Plates Engine (Composer & Packagist)

composer require alwkala/qahera-ui

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>'
]);

4. React 19 & Next.js Server Components (RSC)

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>
  );
}

5. Vanilla Web Components

<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>

6. VS Code, Cursor & Antigravity CSS & HTML Custom Data Autocomplete

// 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
  }
}

What You Get in Your IDE:

npx qahera-ui build:ide-data

📖 Authoritative Specifications & Documentation Links

🛡️ The 17 Non-Negotiable Architectural Invariants

🗺️ Roadmap

🇸🇦 نظرة عامة وميثاق المنظومة باللغة العربية

🤝 Contributing & Community Health

📞 Contact & Official Links

📜 License