# ๐๏ธ 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.
[](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)](#system-health-quality-scorecard)
[-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)](#system-health-quality-scorecard)
[](#system-health-quality-scorecard)
[-DC2626.svg?style=for-the-badge)](#the-17-non-negotiable-architectural-invariants)
[](#the-12-cairo-atlas-neighborhood-themes)
**[ ๐ Living Showcase Hub ](examples/previews/index.html) โข [ ๐๏ธ The 45 Components ](#the-45-canonical-components-v15-scope) โข [ ๐งฉ 21 UX Patterns ](#the-21-compositional-ux-patterns) โข [ ๐๏ธ Cairo Atlas (12 Themes) ](#the-12-cairo-atlas-neighborhood-themes) โข [ ๐ Quick Start ](#quick-start-distribution-channels) โข [ ๐บ๏ธ Roadmap ](#roadmap) โข [ ๐ ุจุงูุนุฑุจูุฉ (README.ar.md) ](README.ar.md)**
---
## ๐ Table of Contents
- [๐ฏ Why Qahera UI Kit?](#why-qahera-ui-kit)
- [๐ System Health & Quality Scorecard](#system-health-quality-scorecard)
- [๐ผ๏ธ Visual Showcase & Architectural Paradigm](#visual-showcase-architectural-paradigm)
- [๐๏ธ The 45 Canonical Components (v1.5 Scope)](#the-45-canonical-components-v15-scope)
- [๐งฉ The 21 Compositional UX Patterns](#the-21-compositional-ux-patterns)
- [๐๏ธ The 12 Cairo Atlas Neighborhood Themes](#the-12-cairo-atlas-neighborhood-themes)
- [๐ Quick Start & Distribution Channels](#quick-start-distribution-channels)
- [1. Zero-Install CLI Scaffolder via `npx` (shadcn-style)](#1-zero-install-cli-scaffolder-via-npx-shadcn-style)
- [2. Zero-Build Global CDN Quickstart (jsDelivr & unpkg)](#2-zero-build-global-cdn-quickstart-jsdelivr--unpkg)
- [3. PHP 8.x Plates Engine (Composer & Packagist)](#3-php-8x-plates-engine-composer--packagist)
- [4. React 19 & Next.js Server Components (RSC)](#4-react-19-nextjs-server-components-rsc)
- [5. Vanilla Web Components](#5-vanilla-web-components)
- [๐ Authoritative Specifications & Documentation Links](#authoritative-specifications-documentation-links)
- [๐ก๏ธ The 17 Non-Negotiable Architectural Invariants](#the-17-non-negotiable-architectural-invariants)
- [๐บ๏ธ Roadmap](#roadmap)
- [๐ธ๐ฆ ูุธุฑุฉ ุนุงู
ุฉ ูู
ูุซุงู ุงูู
ูุธูู
ุฉ ุจุงููุบุฉ ุงูุนุฑุจูุฉ (README.ar.md)](README.ar.md)
- [๐ค Contributing & Community Health](#contributing-community-health)
- [๐ Contact & Official Links](#contact-official-links)
- [๐ License](#license)
---
## ๐ฏ 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
```text
๐๏ธ 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:
```text
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
```html
```
```html
```
---
## ๐๏ธ 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`](contracts/components/Accordion.yaml) | Organizes deep information in vertically stacked collapsible panels. |
| 2 | **Alert** | `feedback` | [`Alert.yaml`](contracts/components/Alert.yaml) | Displays prominent contextual feedback messages directly within layouts. |
| 3 | **Avatar** | `media` | [`Avatar.yaml`](contracts/components/Avatar.yaml) | Visual representation of a user, team, or brand entity with status dot. |
| 4 | **BackToTop** | `navigation` | [`BackToTop.yaml`](contracts/components/BackToTop.yaml) | Floating action button monitoring scroll depth to restore viewport top. |
| 5 | **Badge** | `feedback` | [`Badge.yaml`](contracts/components/Badge.yaml) | Compact metadata tags, categorical status pills, and quantitative counters. |
| 6 | **Breadcrumb** | `navigation` | [`Breadcrumb.yaml`](contracts/components/Breadcrumb.yaml) | Hierarchical navigation trail exposing current page depth. |
| 7 | **Button** | `actions` | [`Button.yaml`](contracts/components/Button.yaml) | Interactive triggers with 6 variants (`primary` $\to$ `destructive`) and 5 sizes. |
| 8 | **Callout** | `feedback` | [`Callout.yaml`](contracts/components/Callout.yaml) | Editorial quotes, architectural insights, and elevated callout blocks. |
| 9 | **CanvasSparks** | `media` | [`CanvasSparks.yaml`](contracts/components/CanvasSparks.yaml) | Atmospheric canvas VFX emitting ambient decorative particle sparks. |
| 10 | **Card** | `containers` | [`Card.yaml`](contracts/components/Card.yaml) | Content surfaces with header, body, footer, and elevated depth states. |
| 11 | **Carousel** | `media` | [`Carousel.yaml`](contracts/components/Carousel.yaml) | Touch-friendly media slider with responsive pagination and navigation controls. |
| 12 | **Checkbox** | `forms` | [`Checkbox.yaml`](contracts/components/Checkbox.yaml) | Accessible multi-selection control with custom checkmark and indeterminate state. |
| 13 | **Chip** | `forms` | [`Chip.yaml`](contracts/components/Chip.yaml) | Removable filter tags and compact multi-selection chips. |
| 14 | **Divider** | `layout` | [`Divider.yaml`](contracts/components/Divider.yaml) | Visual separator delineating content blocks with optional center label. |
| 15 | **Dock** | `navigation` | [`Dock.yaml`](contracts/components/Dock.yaml) | Thumb-accessible mobile navigation bar for primary destination shortcuts. |
| 16 | **Drawer** | `overlay` | [`Drawer.yaml`](contracts/components/Drawer.yaml) | Offcanvas sliding side panel for secondary actions, filters, and navigation. |
| 17 | **Dropdown** | `navigation` | [`Dropdown.yaml`](contracts/components/Dropdown.yaml) | Floating action menu revealing contextual operations or links. |
| 18 | **FileUpload** | `forms` | [`FileUpload.yaml`](contracts/components/FileUpload.yaml) | Drag-and-drop file ingestion zone with progress and validation states. |
| 19 | **Input** | `forms` | [`Input.yaml`](contracts/components/Input.yaml) | Single-line textual input with leading/trailing icons and validation states. |
| 20 | **Kbd** | `data-display`| [`Kbd.yaml`](contracts/components/Kbd.yaml) | System keyboard shortcuts and hotkey indicator tags. |
| 21 | **Megamenu** | `navigation` | [`Megamenu.yaml`](contracts/components/Megamenu.yaml) | Rich multi-column navigation surface for large portals and catalogs. |
| 22 | **Menu** | `navigation` | [`Menu.yaml`](contracts/components/Menu.yaml) | Vertical link list for sidebars, cards, and navigation panels. |
| 23 | **Modal** | `overlay` | [`Modal.yaml`](contracts/components/Modal.yaml) | Focus-trapped dialog overlay for critical user confirmation workflows. |
| 24 | **Navbar** | `navigation` | [`Navbar.yaml`](contracts/components/Navbar.yaml) | Site header hosting brand identity, primary links, and responsive drawer. |
| 25 | **Pagination** | `navigation` | [`Pagination.yaml`](contracts/components/Pagination.yaml) | Multi-page boundary control with numeric links and page size picker. |
| 26 | **Preloader** | `feedback` | [`Preloader.yaml`](contracts/components/Preloader.yaml) | Atmospheric boot loader with animated progress bar and percentage display. |
| 27 | **Progress** | `feedback` | [`Progress.yaml`](contracts/components/Progress.yaml) | Metric status bar supporting determinate and indeterminate animations. |
| 28 | **Radio** | `forms` | [`Radio.yaml`](contracts/components/Radio.yaml) | Mutually exclusive radio option groups with accessible labels. |
| 29 | **Rating** | `feedback` | [`Rating.yaml`](contracts/components/Rating.yaml) | Interactive star rating component with read-only and editable modes. |
| 30 | **Ribbon** | `data-display`| [`Ribbon.yaml`](contracts/components/Ribbon.yaml) | Corner status badge pinned to card and container perimeters. |
| 31 | **Select** | `forms` | [`Select.yaml`](contracts/components/Select.yaml) | Native and styled dropdown selection input with option grouping. |
| 32 | **Skeleton** | `feedback` | [`Skeleton.yaml`](contracts/components/Skeleton.yaml) | Loading silhouette placeholder mimicking component dimensions during fetch. |
| 33 | **Spinner** | `feedback` | [`Spinner.yaml`](contracts/components/Spinner.yaml) | Pure CSS indeterminate micro-loader with semantic tone overrides. |
| 34 | **Stepper** | `navigation` | [`Stepper.yaml`](contracts/components/Stepper.yaml) | Step-by-step progress indicator for multi-stage onboarding and checkout. |
| 35 | **Switch** | `forms` | [`Switch.yaml`](contracts/components/Switch.yaml) | Binary toggle switch with smooth spring transitions and accessible ARIA. |
| 36 | **Table** | `data-display`| [`Table.yaml`](contracts/components/Table.yaml) | Structured data table supporting striped rows, bordered cells, and sticky headers. |
| 37 | **Tabs** | `navigation` | [`Tabs.yaml`](contracts/components/Tabs.yaml) | Accessible tabbed navigation with keyboard arrow navigation in LTR and RTL. |
| 38 | **Textarea** | `forms` | [`Textarea.yaml`](contracts/components/Textarea.yaml) | Multi-line text input with character counting and auto-resizing. |
| 39 | **Timeline** | `data-display`| [`Timeline.yaml`](contracts/components/Timeline.yaml) | Chronological activity feed and milestone log with semantic node icons. |
| 40 | **Toast** | `feedback` | [`Toast.yaml`](contracts/components/Toast.yaml) | Floating ephemeral notification stack with auto-dismiss timers. |
| 41 | **Tooltip** | `overlay` | [`Tooltip.yaml`](contracts/components/Tooltip.yaml) | Contextual hover/focus micro-balloon with 4-directional placement. |
| 42 | **Treeview** | `navigation` | [`Treeview.yaml`](contracts/components/Treeview.yaml) | Hierarchical nested folder and category explorer with expand/collapse. |
| 43 | **Cartouche** | `heritage` | [`cartouche.yaml`](contracts/components/cartouche.yaml) | Egyptian royal cartouche framing motif with hieroglyphic glyph enclosure. |
| 44 | **Frieze** | `heritage` | [`frieze.yaml`](contracts/components/frieze.yaml) | Architectural heritage frieze band with repetitive geometric or lotus border motifs. |
| 45 | **Seal** | `heritage` | [`seal.yaml`](contracts/components/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:
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.
---
## ๐๏ธ 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
```
---
## ๐ 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:
```bash
# 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/qahera-ui@1.5.5/dist/qahera-tokens.min.css` | `https://unpkg.com/qahera-ui@1.5.5/dist/qahera-tokens.min.css` | Global primitives (color scales, typography, spacing, elevations). |
| **Cairo 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 authentic Cairo neighborhood themes (`[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` | 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`):
```html
Qahera CDN Quickstart
CDN Quickstart v1.5.5
ู
ูุธูู
ุฉ ูุงูุฑุฉ ุนุจุฑ ุดุจูุฉ ุงูุชูุฒูุน ุงูุณุฑูุนุฉ
ุชุฌุฑุจุฉ ููุฑูุฉ ุชุนู
ู ุจู 0kb ุฃุฏูุงุช ุจูุงุก ุฃู ุชุฌู
ูุน. ูู
ููู ุงูุชุจุฏูู ุจูู ุงููุบุงุช ูุงูุงุชุฌุงูุงุช (dir="rtl" / dir="ltr") ูุงูุณู
ุงุช ุงูู
ุนู
ุงุฑูุฉ ุงูู 12 (data-theme="zamalek") ุจุณูุงุณุฉ ุชุงู
ุฉ.
```
### 3. PHP 8.x Plates Engine (Composer & Packagist)
Install via Composer into your PHP project:
```bash
composer require alwkala/qahera-ui
```
Register the official Qahera extension with your Plates engine instance:
```php
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' => 'ุชูุงุตูู ุงููุงุชูุฑุฉ ุงูู
ุนู
ุงุฑูุฉ...
'
]);
```
### 4. React 19 & Next.js Server Components (RSC)
Preserve a 0kb client JavaScript footprint using pure Server Components:
```tsx
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 (
);
}
```
### 5. Vanilla Web Components
Import the autonomous bundle to self-register all 42 Custom Elements:
```html
ุฅุฌุฑุงุก ู
ุนูุงุฑู
ูุดุท ุงูุขู
```
### 6. VS Code, Cursor & Antigravity CSS & HTML Custom Data Autocomplete
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 (``) and global attributes (`data-theme`, `data-mode`, `dir`) with full Cairo neighborhood themes and ARIA validation.
```json
// 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 ``, ``, 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:
```bash
npx qahera-ui build:ide-data
```
---
## ๐ Authoritative Specifications & Documentation Links
Qahera UI Kit is governed by its normative specification suite in [`docs/`](docs/):
| Specification Document | Focus Area & Normative Scope | Key Standard |
|---|---|---|
| **[00-BRAND-POSITIONING.md](docs/00-BRAND-POSITIONING.md)** | Studio Identity, Egyptian Cultural Lineage & Sovereignty | Alwkala Manifesto |
| **[01-TOKEN-SPEC.md](docs/01-TOKEN-SPEC.md)** | 3-Tier W3C Token Taxonomy (`--qhr-*`), Colors & Spacing | W3C DTCG Format |
| **[02-COMPONENT-SPEC.md](docs/02-COMPONENT-SPEC.md)** | Component Contract Anatomy, Slots, Props & AI Metadata | YAML Schema Validation |
| **[03-RECIPE-SPEC.md](docs/03-RECIPE-SPEC.md)** | CSS State Binding, Token Mapping & Selector Rules | Atomic Scoped CSS |
| **[04-BEHAVIOR-SPEC.md](docs/04-BEHAVIOR-SPEC.md)** | Alpine.js Hydration & Zero-Dependency Logic | `QAHERA-ALPINE-001` |
| **[05-RENDERER-SPEC.md](docs/05-RENDERER-SPEC.md)** | Multi-Target Compilation (React, PHP, HTML, HTMX, JS) | 100% Semantic Parity |
| **[06-AI-SPEC.md](docs/06-AI-SPEC.md)** | 4-Tier Progressive AI Context Discovery Protocol | Token Efficiency |
| **[07-ACCESSIBILITY-SPEC.md](docs/07-ACCESSIBILITY-SPEC.md)** | WCAG 2.1 AA Compliance, ARIA Roles & Contrast Tests | Contrast $\ge 4.5:1$ |
| **[08-RTL-SPEC.md](docs/08-RTL-SPEC.md)** | Native Logical CSS Invariants & Arabic Typography | Logical Properties Only |
| **[09-CLI-SPEC.md](docs/09-CLI-SPEC.md)** | CLI Engine Architecture (`qahera add / init / list`) | Source Code Ownership |
| **[10-MCP-SPEC.md](docs/10-MCP-SPEC.md)** | Model Context Protocol Tools for Autonomous AI Agents | JSON-RPC Stdio 2.0 |
| **[11-GOVERNANCE.md](docs/11-GOVERNANCE.md)** | Quality Assurance Bar, Testing Gates & Review Policies | Definition of Done |
| **[12-CONTRIBUTING.md](docs/12-CONTRIBUTING.md)** | Local Development Setup, PR Checklists & Standards | Zero Defect Policy |
| **[STATUS.md](docs/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`](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 `` 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.
---
## ๐บ๏ธ 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:
1. Review the **[Contributing Guidelines (CONTRIBUTING.md)](CONTRIBUTING.md)** and **[Architectural Invariants (AGENTS.md)](AGENTS.md)**.
2. Read the **[Contributor Covenant Code of Conduct (CODE_OF_CONDUCT.md)](CODE_OF_CONDUCT.md)**.
3. Review our **[Security Policy & Vulnerability Reporting (SECURITY.md)](SECURITY.md)**.
4. Ensure all local quality audits pass cleanly:
```bash
npm run typecheck && node bin/qahera.js test
```
---
## ๐ Contact & Official Links
* **Studio & Architecture Owner:** [Alwkala](https://github.com/alwkala)
* **Technical Support & Inquiries:** [alwkala@outlook.com](mailto:alwkala@outlook.com)
* **Repository & Source:** [github.com/alwkala/Qahera-UI-Kit](https://github.com/alwkala/Qahera-UI-Kit)
* **Official Releases:** [GitHub Releases](https://github.com/alwkala/Qahera-UI-Kit/releases)
* **Issue Tracker:** [GitHub Issues](https://github.com/alwkala/Qahera-UI-Kit/issues)
---
## ๐ License
Distributed under the **[MIT License](LICENSE)**. ยฉ 2026 Alwkala. All rights reserved.