# Qahera UI Kit — Complete Architectural Manifest (/llms-full.txt)
> Authoritative Normative Specification, Component Contracts, and AI Decision Layer for LLM Inference & RAG Pipelines.
> Maintained by Alwkala (Egyptian / Regional Technology Studio).
> Version: 1.5.2 · Status: Active Production Canonical Pipeline

---

## 1. Executive Summary & Brand Identity
- **Name**: Qahera UI Kit (قاهرة)
- **Owner**: Alwkala (Cairo, Egypt)
- **Tagline**: Executable Design Language for the AI-Assisted Web
- **Core Formula**: Design System + Canonical Registry (86 items) + AI Decision Layer
- **Target Environments**: React 19 (Server Components), PHP 8.x (League/Plates Monolith), W3C Autonomous Web Components, Native Zero-Build HTML, and HTMX.

---

## 2. The 15 Non-Negotiable Invariants
1. **YAML is Authoritative**: YAML is the single source of truth for contracts, recipes, and tokens. JSON is machine-generated.
2. **Generated Files are Never Source of Truth**: Never edit `dist/` or `renderers/` directly to fix a design defect; update contracts/tokens and recompile.
3. **Tokens Precede Styling**: Hardcoded hex colors, arbitrary pixel dimensions, or ad-hoc margins are strictly forbidden; all styles map to `--qhr-*`.
4. **Contracts Precede Implementations**: Every component requires a YAML contract in `contracts/components/` before rendering.
5. **RTL as Infrastructure**: Strict RTL/LTR parity via 100% CSS Logical Properties (`margin-inline`, `padding-inline`, `inset-inline`).
6. **Arabic Typography Discipline**: Alexandria for headings & display (`--qhr-font-heading`), Cairo for body & labels (`--qhr-font-body`), JetBrains Mono for code. Amiri is strictly prohibited.
7. **Heritage Stays in Templates**: Cultural motifs belong downstream in templates and themes; core component contracts remain universal and neutral.
8. **Renderer Parity Zero Vocabulary Drift**: Identical prop names (`variant`, `size`, `tone`, `state`) across all 5 framework targets.
9. **Source Ownership over Runtime Lock-in**: Consuming projects copy and own component source code (shadcn-style).
10. **AI Metadata Requirement**: Every recipe exposes WHAT (purpose), WHEN (use cases), HOW (props/slots), and WHY NOT (anti-patterns).
11. **Zero Emoji Policy**: Emojis (🚀, 🏛️, ☀️, 🌙) are prohibited in UI components; iconography is 100% semantic SVGs from `icons/registry.yaml`.
12. **Modular CSS & RSC 0kb Boundary**: Zero client JavaScript for 32 pure Server Components; `'use client'` is reserved for 15 interactive leaves.
13. **Dogfooding & Canonical Composition**: All site pages, showcases, and templates are built 100% exclusively from canonical `qhr-*` components.
14. **Alpine.js Hydration Protocol**: Component stores declared via `Alpine.data()`; 100% globally unique `:key` attributes in `x-for`; no interactive element nesting.
15. **Thematic Topography & Cultural Coherence**: 12 Cairo neighborhood themes synthesize authentic Egyptian urban identity with global design movements.

---

## 3. Canonical Registry Catalog (86 Items)

### 45 Canonical Components
- **Actions**: Button (`qhr-btn`)
- **Forms & Selection**: Checkbox, Chip, FileUpload, Input, Radio, Select, Switch, Textarea
- **Containers & Layout**: Card, Cartouche (Egyptian royal pilliform frame), Divider
- **Data Display**: Badge, Breadcrumb, Frieze (Architectural relief band divider), Kbd, Ribbon, Table, Timeline
- **Disclosure & Navigation**: Accordion, BackToTop, Dock (Mobile bottom bar), Drawer, Dropdown, Megamenu, Menu, Navbar, Pagination, Stepper, Tabs, Treeview
- **Feedback & Status**: Alert, CanvasSparks, Preloader, Progress, Rating, Seal (Royal accreditation stamp), Skeleton, Spinner, Toast, Tooltip

