+
+**صُنعت بكل فخر واعتزاز بواسطة فريق TidyFactor الأساسي ووكالة الوكالة الرقمية (Alwkala).**
+*تمكين وكلاء البرمجة بالذكاء الاصطناعي من التصميم بدقة وذوق رفيع وصفر رداءة.*
-- **الترخيص**: Apache-2.0. مفتوح المصدر ومجاني للاستخدام الشخصي والتجاري.
-- **الحوكمة**: تخضع المهارة بالكامل لـ **القواعد الهيكلية الـ 15** لمنظومة مهارات تايدي فاكتور.
-- **المنظومة**: جزء من **منظومة TidyFactor** ([tidyfactor.com](https://tidyfactor.com)) برعاية وتطوير **الوكالة (Alwkala)** ([alwkala.com](https://alwkala.com)).
+
diff --git a/README.de.md b/README.de.md
index 19fc157..5c3ef2f 100644
--- a/README.de.md
+++ b/README.de.md
@@ -4,8 +4,14 @@
**Code-Native UI-Design-Lifecycle-Engine und Anti-Slop Designsystem-Suite für KI-Agenten**
-[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://github.com/TidyFactor/Design/stargazers)
[](LICENSE)
+[](https://github.com/TidyFactor)
+[](SKILL.md)
+[](README.ar.md)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
+[](SKILL.md)
[ English ](README.md) • [ العربية ](README.ar.md) • [ فارسی ](README.fa.md) • [ Español ](README.es.md) • [ Português ](README.pt.md) • [ 简体中文 ](README.zh.md) • [ Deutsch ](README.de.md) • [ Français ](README.fr.md)
diff --git a/README.es.md b/README.es.md
index bdf0bcc..3791f72 100644
--- a/README.es.md
+++ b/README.es.md
@@ -4,8 +4,14 @@
**Motor de Ciclo de Vida de Diseño UI Nativo en Código y Suite de Diseño Anti-Slop para Agentes de IA**
-[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://github.com/TidyFactor/Design/stargazers)
[](LICENSE)
+[](https://github.com/TidyFactor)
+[](SKILL.md)
+[](README.ar.md)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
+[](SKILL.md)
[ English ](README.md) • [ العربية ](README.ar.md) • [ فارسی ](README.fa.md) • [ Español ](README.es.md) • [ Português ](README.pt.md) • [ 简体中文 ](README.zh.md) • [ Deutsch ](README.de.md) • [ Français ](README.fr.md)
diff --git a/README.fa.md b/README.fa.md
index a9ef20f..1bc719e 100644
--- a/README.fa.md
+++ b/README.fa.md
@@ -9,8 +9,14 @@
**پایگاه رسمی مهندسی سیستم طراحی و نمونهسازی تعاملی مبتنی بر کد در اکوسیستم TidyFactor.**
-[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://github.com/TidyFactor/Design/stargazers)
[](LICENSE)
+[](https://github.com/TidyFactor)
+[](SKILL.md)
+[](README.ar.md)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
+[](SKILL.md)
[](README.fa.md)
[](#-دروازه-کیفیت-مکانیکی-و-پاد-کلیشه)
diff --git a/README.fr.md b/README.fr.md
index 82466c9..b737f1d 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -4,8 +4,14 @@
**Moteur de Cycle de Vie de Design UI Natif en Code et Suite de Systèmes de Design Anti-Slop pour Agents IA**
-[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://www.npmjs.com/package/@tidyfactor/design)
+[](https://github.com/TidyFactor/Design/stargazers)
[](LICENSE)
+[](https://github.com/TidyFactor)
+[](SKILL.md)
+[](README.ar.md)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
+[](SKILL.md)
[ English ](README.md) • [ العربية ](README.ar.md) • [ فارسی ](README.fa.md) • [ Español ](README.es.md) • [ Português ](README.pt.md) • [ 简体中文 ](README.zh.md) • [ Deutsch ](README.de.md) • [ Français ](README.fr.md)
diff --git a/README.md b/README.md
index 22dbb10..21da065 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,78 @@
-
+ +
---
+## 📚 Table of Contents
+
+- [🎯 Why TidyFactor/Design — The Code-Native Alternative to Figma](#-why-tidyfactordesign--the-code-native-alternative-to-figma)
+- [🏛️ The Core Breakthrough: Design Intelligence vs. Execution](#%EF%B8%8F-the-core-breakthrough-design-intelligence-vs-execution)
+- [🚀 Quick Start](#-quick-start)
+- [🧭 Dual-Mode Decision Architecture (DM-DA Protocol)](#-dual-mode-decision-architecture-dm-da-protocol)
+- [🔄 The 7 UI Design Lifecycle Stages](#-the-7-ui-design-lifecycle-stages)
+- [⚡ The 24-Command Registry](#-the-24-command-registry)
+- [🧠 Operational Memory — Rules, Matrices & Zero Invention](#-operational-memory--rules-matrices--zero-invention)
+- [🧩 Production Component Library (Volume 01 – Volume 03)](#-production-component-library-volume-01--volume-03)
+- [🛡️ Anti-Slop Governance & Mechanical Quality Gate](#%EF%B8%8F-anti-slop-governance--mechanical-quality-gate)
+- [🇸🇦 Native Arabic & Surgical RTL Engineering](#-native-arabic--surgical-rtl-engineering)
+- [⚡ Token Efficiency & YAML Primacy (Rule 15)](#-token-efficiency--yaml-primacy-rule-15)
+- [🏛️ The 15 Structural Rules & Compliance Scorecard](#%EF%B8%8F-the-15-structural-rules--compliance-scorecard)
+- [❓ FAQ](#-faq)
+- [🤝 Contributing & Community](#-contributing--community)
+- [📜 License](#-license)
+
+---
+
+## 🎯 Why TidyFactor/Design — The Code-Native Alternative to Figma
+
+> [!IMPORTANT]
+> **The Design Slop Epidemic in AI Coding**
+> When you ask a generic AI model to *"create a modern SaaS landing page"*, it produces a bland statistical average: repetitive purple-gradient heroes, unreadable Inter typography everywhere, arbitrary 3-column cards with card-in-card nesting, and fragmented CSS.
+> **TidyFactor Design is the architectural cure:** It transforms the expertise of a senior UI/UX designer and design engineer into an **executable operating system** for AI coding agents.
+
+### Figma vs. TidyFactor Design: A Fundamental Paradigm Shift
+
+TidyFactor Design does not try to be a vector drawing tool on a 2D canvas. It is **the Code-Native Design Workflow** built specifically for developers, design engineers, and AI coding agents:
+
+| Dimension | Traditional Figma Workflow | TidyFactor Design (Code-Native Engine) |
+|---|---|---|
+| **Core Paradigm** | Visual graphic canvas | **Code-native design engineering workflow** |
+| **Workspace** | Canvas-centric vector drawings | **Code-centric semantic HTML5 / CSS3 / Vanilla JS** |
+| **Primary Actors** | Visual designer $\to$ Developer handoff | **AI Coding Agent + Developer + Design Engineer unified** |
+| **Atomic Units** | Proprietary canvas components & variables | **Design tokens (`brand.yaml`) + component matrices + workflows** |
+| **Prototyping** | Static screen transition linkers | **Real, responsive, zero-build HTML/CSS/JS runtime in the browser** |
+| **Handoff Friction** | High friction: redlining, pixel drift, re-coding | **Zero Handoff Drift**: The design *is* the production code |
+| **Governance & QA** | Subjective human visual inspection | **Mechanical Quality Gates**: Automated 7-axis AST audits (`validate_skill.py`) |
+| **Scope** | UI asset drawing | **End-to-end 7-stage design lifecycle management** |
+
+---
+
## 🏛️ The Core Breakthrough: Design Intelligence vs. Execution
-The foundational innovation of **TidyFactor Design** is the strict architectural separation of **Design Knowledge** from **Design Implementation**:
+The most powerful innovation of **TidyFactor Design** is the strict architectural separation of **Design Intelligence** from **Design Implementation**:
```
DESIGN INTELLIGENCE
@@ -31,12 +80,12 @@ The foundational innovation of **TidyFactor Design** is the strict architectural
┌──────────┴──────────┐
↓ ↓
Operational Memory Workflows
- (Rules, Matrices, CDL) (Ordered Steps)
+ (Rules, Matrices, Schemas) (Ordered Steps & Checklists)
│ │
└──────────┬──────────┘
↓
- AI Coding Agent
- (Antigravity / Claude / Cursor)
+ AI Coding Agent
+ (Antigravity / Claude / Cursor)
↓
Design System SSOT
(brand.yaml + tokens.css)
@@ -45,57 +94,92 @@ The foundational innovation of **TidyFactor Design** is the strict architectural
(Zero per-page CSS/JS)
↓
Mechanical Audit Gate
- (7-Axis Stamp + AI Tells)
+ (7-Axis Stamp + Anti-Slop)
↓
- Production Handoff
- (Clean CSS Tokens + Specs)
+ Production Delivery
+ (Clean CSS Tokens + Handoff)
```
-### Why it is a *Design Engineering Operating System*, not just a Prompt
-When you ask an AI model to *"create a landing page"*, it attempts to simultaneously invent visual philosophy, layout, color theory, component hierarchy, responsive behavior, and implementation code in a single unconstrained prompt. The result is almost invariably **generic AI slop**: repetitive purple-gradient heroes, un-anchored CTAs, card-in-card nesting, and fragmented CSS.
+### Why This Makes the Skill Reusable Across Every Project
+Because design knowledge is codified into **Operational Memory** (rules, matrices, typography pairings, motion physics) and separated from the code generation workflows, the AI agent **never guesses or re-invents visual engineering rules**. It executes against a shared, verified Single Source of Truth.
-**TidyFactor Design** replaces arbitrary prompt generation with a **Deterministic Design Engineering Pipeline**:
-
-$$\text{Traditional AI Prompting: } \text{Prompt} \longrightarrow \text{AI generates generic UI}$$
-$$\text{TidyFactor Design Engine: } \text{Design Brief} \longrightarrow \text{Rules} \longrightarrow \text{System} \longrightarrow \text{Code} \longrightarrow \text{Validation} \longrightarrow \text{Handoff}$$
+$$\text{Traditional Prompting: } \text{Prompt} \longrightarrow \text{AI generates generic, drifted UI}$$
+$$\text{TidyFactor Design: } \text{Design Brief} \longrightarrow \text{Rules} \longrightarrow \text{System} \longrightarrow \text{Code} \longrightarrow \text{Validation} \longrightarrow \text{Handoff}$$
---
-## ⚡ The Definitive Comparison: Figma vs. TidyFactor Design
+## 🚀 Quick Start
-TidyFactor Design is **the Code-Native Alternative to Figma** for the AI coding agent era:
+### 1. Installation via NPM / NPX
+Install the skill into your local project workspace:
+```bash
+# Add to current workspace
+npx @tidyfactor/design add
-| Dimension | Figma | TidyFactor Design |
-|---|---|---|
-| **Primary Environment** | Visual Canvas GUI | Code-Native Live Browser Workspace |
-| **Architectural Focus** | Canvas-centric vector drawings | Code-centric semantic HTML5 / CSS3 / Vanilla JS |
-| **Target User** | Human UI/UX Designer | AI Agent + Developer + Design Engineer |
-| **Component Model** | Proprietary frames & canvas variants | CSS Custom Properties + 8-State Component Wrappers |
-| **Prototyping** | Click-through screen transitions | Fully interactive, responsive HTML/CSS/JS runtime |
-| **Handoff Friction** | Redundant redlining & re-implementation in code | **Zero Handoff Drift**: Design *is* the production code |
-| **Governance & QA** | Manual design review & subjective inspection | **Mechanical Quality Gates**: Automated 7-axis audit scripts |
-| **System Scope** | Asset creation | Full 7-Stage UI Design Lifecycle Management |
+# Or run the global CLI runner
+npx @tidyfactor/cli add tidyfactor-design
+```
+
+### 2. Invocable in All Major AI Coding Agents
+Invoke directly inside **Google Antigravity, Claude Code, Cursor, Codex, or Windsurf**:
+```text
+/tidyfactor-design
+```
+Or run individual lifecycle commands:
+```text
+/brief # Establish design context (Mode A: 3-round fast track, or Mode B: debate)
+/tokens # Generate CSS tokens and brand variables
+/components # Assemble 8-state interactive components
+/page # Compose a complete, token-disciplined page
+/audit # Audit against the 16 AI tells and 7-axis quality stamp
+```
---
-## 🧠 The Concept of "Operational Memory"
+## 🧭 Dual-Mode Decision Architecture (DM-DA Protocol)
-In TidyFactor, `references/memory/` files are **NOT** narrative articles or marketing essays. They are **executable engineering constraints**, tabular decision matrices, and authoritative schemas:
+TidyFactor Design incorporates **The Contextual Decision Layer (CDL v2.0)**, operating under the formal role of **TidyFactor Dual-Mode Decision Architect (DM-DA)**:
-- **Typography Matrix (`12-typography-matrix.md`)**: Exact mood-routed Arabic/Latin font pairings with ratio scales.
-- **Layout Archetypes (`13-layout-archetypes.md`)**: L1–L4 structural macrostructures with explicit container grids.
-- **Motion Principles (`04-motion-principles.md`)**: Exact cubic-bezier easing curves and reduced-motion fallback contracts.
-- **Core Component Matrices (`21-` through `28-`)**: Exhaustive catalogs of Eyebrows, Heros, Cards, 8-State Buttons, Section Dividers, Tabular Metrics, and Trust Bullets.
-- **Quality Bar (`06-quality-bar.md`)**: The 16 named AI anti-pattern tells and 11 Codex defect bans with automated audit thresholds.
-- **Arabic / RTL Rigor (`08-arabic-bilingual.md`)**: Curated bidirectional rules (El Messiri display, Tajawal body, never Amiri >24px).
+```
+ USER INTENT
+ │
+ ┌─────────────┴─────────────┐
+ ↓ ↓
+ [MODE A] 🎯 [MODE B] 🔥
+ Smart 3-Round Protocol Relentless Debate & Interview
+ (Fast-Track Alignment) (Deep Ideological Extraction)
+ │ │
+ 3 Rounds Max Continuous Counter-Questions
+ │ Challenges Anti-Patterns
+ │ Forces Logical Trade-offs
+ ↓ │
+ Emit Brief / Cache │ Terminated by "END DEBATE"
+ │ ↓
+ └───────────┬───────────────┘
+ ↓
+ .tidyfactor/brief.md
+ Artifact: DEBATE_SYNTHESIS.md
+ ↓
+ Deterministic Code Emission
+```
-Because this operational memory is decoupled and injected on-demand, the AI agent **never re-invents visual engineering rules**; it executes against deterministic ground truth.
+### [MODE A] 🎯 Smart 3-Round Protocol (الارتجال الذكي المقيد)
+- **Round 1 (Root & Mission)**: Extract primary audience mindset (`inspire`, `evaluate`, `act`, `learn`) and product mission.
+- **Round 2 (Boundaries & Stack)**: Lock CSS engine (`native`, `tailwind`, `daisyui`, `pico`, `hybrid`), page archetype (`L1`–`L4`), and typography pairing.
+- **Round 3 (Final Conflicts & Safe Defaults)**: Resolve edge trade-offs and auto-populate unasked parameters with safe defaults.
+- **Escalation Gate**: Emits `.tidyfactor/brief.md` instantly and presents the choice: *"Adopt baseline immediately OR escalate to Debate Mode?"*
+
+### [MODE B] 🔥 Relentless Debate & Interview (الاستجواب والمناظرة اللانهائية)
+- **Continuous Multi-Turn Interrogation**: Activated via `/debate`, `/grill-me`, or Mode A escalation.
+- **Relentlessly Challenges Assumptions**: Exposes anti-patterns, forces binary trade-offs, and tests RTL/motion fragility before any code is written.
+- **Strict Termination Rule**: Only ends when the user explicitly triggers `"END DEBATE"` or `"اعتماد"`.
+- **Deliverable**: Emits a formal `architectural_debate_synthesis.md` artifact.
---
-## 🔄 The 7 UI Design Lifecycle Stages & 24 Command Registry
+## 🔄 The 7 UI Design Lifecycle Stages
-The skill provides 24 specialized slash commands mapped across 7 rigorous lifecycle stages:
+The design engineering process is partitioned into 7 sequential stages:
```mermaid
graph LR
@@ -107,44 +191,71 @@ graph LR
S6 --> S7["7. Delivery"]
```
-| Lifecycle Stage | Slash Command | User Intent | What It Injects | Output / Deliverable |
+1. **Discovery**: Understand audience psychology, purpose, and visual DNA.
+2. **Foundation**: Establish color tokens, WCAG AAA contrast, typography pairings, and design school.
+3. **Architecture**: Select layout archetypes, navigation shells, footers, and page templates.
+4. **Components**: Author 8-state interactive UI primitives with flex pinning and strict component anatomy.
+5. **Motion**: Inject physics-based easing curves, GSAP ScrollTrigger seams, and reduced-motion guards.
+6. **Quality**: Execute mechanical 7-axis self-critique audits, performance budgeting, and anti-slop scans.
+7. **Delivery**: Export clean CSS variable maps, static zero-build prototypes, and developer handoff specs.
+
+---
+
+## ⚡ The 24-Command Registry
+
+| Lifecycle Stage | Slash Command | Purpose & User Intent | Injected Operational Memory | Primary Output |
|---|---|---|---|---|
-| **1. Discovery** | `/brief` | Strategic Design Discovery & Brief Resolution | `workflows/brief.md` + `memory/decision-points.md` + `memory/06-quality-bar.md` | `.tidyfactor/design-brief.snapshot.json` + `design-brief.md` |
-| **1. Discovery** | `/study` | Extract design DNA from reference URL/image | `commands/study.md` + `memory/01-design-schools.md` + `memory/06-quality-bar.md` | Structured visual DNA report |
-| **2. Foundation** | `/init` | Start brand-new design system / prototype | `workflows/init-prototype.md` + `memory/architecture.md` + `memory/foundations.md` | Scaffolded `design-system/` + semantic `index.html` |
-| **2. Foundation** | `/brand` | Scaffold or manage `brand.yaml` / `brand.json` | `commands/brand.md` + `memory/11-brand-json-v2.md` | Validated `brand.yaml` design token SSOT |
-| **2. Foundation** | `/typography` | Mood-routed typography pairing | `commands/typography.md` + `memory/12-typography-matrix.md` | Font tokens in `tokens.css` + Google Fonts preconnect |
-| **2. Foundation** | `/school` | Select design school & movement | `commands/school.md` + `memory/01-design-schools.md` | Visual school declaration locked in `brand.yaml` |
-| **2. Foundation** | `/tokens` | Manage design tokens and CSS variables | `commands/tokens.md` + `memory/02-design-tokens.md` | Synchronized `design-system/tokens.css` |
-| **2. Foundation** | `/palette` | Extract color palette & compute WCAG AAA | `commands/palette.md` + `scripts/extract_palette.py` | WCAG 2.1 AAA contrast tokens for light/dark modes |
-| **2. Foundation** | `/assets` | Asset hygiene, media & image optimization | `commands/assets.md` + `scripts/optimize_images.py` | Constrained WebP assets and transparent cutouts |
-| **3. Architecture** | `/layout` | Select macrostructure layout archetype | `commands/layout.md` + `memory/13-layout-archetypes.md` | L1–L4 responsive grid shell scaffolded |
-| **3. Architecture** | `/nav-footer` | Choose navigation (N1-N9) & footer (Ft1-Ft8) | `commands/nav-footer.md` + `memory/14-nav-footer-catalog.md` | Production nav and footer components wired |
-| **3. Architecture** | `/page` | Add content or marketing page | `workflows/init-prototype.md` + `memory/05-component-anatomy.md` | Markup-only `pages/
- 
-
+ +
+
+