qahera-ui

v1.5.5

Published

7 days ago

AI-Native, Contract-Driven Design System & Multi-Target Component Architecture by Alwkala

0High
0Medium
0Low

alwkala

qahera-ui qahera design-system ai-native shadcn components arabic-ui rtl alwkala

🏛️ Qahera UI Kit `v1.5.5`

The AI-Native, Contract-Driven Design System & Multi-Target Component Architecture

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 • 🏛️ The 45 Components • 🧩 21 UX Patterns • 🏙️ Cairo Atlas (12 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.5.2}} = \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.

| Dimension | Conventional UI Libraries (daisyUI / Bootstrap) | Raw AI LLM Codegen | Qahera UI Kit | |---|---|---|---| | Architectural Source | Hardcoded CSS / Framework classes | Arbitrary statistical guesswork | Deterministic YAML Contracts & Tokens | | Source Ownership | Heavy npm package runtime lock-in | Fragile inline Tailwind copy-paste | Full Source Ownership (shadcn-style qahera add) | | RTL & Arabic Parity | Secondary CSS hack or after-thought | Directional margin errors (mr-*, ml-*) | Core Infrastructure: 100% Logical CSS + Alexandria/Cairo fonts | | AI Agent Ergonomics | Must parse thousands of CSS classes | Inconsistent visual styles & emoji slop | 4-Tier Progressive AI Context (ai/components.yaml) | | Multi-Stack Parity | Single-framework locked (React or CSS) | Fragile porting between stacks | 100% Semantic Parity across 6 Targets (React, PHP, HTML, HTMX, JS) | | Visual Iconography | Inconsistent icon fonts or random SVGs | Arbitrary emojis (🗑️, 🚀, ✕) | Zero Emoji (QAHERA-VISUAL-001): 46 Semantic SVG Icons |

📊 System Health & Quality Scorecard

🏛️ 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.

🖼️ Visual Showcase & Architectural Paradigm

1. The Multi-Target Architecture Pipeline

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

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)

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