### 21 Composite UX Patterns
1. `search-toolbar`: Search input, filters, sort dropdown, action buttons.
2. `confirmation`: High-consequence action modal dialog with destructive/secondary buttons.
3. `dashboard-stat`: Metric telemetry card with trend indicator and sparkline context.
4. `empty-state`: First-use / zero-data card with icon, title, copy, and primary action.
5. `filter-bar`: Multi-dimensional category chip bar with clear-all triggers.
6. `form-actions`: Fixed bottom or inline submission and cancellation action bar.
7. `pagination`: Multi-page numeric stepper with page size selector.
8. `data-table-toolbar`: Enterprise grid control with search, bulk actions, and export.
9. `luxury-product-card`: Commercial card with image showcase, badge, price, and cart CTA.
10. `editorial-story`: Monograph narrative container with lead header, cartouche, and metadata.
11. `store-locator`: Geolocation filter card with branch directory and interactive pin cards.
12. `vip-membership`: Loyalty tier status container with benefits checklist and upgrade CTA.
13. `chat-stream`: Conversational agent message history with AI thought disclosure.
14. `date-paginator`: Segmented calendar date horizon with quick day/week jumps.
15. `file-manager-grid`: Cloud asset browser with thumbnail grid, file tags, and quick actions.
16. `hero-skyline-panorama`: Cinematic Cairo architectural skyline header with telemetry badges.
17. `kanban-board`: Multi-lane operations board with task cards and stage columns.
18. `metric-comparison-grid`: Side-by-side KPI benchmark cards with delta progress bars.
19. `questionnaire`: Multi-step interactive survey wizard with radio options and progress bar.
20. `sortable-list`: Reorderable item list with drag handles and categorical badges.
21. `user-card`: Executive or team profile dossier card with avatar, role, and bio.

### 20 Production Application Templates
1. `flagship-portal`: Official platform showcase and design system hub.
2. `academic-executive`: Academic chair monograph dossier and completion archive.
3. `admin`: Enterprise resource manager with data grids and role-based permissions.
4. `dashboard`: Executive KPI telemetry, sparklines, and metric comparisons.
5. `auth`: Unified authentication center (login, register, two-factor, reset).
6. `ecommerce`: Luxury digital boutique with faceted filtering and flyout drawer.
7. `helpdesk-kanban`: Operations triage center with AI copilot stream and kanban lanes.
8. `fintech-wealth`: High-net-worth asset telemetry and portfolio risk distributions.
9. `education`: Digital academy LMS with curriculum chapters and progress tracking.
10. `file-manager`: Sovereign cloud file browser with multi-type asset inspectors.
11. `tables`: Multi-column data grid showcase with sorting, column toggle, and pagination.
12. `charts`: Data visualization dashboard with sparklines and metric benchmarks.
13. `box-cards`: Advanced container matrix and polymorphic card layouts.
14. `widgets`: Micro-telemetry glance cards and status monitors.
15. `layouts`: Grid structures, sidebar drawers, and multi-tier container layouts.
16. `shop`: Faceted retail catalog with live search and price range filters.
17. `landing`: Cinematic luxury brand landing page with interactive preloader.
18. `documentation`: Technical developer documentation portal with code tabs.
19. `emails`: Cross-client responsive transactional email templates.
20. `errors`: Resilient 404, 500, and offline network error states.

---

## 4. 12 Cairo Neighborhood Themes
1. `heliopolis`: Art Deco geometric elegance, terracotta tones, gold accents.
2. `downtown`: Khedivial Belle Époque European classicism, slate blue, warm brass.
3. `new-cairo`: Modernist hyper-clean minimalist, high-contrast, obsidian and pure glass.
4. `maadi`: Leafy garden tranquility, botanical eucalyptus green, organic textures.
5. `shubra`: High-density industrial vitality, warm copper, energetic burnt amber.
6. `zamalek`: Diplomatic colonial grandeur, Nile riverine teal, antique parchment.
7. `garden-city`: Curved street neo-classicism, soft marble ivory, dark bronze.
8. `dokki`: Academic/tech slate, cybernetic cyan accents, structured cobalt.
9. `mokattam`: Elevated cliffside panorama, limestone dusk, desert twilight violet.
10. `old-cairo`: Islamic architectural heritage, mashrabiya lattice geometry, deep lapis lazuli.
11. `nubia`: Vernacular earthen claymorphism, cobalt Nile, sun-drenched ochre.
12. `sinai`: Raw desert materiality, bedrock sandstone, deep starlight indigo.

---

## 5. Developer CLI Quickstart
```bash
# Add components directly into your project (shadcn-style)
npx qahera add button card modal --target=react
npx qahera add pattern:dashboard-stat --target=php
npx qahera add template:admin --target=react

# List all available canonical assets
node bin/qahera.js list

# Run strict multi-stage quality verification
node bin/qahera.js test
```