| # | Canonical Component | Category | Contract Definition | Primary Architectural Purpose | |---|---|---|---|---| | 1 | Accordion | disclosure | Accordion.yaml | Organizes deep information in vertically stacked collapsible panels. | | 2 | Alert | feedback | Alert.yaml | Displays prominent contextual feedback messages directly within layouts. | | 3 | Avatar | media | Avatar.yaml | Visual representation of a user, team, or brand entity with status dot. | | 4 | BackToTop | navigation | BackToTop.yaml | Floating action button monitoring scroll depth to restore viewport top. | | 5 | Badge | feedback | Badge.yaml | Compact metadata tags, categorical status pills, and quantitative counters. | | 6 | Breadcrumb | navigation | Breadcrumb.yaml | Hierarchical navigation trail exposing current page depth. | | 7 | Button | actions | Button.yaml | Interactive triggers with 6 variants (primary $\to$ destructive) and 5 sizes. | | 8 | Callout | feedback | Callout.yaml | Editorial quotes, architectural insights, and elevated callout blocks. | | 9 | CanvasSparks | media | CanvasSparks.yaml | Atmospheric canvas VFX emitting ambient decorative particle sparks. | | 10 | Card | containers | Card.yaml | Content surfaces with header, body, footer, and elevated depth states. | | 11 | Carousel | media | Carousel.yaml | Touch-friendly media slider with responsive pagination and navigation controls. | | 12 | Checkbox | forms | Checkbox.yaml | Accessible multi-selection control with custom checkmark and indeterminate state. | | 13 | Chip | forms | Chip.yaml | Removable filter tags and compact multi-selection chips. | | 14 | Divider | layout | Divider.yaml | Visual separator delineating content blocks with optional center label. | | 15 | Dock | navigation | Dock.yaml | Thumb-accessible mobile navigation bar for primary destination shortcuts. | | 16 | Drawer | overlay | Drawer.yaml | Offcanvas sliding side panel for secondary actions, filters, and navigation. | | 17 | Dropdown | navigation | Dropdown.yaml | Floating action menu revealing contextual operations or links. | | 18 | FileUpload | forms | FileUpload.yaml | Drag-and-drop file ingestion zone with progress and validation states. | | 19 | Input | forms | Input.yaml | Single-line textual input with leading/trailing icons and validation states. | | 20 | Kbd | data-display| Kbd.yaml | System keyboard shortcuts and hotkey indicator tags. | | 21 | Megamenu | navigation | Megamenu.yaml | Rich multi-column navigation surface for large portals and catalogs. | | 22 | Menu | navigation | Menu.yaml | Vertical link list for sidebars, cards, and navigation panels. | | 23 | Modal | overlay | Modal.yaml | Focus-trapped dialog overlay for critical user confirmation workflows. | | 24 | Navbar | navigation | Navbar.yaml | Site header hosting brand identity, primary links, and responsive drawer. | | 25 | Pagination | navigation | Pagination.yaml | Multi-page boundary control with numeric links and page size picker. | | 26 | Preloader | feedback | Preloader.yaml | Atmospheric boot loader with animated progress bar and percentage display. | | 27 | Progress | feedback | Progress.yaml | Metric status bar supporting determinate and indeterminate animations. | | 28 | Radio | forms | Radio.yaml | Mutually exclusive radio option groups with accessible labels. | | 29 | Rating | feedback | Rating.yaml | Interactive star rating component with read-only and editable modes. | | 30 | Ribbon | data-display| Ribbon.yaml | Corner status badge pinned to card and container perimeters. | | 31 | Select | forms | Select.yaml | Native and styled dropdown selection input with option grouping. | | 32 | Skeleton | feedback | Skeleton.yaml | Loading silhouette placeholder mimicking component dimensions during fetch. | | 33 | Spinner | feedback | Spinner.yaml | Pure CSS indeterminate micro-loader with semantic tone overrides. | | 34 | Stepper | navigation | Stepper.yaml | Step-by-step progress indicator for multi-stage onboarding and checkout. | | 35 | Switch | forms | Switch.yaml | Binary toggle switch with smooth spring transitions and accessible ARIA. | | 36 | Table | data-display| Table.yaml | Structured data table supporting striped rows, bordered cells, and sticky headers. | | 37 | Tabs | navigation | Tabs.yaml | Accessible tabbed navigation with keyboard arrow navigation in LTR and RTL. | | 38 | Textarea | forms | Textarea.yaml | Multi-line text input with character counting and auto-resizing. | | 39 | Timeline | data-display| Timeline.yaml | Chronological activity feed and milestone log with semantic node icons. | | 40 | Toast | feedback | Toast.yaml | Floating ephemeral notification stack with auto-dismiss timers. | | 41 | Tooltip | overlay | Tooltip.yaml | Contextual hover/focus micro-balloon with 4-directional placement. | | 42 | Treeview | navigation | Treeview.yaml | Hierarchical nested folder and category explorer with expand/collapse. | | 43 | Cartouche | heritage | cartouche.yaml | Egyptian royal cartouche framing motif with hieroglyphic glyph enclosure. | | 44 | Frieze | heritage | frieze.yaml | Architectural heritage frieze band with repetitive geometric or lotus border motifs. | | 45 | Seal | heritage | seal.yaml | Historic Egyptian official seal and medallion insignia with stamp emboss and radial text. |

🧩 The 21 Compositional UX Patterns

Higher-order compositional patterns constructed strictly from canonical primitives:

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

🏙️ The 12 Cairo Atlas Neighborhood Themes

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:

| Neighborhood Theme | Architectural Movement | Primary Light | Primary Dark | Radius Token | Key Visual Aesthetic | |---|---|---|---|---|---| | Garden City | Classical European Belle Époque | #1E3A8A | #3B82F6 | 12px (Medium) | Serene colonial calm, soft elevated shadows | | Zamalek | Neo-Classical & Island Opulence | #D4AF37 | #F59E0B | 10px (Classic) | Royal Champagne Gold, obsidian cards, refined depth | | Downtown | Khedivial Art Deco & Haussmann | #B45309 | #C29B38 | 0px (Sharp) | Razor-sharp architectural edges, high contrast brass | | Heliopolis | Heliopolis Style (Baron Empain) | #C2410C | #EA580C | 10px (Warm) | Warm terracotta, desert sandstone, arched rhythm | | Maadi | Garden Suburb & Biophilic | #15803D | #22C55E | 18px (Organic) | Lush green foliage, calm organic radii, soft surfaces | | Roxy | Mid-Century Commercial Modern | #7C3AED | #8B5CF6 | 10px (Modern) | Energetic retail contrast, vibrant modern violet | | Sakakini | Rococo Palace & Eclecticism | #BE185D | #F43F5E | 14px (Rococo) | Intricate neon reflections, stained glass accents | | El Hussein | Historic Fatimid Islamic Cairo | #991B1B | #DC2626 | 8px (Arabesque) | Deep madder red, antique gold, historic geometric dignity | | Shubra | Authentic Egyptian Neo-Brutalism | #374151 | #6B7280 | 0px (Brutalist) | High-contrast black outlines, hard offset block shadows | | El Zaytoun | Functionalist Modern Geometry | #0284C7 | #38BDF8 | 8px (Clean) | Classic azure, balanced geometric grids, utilitarian clarity | | El Marg | Nile Oasis & Date Palm Heritage | #047857 | #10B981 | 14px (Palm) | Verdant date palm greens, golden border rims | | New Cairo | Hyper-Modernist Glassmorphism | #06B6D4 | #22D3EE | 22px (Glass) | Frosted glass backdrop blur (22px), vibrant cyan halos |

Activate any theme seamlessly via HTML attributes:

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

🚀 Quick Start & Distribution Channels

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

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

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. 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`)

| Slash Command / Prompt | Engine Workflow | Description & Output | |---|---|---| | /qahera-ui compose [screen] | compose-screen.md | Composes complete production screens using exclusively canonical primitives and patterns. | | /qahera-ui pattern [name] | patterns-catalog.md | Scaffolds any of the 20 higher-order UX patterns (e.g. DataTableToolbar, ChatStream). | | /qahera-ui theme [neighborhood] | tokens/themes/*.yaml | Switches or previews any of the 12 Cairo Atlas themes (e.g. zamalek, downtown). | | /qahera-ui audit | audit-kit.md | Strictly audits markup and styles against all 17 Non-Negotiable Invariants. | | /qahera-ui scaffold [name] | author-component.md | Scaffolds new components through the contract-first pipeline across all 6 targets. |

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

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.

The 3 Architectural CSS Layers

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

| Asset Bundle | jsDelivr URL | unpkg URL | Purpose | |---|---|---|---| | Design Tokens | https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-tokens.min.css | https://unpkg.com/[email protected]/dist/qahera-tokens.min.css | Global primitives (color scales, typography, spacing, elevations). | | Cairo Themes | https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera-themes.min.css | https://unpkg.com/[email protected]/dist/qahera-themes.min.css | 12 authentic Cairo neighborhood themes ([data-theme="..."]). | | Components | https://cdn.jsdelivr.net/npm/[email protected]/dist/qahera.min.css | https://unpkg.com/[email protected]/dist/qahera.min.css | All 45 canonical atomic component styles (qhr-*). |

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

Ready-to-Run HTML5 Production Boilerplate

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/[email protected]/dist/qahera-tokens.min.css">

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

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

  <!-- Optional: Alpine.js for Interactive Components (Dropdown, Modal, Accordion) -->
  <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/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)

Install via Composer into your PHP project:

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)

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

5. Vanilla Web Components

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>

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

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

Smart CSS Token Map (qahera.css-data.json): Context-aware completion across all 325 canonical tokens with bilingual Markdown documentation cards.
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
  }
}

What You Get in Your IDE:

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

📖 Authoritative Specifications & Documentation Links

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

| Specification Document | Focus Area & Normative Scope | Key Standard | |---|---|---| | 00-BRAND-POSITIONING.md | Studio Identity, Egyptian Cultural Lineage & Sovereignty | Alwkala Manifesto | | 01-TOKEN-SPEC.md | 3-Tier W3C Token Taxonomy (--qhr-*), Colors & Spacing | W3C DTCG Format | | 02-COMPONENT-SPEC.md | Component Contract Anatomy, Slots, Props & AI Metadata | YAML Schema Validation | | 03-RECIPE-SPEC.md | CSS State Binding, Token Mapping & Selector Rules | Atomic Scoped CSS | | 04-BEHAVIOR-SPEC.md | Alpine.js Hydration & Zero-Dependency Logic | QAHERA-ALPINE-001 | | 05-RENDERER-SPEC.md | Multi-Target Compilation (React, PHP, HTML, HTMX, JS) | 100% Semantic Parity | | 06-AI-SPEC.md | 4-Tier Progressive AI Context Discovery Protocol | Token Efficiency | | 07-ACCESSIBILITY-SPEC.md | WCAG 2.1 AA Compliance, ARIA Roles & Contrast Tests | Contrast $\ge 4.5:1$ | | 08-RTL-SPEC.md | Native Logical CSS Invariants & Arabic Typography | Logical Properties Only | | 09-CLI-SPEC.md | CLI Engine Architecture (qahera add / init / list) | Source Code Ownership | | 10-MCP-SPEC.md | Model Context Protocol Tools for Autonomous AI Agents | JSON-RPC Stdio 2.0 | | 11-GOVERNANCE.md | Quality Assurance Bar, Testing Gates & Review Policies | Definition of Done | | 12-CONTRIBUTING.md | Local Development Setup, PR Checklists & Standards | Zero Defect Policy | | STATUS.md | System Health, Component Inventory & Test Coverage | Real-time Audit |

🛡️ The 17 Non-Negotiable Architectural Invariants

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

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

🗺️ Roadmap

| Version | Milestone Focus | Deliverables & Scope | Status | Release Date | |---|---|---|---|---| | v1.0.0 | Core Foundation & Contracts | 38 Contracts, 41 Icons, 3-Tier Tokens, Compiler Engine | Completed | 2026-08 | | v1.4.0 | Sovereign Cairo Studio | 12 Cairo Atlas Themes, Viewport Simulator, Radius Matrix | Completed | 2026-09 | | v1.5.0 | Universal Living Showcase v3.0 | 42 Components, 20 Patterns, 78-Item Hub, Level 5 OSS CI | Completed | 2026-09-07 | | v1.5.1 | Zero-Install CLI & AI Skill Engine | npx qahera-ui, NPM Launch, Dual-Bin Engine, Sovereign Skill | Completed | 2026-09-12 | | v1.5.2 | React Pattern Parity & Kit Hygiene | 21/21 React Patterns, AI Manifest 45 Components, Strict TypeScript Zero-Error | Completed | 2026-09-17 | | v1.5.3 | Packagist, CDN & Platform Sync | Official composer.json, CDN Quickstarts, NPM Arabic Parity, Universal State Sync | Completed | 2026-09-17 | | v1.5.4 | VS Code Custom Data & Studio UX | Official qahera.css-data.json, 325 Tokens Autocomplete, build:css-data CLI, Studio Polish | Completed | 2026-09-17 | | v1.5.5 | Smart HTML Custom Data, Zero-Touch IDE & CDN Boilerplate | qahera.html-data.json (45 Tags + 13 Themes), Zero-Touch IDE Setup in init, qahera cdn command, AI Skill v1.2.0 | Completed | 2026-09-17 | | v1.6.0 | Tokens Studio & Figma Sync | Bidirectional Figma Tokens sync, automated token pull | Planned | Q4 2026 | | v2.0.0 | Autonomous AI Agent Engine | MCP native server, headless prompt-to-production compiler | Roadmap | Q1 2027 |

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

منظومة قاهرة (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 مع حظر أي رموز تعبيرية في مكونات الواجهة لضمان الرصانة المؤسسية.

🤝 Contributing & Community Health

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

Review the Contributing Guidelines (CONTRIBUTING.md) and Architectural Invariants (AGENTS.md).
Read the Contributor Covenant Code of Conduct (CODE_OF_CONDUCT.md).
Review our Security Policy & Vulnerability Reporting (SECURITY.md).
Ensure all local quality audits pass cleanly:
```
npm run typecheck && node bin/qahera.js test
```

📞 Contact & Official Links

Studio & Architecture Owner: Alwkala
Technical Support & Inquiries: [email protected]
Repository & Source: github.com/alwkala/Qahera-UI-Kit
Official Releases: GitHub Releases
Issue Tracker: GitHub Issues