`memory/05-component-anatomy.md` | **صفحة تطبيق**: إنشاء هيكل لوحة تحكم أو تطبيق ويب مع بطاقات الإحصائيات وجداول البيانات. | - ---- - -### المرحلة 4: المكونات والتفاعل (Components & State Matrix) -*بناء فئات المكونات المشتركة ومعالجة جميع الحالات التفاعلية الـ 8.* - -| الأمر | صيغة الاستدعاء | الذاكرة المحملة | المخرجات والقيمة للمستخدم | -|---|---|---|---| -| **`/components`** | `/components` | `memory/05-component-anatomy.md`
`references/memory/architecture.md` | **مكتبة المكونات**: بناء الفئات المشتركة في `design-system/components.css` وإنشاء المعارض التفاعلية (`.preview.html`). | -| **`/states`** | `/states` | `memory/05-component-anatomy.md`
`memory/07-consistency-contract.md` | **مصفوفة الحالات**: تطبيق الحالات التفاعلية الـ 8 (الافتراضية، التمرير، النشطة، التركيز، المعطلة، التحميل، الخطأ، النجاح). | +| وجه المقارنة | فيجما (Figma) | تايدي فاكتور ديزاين (TidyFactor Design) | +|---|---|---| +| **بيئة العمل** | أداة تصميم مرئي ولوحات قماشية (Canvas GUI) | مساحة عمل برمجية حية تعمل مباشرة في المتصفح | +| **محور التركيز** | رسومات موجهة (Vector Graphics) | عناصر قياسية معتمدة على HTML5 / CSS3 / Vanilla JS | +| **المستخدم المستهدف** | مصمم الواجهات وتجربة المستخدم (UI/UX) | وكيل الذكاء الاصطناعي + المطور + مهندس التصميم | +| **نموذج المكونات** | إطارات ومتغيرات مرئية داخل ملفات التطبيق | متغيرات CSS وشاشات ومغلفات للمكونات بـ 8 حالات تفاعلية | +| **بناء النماذج الأولية** | محاكاة انتقالات ونقر بين الشاشات | نموذج أولي تفاعلي حقيقي ومتجاوب بالكامل في المتصفح | +| **تسليم التصميم للمطور** | فجوة شائعة بين التصميم وإعادة كتابته كودياً | **انعدام فجوة التسليم**: التصميم هو الكود الفعلي للإنتاج | +| **الحوكمة وضمان الجودة** | مراجعة بصرية يدوية وتخمين المطورين | **بوابات جودة ميكانيكية**: سكربتات فحص حتمية بمحاور الـ 7 | +| **نطاق المنظومة** | إنتاج الرسومات والواجهات الأولية | إدارة كاملة لدورة حياة التصميم عبر 7 مراحل هندسية | --- -### المرحلة 5: الحركة والحيوية (Motion & Interactive Experience) -*تنسيق تحريكات الدخول، تأثيرات التمرير، التفاعلات الدقيقة، والدعم اللغوي.* +## 🧠 ما هي "الذاكرة التشغيلية" (Operational Memory)؟ -| الأمر | صيغة الاستدعاء | الذاكرة المحملة | المخرجات والقيمة للمستخدم | -|---|---|---|---| -| **`/motion`** | `/motion` | `memory/04-motion-principles.md` | **تنسيق الحركة**: تطبيق تفاعلات التمرير، تغيّر خلفية `#ambient` البيئي، محركات الـ Canvas Scroll-Film، وطبقات الـ Z-Stack. | -| **`/flow`** | `/flow` | `memory/09-prototype-flow.md` | **التنقل التفاعلي**: ربط شريط التنقل العائم المساعد (`proto-nav.js`) للتنقل بين شاشات النموذج. | -| **`/i18n`** | `/i18n` | `memory/08-arabic-bilingual.md` | **محرك اللغة العربية و RTL**: ضبط خصائص الاتجاه المنطقية، خطوط El Messiri/Tajawal، ومحددات الحشمة الثقافية. | +ملفات الذاكرة داخل مجلد `references/memory/` **ليست مقالات إنشائية أو نصائح تسويقية**، بل هي **قواعد هندسية، ومصفوفات حسابية، ومحددات تقنية صارمة**: ---- +- **مصفوفة الخطوط والأوزان (`12-typography-matrix.md`)**: جداول دقيقة لاقتران الخطوط العربية واللاتينية بحسابات النسب الرياضية. +- **النماذج الهيكلية للواجهات (`13-layout-archetypes.md`)**: هياكل التصميم الكلية (L1–L4) مع أبعاد المسافات والشبكات. +- **مبادئ وتواقيع الحركة (`04-motion-principles.md`)**: منحنيات التهدئة (Cubic-bezier) وقواعد الوصول لأصحاب الحركة المخففة. +- **مصفوفات تشريح المكونات (`21-` إلى `28-`)**: كتالوجات شاملة لشعارات العناوين، أقسام الهيرو، البطاقات، الأزرار بـ 8 حالات، الفواصل البارامترية، والمقاييس الرقمية. +- **معايير الجودة ومناهضة التكرار (`06-quality-bar.md`)**: المؤشرات الـ 16 لهلوسة الذكاء الاصطناعي والعيوب الـ 11 المحظورة آلياً. +- **قواعد اللغة العربية والاتجاه من اليمين لليسار (`08-arabic-bilingual.md`)**: (خط المصيري للعناوين، وتجوال للمتن، ومنع خط الأميري للعناوين فوق 24px). -### المرحلة 6: الجودة والتدقيق (Quality Assurance & Audit) -*فحص ميزانيات الأداء، تطبيق قواعد المناهضة، والهندسة العكسية للمواقع.* - -| الأمر | صيغة الاستدعاء | الذاكرة المحملة | المخرجات والقيمة للمستخدم | -|---|---|---|---| -| **`/perf`** | `/perf` | `memory/15-performance-budget.md` | **فحص ميزانية الأداء**: توليد جدول الأوزان والأحجام الأقصى (البطل ≤ 400KB، الخطوط ≤ 3 عائلات، الشعار ≤ 40KB). | -| **`/audit`** | `/audit` | `references/workflows/audit-prototype.md`
`memory/06-quality-bar.md` | **تدقيق الجودة**: تقرير فحص قراءة فقط لقواعد المناهضة الـ 16 وعقد الاتساق الهيكلي. | -| **`/clone`** | `/clone <رابط>` | `references/workflows/clone-prototype.md`
`memory/03-narrative-conversion.md` | **استخراج نظام التصميم**: الهندسة العكسية للمواقع واستخراج الألوان الفعلية (`getComputedStyle()`) في `brand.json`. | -| **`/retrofit`** | `/retrofit` | `references/workflows/retrofit-prototype.md`
`memory/07-consistency-contract.md` | **توحيد النماذج**: إعادة هيكلة المشاريع المشتتة لتعتمد نظام تصميم موحد في `design-system/`. | +بفضل هذا الفصل، لا يحتاج وكيل الذكاء الاصطناعي لإعادة اختراع القواعد، بل يقرأ الحقيقة التشغيلية الموثقة وينفذ بناءً عليها. --- -### المرحلة 7: التسليم والنشر (Delivery & Developer Handoff) -*تجميع أصول الإنتاج، تصدير توثيق المطورين، وتشغيل خوادم النشر.* +## 🔄 مراحل دورة حياة التصميم السبع وسجل الأوامر الـ 24 -| الأمر | صيغة الاستدعاء | الذاكرة المحملة | المخرجات والقيمة للمستخدم | -|---|---|---|---| -| **`/handoff`** | `/handoff` | `memory/11-brand-json-v2.md`
`memory/05-component-anatomy.md` | **حزمة تسليم المطورين**: تصدير جداول الرموز، مصفوفة حالات المكونات، وقواعد الشبكة في `docs/handoff/`. | -| **`/deploy`** | `/deploy` | `memory/06-quality-bar.md`
`memory/10-python-tooling.md` | **التصدير النهائي**: تشغيل خادم المعاينة المحلي، فحص `test_build.py`، ضغط الأصول، وتجميع حزمة النشر (`build.py`). | +تغطي المهارة دورة حياة التصميم عبر **7 مراحل متسلسلة** يديرها **24 أمراً تنفيذياً (Slash Commands)**: ---- - -## 🎨 8 قواعد تصميمية مرنة (CSS Foundations) - -تحديد القاعدة التصميمية يتم مرة واحدة أثناء `/init` ولا يتم خلط القواعد في مشروع واحد: +```mermaid +graph LR + S1["1. الاستكشاف"] --> S2["2. التأسيس"] + S2 --> S3["3. المعمارية"] + S3 --> S4["4. المكونات"] + S4 --> S5["5. الحركة"] + S5 --> S6["6. الجودة"] + S6 --> S7["7. التسليم"] +``` -| القاعدة التصميمية | الرمز | الأنسب لـ | تفاصيل الهيكلية | -|---|---|---|---| -| **Native CSS** | `--foundation=native` | أنظمة التصميم النقية بدون مكتبات خارجية | متغيرات CSS مخصصة وفئات مكونات مفاهيمية في `tokens.css` و `components.css`. | -| **Tailwind Utility** | `--foundation=tailwind` | النمذجة السريعة بالفئات المباشرة | محرك Tailwind v4 عبر CDN مع ربط رموز التصميم المخصصة. | -| **daisyUI** | `--foundation=daisyui` | التطبيقات السريعة بمكونات جاهزة | Tailwind CDN + مكتبة مكونات daisyUI المجهزة بمتغيرات التصميم. | -| **Hybrid** | `--foundation=hybrid` | التطبيقات ولوحات التحكم ذات الهوية الخاصة | مكونات daisyUI المركبة مع فئات Native CSS للهوية البصرية الفريدة. | -| **shadcn/ui** | `--foundation=shadcn` | المكونات ذات إمكانية الوصول العالية | Tailwind v4 + خريطة رموز مكونات Radix UI الوصولية. | -| **Pico CSS v2** | `--foundation=pico` | المواقع والأدلة فائقة السرعة | وسوم HTML5 نُسقت بنظافة بدون تضخم في فئات الفاعلية. | -| **Bootstrap 5.3** | `--foundation=bootstrap` | الأنظمة المؤسسية والنمط الداكن | متغيرات المؤسسات مع دعم النمط الداكن المباشر `data-bs-theme="dark"`. | -| **Alpine + Tailwind** | `--foundation=alpine` | التفاعلات الدقيقة السريعة | توجيهات Alpine.js التفاعلية (`x-data`, `x-on`) مع محرك Tailwind v4. | +| المرحلة | الأمر السريع | الهدف التشغيلي | ما يتم حقنه من الذاكرة | المخرج الحتمي | +|---|---|---|---|---| +| **1. الاستكشاف** | `/brief` | موجز التصميم الاستراتيجي وحل المعطيات المجهولة | `workflows/brief.md` + `memory/decision-points.md` + `memory/06-quality-bar.md` | ملف `.tidyfactor/design-brief.snapshot.json` + الموجز | +| **1. الاستكشاف** | `/study` | استخراج الشفرة الوراثية البصرية من موقع أو صورة | `commands/study.md` + `memory/01-design-schools.md` + `memory/06-quality-bar.md` | تقرير تحليلي بخصائص التكوين والسمات | +| **2. التأسيس** | `/init` | بدء نظام تصميم ونموذج أولي جديد من الصفر | `workflows/init-prototype.md` + `memory/architecture.md` + `memory/foundations.md` | مجلد `design-system/` + صفحة `index.html` دلالية | +| **2. التأسيس** | `/brand` | إدارة سمات العلامة في `brand.yaml` / `brand.json` | `commands/brand.md` + `memory/11-brand-json-v2.md` | ملف `brand.yaml` موثق ومطابق للمخطط | +| **2. التأسيس** | `/typography` | اختيار واقتران الخطوط المناسبة لطبيعة المشروع | `commands/typography.md` + `memory/12-typography-matrix.md` | تضمين خطوط جوجل في `tokens.css` والترويسة | +| **2. التأسيس** | `/school` | تحديد المدرسة والتوجه البصري للمشروع | `commands/school.md` + `memory/01-design-schools.md` | تثبيت المدرسة وتوثيقها في `brand.yaml` | +| **2. التأسيس** | `/tokens` | إدارة متغيرات CSS وقيم نظام التصميم | `commands/tokens.md` + `memory/02-design-tokens.md` | تحديث `design-system/tokens.css` | +| **2. التأسيس** | `/palette` | استخراج لوحة الألوان وحساب تباين WCAG AAA | `commands/palette.md` + `scripts/extract_palette.py` | ألوان مستوفية لمعايير التباين للوضع النهاري والليلي | +| **2. التأسيس** | `/assets` | تحسين وضبط أحجام الصور وعزل الخلفيات | `commands/assets.md` + `scripts/optimize_images.py` | صور مضغوطة بصيغة WebP ومفرغة الشفافية | +| **3. المعمارية** | `/layout` | اختيار الهيكل المعماري للصفحات وشبكة التوزيع | `commands/layout.md` + `memory/13-layout-archetypes.md` | بناء حاويات الشبكة L1–L4 المتجاوبة | +| **3. المعمارية** | `/nav-footer` | تركيب أنظمة التنقل (N1-N9) والتذييل (Ft1-Ft8) | `commands/nav-footer.md` + `memory/14-nav-footer-catalog.md` | شريط التنقل المتجاوب وتذييل الصفحة المعتمد | +| **3. المعمارية** | `/page` | إضافة صفحة تسويقية أو محتوى جديد | `workflows/init-prototype.md` + `memory/05-component-anatomy.md` | صفحة `pages/
-# tidyfactor-design `v1.5.0`
+# tidyfactor-design `v1.9.0`
-**Code-Native UI-Design-Lifecycle & Interaktive Prototyping Engine für KI-Coding-Agenten**
+**Code-Native UI-Design-Lifecycle-Engine und Anti-Slop Designsystem-Suite für KI-Agenten**
[](https://www.npmjs.com/package/@tidyfactor/design)
[](LICENSE)
@@ -13,32 +13,90 @@
---
-## ⚡ Schnellstart (Quickstart)
+## 💡 Kernphilosophie: Trennung von Design-Intelligenz und Implementierung
-```bash
-# Installation & Direktaufruf via NPX
-npx @tidyfactor/cli-design
-```
+Das fundamentale Prinzip von **TidyFactor Design** besteht in der strikten Trennung von **Design-Wissen und -Intelligenz** von der **technischen Code-Implementierung**:
-Oder direkt in Ihrem KI-Assistenten aufrufen (*Google Antigravity, Claude Code, Cursor, Codex*):
-```text
-/tidyfactor-design
```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Agent
+ ↓
+ Design System
+ ↓
+ HTML/CSS/JS
+ ↓
+ Audit
+ ↓
+ Handoff
+```
+
+Diese Architektur macht die Skill zu einem wiederverwendbaren **Design-Engineering-Betriebssystem**, das deterministisch über unterschiedlichste Projekte hinweg agiert. Anstatt per Prompt unüberlegte Oberflächen zu generieren, führt der KI-Agent einen vollständigen, strukturierten Design-Lebenszyklus aus.
---
-## 📋 Befehls- & Workflow-Matrix
+## ⚖️ TidyFactor Design vs. Figma: Die Code-Native Alternative
-| Befehl | Ziel & Ergebnis | Workflow-Referenz |
+TidyFactor Design ist kein klassisches vektorbasiertes Zeichenwerkzeug, sondern eine **Code-Native Alternative zu Figma**:
+
+| Kriterium | Figma | TidyFactor Design |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **Paradigma** | Visuelles Gestaltungswerkzeug | Code-nativer Design-Workflow |
+| **Arbeitsbereich** | Canvas-zentriert | Code-zentriert |
+| **Zielgruppe** | Visuelle Designer | KI-Agent + Entwickler + Design-Engineer |
+| **Bausteine** | Visuelle Komponenten & Variablen | Design-Tokens + Komponenten + Workflows |
+| **Prototyping** | Klickbare Screen-Prototypen | Echte HTML/CSS/JS-Prototypen (Zero-Build-Step) |
+| **Handoff** | Manuelle Übergabe Designer → Entwickler | Design und Implementierung in einer einheitlichen Umgebung |
+| **Governance** | Manuelle visuelle Prüfung | Mechanische, automatisierte Qualitätsprüfungen |
+| **Umfang** | Oberflächengestaltung | Ganzheitliches Design-Lifecycle-Management |
+
+---
+
+## 🧠 Was bedeutet „Operational Memory“?
+
+Das operative Gedächtnis (`references/memory/`) besteht nicht aus abstrakten Texten, sondern aus **anwendbaren Regeln, Matrizen, Schemata und konkreten Restriktionen**:
+
+- **Typografie-Matrix** (`01-typography-matrix.md`): Hierarchien und mathematische Skalen.
+- **Layout-Archetypen** (`02-layout-archetypes.md`): Raster und Raumaufteilungen.
+- **Bewegungsprinzipien** (`03-motion-principles.md`): Physikbasierte Kurven und GSAP-Muster.
+- **Komponenten-Anatomie** (`04-component-anatomy.md`): Standardisierter Komponentenaufbau.
+- **Quality Bar** (`06-quality-bar.md`): Mechanische 7-Achsen-Qualitätsprüfung (`P5 H5 E5 S5 R5 V5 D5`).
+- **RTL- & Arabisch-Regeln** (`14-arabic-rtl-matrix.md`): Bidirektionale Layouts und Typografie.
+
+Der KI-Agent muss grundlegende Design-Entscheidungen nicht jedes Mal neu erraten, sondern greift auf ein geprüftes operatives Regelwerk zurück.
+
+---
+
+## 🚫 Anti-Slop Governance: Mechanisch überprüfbare Qualität
+
+Standard-KI neigt zu austauschbaren, künstlich wirkenden Oberflächen. TidyFactor Design setzt dem strikte Qualitätskriterien entgegen:
+
+- ❌ **Verbot generischer KI-Muster**: Keine lila Farbverläufe (*Purple Gradient Heros*), kein inflationäres *Inter Everywhere*, keine identischen 3-Spalten-Raster und keine unstrukturierten Kartenverschachtelungen.
+- 🎨 **Spezifische Designsysteme**: Farbwelten mit WCAG AAA-Kontrast und Oberflächen mit echter visueller Tiefe.
+- ⚡ **YAML-Primat (Regel 15)**: Definition von Tokens in `brand.yaml`, was 35–50 % an LLM-Kontexttickets einspart.
+
+---
+
+## 🔄 Die 7 Lebenszyklus-Phasen und 24 Befehle
+
+1. **Discovery**: `/study`, `/brief`
+2. **Foundation**: `/init`, `/brand`, `/typography`, `/school`, `/tokens`, `/palette`, `/assets`
+3. **Architecture**: `/layout`, `/nav-footer`, `/page`, `/dashboard`
+4. **Components**: `/components`, `/states`
+5. **Motion**: `/motion`, `/flow`, `/i18n`
+6. **Quality**: `/perf`, `/audit`, `/clone`, `/retrofit`
+7. **Delivery**: `/handoff`, `/deploy`
---
-## 📖 Vollständige Technische Dokumentation
+## 📚 Dokumentation & Leitfäden
-Ausführliche Spezifikationen, Architekturguides und Tools finden Sie im [Offiziellen Technischen README auf Englisch (README.md)](README.md).
+- 📖 [Ausführlicher Leitfaden für Design-Engineering und Nutzung (docs/GUIDE.md)](docs/GUIDE.md)
+- 📖 [Arabischer Engineering-Leitfaden (docs/GUIDE.ar.md)](docs/GUIDE.ar.md)
+- 📋 [Vollständige technische Spezifikation (README.md)](README.md)
diff --git a/README.es.md b/README.es.md
index b75dcf0..bdf0bcc 100644
--- a/README.es.md
+++ b/README.es.md
@@ -1,8 +1,8 @@
-# tidyfactor-design `v1.5.0`
+# tidyfactor-design `v1.9.0`
-**Motor de Ciclo de Vida de Diseño UI Nativo en Código y Prototipado Interactivo para Agentes de IA**
+**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)
[](LICENSE)
@@ -13,32 +13,92 @@
---
-## ⚡ Inicio Rápido (Quickstart)
+## 💡 La Filosofía Central: Separación de la Inteligencia de Diseño de su Implementación
-```bash
-# Instalación e invocación vía NPX
-npx @tidyfactor/cli-design
-```
+El pilar fundamental de **TidyFactor Design** radica en separar la **inteligencia y conocimiento de diseño** de la **ejecución técnica en código**:
-O invócalo directamente dentro de tu asistente de IA (*Google Antigravity, Claude Code, Cursor, Codex*):
-```text
-/tidyfactor-design
```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Agent
+ ↓
+ Design System
+ ↓
+ HTML/CSS/JS
+ ↓
+ Audit
+ ↓
+ Handoff
+```
+
+Esta arquitectura convierte a la habilidad en un **Sistema Operativo de Ingeniería de Diseño** reutilizable, transferible y predecible entre diferentes proyectos. En lugar de limitarse a generar código mediante un simple prompt, el agente ejecuta un ciclo de diseño formal y estructurado.
---
-## 📋 Matriz de Comandos Principales
+## ⚖️ TidyFactor Design vs. Figma: La Alternativa Nativa en Código
-| Comando | Objetivo y Resultado | Flujo de Trabajo |
+TidyFactor Design no pretende ser una herramienta de dibujo vectorial tradicional en lienzo, sino una **alternativa de diseño nativa en código (Code-Native Alternative)**:
+
+| Característica | Figma | TidyFactor Design |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **Paradigma** | Herramienta de diseño visual | Flujo de trabajo de diseño nativo en código |
+| **Entorno** | Centrado en el lienzo (Canvas-centric) | Centrado en código (Code-centric) |
+| **Audiencia** | Diseñadores visuales | Agente de IA + Desarrollador + Design Engineer |
+| **Bloques de construcción** | Componentes y variables visuales | Tokens + componentes + flujos deterministas |
+| **Prototipado** | Prototipos interactivos de pantalla | Prototipos reales en HTML/CSS/JS (cero build step) |
+| **Handoff** | Transferencia manual Diseñador → Dev | Diseño e implementación unificados |
+| **Gobernanza** | Inspección visual manual | Controles de calidad mecánicos y automatizados |
+| **Ámbito** | Creación de interfaces de usuario | Gestión del ciclo de vida de diseño completo |
+
+---
+
+## 🧠 ¿Qué es la Memoria Operacional (Operational Memory)?
+
+La memoria operacional (`references/memory/`) no consiste en teoría o artículos abstractos. Se compone de **estructuras de datos, matrices operativas, esquemas de diseño y restricciones ejecutables**:
+
+- **Matrices Tipográficas** (`01-typography-matrix.md`): Jerarquías y escalas sin arbitrariedad.
+- **Arquetipos de Layout** (`02-layout-archetypes.md`): Retículas y estructuras espaciales.
+- **Principios de Movimiento** (`03-motion-principles.md`): Física de curvas de animación, tiempos y GSAP.
+- **Anatomía de Componentes** (`04-component-anatomy.md`): Reglas de estructura de componentes.
+- **Barrera de Calidad** (`06-quality-bar.md`): Verificación mecánica en 7 ejes (`P5 H5 E5 S5 R5 V5 D5`).
+- **Reglas RTL y Árabe** (`14-arabic-rtl-matrix.md`): Tipografía y composición bidireccional nativa.
+
+El agente de IA no necesita improvisar o reinventar las bases en cada proyecto; cuenta con una base de reglas operativas precisas y estandarizadas.
+
+---
+
+## 🚫 Gobernanza Anti-Slop: Calidad Mecánica Comprobable
+
+A diferencia de los asistentes genéricos que generan interfaces predecibles, repetitivas y saturadas de patrones artificiales, TidyFactor Design impone **barreras de calidad mecánicas y comprobables**:
+
+- ❌ **Prohibición de Slop de IA**: Adiós a *Purple Gradients*, *Inter Everywhere*, rejillas idénticas de 3 columnas, tarjetas anidadas sin jerarquía (*Card-in-card*) y orbes flotantes (*Floating orbs*).
+- 🎨 **Sistemas de Diseño Específicos**: Paletas cromáticas con ratios de contraste WCAG AAA y superficies con profundidad real.
+- ⚡ **Primacía YAML (Regla 15)**: Almacenamiento de tokens de marca en `brand.yaml`, ahorrando entre 35% y 50% de tokens de contexto para el LLM.
+
+---
+
+## 🔄 Las 7 Fases del Ciclo de Vida y los 24 Comandos
+
+TidyFactor Design estructura el diseño en 7 etapas consecutivas gobernadas por un registro de **24 Slash Commands**:
+
+1. **Discovery**: `/study`, `/brief`
+2. **Foundation**: `/init`, `/brand`, `/typography`, `/school`, `/tokens`, `/palette`, `/assets`
+3. **Architecture**: `/layout`, `/nav-footer`, `/page`, `/dashboard`
+4. **Components**: `/components`, `/states`
+5. **Motion**: `/motion`, `/flow`, `/i18n`
+6. **Quality**: `/perf`, `/audit`, `/clone`, `/retrofit`
+7. **Delivery**: `/handoff`, `/deploy`
---
-## 📖 Especificación Técnica Completa
+## 📚 Documentación y Guías
-Para la arquitectura profunda, esquemas JSON y documentación de herramientas nativas, consulta el [README Técnico en Inglés (README.md)](README.md).
+- 📖 [Guía Exhaustiva de Ingeniería y Uso (docs/GUIDE.md)](docs/GUIDE.md)
+- 📖 [Guía de Ingeniería en Árabe (docs/GUIDE.ar.md)](docs/GUIDE.ar.md)
+- 📋 [Especificación Técnica Completa (README.md)](README.md)
diff --git a/README.fa.md b/README.fa.md
index 175e73d..a9ef20f 100644
--- a/README.fa.md
+++ b/README.fa.md
@@ -1,44 +1,91 @@
`memory/06-quality-bar.md` | **Design DNA Report**: Samples computed styles (`getComputedStyle()`), font family declarations, and macrostructure without copying raw layout or text. | -| **`/brief`** | `/brief` | `memory/01-design-schools.md`
`memory/13-layout-archetypes.md` | **Design Context Gate**: Executes 3-question context gate (Audience mode: inspire/evaluate/act/learn, Surface type, Tone school) & Fit Test filter. | - ---- - -### Stage 2: Foundation & System Setup -*Scaffold identity tokens, brand schema, color systems, typography pairings, and design schools.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/init`** | `/init [dir] [--foundation=name]` | `references/workflows/init-prototype.md`
`references/memory/architecture.md` | **Project Scaffold**: Scaffolds clean `design-system/` directory, locked CSS foundation, `brand.json`, and initial index page. | -| **`/brand`** | `/brand` | `memory/11-brand-json-v2.md`
`memory/02-design-tokens.md` | **Brand Schema v2**: Configures dual-mode `colors.light/dark` (16 tokens each), `shadows.focusRing`, motion tokens, and accessibility floors. | -| **`/typography`** | `/typography` | `memory/12-typography-matrix.md`
`memory/08-arabic-bilingual.md` | **Typography Matrix**: Routes to 7 curated Arabic + Latin font pairings (e.g. El Messiri/Tajawal, Markazi Text/IBM Plex, Jomhuria display). | -| **`/school`** | `/school [movement]` | `memory/01-design-schools.md` | **Visual Movement**: Locks design language direction (Minimalist, Brutalism, Glassmorphism, Neumorphism, Swiss, Luxury). | -| **`/tokens`** | `/tokens` | `memory/02-design-tokens.md`
`references/memory/architecture.md` | **Token Single Source**: Manages `design-system/tokens.css` custom properties and mapping rules. | -| **`/palette`** | `/palette` | `memory/02-design-tokens.md`
`memory/10-python-tooling.md` | **Palette Extractor**: Runs `extract_palette.py` to derive dominant brand colors and WCAG 2.1 AA contrast scores. | -| **`/assets`** | `/assets` | `memory/10-python-tooling.md` | **Asset Hygiene**: Automated background removal (`rembg`), WebP compression, and image optimization (`optimize_images.py`). | +| Lifecycle Stage | Slash Command | User Intent | What It Injects | Output / Deliverable | +|---|---|---|---|---| +| **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/.html` reading shared tokens |
+| **3. Architecture** | `/dashboard` | Add data-dense dashboard or app screen | `workflows/init-prototype.md` + `memory/05-component-anatomy.md` | Tabular dashboard layout with KPI cards and shell rails |
+| **4. Components** | `/components` | Manage shared UI components & 8-state catalog | `commands/components.md` + `memory/05-component-anatomy.md` | `design-system/components.css` component definitions |
+| **4. Components** | `/states` | Define interactive 8-state wrappers | `commands/states.md` + `memory/05-component-anatomy.md` | Interactive states (idle, hover, active, focus, loading...) |
+| **5. Motion** | `/motion` | Shared animations, scroll & motion recipes | `commands/motion.md` + `memory/04-motion-principles.md` | `design-system/motion.js` with GSAP & Lenis fallbacks |
+| **5. Motion** | `/flow` | Wire interactive prototype navigation flow | `commands/flow.md` + `memory/09-prototype-flow.md` | Client-side routing between prototype pages |
+| **5. Motion** | `/i18n` | Arabic/RTL localization & bidirectional UI | `commands/i18n.md` + `memory/08-arabic-bilingual.md` | Automatic RTL mirroring (`dir="rtl"`) & Arabic type |
+| **6. Quality** | `/perf` | Asset performance budget & size verification | `commands/perf.md` + `memory/15-performance-budget.md` | Audit scorecard checking sub-500KB total page weight |
+| **6. Quality** | `/audit` | Structural consistency audit & quality bar | `workflows/audit-prototype.md` + `memory/06-quality-bar.md` | 7-Axis Quality Stamp + Anti-Slop detection report |
+| **6. Quality** | `/clone` | Extract design system from external URL/clone | `workflows/clone-prototype.md` + `memory/03-narrative-conversion.md` | Clean reconstructed tokens from reference site |
+| **6. Quality** | `/retrofit` | Unify drifted prototype under design system | `workflows/retrofit-prototype.md` + `memory/07-consistency-contract.md` | Inline styles eradicated and mapped to shared tokens |
+| **7. Delivery** | `/handoff` | Developer handoff specs & CSS variable map | `commands/handoff.md` + `memory/11-brand-json-v2.md` | Production handoff tables + optional Brain KI sync |
+| **7. Delivery** | `/deploy` | Local preview server and static deployment | `commands/deploy.md` + `memory/06-quality-bar.md` | Live preview via local server with zero build step |
---
-### Stage 3: Architecture & Layout Structuring
-*Blueprint page macrostructures, navigation patterns, and surface layouts.*
+## 📐 Core UI Component & Page Composition Architecture (Volume 01–03)
-| Command | Signature Syntax | What It Loads | Output & Value |
-|---|---|---|---|
-| **`/layout`** | `/layout [archetype]` | `memory/13-layout-archetypes.md`
`references/memory/architecture.md` | **Layout Archetypes**: Applies 8 specialized blueprints (`fullbleed`, `editorial`, `spatial`, `interface`, `minimal`, `product`, `store`, `auto`). | -| **`/nav-footer`** | `/nav-footer` | `memory/14-nav-footer-catalog.md`
`memory/06-quality-bar.md` | **Nav & Footer Catalog**: Selects Navigation (N1–N9, e.g. Floating Pill, Newspaper Masthead) & Footer (Ft1–Ft8) avoiding generic AI templates. | -| **`/page`** | `/page` | `references/workflows/init-prototype.md`
`memory/05-component-anatomy.md` | **Marketing Screen**: Scaffolds content or landing page markup ONLY (`pages/.html`) with zero inline CSS/JS. |
-| **`/dashboard`** | `/dashboard ` | `references/workflows/init-prototype.md`
`memory/05-component-anatomy.md` | **Application Screen**: Scaffolds data dashboard or web app shell with stat cards, data tables, and filters. | +`tidyfactor-design` v1.9.0 introduces 8 comprehensive Component Architecture Matrices in operational memory: ---- - -### Stage 4: Component Design & State Matrix -*Build reusable UI component classes with complete interactive state handling.* +``` +references/memory/ +├── 21-eyebrow-kicker-matrix.md # 16 micro-hierarchy kickers across 4 structural families +├── 22-hero-section-matrix.md # 8 GSAP ScrollTrigger + SVG motion architectures +├── 23-card-architecture-matrix.md # 16 modular card variants (flex-col, mt-auto CTA anchoring) +├── 24-button-cta-matrix.md # 16 button alternatives with full 8-state interaction matrices +├── 25-divider-separator-matrix.md # Volume 03 Section Transitions & parametric SVG wavePath seams +├── 26-metrics-stat-matrix.md # 12 tabular stat cards (tabular-nums, SVG rings, initCounters) +├── 27-list-indicator-matrix.md # 12 trust bullet indicators (Status Rings, Milestone Trees) +└── 28-shared-motion-primitives.md # Shared GSAP foundations (easing, prepDraw, splitChars) +``` -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/components`** | `/components` | `memory/05-component-anatomy.md`
`references/memory/architecture.md` | **Component Library**: Builds reusable classes in `design-system/components.css` and generates 8-State Demo Wrappers (`.preview.html`). | -| **`/states`** | `/states` | `memory/05-component-anatomy.md`
`memory/07-consistency-contract.md` | **State Matrix**: Enforces 8 interactive component states (Default, Hover, Active, Focus-Visible, Disabled, Loading, Error, Success). | +### Key Architectural Invariants: +1. **Vertical Flex & Pinning Contract**: Every card must use `display: flex; flex-direction: column;`. Actions MUST be pinned to the bottom via `margin-top: auto` to prevent jagged button rows. +2. **Seam Ownership Mental Model**: In `25-divider-separator-matrix.md`, the seam belongs to the **outgoing section**; it draws from incoming section color via `currentColor`, eliminating background gap seams. +3. **Heritage Detailing & Zero Motif Overlap**: Mashrabiya, Lotus, and Kufic geometric patterns are isolated to section transitions or background watermarks using CSS `mask-image` with opacity $\le 0.08$. Motif overlays on text are strictly banned. --- -### Stage 5: Motion & Interactive Experience -*Choreograph entrance reveals, scroll-driven effects, micro-interactions, and localization.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/motion`** | `/motion` | `memory/04-motion-principles.md` | **Motion Choreography**: Implements 4-tier whimsy taxonomy, background `#ambient` color shifts, canvas scroll-film engines, and z-stack layers. | -| **`/flow`** | `/flow` | `memory/09-prototype-flow.md` | **Interactive Flow**: Wires floating prototype navigation toolbar (`proto-nav.js`) for screen-to-screen clickable testing. | -| **`/i18n`** | `/i18n` | `memory/08-arabic-bilingual.md` | **Arabic & RTL Engine**: Configures `dir="rtl"` logical properties, Arabic typography, and cultural modesty guidelines. | +## ⚡ Rule 15: Token Efficiency & Semantic Density (YAML Primacy) ---- - -### Stage 6: Quality Assurance & Audit -*Verify performance budgets, enforce anti-slop rules, and reverse-engineer legacy sites.* +In alignment with **Rule 15**, `tidyfactor-design` adopts **YAML Primacy** for the entire cognitive layer: -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/perf`** | `/perf` | `memory/15-performance-budget.md` | **Performance Budget Audit**: Generates data table verifying asset weight limits (hero cutout ≤ 400KB, fonts ≤ 3 families/4 weights, logo ≤ 40KB). | -| **`/audit`** | `/audit` | `references/workflows/audit-prototype.md`
`memory/06-quality-bar.md` | **Quality Bar Audit**: Executes read-only compliance report against 16 AI anti-pattern tells and structural consistency contract. | -| **`/clone`** | `/clone` | `references/workflows/clone-prototype.md`
`memory/03-narrative-conversion.md` | **Design System Extraction**: Reverse-engineers external sites by sampling computed styles and token mapping into `brand.json`. | -| **`/retrofit`** | `/retrofit` | `references/workflows/retrofit-prototype.md`
`memory/07-consistency-contract.md` | **Prototype Unification**: Refactors drifted multi-page prototypes to adopt a central shared `design-system/`. | +- **~40% Context Token Reduction**: `brand.yaml` consumes ~1,290 tokens versus ~2,180 tokens in JSON by removing brackets, quotes, and trailing commas. +- **Zero Syntax Drift**: Completely eliminates LLM syntax errors caused by missing or extraneous commas. +- **Dual-Engine Backward Compatibility**: All tooling automatically reads `brand.yaml` first, falling back gracefully to `brand.json` for legacy codebases. --- -### Stage 7: Delivery & Developer Handoff -*Package production assets, export documentation, and run deployment servers.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/handoff`** | `/handoff` | `memory/11-brand-json-v2.md`
`memory/05-component-anatomy.md` | **Developer Handoff Package**: Exports token mapping tables, 8-state component specs, grid container rules, and motion curves into `docs/handoff/`. | -| **`/deploy`** | `/deploy` | `memory/06-quality-bar.md`
`memory/10-python-tooling.md` | **Production Export**: Launches local preview server, runs `test_build.py`, asset minification, and generates release bundle (`build.py`). | +## 🛡️ Anti-Slop Mechanical Governance & Quality Gate + +TidyFactor Design mechanically detects and auto-rejects generic AI patterns during `/audit`: + +### 🚫 The 16 Named AI Anti-Pattern Tells +1. **Purple-Gradient Hero**: Purple-to-pink/blue background gradient with white centered text. +2. **Inter-Everywhere**: Single unpaired font family used across display and body. +3. **3-Column Feature Grid**: 3 identical columns with generic icons and 2-line headings. +4. **Card-in-Card**: Arbitrary nested card containers with no semantic hierarchy. +5. **Gradient Headline**: `background-clip: text` linear gradient fill on headlines. +6. **Side-Stripe Card**: 4–6px thick colored border on card edges as a decorative crutch. +7. **Full-Viewport Centered Hero**: `min-height: 100vh` centered short sentence + massive CTA. +8. **Pure Black / Pure White**: `#000000` or `#ffffff` flat surfaces (must use tinted neutrals). +9. **Default-Attractor Sameness**: Reusing identical macrostructures across consecutive pages. +10. **Specimen Fall-Through**: Defaulting to editorial `01 - HELLO` specimen layout for SaaS. +11. **The AI Nav**: Wordmark left, 4-5 links center, CTA right, 1px bottom border. +12. **The AI Footer**: 4 generic columns (Product, Company, Resources, Legal) + copyright. +13. **Aurora-Blob Background**: Flowing organic mesh blobs in purple/cyan behind hero text. +14. **Floating-Orb Decoration**: 3D spheres or blurred circles drifting aimlessly behind hero. +15. **Italic Headers**: Flipping one arbitrary word to italic (`Built to think`) for fake editorial flair. +16. **Lazy-Loaded LCP**: Adding `loading="lazy"` to the main hero image (tanks Core Web Vitals). + +### 🏷️ The 7-Axis Pre-Emit Self-Critique Stamp +Every generated prototype component, token set, or layout must be stamped with: +`/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */` +- **P** — Philosophy & School Authenticity +- **H** — Hierarchy & Layout Balance +- **E** — Encapsulation & Zero Per-Page CSS/JS +- **S** — State Completeness (8-State Wrappers) +- **R** — RTL & Typography Rigor (El Messiri + Tajawal) +- **V** — Velocity & Motion Polish (Sub-200ms Easing) +- **D** — Decision Alignment (100% Synchronized with `brand.yaml`) --- ## 🎨 8 Pluggable CSS Foundations -Lock a CSS foundation once per project during `/init`. Never mix foundations in the same project: - -| Foundation | Command Flag | Best For | Architecture Details | -|---|---|---|---| -| **Native CSS** | `--foundation=native` | Pure zero-dependency design systems | Custom CSS variables & semantic component classes in `tokens.css` & `components.css`. | -| **Tailwind Utility** | `--foundation=tailwind` | Fast utility-first prototyping | Tailwind v4 utility engine via CDN with custom design-token utility mappings. | -| **daisyUI** | `--foundation=daisyui` | Rapid web application screens | Tailwind CDN + daisyUI component library themed via custom token CSS variables. | -| **Hybrid** | `--foundation=hybrid` | Signature brand apps & dashboards | daisyUI composite application widgets + Native CSS for signature brand components. | -| **shadcn/ui** | `--foundation=shadcn` | Accessible primitive tokens | Tailwind v4 + Radix UI accessible token mapping & design primitive styles. | -| **Pico CSS v2** | `--foundation=pico` | Ultra-fast semantic minimalist sites | Semantic HTML5 tags styled cleanly without utility class bloat. | -| **Bootstrap 5.3** | `--foundation=bootstrap` | Enterprise apps & dark themes | Enterprise CSS variables with native `data-bs-theme="dark"` theme switching. | -| **Alpine + Tailwind** | `--foundation=alpine` | Interactive client micro-interactions | Alpine.js reactive state directives (`x-data`, `x-on`) paired with Tailwind v4 utilities. | - ---- - -## 🛡️ Anti-Slop Governance & Quality Bar (Rule 8) - -`tidyfactor-design` enforces strict anti-slop rules derived from premier design engineering standards (*Taste-Skill*, *Hallmark*, *Anthropic Frontend-Design*, *Website Cloner*). - -> [!IMPORTANT] -> **Pre-Emit Self-Critique Stamp**: Every generated prototype page or component is evaluated on 6 axes: **Philosophy (P)**, **Hierarchy (H)**, **Execution (E)**, **Specificity (S)**, **Restraint (R)**, and **Variety (V)**. Scores < 3 trigger an automatic revision pass before emission: -> `/* Pre-emit critique: P5 H4 E5 S4 R5 V5 */` - -### ⚙️ The Three-Dial System (`brand.json`) -Configure layout asymmetry, animation depth, and data density dynamically: - -```json -{ - "dials": { - "designVariance": 8, - "motionIntensity": 6, - "visualDensity": 4 - } -} -``` - -### ⛔ 16 Auto-Rejected AI Anti-Patterns - -| Anti-Pattern Tell | Why It Fails | Mechanical Quality Rule | -|---|---|---| -| **Purple-Gradient Hero** | Most recognized AI template tell | Single anchor hue; no gradient hero backgrounds. | -| **Inter-Everywhere** | Unpaired single-font layout | Pair distinctive display + body faces (`El Messiri` / `Tajawal` / `Outfit`). | -| **3-Column Feature Grid** | Generic 3-equal card row | Asymmetric grid, variable card heights, or inline icon lists. | -| **Card-in-Card Bloat** | Unnecessary nested container cards | Banned. Flat borders or surface tinting without extra containers. | -| **Gradient Headline Fill** | `background-clip: text` linear gradient | Solid high-contrast text; reserve gold gradient for dark luxury accents. | -| **Side-Stripe Card** | 4–6px thick border on left edge of card | Banned. Clean 1px border or subtle elevation shadow. | -| **Full-Viewport Hero** | `min-height: 100vh` centered short sentence | Hero desktop top padding capped at `pt-24` (6rem); headline max 2 lines. | -| **Pure Black / White** | Pure `#000000` or `#ffffff` flat surfaces | Must use tinted neutrals (`#0F172A`, `#F8FAFC`). | -| **Default Sameness** | Same macrostructure across consecutive pages | Vary layout archetypes across project screens (`memory/13-layout-archetypes.md`). | -| **Specimen Fall-Through**| Defaulting to editorial `01 - HELLO` specimen | Match surface archetype to domain register (e.g. `interface` for SaaS). | -| **The AI Nav** | Wordmark left, 4 links center, CTA right | Banned. Use N1–N9 catalog (e.g. N1 Floating Pill or N5 Edge-Aligned). | -| **The AI Footer** | 4 equal columns + social row + copyright | Banned. Use Ft1–Ft8 catalog (e.g. Ft1 Mast-Headed or Ft5 Letter Close). | -| **Aurora-Blob Background** | Organic mesh blobs drifting behind hero | Banned. Use soft radial `#glow` layer or clean ambient ground. | -| **Floating-Orb Decoration** | Blurred 3D spheres drifting behind text | Banned. Keep background clean and focused on copy/media. | -| **Italic Header Trick** | Flipping one word in header to italic | Banned. Rely on genuine typographic hierarchy and weight contrast. | -| **Lazy-Loaded LCP** | Adding `loading="lazy"` to hero image | Banned. Hero LCP images must load eager; lazy-load below-the-fold only. | - ---- - -## 🏛️ System Architecture & File Structure - -```mermaid -graph TD - A["User Prompt / Command"] --> B["SKILL.md (~350 Tokens Load)"] - B --> C["24 Runtime Commands across 7 Lifecycle Stages"] - C --> D["Outcome Workflows (references/workflows/)"] - C --> E["Operational Memory (memory/ & references/memory/)"] - - D --> F["Shared Design System (design-system/)"] - F --> G["tokens.css & brand.json (v2)"] - F --> H["components.css & base.css"] - F --> I["motion.js & interactions.js"] - - G --> J["Markup-Only Pages (pages/*.html)"] - H --> J - I --> J -``` +Lock your foundation once per project during `/brief` or `/init`. Never mix foundations: -### 📁 Project Directory Layout - -``` -my-prototype/ -├── design-system/ -│ ├── tokens.css ← Single source of truth: color, typography, spacing, radius, motion -│ ├── base.css ← CSS reset, typography inheritance & dark mode rules -│ ├── components.css ← Shared component library (buttons, cards, navbars, modals) -│ ├── utilities.css ← Spatial layout & container helper classes -│ ├── motion.js ← Shared scroll-reveals, ambient color shifts & choreography -│ ├── interactions.js ← Shared dropdowns, tabs, modals & toggle behavior -│ └── brand.json ← Identity tokens, voice registers & brand dials (v2 schema) -├── pages/ -│ ├── index.html ← Landing page markup ONLY (zero inline CSS/JS) -│ ├── dashboard.html ← App dashboard markup ONLY -│ └── pricing.html ← Pricing table markup ONLY -├── scripts/ ← Python Power Tools (palette extraction, BG removal, WebP compression) -├── docs/ ← Handoff specs and research documentation -├── proto-nav.js ← Dev-only floating prototype toolbar -└── brand.json ← Project-root brand identity configuration -``` +1. **Native CSS** — Pure modern CSS custom properties, zero dependencies, ultimate portability. +2. **Tailwind CSS** — Utility-first workflow mapped to design tokens via `tailwind.config.js`. +3. **daisyUI** — Semantic component classes over Tailwind with pre-built theme mappings. +4. **Hybrid** — Native design tokens (`tokens.css`) paired with utility classes for page assembly. +5. **shadcn/ui** — Modern headless component architecture with Tailwind utility styling. +6. **Pico CSS** — Classless, ultra-light semantic CSS for minimal content-first platforms. +7. **Bootstrap 5** — SASS token overrides for enterprise migrations. +8. **Alpine.js** — Lightweight declarative reactive micro-interactions without SPAs. --- -## 🇸🇦 Native Arabic & RTL System +## 🛠️ Python Tooling Suite (`scripts/`) -`tidyfactor-design` provides first-class support for bilingual Middle Eastern digital products: - -- **Typography Rules**: Headings = **El Messiri**, Body = **Tajawal**. Never Amiri for headings above 24px. -- **RTL Logical Properties**: Layout direction switching (`dir="rtl"` / `dir="ltr"`) uses CSS logical properties (`margin-inline-start`, `padding-inline`, `border-inline-end`). -- **Modesty Guidelines**: Cultural visual rules for regional targets (modest photography selection, proper emblem placement). -- **RTL Nav & Toolbar**: Floating prototype toolbar (`proto-nav.js`) automatically mirrors alignment in RTL mode. +- **`scripts/audit_design.py`**: AST parser verifying zero per-page CSS/JS, token compliance, and anti-pattern tells. +- **`scripts/extract_palette.py`**: Computes WCAG 2.1 AAA contrast ratios and generates `tokens.css` + `brand.yaml`. Supports `--source --yaml`.
+- **`scripts/optimize_images.py`**: Resizes assets to design tokens, generates WebP formats, and constrains image budgets. Supports `--target --webp`.
---
-## 🚀 Quick Start & CLI Workflows
-
-Published on NPM as [**`@tidyfactor/design`**](https://www.npmjs.com/package/@tidyfactor/design).
+## 🚀 Quickstart & Installation
-### 1. Interactive Scaffold CLI
+Install via the TidyFactor CLI or directly through any AI Coding Agent:
```bash
-# Scaffold new prototype workspace
-npx @tidyfactor/cli-design my-proto
+# Via TidyFactor CLI (NPM)
+npx @tidyfactor/cli add tidyfactor-design
-# Specify CSS Foundation (--foundation=native|tailwind|daisyui|hybrid|shadcn|pico|bootstrap|alpine)
-npx @tidyfactor/cli-design my-app --foundation=native --school=luxury
-
-# Automated AI Agent / CI mode (zero prompts)
-npx @tidyfactor/cli-design my-design-system --yes
-```
-
-### 2. Inject Agent Skill into Existing Workspace
-
-```bash
-npx @tidyfactor/cli-design add-skill
+# Open Agent Skills standard (Claude Code / Cursor / Windsurf)
+npx skills add TidyFactor/Design
```
-*Injects `.agents/skills/tidyfactor-design/`, `.claude-skill/`, `memory/`, `templates/`, and `AGENTS.md` directly into your existing repo.*
-
-### 3. Local Preview & Development Server
+### Typical Workflow Sequence:
```bash
-# Launch zero-dependency local preview server
-python -m http.server 8123
-
-# Open browser at http://localhost:8123
-```
-
----
+# 1. Establish design context and resolve unknowns
+/brief
-## 🏛️ TidyFactor Skill Methodology & 8/8 Governance Architecture
+# 2. Scaffold design system and initial prototype
+/init
-You will notice the badge **`Architect Score: 8/8 Pass (100%)`** across TidyFactor repositories. What does this mean?
+# 3. Extract palette from logo or reference image
+/palette --source assets/logo.png
-The **TidyFactor Skill Methodology** (governed by [`tidyfactor-skill-architect`](file:///c:/wamp64/www/TidyFactor/Skills/Skills-LAB/.agents/skills/tidyfactor-skill-architect/)) is an opinionated, production-grade architectural framework for building AI Agent Skills. It guarantees that an agent skill is not a giant, uncontrolled prompt or a random file dump, but a structured, deterministic runtime system optimized for low latency, zero context bloat, and strict execution quality.
+# 4. Review and audit structural compliance
+/audit
-### 📋 The 8 Architectural Rules Every TidyFactor Skill Must Pass
-
-| # | Governance Rule | Mechanical Specification | Value to User & AI Agents |
-|---|---|---|---|
-| **1** | **Dispatcher Discipline** | `SKILL.md` acts strictly as an entry-point command dispatcher (~350 tokens). It declares what commands exist and routes to workflow/memory files without carrying task execution instructions itself. | **Zero Context Waste**: Your AI Agent loads only ~350 tokens on startup instead of parsing 2,000+ lines of domain rules. |
-| **2** | **One Workflow = One Outcome** | Every workflow file (`references/workflows/`) owns exactly one outcome and ends with an explicit, mechanical validation checklist. | **Deterministic Results**: Prevents AI hallucination or half-finished steps; guarantees tasks complete against a checklist. |
-| **3** | **Operational Memory** | Files in `memory/` contain pure facts, rules, matrices, templates, and schemas — zero prose or narrative. | **High Signal-to-Noise**: Injects crisp, actionable domain constraints directly into the prompt without token bloat. |
-| **4** | **No Empty Structures** | Folder hierarchies (`references/commands/`, `references/workflows/`, `memory/`) exist only when holding multiple items. | **Clean Repository**: Eliminates unnecessary file nesting and maintains portable simplicity. |
-| **5** | **Philosophy Isolation** | Branding rationale, manifestos, or methodologies belong in optional `memory/philosophy.md` — never inside operational execution files. | **Pure Technical Execution**: Agents read only execution rules without parsing marketing philosophy. |
-| **6** | **Trigger-Justified Growth** | New commands and memory files are added strictly when triggered by quantifiable lifecycle needs (e.g. 7-stage lifecycle expansion). | **No Speculative Bloat**: Keeps the skill lean, fast, and maintainable. |
-| **7** | **Anti-Slop & Quality Bar** | Frontend generation workflows enforce Pre-Emit Self-Critique (1-5 scoring on 6 axes: P, H, E, S, R, V) and 16 mechanical AI anti-pattern checks. | **Guaranteed Aesthetic Quality**: Blocks generic "AI-looking" code, purple hero gradients, wrapped CTAs, and duplicate UI patterns. |
-| **8** | **Multi-Target Parity Validation** | 100% parity across Agent skill targets (`.agents`, `.claude-skill`, and root repo files) verified automatically via `node tools/validate-skill.js`. | **Cross-Platform Compatibility**: Works identically in Antigravity, Claude Code, Cursor, Codex, and Windsurf. |
-
----
-
-
----
-
-## 🏛️ TidyFactor Ecosystem Architecture
-
-**TidyFactor** is a modular web architecture and AI coding agent skill ecosystem built on clear separation of concerns across the product lifecycle:
-
-```
-TidyFactor Organization (github.com/TidyFactor)
-│
-├── Design Skills
-│ ├── Cinematic → Experience / "Wow" (Apple × Cartier Scroll-Driven Landing Pages)
-│ ├── Design → Prototype / "Build" (Code-Native UI Design Engine & Figma Alternative)
-│ └── Styler → Production / "Ship" (Framework Styler & RTL Polish Engine)
-│
-├── Development Skills
-│ ├── HTML → Content & Static (Semantic SEO & Static Platform Starter)
-│ ├── HTMX → Hypermedia (Server-Driven Micro-Interactions)
-│ ├── JS → Vanilla SPA (Framework-Free Reactive ES Modules)
-│ ├── PHP → Server-Rendered (Modern PHP 8.x Component UI & Architecture)
-│ └── Next → Multi-Tenant SaaS (Next.js 16, React 19, Supabase RLS & Dev-Perf)
-│
-└── Growth Skills
- └── Marketing → Growth / Revenue (Direct Response, Pillar SEO & Content Lifecycles)
+# 5. Export developer handoff specifications
+/handoff
```
-### 💎 Frontend Triad
-
-```
- TidyFactor
- │
- ┌─────────┼─────────┐
- │ │ │
- Cinematic Design Styler
- │ │ │
- Experience Prototype Production
- │ │ │
- "Wow" "Build" "Ship"
-```
-
-### 📦 Community Package & Skill Parity
-
-| Track | Category | GitHub Repository | Agent Skill | NPM Package |
-| :--- | :--- | :--- | :--- | :--- |
-| **Cinematic** | Design | [`TidyFactor/Cinematic`](https://github.com/TidyFactor/Cinematic) | `tidyfactor-cinematic` | [`@tidyfactor/cinematic`](https://www.npmjs.com/package/@tidyfactor/cinematic) |
-| **Design** | Design | [`TidyFactor/Design`](https://github.com/TidyFactor/Design) | `tidyfactor-design` | [`@tidyfactor/design`](https://www.npmjs.com/package/@tidyfactor/design) |
-| **Styler** | Design | [`TidyFactor/Styler`](https://github.com/TidyFactor/Styler) | `tidyfactor-styler` | [`@tidyfactor/styler`](https://www.npmjs.com/package/@tidyfactor/styler) |
-| **Next** | Development | [`TidyFactor/Next`](https://github.com/TidyFactor/Next) | `tidyfactor-next` | [`@tidyfactor/next`](https://www.npmjs.com/package/@tidyfactor/next) |
-| **HTML** | Development | [`TidyFactor/HTML`](https://github.com/TidyFactor/HTML) | `tidyfactor-html` | [`@tidyfactor/html`](https://www.npmjs.com/package/@tidyfactor/html) |
-| **HTMX** | Development | [`TidyFactor/HTMX`](https://github.com/TidyFactor/HTMX) | `tidyfactor-htmx` | [`@tidyfactor/htmx`](https://www.npmjs.com/package/@tidyfactor/htmx) |
-| **JS** | Development | [`TidyFactor/JS`](https://github.com/TidyFactor/JS) | `tidyfactor-js` | [`@tidyfactor/js`](https://www.npmjs.com/package/@tidyfactor/js) |
-| **PHP** | Development | [`TidyFactor/PHP`](https://github.com/TidyFactor/PHP) | `tidyfactor-php` | [`@tidyfactor/php`](https://www.npmjs.com/package/@tidyfactor/php) |
-| **Marketing** | Growth | [`TidyFactor/Marketing`](https://github.com/TidyFactor/Marketing) | `tidyfactor-marketing` | [`@tidyfactor/marketing`](https://www.npmjs.com/package/@tidyfactor/marketing) |
-
----
-
-## 👨💻 Organization & Support
-
-- 🌐 **Official Website:** [https://tidyfactor.com/](https://tidyfactor.com/)
-- 📚 **Official Documentation:** [https://tidyfactor.com/documentation](https://tidyfactor.com/documentation)
-- 🤝 **Official Partner Website:** [Alwkala Digital Agency](https://alwkala.com/)
-- 🐙 **GitHub Organization:** [github.com/TidyFactor](https://github.com/TidyFactor)
-- 📧 **Business Inquiries:** [hello@tidyfactor.com](mailto:hello@tidyfactor.com)
-- 📱 **WhatsApp:** [+20 101 665 6899](https://wa.me/201016656899)
-- 📞 **Phone:** +20 101 665 6899
-- 📍 **Location:** Cairo, Egypt
-
---
-## 📜 License
+## 🏛️ License & Governance
-Licensed under the **Apache License 2.0**. Copyright (c) 2026 [TidyFactor](https://tidyfactor.com) & [Alwkala](https://alwkala.com).
+- **License**: Apache-2.0. Open-source, free for personal and commercial use.
+- **SSOT Governance**: Governed strictly under the **15 Structural Rules** of TidyFactor Skills-LAB.
+- **Ecosystem**: Part of the **TidyFactor Ecosystem** ([tidyfactor.com](https://tidyfactor.com)), stewarded by **Alwkala** ([alwkala.com](https://alwkala.com)).
diff --git a/README.pt.md b/README.pt.md
index ac5b9b2..886505a 100644
--- a/README.pt.md
+++ b/README.pt.md
@@ -1,8 +1,8 @@
-# tidyfactor-design `v1.5.0`
+
---
-## ⚡ راهاندازی سریع (Quickstart)
+## 🏛️ نوآوری بنیادین: جداسازی "دانش طراحی" از "اجرای طراحی"
-```bash
-# نصب و اجرای مستقیم از طریق NPX
-npx @tidyfactor/cli-design
-```
+نوآوری اصلی **TidyFactor Design** تفکیک ساختاری و مهندسی میان **دانش و بینش طراحی** و **اجرای کد** است:
-یا فراخوانی مستقیم در دستیار برنامهنویسی (*Google Antigravity, Claude Code, Cursor, Codex*):
-```text
-/tidyfactor-design
```
+ دانش طراحی (DESIGN INTELLIGENCE)
+ │
+ ┌─────────────────┴─────────────────┐
+ ↓ ↓
+ حافظه عملیاتی (Memory) جریانهای کاری (Workflows)
+ (قواعد، ماتریسها، الگوها، CDL) (گامهای منظم اجرایی)
+ │ │
+ └─────────────────┬─────────────────┘
+ ↓
+ عامل هوش مصنوعی
+ (Antigravity / Claude / Cursor)
+ ↓
+ سیستم طراحی یکپارچه
+ (brand.yaml + tokens.css)
+ ↓
+ رابط کاربری زنده با کد
+ (HTML/CSS/JS بدون بیلد)
+ ↓
+ ممیزی خودکار و قطعی
+ (مهر محورهای ۷ گانه کیفیت)
+ ↓
+ تحویل نهایی به توسعه
+ (Production-Ready Handoff)
+```
+
+### چرا این یک "مهندسی سیستم طراحی" است و نه صرفاً یک پرامپت یا کتابخانه کامپوننت؟
+وقتی از هوش مصنوعی میخواهید یک صفحه وب طراحی کند، تلاش میکند تمام متغیرها را همزمان در یک پرامپت حدس بزند که نتیجه آن **خروجی کلیشهای و تکراری (AI Slop)** است. TidyFactor Design این فرآیند را به یک **سیستم مهندسی قطعی** تبدیل میکند:
+
+$$\text{پرامپت سنتی: } \text{پرامپت} \longrightarrow \text{هوش مصنوعی یک خروجی کلیشهای تولید میکند}$$
+$$\text{موتور طراحی تایدی فاکتور: } \text{خلاصه نیازها} \longrightarrow \text{قواعد} \longrightarrow \text{سیستم} \longrightarrow \text{کد استاندارد} \longrightarrow \text{اعتبارسنجی} \longrightarrow \text{تحویل}$$
---
-## 📋 ماتریس دستورات اصلی
+## ⚡ مقایسه با فیگما: جایگزین مبتنی بر کد (Code-Native Alternative to Figma)
-| دستور | هدف و نتیجه | جریان کاری (Workflow) |
+| معیار | فیگما (Figma) | تایدی فاکتور دیزاین (TidyFactor Design) |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **محیط کار** | بوم گرافیکی وکتور (GUI) | محیط زنده و اجرایی درون مرورگر |
+| **تمرکز محوری** | متمرکز بر بوم (Canvas-centric) | متمرکز بر کد استاندارد HTML5 / CSS3 / Vanilla JS |
+| **مخاطب هدف** | طراح رابط و تجربه کاربری (UI/UX) | عامل هوش مصنوعی + توسعهدهنده + مهندس طراحی |
+| **مدل کامپوننت** | فریمها و متغیرهای بصری | متغیرهای CSS و کامپوننتهای ۸ حالته تعاملی |
+| **پروتوتایپ** | نمونهسازی کلیکی و شبیهسازی | نمونهسازی زنده، واقعی و کاملاً ریسپانسیو در مرورگر |
+| **تحویل به توسعهدهنده** | انتقال با ایجاد دوباره کدها | **انتقال بدون اصطکاک**: طراحی دقیقاً همان کد تولیدی است |
+| **تضمین کیفیت** | بازبینی دستی و سلیقهای | **دروازههای کیفیت مکانیکی**: تستهای خودکار AST و ممیزی ۷ محوره |
+| **چرخه حیات** | خلق المانهای بصری | مدیریت کامل ۷ مرحله چرخه حیات طراحی رابط کاربری |
+
+---
+
+## 🔄 ۷ مرحله چرخه حیات و ۲۴ دستور اجرایی (Slash Commands)
+
+1. **کشف و تحقیق (Discovery)**: `/brief` (تعیین پارامترها و حل مجهولات)، `/study` (استخراج DNA طراحی).
+2. **پایهگذاری (Foundation)**: `/init` (آغاز سیستم طراحی)، `/brand` (مدیریت سمبلهای برند)، `/typography` (جفت خطوط هماهنگ)، `/school` (مکتب بصری)، `/tokens` (متغیرهای CSS)، `/palette` (کنتراست WCAG AAA)، `/assets` (بهینهسازی رسانه).
+3. **معماری (Architecture)**: `/layout` (شبکهبندی L1-L4)، `/nav-footer` (هدر و فوتر)، `/page` (صفحه جدید)، `/dashboard` (داشبورد آماری).
+4. **کامپوننتها (Components)**: `/components` (مدیریت اجزا)، `/states` (حالتهای ۸ گانه).
+5. **حرکت و تعامل (Motion)**: `/motion` (انیمیشنهای GSAP)، `/flow` (مسیرهای تعامل)، `/i18n` (راستچین RTL).
+6. **کنترل کیفیت (Quality)**: `/perf` (بودجه عملکردی)، `/audit` (ممیزی پاد-کلیشه)، `/clone` (استخراج ساختار)، `/retrofit` (یکپارچهسازی).
+7. **تحویل (Delivery)**: `/handoff` (مشخصات تحویل توسعهدهنده)، `/deploy` (پیشنمایش محلی).
---
-## 📖 مستندات فنی کامل و رسمی
+## 🏛️ مجوز و حاکمیت
-برای دسترسی به اسکیماهای معماری، الگوهای کامل طراحی و ابزارهای بومی، به [مستندات فنی کامل به زبان انگلیسی (README.md)](README.md) مراجعه نمایید.
+- **مجوز**: Apache-2.0. کاملاً متنباز و رایگان برای استفاده شخصی و تجاری.
+- **توسعه**: بخشی از **اکوسیستم TidyFactor** ([tidyfactor.com](https://tidyfactor.com)) تحت نظارت **آژانس الوکاله (Alwkala)** ([alwkala.com](https://alwkala.com)).
diff --git a/README.fr.md b/README.fr.md
index 7cea4f2..82466c9 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -1,8 +1,8 @@
+ 
+
-# tidyfactor-design `v1.5.0`
+# tidyfactor-design `v1.9.0`
-**Moteur de Cycle de Vie de Design UI Natif en Code et Prototypage Interactif pour Agents d'IA**
+**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)
[](LICENSE)
@@ -13,32 +13,90 @@
---
-## ⚡ Démarrage Rapide (Quickstart)
+## 💡 Philosophie Fondatrice : Dissociation de l'Intelligence de Design et de son Implémentation
-```bash
-# Installation et exécution via NPX
-npx @tidyfactor/cli-design
-```
+Le principe directeur de **TidyFactor Design** repose sur la séparation stricte entre **l'intelligence de design** et son **exécution technique en code** :
-Ou appelez-le directement depuis votre assistant IA (*Google Antigravity, Claude Code, Cursor, Codex*) :
-```text
-/tidyfactor-design
```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Agent
+ ↓
+ Design System
+ ↓
+ HTML/CSS/JS
+ ↓
+ Audit
+ ↓
+ Handoff
+```
+
+Cette architecture transforme la compétence en un **Système d'Exploitation d'Ingénierie de Design** reproductible et déterministe à travers divers projets. Au lieu de demander à un agent de générer une interface à partir d'un prompt brut, l'IA exécute un cycle de vie d'ingénierie formel.
---
-## 📋 Matrice des Commandes Principales
+## ⚖️ TidyFactor Design vs Figma : L'Alternative Native en Code
-| Commande | Objectif & Résultat | Référence de Workflow |
+TidyFactor Design ne vise pas à concurrencer les logiciels traditionnels de dessin vectoriel sur toile, mais constitue une **Alternative Native en Code à Figma (Code-Native Alternative)** :
+
+| Critère | Figma | TidyFactor Design |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **Paradigme** | Outil de dessin visuel | Flux de travail de design natif en code |
+| **Environnement** | Centré sur la toile (Canvas-centric) | Centré sur le code (Code-centric) |
+| **Public cible** | Designers visuels | Agents IA + Développeurs + Design Engineers |
+| **Éléments de base** | Composants et variables visuels | Design tokens + composants + flux déterministes |
+| **Prototypage** | Maquettes cliquables d'écrans | Prototypes réels en HTML/CSS/JS (zéro build step) |
+| **Handoff** | Transfert manuel Designer → Développeur | Conception et implémentation unifiées |
+| **Gouvernance** | Vérification manuelle visuelle | Portes de qualité mécaniques et automatisées |
+| **Périmètre** | Création d'interfaces utilisateur | Gestion complète du cycle de vie de design |
+
+---
+
+## 🧠 Qu'est-ce que la Mémoire Opérationnelle (Operational Memory) ?
+
+La mémoire opérationnelle (`references/memory/`) ne contient pas de prose théorique, mais des **règles applicables, des matrices structurées, des schémas de conception et des contraintes exécutables** :
+
+- **Matrice Typographique** (`01-typography-matrix.md`) : Hiérarchies et échelles harmoniques.
+- **Archétypes de Layout** (`02-layout-archetypes.md`) : Grilles et structuration spatiale.
+- **Principes de Mouvement** (`03-motion-principles.md`) : Courbes cinématiques, cadences et intégration GSAP.
+- **Anatomie des Composants** (`04-component-anatomy.md`) : Structure standardisée des éléments d'interface.
+- **Barre de Qualité** (`06-quality-bar.md`) : Grille d'audit mécanique en 7 axes (`P5 H5 E5 S5 R5 V5 D5`).
+- **Règles RTL et Arabes** (`14-arabic-rtl-matrix.md`) : Typographie et composition bidirectionnelle native.
+
+L'agent IA n'a plus besoin de réinventer les règles typographiques à chaque session : il opère à partir d'un socle d'ingénierie préétabli.
+
+---
+
+## 🚫 Gouvernance Anti-Slop : Critères de Qualité Mécaniques
+
+Contrairement aux outils d'IA générative produisant des interfaces stéréotypées et répétitives, TidyFactor Design applique des **contrôles qualité mécaniques et vérifiables** :
+
+- ❌ **Interdiction des Clichés d'IA** : Élimination des dégradés violets génériques (*Purple Gradient Heros*), de l'omniprésence d'Inter (*Inter Everywhere*), des grilles à 3 colonnes arbitraires et des orbes lumineuses flottantes (*Aurora blobs*).
+- 🎨 **Systèmes de Design Raffinés** : Palettes respectant les contrastes WCAG AAA et surfaces tactiles à profondeur réelle.
+- ⚡ **Primauté YAML (Règle 15)** : Stockage des tokens de marque dans `brand.yaml`, réduisant de 35 à 50 % la consommation de tokens contextuels pour le LLM.
+
+---
+
+## 🔄 Les 7 Étapes du Cycle de Vie et les 24 Commandes
+
+1. **Discovery** : `/study`, `/brief`
+2. **Foundation** : `/init`, `/brand`, `/typography`, `/school`, `/tokens`, `/palette`, `/assets`
+3. **Architecture** : `/layout`, `/nav-footer`, `/page`, `/dashboard`
+4. **Components** : `/components`, `/states`
+5. **Motion** : `/motion`, `/flow`, `/i18n`
+6. **Quality** : `/perf`, `/audit`, `/clone`, `/retrofit`
+7. **Delivery** : `/handoff`, `/deploy`
---
-## 📖 Documentation Technique Complète
+## 📚 Documentation et Guides
-Pour consulter l'architecture approfondie et les spécifications complètes, veuillez vous référer au [README Technique Officiel en Anglais (README.md)](README.md).
+- 📖 [Guide Complet d'Ingénierie et d'Utilisation (docs/GUIDE.md)](docs/GUIDE.md)
+- 📖 [Guide d'Ingénierie en Arabe (docs/GUIDE.ar.md)](docs/GUIDE.ar.md)
+- 📋 [Spécification Technique Complète (README.md)](README.md)
diff --git a/README.md b/README.md
index 76e039d..22dbb10 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
-# 🎨 TidyFactor Design `v1.6.0`
+# 🎨 TidyFactor Design `v1.9.0`
### Code-Native UI Design Lifecycle Engine & Anti-Slop Design System Suite
**The official UI design & interactive prototyping foundation for the TidyFactor Ecosystem.**
@@ -12,74 +12,90 @@
[](https://www.npmjs.com/package/@tidyfactor/design)
[](LICENSE)
[](README.ar.md)
-[](#-anti-slop-governance--quality-bar-rule-8)
-[-green.svg?style=for-the-badge)](#-license--governance)
+[](#-anti-slop-mechanical-governance--quality-gate)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
-[✨ Live Demo](https://alwkala.com/tidyfactor-design/) • [🖼️ Visual Showcase](#%EF%B8%8F-visual-showcase--surface-demos) • [⚡ 24 Slash Commands](#-the-7-ui-design-lifecycle-stages--24-command-registry) • [🎨 8 CSS Foundations](#-8-pluggable-css-foundations) • [🛡️ Anti-Slop Rules](#-anti-slop-governance--quality-bar-rule-8) • [📖 بالعربية](README.ar.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)
---
-> [!NOTE]
-> **TidyFactor Design** is an AI-era, code-native alternative to Figma and complete UI Design Lifecycle Engine. It empowers developers, design engineers, and AI coding agents (*Google Antigravity, Claude Code, Cursor, Codex, Windsurf*) to manage all 7 stages of UI design—from initial discovery through developer handoff—using clean, interactive HTML/CSS/JS with zero build steps and zero per-page CSS/JS drift.
+## 🏛️ The Core Breakthrough: Design Intelligence vs. Execution
----
-
-## 🌟 Value Proposition & Why TidyFactor Design?
-
-| For Developers | For Design Engineers | For AI Coding Agents |
-|---|---|---|
-| **Zero Build Step**: No webpack/vite compilation needed; open `.html` files directly in any browser. | **Figma Alternative**: Design directly in production-ready code with responsive live interactivity. | **Token-Efficient**: Modular slash commands load only necessary context (~350 tokens) per task. |
-| **Zero Per-Page Drift**: All visual styles and components live strictly inside `design-system/`. | **8 Pluggable Foundations**: Choose Native CSS, Tailwind, daisyUI, shadcn/ui, Pico, Bootstrap, or Alpine. | **Anti-Slop Certified**: Structurally blocks generic AI design tells via 16 mechanical quality rules. |
-| **Production Handoff**: Clean, predictable CSS variables and HTML markup ready for framework integration. | **Native RTL & Arabic**: Bidi-first layout support with El Messiri + Tajawal typography pairing. | **Deterministic Workflows**: 100% compliance across 24 commands with automated validation tooling. |
-
----
+The foundational innovation of **TidyFactor Design** is the strict architectural separation of **Design Knowledge** from **Design Implementation**:
-## 🖼️ Visual Showcase & Surface Demos
+```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ (Rules, Matrices, CDL) (Ordered Steps)
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Coding Agent
+ (Antigravity / Claude / Cursor)
+ ↓
+ Design System SSOT
+ (brand.yaml + tokens.css)
+ ↓
+ Interactive HTML/CSS/JS
+ (Zero per-page CSS/JS)
+ ↓
+ Mechanical Audit Gate
+ (7-Axis Stamp + AI Tells)
+ ↓
+ Production Handoff
+ (Clean CSS Tokens + Specs)
+```
-`tidyfactor-design` generates rich, responsive, anti-slop visual surfaces tailored to specific domain registers:
+### 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.
-### 1. Dual-Mode Design System (Light & Dark)
-*Dynamic theme switching powered by `brand.json` v2 token mappings (`colors.light` & `colors.dark`) without page reloads.*
+**TidyFactor Design** replaces arbitrary prompt generation with a **Deterministic Design Engineering Pipeline**:
-| Light Mode Surface | Dark Mode Surface |
-|---|---|
-|  |  |
+$$\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}$$
---
-### 2. Application & Analytics Dashboards
-*Data-rich layouts featuring tabular numeric formatting, KPI stat cards, filters, and shell rails.*
-
-
-
----
+## ⚡ The Definitive Comparison: Figma vs. TidyFactor Design
-### 3. E-Commerce & Product Showcase
-*High-conversion commerce surfaces with gallery previews, spec tables, variant selectors, and CTAs.*
+TidyFactor Design is **the Code-Native Alternative to Figma** for the AI coding agent era:
-
+| 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 |
---
-### 4. Editorial & Magazine Publishing
-*Literary typography hierarchy featuring Markazi Text / El Messiri headings, multi-column storytelling, and colophons.*
-
-
+## 🧠 The Concept of "Operational Memory"
----
+In TidyFactor, `references/memory/` files are **NOT** narrative articles or marketing essays. They are **executable engineering constraints**, tabular decision matrices, and authoritative schemas:
-### 5. Atmospheric & Cinematic Showcase
-*Full-bleed atmospheric storytelling with ambient background color shifts, canvas scroll-film reveals, and specular sheens.*
+- **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).
-
+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.
---
## 🔄 The 7 UI Design Lifecycle Stages & 24 Command Registry
-`tidyfactor-design` structures the entire design workflow into **7 sequential stages**, providing 24 specialized slash commands that load precise operational memory without context bloat:
+The skill provides 24 specialized slash commands mapped across 7 rigorous lifecycle stages:
```mermaid
graph LR
@@ -91,328 +107,160 @@ graph LR
S6 --> S7["7. Delivery"]
```
----
-
-### Stage 1: Discovery & Research
-*Extract design DNA, establish context, and determine visual fit before writing code.*
-
-| Command | Signature Syntax | What It Loads | Output & Value |
-|---|---|---|---|
-| **`/study`** | `/study [url\|image]` | `memory/01-design-schools.md`
-# 🎨 TidyFactor Design `v1.6.0`
+# 🎨 TidyFactor Design `v1.9.0`
### Code-Native UI Design Lifecycle Engine & Anti-Slop Design System Suite
**The official UI design & interactive prototyping foundation for the TidyFactor Ecosystem.**
@@ -12,74 +12,90 @@
[](https://www.npmjs.com/package/@tidyfactor/design)
[](LICENSE)
[](README.ar.md)
-[](#-anti-slop-governance--quality-bar-rule-8)
-[-green.svg?style=for-the-badge)](#-license--governance)
+[](#-anti-slop-mechanical-governance--quality-gate)
+[-green.svg?style=for-the-badge)](#-the-15-structural-rules-of-tidyfactor-skills)
-[✨ Live Demo](https://alwkala.com/tidyfactor-design/) • [🖼️ Visual Showcase](#%EF%B8%8F-visual-showcase--surface-demos) • [⚡ 24 Slash Commands](#-the-7-ui-design-lifecycle-stages--24-command-registry) • [🎨 8 CSS Foundations](#-8-pluggable-css-foundations) • [🛡️ Anti-Slop Rules](#-anti-slop-governance--quality-bar-rule-8) • [📖 بالعربية](README.ar.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)
`memory/06-quality-bar.md` | **Design DNA Report**: Samples computed styles (`getComputedStyle()`), font family declarations, and macrostructure without copying raw layout or text. | -| **`/brief`** | `/brief` | `memory/01-design-schools.md`
`memory/13-layout-archetypes.md` | **Design Context Gate**: Executes 3-question context gate (Audience mode: inspire/evaluate/act/learn, Surface type, Tone school) & Fit Test filter. | - ---- - -### Stage 2: Foundation & System Setup -*Scaffold identity tokens, brand schema, color systems, typography pairings, and design schools.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/init`** | `/init [dir] [--foundation=name]` | `references/workflows/init-prototype.md`
`references/memory/architecture.md` | **Project Scaffold**: Scaffolds clean `design-system/` directory, locked CSS foundation, `brand.json`, and initial index page. | -| **`/brand`** | `/brand` | `memory/11-brand-json-v2.md`
`memory/02-design-tokens.md` | **Brand Schema v2**: Configures dual-mode `colors.light/dark` (16 tokens each), `shadows.focusRing`, motion tokens, and accessibility floors. | -| **`/typography`** | `/typography` | `memory/12-typography-matrix.md`
`memory/08-arabic-bilingual.md` | **Typography Matrix**: Routes to 7 curated Arabic + Latin font pairings (e.g. El Messiri/Tajawal, Markazi Text/IBM Plex, Jomhuria display). | -| **`/school`** | `/school [movement]` | `memory/01-design-schools.md` | **Visual Movement**: Locks design language direction (Minimalist, Brutalism, Glassmorphism, Neumorphism, Swiss, Luxury). | -| **`/tokens`** | `/tokens` | `memory/02-design-tokens.md`
`references/memory/architecture.md` | **Token Single Source**: Manages `design-system/tokens.css` custom properties and mapping rules. | -| **`/palette`** | `/palette
`memory/10-python-tooling.md` | **Palette Extractor**: Runs `extract_palette.py` to derive dominant brand colors and WCAG 2.1 AA contrast scores. | -| **`/assets`** | `/assets` | `memory/10-python-tooling.md` | **Asset Hygiene**: Automated background removal (`rembg`), WebP compression, and image optimization (`optimize_images.py`). | +| Lifecycle Stage | Slash Command | User Intent | What It Injects | Output / Deliverable | +|---|---|---|---|---| +| **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/
`references/memory/architecture.md` | **Layout Archetypes**: Applies 8 specialized blueprints (`fullbleed`, `editorial`, `spatial`, `interface`, `minimal`, `product`, `store`, `auto`). | -| **`/nav-footer`** | `/nav-footer` | `memory/14-nav-footer-catalog.md`
`memory/06-quality-bar.md` | **Nav & Footer Catalog**: Selects Navigation (N1–N9, e.g. Floating Pill, Newspaper Masthead) & Footer (Ft1–Ft8) avoiding generic AI templates. | -| **`/page`** | `/page
`memory/05-component-anatomy.md` | **Marketing Screen**: Scaffolds content or landing page markup ONLY (`pages/
`memory/05-component-anatomy.md` | **Application Screen**: Scaffolds data dashboard or web app shell with stat cards, data tables, and filters. | +`tidyfactor-design` v1.9.0 introduces 8 comprehensive Component Architecture Matrices in operational memory: ---- - -### Stage 4: Component Design & State Matrix -*Build reusable UI component classes with complete interactive state handling.* +``` +references/memory/ +├── 21-eyebrow-kicker-matrix.md # 16 micro-hierarchy kickers across 4 structural families +├── 22-hero-section-matrix.md # 8 GSAP ScrollTrigger + SVG motion architectures +├── 23-card-architecture-matrix.md # 16 modular card variants (flex-col, mt-auto CTA anchoring) +├── 24-button-cta-matrix.md # 16 button alternatives with full 8-state interaction matrices +├── 25-divider-separator-matrix.md # Volume 03 Section Transitions & parametric SVG wavePath seams +├── 26-metrics-stat-matrix.md # 12 tabular stat cards (tabular-nums, SVG rings, initCounters) +├── 27-list-indicator-matrix.md # 12 trust bullet indicators (Status Rings, Milestone Trees) +└── 28-shared-motion-primitives.md # Shared GSAP foundations (easing, prepDraw, splitChars) +``` -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/components`** | `/components` | `memory/05-component-anatomy.md`
`references/memory/architecture.md` | **Component Library**: Builds reusable classes in `design-system/components.css` and generates 8-State Demo Wrappers (`.preview.html`). | -| **`/states`** | `/states` | `memory/05-component-anatomy.md`
`memory/07-consistency-contract.md` | **State Matrix**: Enforces 8 interactive component states (Default, Hover, Active, Focus-Visible, Disabled, Loading, Error, Success). | +### Key Architectural Invariants: +1. **Vertical Flex & Pinning Contract**: Every card must use `display: flex; flex-direction: column;`. Actions MUST be pinned to the bottom via `margin-top: auto` to prevent jagged button rows. +2. **Seam Ownership Mental Model**: In `25-divider-separator-matrix.md`, the seam belongs to the **outgoing section**; it draws from incoming section color via `currentColor`, eliminating background gap seams. +3. **Heritage Detailing & Zero Motif Overlap**: Mashrabiya, Lotus, and Kufic geometric patterns are isolated to section transitions or background watermarks using CSS `mask-image` with opacity $\le 0.08$. Motif overlays on text are strictly banned. --- -### Stage 5: Motion & Interactive Experience -*Choreograph entrance reveals, scroll-driven effects, micro-interactions, and localization.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/motion`** | `/motion` | `memory/04-motion-principles.md` | **Motion Choreography**: Implements 4-tier whimsy taxonomy, background `#ambient` color shifts, canvas scroll-film engines, and z-stack layers. | -| **`/flow`** | `/flow` | `memory/09-prototype-flow.md` | **Interactive Flow**: Wires floating prototype navigation toolbar (`proto-nav.js`) for screen-to-screen clickable testing. | -| **`/i18n`** | `/i18n` | `memory/08-arabic-bilingual.md` | **Arabic & RTL Engine**: Configures `dir="rtl"` logical properties, Arabic typography, and cultural modesty guidelines. | +## ⚡ Rule 15: Token Efficiency & Semantic Density (YAML Primacy) ---- - -### Stage 6: Quality Assurance & Audit -*Verify performance budgets, enforce anti-slop rules, and reverse-engineer legacy sites.* +In alignment with **Rule 15**, `tidyfactor-design` adopts **YAML Primacy** for the entire cognitive layer: -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/perf`** | `/perf` | `memory/15-performance-budget.md` | **Performance Budget Audit**: Generates data table verifying asset weight limits (hero cutout ≤ 400KB, fonts ≤ 3 families/4 weights, logo ≤ 40KB). | -| **`/audit`** | `/audit` | `references/workflows/audit-prototype.md`
`memory/06-quality-bar.md` | **Quality Bar Audit**: Executes read-only compliance report against 16 AI anti-pattern tells and structural consistency contract. | -| **`/clone`** | `/clone
`memory/03-narrative-conversion.md` | **Design System Extraction**: Reverse-engineers external sites by sampling computed styles and token mapping into `brand.json`. | -| **`/retrofit`** | `/retrofit` | `references/workflows/retrofit-prototype.md`
`memory/07-consistency-contract.md` | **Prototype Unification**: Refactors drifted multi-page prototypes to adopt a central shared `design-system/`. | +- **~40% Context Token Reduction**: `brand.yaml` consumes ~1,290 tokens versus ~2,180 tokens in JSON by removing brackets, quotes, and trailing commas. +- **Zero Syntax Drift**: Completely eliminates LLM syntax errors caused by missing or extraneous commas. +- **Dual-Engine Backward Compatibility**: All tooling automatically reads `brand.yaml` first, falling back gracefully to `brand.json` for legacy codebases. --- -### Stage 7: Delivery & Developer Handoff -*Package production assets, export documentation, and run deployment servers.* - -| Command | Signature Syntax | What It Loads | Output & Value | -|---|---|---|---| -| **`/handoff`** | `/handoff` | `memory/11-brand-json-v2.md`
`memory/05-component-anatomy.md` | **Developer Handoff Package**: Exports token mapping tables, 8-state component specs, grid container rules, and motion curves into `docs/handoff/`. | -| **`/deploy`** | `/deploy` | `memory/06-quality-bar.md`
`memory/10-python-tooling.md` | **Production Export**: Launches local preview server, runs `test_build.py`, asset minification, and generates release bundle (`build.py`). | +## 🛡️ Anti-Slop Mechanical Governance & Quality Gate + +TidyFactor Design mechanically detects and auto-rejects generic AI patterns during `/audit`: + +### 🚫 The 16 Named AI Anti-Pattern Tells +1. **Purple-Gradient Hero**: Purple-to-pink/blue background gradient with white centered text. +2. **Inter-Everywhere**: Single unpaired font family used across display and body. +3. **3-Column Feature Grid**: 3 identical columns with generic icons and 2-line headings. +4. **Card-in-Card**: Arbitrary nested card containers with no semantic hierarchy. +5. **Gradient Headline**: `background-clip: text` linear gradient fill on headlines. +6. **Side-Stripe Card**: 4–6px thick colored border on card edges as a decorative crutch. +7. **Full-Viewport Centered Hero**: `min-height: 100vh` centered short sentence + massive CTA. +8. **Pure Black / Pure White**: `#000000` or `#ffffff` flat surfaces (must use tinted neutrals). +9. **Default-Attractor Sameness**: Reusing identical macrostructures across consecutive pages. +10. **Specimen Fall-Through**: Defaulting to editorial `01 - HELLO` specimen layout for SaaS. +11. **The AI Nav**: Wordmark left, 4-5 links center, CTA right, 1px bottom border. +12. **The AI Footer**: 4 generic columns (Product, Company, Resources, Legal) + copyright. +13. **Aurora-Blob Background**: Flowing organic mesh blobs in purple/cyan behind hero text. +14. **Floating-Orb Decoration**: 3D spheres or blurred circles drifting aimlessly behind hero. +15. **Italic Headers**: Flipping one arbitrary word to italic (`Built to think`) for fake editorial flair. +16. **Lazy-Loaded LCP**: Adding `loading="lazy"` to the main hero image (tanks Core Web Vitals). + +### 🏷️ The 7-Axis Pre-Emit Self-Critique Stamp +Every generated prototype component, token set, or layout must be stamped with: +`/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */` +- **P** — Philosophy & School Authenticity +- **H** — Hierarchy & Layout Balance +- **E** — Encapsulation & Zero Per-Page CSS/JS +- **S** — State Completeness (8-State Wrappers) +- **R** — RTL & Typography Rigor (El Messiri + Tajawal) +- **V** — Velocity & Motion Polish (Sub-200ms Easing) +- **D** — Decision Alignment (100% Synchronized with `brand.yaml`) --- ## 🎨 8 Pluggable CSS Foundations -Lock a CSS foundation once per project during `/init`. Never mix foundations in the same project: - -| Foundation | Command Flag | Best For | Architecture Details | -|---|---|---|---| -| **Native CSS** | `--foundation=native` | Pure zero-dependency design systems | Custom CSS variables & semantic component classes in `tokens.css` & `components.css`. | -| **Tailwind Utility** | `--foundation=tailwind` | Fast utility-first prototyping | Tailwind v4 utility engine via CDN with custom design-token utility mappings. | -| **daisyUI** | `--foundation=daisyui` | Rapid web application screens | Tailwind CDN + daisyUI component library themed via custom token CSS variables. | -| **Hybrid** | `--foundation=hybrid` | Signature brand apps & dashboards | daisyUI composite application widgets + Native CSS for signature brand components. | -| **shadcn/ui** | `--foundation=shadcn` | Accessible primitive tokens | Tailwind v4 + Radix UI accessible token mapping & design primitive styles. | -| **Pico CSS v2** | `--foundation=pico` | Ultra-fast semantic minimalist sites | Semantic HTML5 tags styled cleanly without utility class bloat. | -| **Bootstrap 5.3** | `--foundation=bootstrap` | Enterprise apps & dark themes | Enterprise CSS variables with native `data-bs-theme="dark"` theme switching. | -| **Alpine + Tailwind** | `--foundation=alpine` | Interactive client micro-interactions | Alpine.js reactive state directives (`x-data`, `x-on`) paired with Tailwind v4 utilities. | - ---- - -## 🛡️ Anti-Slop Governance & Quality Bar (Rule 8) - -`tidyfactor-design` enforces strict anti-slop rules derived from premier design engineering standards (*Taste-Skill*, *Hallmark*, *Anthropic Frontend-Design*, *Website Cloner*). - -> [!IMPORTANT] -> **Pre-Emit Self-Critique Stamp**: Every generated prototype page or component is evaluated on 6 axes: **Philosophy (P)**, **Hierarchy (H)**, **Execution (E)**, **Specificity (S)**, **Restraint (R)**, and **Variety (V)**. Scores < 3 trigger an automatic revision pass before emission: -> `/* Pre-emit critique: P5 H4 E5 S4 R5 V5 */` - -### ⚙️ The Three-Dial System (`brand.json`) -Configure layout asymmetry, animation depth, and data density dynamically: - -```json -{ - "dials": { - "designVariance": 8, - "motionIntensity": 6, - "visualDensity": 4 - } -} -``` - -### ⛔ 16 Auto-Rejected AI Anti-Patterns - -| Anti-Pattern Tell | Why It Fails | Mechanical Quality Rule | -|---|---|---| -| **Purple-Gradient Hero** | Most recognized AI template tell | Single anchor hue; no gradient hero backgrounds. | -| **Inter-Everywhere** | Unpaired single-font layout | Pair distinctive display + body faces (`El Messiri` / `Tajawal` / `Outfit`). | -| **3-Column Feature Grid** | Generic 3-equal card row | Asymmetric grid, variable card heights, or inline icon lists. | -| **Card-in-Card Bloat** | Unnecessary nested container cards | Banned. Flat borders or surface tinting without extra containers. | -| **Gradient Headline Fill** | `background-clip: text` linear gradient | Solid high-contrast text; reserve gold gradient for dark luxury accents. | -| **Side-Stripe Card** | 4–6px thick border on left edge of card | Banned. Clean 1px border or subtle elevation shadow. | -| **Full-Viewport Hero** | `min-height: 100vh` centered short sentence | Hero desktop top padding capped at `pt-24` (6rem); headline max 2 lines. | -| **Pure Black / White** | Pure `#000000` or `#ffffff` flat surfaces | Must use tinted neutrals (`#0F172A`, `#F8FAFC`). | -| **Default Sameness** | Same macrostructure across consecutive pages | Vary layout archetypes across project screens (`memory/13-layout-archetypes.md`). | -| **Specimen Fall-Through**| Defaulting to editorial `01 - HELLO` specimen | Match surface archetype to domain register (e.g. `interface` for SaaS). | -| **The AI Nav** | Wordmark left, 4 links center, CTA right | Banned. Use N1–N9 catalog (e.g. N1 Floating Pill or N5 Edge-Aligned). | -| **The AI Footer** | 4 equal columns + social row + copyright | Banned. Use Ft1–Ft8 catalog (e.g. Ft1 Mast-Headed or Ft5 Letter Close). | -| **Aurora-Blob Background** | Organic mesh blobs drifting behind hero | Banned. Use soft radial `#glow` layer or clean ambient ground. | -| **Floating-Orb Decoration** | Blurred 3D spheres drifting behind text | Banned. Keep background clean and focused on copy/media. | -| **Italic Header Trick** | Flipping one word in header to italic | Banned. Rely on genuine typographic hierarchy and weight contrast. | -| **Lazy-Loaded LCP** | Adding `loading="lazy"` to hero image | Banned. Hero LCP images must load eager; lazy-load below-the-fold only. | - ---- - -## 🏛️ System Architecture & File Structure - -```mermaid -graph TD - A["User Prompt / Command"] --> B["SKILL.md (~350 Tokens Load)"] - B --> C["24 Runtime Commands across 7 Lifecycle Stages"] - C --> D["Outcome Workflows (references/workflows/)"] - C --> E["Operational Memory (memory/ & references/memory/)"] - - D --> F["Shared Design System (design-system/)"] - F --> G["tokens.css & brand.json (v2)"] - F --> H["components.css & base.css"] - F --> I["motion.js & interactions.js"] - - G --> J["Markup-Only Pages (pages/*.html)"] - H --> J - I --> J -``` +Lock your foundation once per project during `/brief` or `/init`. Never mix foundations: -### 📁 Project Directory Layout - -``` -my-prototype/ -├── design-system/ -│ ├── tokens.css ← Single source of truth: color, typography, spacing, radius, motion -│ ├── base.css ← CSS reset, typography inheritance & dark mode rules -│ ├── components.css ← Shared component library (buttons, cards, navbars, modals) -│ ├── utilities.css ← Spatial layout & container helper classes -│ ├── motion.js ← Shared scroll-reveals, ambient color shifts & choreography -│ ├── interactions.js ← Shared dropdowns, tabs, modals & toggle behavior -│ └── brand.json ← Identity tokens, voice registers & brand dials (v2 schema) -├── pages/ -│ ├── index.html ← Landing page markup ONLY (zero inline CSS/JS) -│ ├── dashboard.html ← App dashboard markup ONLY -│ └── pricing.html ← Pricing table markup ONLY -├── scripts/ ← Python Power Tools (palette extraction, BG removal, WebP compression) -├── docs/ ← Handoff specs and research documentation -├── proto-nav.js ← Dev-only floating prototype toolbar -└── brand.json ← Project-root brand identity configuration -``` +1. **Native CSS** — Pure modern CSS custom properties, zero dependencies, ultimate portability. +2. **Tailwind CSS** — Utility-first workflow mapped to design tokens via `tailwind.config.js`. +3. **daisyUI** — Semantic component classes over Tailwind with pre-built theme mappings. +4. **Hybrid** — Native design tokens (`tokens.css`) paired with utility classes for page assembly. +5. **shadcn/ui** — Modern headless component architecture with Tailwind utility styling. +6. **Pico CSS** — Classless, ultra-light semantic CSS for minimal content-first platforms. +7. **Bootstrap 5** — SASS token overrides for enterprise migrations. +8. **Alpine.js** — Lightweight declarative reactive micro-interactions without SPAs. --- -## 🇸🇦 Native Arabic & RTL System +## 🛠️ Python Tooling Suite (`scripts/`) -`tidyfactor-design` provides first-class support for bilingual Middle Eastern digital products: - -- **Typography Rules**: Headings = **El Messiri**, Body = **Tajawal**. Never Amiri for headings above 24px. -- **RTL Logical Properties**: Layout direction switching (`dir="rtl"` / `dir="ltr"`) uses CSS logical properties (`margin-inline-start`, `padding-inline`, `border-inline-end`). -- **Modesty Guidelines**: Cultural visual rules for regional targets (modest photography selection, proper emblem placement). -- **RTL Nav & Toolbar**: Floating prototype toolbar (`proto-nav.js`) automatically mirrors alignment in RTL mode. +- **`scripts/audit_design.py`**: AST parser verifying zero per-page CSS/JS, token compliance, and anti-pattern tells. +- **`scripts/extract_palette.py`**: Computes WCAG 2.1 AAA contrast ratios and generates `tokens.css` + `brand.yaml`. Supports `--source
-# tidyfactor-design `v1.5.0`
+# tidyfactor-design `v1.9.0`
-**Motor de Ciclo de Vida de Design UI Nativo em Código e Prototipagem Interativa para Agentes de IA**
+**Motor de Ciclo de Vida de Design UI Nativo em Código e Suíte Anti-Slop para Agentes de IA**
[](https://www.npmjs.com/package/@tidyfactor/design)
[](LICENSE)
@@ -13,32 +13,90 @@
---
-## ⚡ Início Rápido (Quickstart)
+## 💡 Filosofia Central: Separação de Inteligência de Design da Implementação
-```bash
-# Instalação e execução via NPX
-npx @tidyfactor/cli-design
-```
+A base conceitual do **TidyFactor Design** baseia-se na separação estrita entre o **conhecimento e inteligência de design** e a **execução técnica em código**:
-Ou execute diretamente dentro do seu assistente de IA (*Google Antigravity, Claude Code, Cursor, Codex*):
-```text
-/tidyfactor-design
```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Agent
+ ↓
+ Design System
+ ↓
+ HTML/CSS/JS
+ ↓
+ Audit
+ ↓
+ Handoff
+```
+
+Esta arquitetura transforma a skill em um **Sistema Operacional de Engenharia de Design** reutilizável e determinístico entre projetos variados. Em vez de simplesmente solicitar ao modelo que "crie uma interface bonita", o agente executa um ciclo de vida de design formal.
---
-## 📋 Matriz de Comandos Principais
+## ⚖️ TidyFactor Design vs. Figma: Alternativa Nativa em Código
-| Comando | Objetivo e Resultado | Fluxo de Trabalho |
+O TidyFactor Design não busca ser um aplicativo de desenho vetorial convencional, mas sim uma **Alternativa Nativa em Código ao Figma (Code-Native Alternative)**:
+
+| Característica | Figma | TidyFactor Design |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **Paradigma** | Ferramenta visual de design | Fluxo de design nativo em código |
+| **Ambiente** | Focado em Canvas (Canvas-centric) | Focado em Código (Code-centric) |
+| **Público** | Designers visuais | Agentes de IA + Desenvolvedores + Design Engineers |
+| **Componentes** | Componentes e variáveis visuais | Tokens + componentes + fluxos determinísticos |
+| **Prototipagem** | Protótipos visuais de tela | Protótipos reais em HTML/CSS/JS (zero build step) |
+| **Handoff** | Transferência manual Designer → Dev | Design e implementação unificados no mesmo ambiente |
+| **Governança** | Inspeção visual manual | Validações mecânicas de qualidade automatizadas |
+| **Escopo** | Criação de interface de usuário | Gestão completa do ciclo de vida de design |
+
+---
+
+## 🧠 O Que É Memória Operacional (Operational Memory)?
+
+A memória operacional (`references/memory/`) não consiste em artigos teóricos, mas em **regras acionáveis, matrizes estruturadas, esquemas de design e restrições executáveis**:
+
+- **Matriz Tipográfica** (`01-typography-matrix.md`): Hierarquias e escalas sem suposições.
+- **Arquétipos de Layout** (`02-layout-archetypes.md`): Grades e disposições espaciais.
+- **Princípios de Movimento** (`03-motion-principles.md`): Curvas de animação física, tempos e integração GSAP.
+- **Anatomia de Componentes** (`04-component-anatomy.md`): Estrutura canônica de elementos UI.
+- **Quality Bar** (`06-quality-bar.md`): Auditoria mecânica em 7 eixos (`P5 H5 E5 S5 R5 V5 D5`).
+- **Regras RTL e Árabe** (`14-arabic-rtl-matrix.md`): Tipografia e adaptação bidirecional nativa.
+
+O modelo não precisa redescobrir como projetar uma tipografia a cada execução; ele opera sobre padrões já validados e testados.
+
+---
+
+## 🚫 Governança Anti-Slop: Qualidade Mecânica Auditável
+
+Ao contrário de geradores genéricos de IA que produzem interfaces genéricas e artificiais, o TidyFactor Design estabelece **restrições formais de auditoria**:
+
+- ❌ **Bloqueio de Clichês de IA**: Eliminação de *Purple Gradient Heros*, *Inter Everywhere*, grids de 3 colunas repetitivos, cartões aninhados sem contraste (*Card-in-card*) e orbes flutuantes (*Aurora blobs*).
+- 🎨 **Sistemas de Design Coesos**: Paletas com contraste WCAG AAA e superfícies táteis com profundidade real.
+- ⚡ **Primazia YAML (Regra 15)**: Definição de tokens de marca em `brand.yaml`, economizando entre 35% e 50% de tokens de contexto para os LLMs.
+
+---
+
+## 🔄 As 7 Fases do Ciclo de Vida e os 24 Comandos
+
+1. **Discovery**: `/study`, `/brief`
+2. **Foundation**: `/init`, `/brand`, `/typography`, `/school`, `/tokens`, `/palette`, `/assets`
+3. **Architecture**: `/layout`, `/nav-footer`, `/page`, `/dashboard`
+4. **Components**: `/components`, `/states`
+5. **Motion**: `/motion`, `/flow`, `/i18n`
+6. **Quality**: `/perf`, `/audit`, `/clone`, `/retrofit`
+7. **Delivery**: `/handoff`, `/deploy`
---
-## 📖 Especificação Técnica Canônica
+## 📚 Documentação e Guias
-Para a arquitetura detalhada, esquemas JSON completos e código fonte nativo, consulte a [Documentação Técnica Canônica em Inglês (README.md)](README.md).
+- 📖 [Guia Completo de Engenharia e Uso (docs/GUIDE.md)](docs/GUIDE.md)
+- 📖 [Guia de Engenharia em Árabe (docs/GUIDE.ar.md)](docs/GUIDE.ar.md)
+- 📋 [Especificação Técnica Completa (README.md)](README.md)
diff --git a/README.zh.md b/README.zh.md
index cc417bf..4debf2d 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,8 +1,8 @@
-# tidyfactor-design `v1.5.0`
+# tidyfactor-design `v1.9.0`
-**面向 AI 智能体的代码原生 UI 设计生命周期与高保真交互原型引擎**
+**代码原生 UI 设计生命周期引擎与 AI 智能体 Anti-Slop 设计系统套件**
[](https://www.npmjs.com/package/@tidyfactor/design)
[](LICENSE)
@@ -13,32 +13,90 @@
---
-## ⚡ 快速上手 (Quickstart)
+## 💡 核心设计哲学：将“设计智能”与“设计实现”彻底解耦
-```bash
-# 通过 NPX 快速运行
-npx @tidyfactor/cli-design
-```
+**TidyFactor Design** 的核心突破在于将**设计知识与智能（Design Intelligence）**与**具体的代码实现（Implementation）**进行严格解耦：
-或在 AI 编码助手 (*Google Antigravity, Claude Code, Cursor, Codex*) 中调用：
-```text
-/tidyfactor-design
```
+ DESIGN INTELLIGENCE
+ │
+ ┌──────────┴──────────┐
+ ↓ ↓
+ Operational Memory Workflows
+ │ │
+ └──────────┬──────────┘
+ ↓
+ AI Agent
+ ↓
+ Design System
+ ↓
+ HTML/CSS/JS
+ ↓
+ Audit
+ ↓
+ Handoff
+```
+
+这一架构将技能转变为一个可在多个项目间无缝复用、确定性执行的**设计工程操作系统（Design Engineering Operating System）**。AI Agent 不再仅仅根据提示词盲目生成代码，而是按照工程化设计生命周期有序推进。
---
-## 📋 核心命令矩阵
+## ⚖️ TidyFactor Design 对比 Figma：代码原生的代际替代方案
-| 命令 | 目标与产出 | 执行工作流 |
+TidyFactor Design 并不是传统的矢量画布绘制工具，而是**面向 AI 与开发者的代码原生替代方案（Code-Native Alternative）**：
+
+| 维度 | Figma | TidyFactor Design |
|---|---|---|
-| `/brief` | Briefing de diseño y descubrimiento de marca | `workflows/brief.md` |
-| `/tokens` | Generación de design tokens y escalas | `workflows/tokens.md` |
-| `/components` | Prototipado interactivo de componentes UI | `workflows/components.md` |
-| `/page` | Montaje de páginas completas interactivas | `workflows/page.md` |
-| `/rtl` | Validación y soporte nativo RTL/Árabe | `workflows/rtl.md` |
+| **核心范式** | 视觉绘图工具 | 代码原生设计工程工作流 |
+| **工作环境** | 以画布为中心 (Canvas-centric) | 以代码为中心 (Code-centric) |
+| **目标受众** | 视觉设计师 | AI Agent + 开发者 + 设计工程师 |
+| **基础单元** | 视觉组件与变量 | Design Tokens + 原生组件 + 工作流 |
+| **原型验证** | 屏幕视觉连线原型 | 真实 HTML/CSS/JS 原型（零构建开销） |
+| **交付机制** | 设计师向开发者手动 Handoff | 设计与实现在统一代码环境中闭环 |
+| **质量治理** | 人工视觉抽检 | 机械化、自动化质量审查门禁 |
+| **业务范畴** | UI 界面绘制 | 全生命周期设计工程管理 |
+
+---
+
+## 🧠 什么是操作性记忆 (Operational Memory)？
+
+操作性记忆 (`references/memory/`) 绝非冗长的泛论文章，而是**纯粹的规则、矩阵、数据架构与约束条件**：
+
+- **排版矩阵** (`01-typography-matrix.md`): 确定性字号与层级规则。
+- **布局原型** (`02-layout-archetypes.md`): 栅格与空间架构定义。
+- **动效原则** (`03-motion-principles.md`): 物理动画曲线、时间尺度与 GSAP 原生模式。
+- **组件解剖** (`04-component-anatomy.md`): 界面组件标准构造规范。
+- **质量门禁** (`06-quality-bar.md`): 七维自评质检戳记 (`P5 H5 E5 S5 R5 V5 D5`)。
+- **阿语与 RTL 规范** (`14-arabic-rtl-matrix.md`): 双向流与高质量阿文字体规范。
+
+AI 智能体无需在每次生成时从头猜测设计原则，直接调用已验证的工程矩阵。
+
+---
+
+## 🚫 Anti-Slop 治理：可验证的机械质量门禁
+
+普通 AI 生成的 UI 往往充斥着千篇一律的模式与工业废料（Slop）。TidyFactor Design 设立了强力的**机械质检验收标准**：
+
+- ❌ **严禁 AI 刻板套路**：杜绝紫色渐变 Hero（Purple Gradient）、滥用 Inter 字体、千篇一律的三栏卡片网格、无序卡片嵌套（Card-in-card）以及漂浮光斑（Aurora blobs）。
+- 🎨 **定制化设计系统**：严格遵守 WCAG AAA 对比度标准，构建具有真实触感与层次的界面。
+- ⚡ **YAML 优先原则 (Rule 15)**：品牌与设计 Token 优先采用 `brand.yaml`，降低 35–50% 的上下文 Token 占用。
+
+---
+
+## 🔄 七大生命周期阶段与 24 个指令
+
+1. **Discovery (探索阶段)**: `/study`, `/brief`
+2. **Foundation (基础阶段)**: `/init`, `/brand`, `/typography`, `/school`, `/tokens`, `/palette`, `/assets`
+3. **Architecture (架构阶段)**: `/layout`, `/nav-footer`, `/page`, `/dashboard`
+4. **Components (组件阶段)**: `/components`, `/states`
+5. **Motion (动效阶段)**: `/motion`, `/flow`, `/i18n`
+6. **Quality (质检阶段)**: `/perf`, `/audit`, `/clone`, `/retrofit`
+7. **Delivery (交付阶段)**: `/handoff`, `/deploy`
---
-## 📖 完整技术规范与文档
+## 📚 详细文档与工程指南
-如需查看深层架构设计、完整 JSON Schema 契约和原生代码，请参阅[英文权威技术文档 (README.md)](README.md)。
+- 📖 [完整设计工程与用户指南 (docs/GUIDE.md)](docs/GUIDE.md)
+- 📖 [阿拉伯语工程指南 (docs/GUIDE.ar.md)](docs/GUIDE.ar.md)
+- 📋 [完整技术规范 (README.md)](README.md)
diff --git a/SKILL.md b/SKILL.md
index b71adf2..7eff4af 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -2,38 +2,37 @@
name: tidyfactor-design
description: "Code-native UI design lifecycle engine (Figma alternative) with Contextual Decision Layer (CDL). Supports all 7 design stages with zero per-page CSS/JS and pluggable CSS foundations (Native, Tailwind, daisyUI, Pico, Hybrid). Trigger on commands 'brief', 'study', 'init', 'brand', 'tokens', 'palette', 'layout', 'components', 'page', 'dashboard', 'motion', 'i18n', 'audit', 'deploy', or design system requests."
---
+
# TidyFactor Design (Code-Native UI Design Lifecycle Engine)
A command dispatcher supporting the full UI design lifecycle—from discovery through developer handoff—with zero build steps and complete design system consistency.
-## Lifecycle Commands (7 Stages)
-
-| Lifecycle Stage | User intent | Command | What it loads |
-|---|---|---|---|
-| **1. Discovery** | Strategic Design Discovery & Brief Resolution | `references/commands/brief.md` | `references/workflows/brief.md` + `references/memory/decision-points.md` + `references/memory/quality-bar.md` |
-| **1. Discovery** | Extract design DNA from reference URL/image | `references/commands/study.md` | `references/commands/study.md` + `references/memory/01-design-schools.md` |
-| **2. Foundation** | Start brand-new design system / prototype | `references/commands/init.md` | `references/workflows/init-prototype.md` + `references/memory/architecture.md` + `references/memory/foundations.md` |
-| **2. Foundation** | Scaffold or manage brand.json v2 schema | `references/commands/brand.md` | `references/commands/brand.md` + `references/memory/11-brand-json-v2.md` |
-| **2. Foundation** | Select mood-routed typography pairing | `references/commands/typography.md` | `references/commands/typography.md` + `references/memory/12-typography-matrix.md` |
-| **2. Foundation** | Choose design movement / visual direction | `references/commands/school.md` | `references/commands/school.md` + `references/memory/01-design-schools.md` |
-| **2. Foundation** | Manage design tokens and brand colors | `references/commands/tokens.md` | `references/commands/tokens.md` + `references/memory/02-design-tokens.md` |
-| **2. Foundation** | Scaffold color palette from reference image | `references/commands/palette.md` | `references/commands/palette.md` + `references/memory/02-design-tokens.md` |
-| **2. Foundation** | Asset hygiene and image optimization | `references/commands/assets.md` | `references/commands/assets.md` + `references/memory/10-python-tooling.md` |
-| **3. Architecture** | Select macrostructure layout archetype | `references/commands/layout.md` | `references/commands/layout.md` + `references/memory/13-layout-archetypes.md` |
-| **3. Architecture** | Choose navigation (N1-N9) and footer (Ft1-Ft8) | `references/commands/nav-footer.md` | `references/commands/nav-footer.md` + `references/memory/14-nav-footer-catalog.md` |
-| **3. Architecture** | Add a new content or marketing page | `references/commands/page.md` | `references/workflows/init-prototype.md` + `references/memory/05-component-anatomy.md` |
-| **3. Architecture** | Add a new dashboard or app screen | `references/commands/dashboard.md` | `references/workflows/init-prototype.md` + `references/memory/05-component-anatomy.md` |
-| **4. Components** | Manage shared UI components (8-state wrappers) | `references/commands/components.md` | `references/commands/components.md` + `references/memory/05-component-anatomy.md` |
-| **4. Components** | Define interactive component states | `references/commands/states.md` | `references/commands/states.md` + `references/memory/05-component-anatomy.md` |
-| **5. Motion** | Add shared animations, recipes & ambient layers | `references/commands/motion.md` | `references/commands/motion.md` + `references/memory/04-motion-principles.md` |
-| **5. Motion** | Wire interactive prototype navigation | `references/commands/flow.md` | `references/commands/flow.md` + `references/memory/09-prototype-flow.md` |
-| **5. Motion** | Add Arabic/RTL or bilingual localization | `references/commands/i18n.md` | `references/commands/i18n.md` + `references/memory/08-arabic-bilingual.md` |
-| **6. Quality** | Verify asset performance budgets & size limits | `references/commands/perf.md` | `references/commands/perf.md` + `references/memory/15-performance-budget.md` |
-| **6. Quality** | Audit structural consistency & quality bar | `references/commands/audit.md` | `references/workflows/audit-prototype.md` + `references/memory/quality-bar.md` |
-| **6. Quality** | Extract design system from external site | `references/commands/clone.md` | `references/workflows/clone-prototype.md` + `references/memory/03-narrative-conversion.md` |
-| **6. Quality** | Unify drifted prototype under design system | `references/commands/retrofit.md` | `references/workflows/retrofit-prototype.md` + `references/memory/07-consistency-contract.md` |
-| **7. Delivery** | Export developer handoff specs & token map | `references/commands/handoff.md` | `references/commands/handoff.md` + `references/memory/11-brand-json-v2.md` |
-| **7. Delivery** | Local preview and deployment | `references/commands/deploy.md` | `references/commands/deploy.md` + `references/memory/06-quality-bar.md` |
+## Commands
+
+| User intent | Command | What it loads |
+|---|---|---|
+| Strategic Discovery & Brief Resolution | `references/commands/brief.md` | `workflows/brief.md` + `memory/decision-points.md` + `memory/06-quality-bar.md` |
+| Extract design DNA from reference | `references/commands/study.md` | `commands/study.md` + `memory/01-design-schools.md` + `memory/06-quality-bar.md` |
+| Start brand-new design system / prototype | `references/commands/init.md` | `workflows/init-prototype.md` + `memory/architecture.md` + `memory/foundations.md` |
+| Scaffold or manage brand tokens (YAML / JSON) | `references/commands/brand.md` | `commands/brand.md` + `memory/11-brand-json-v2.md` |
+| Mood-routed typography pairing | `references/commands/typography.md` | `commands/typography.md` + `memory/12-typography-matrix.md` |
+| Select design school & movement | `references/commands/school.md` | `commands/school.md` + `memory/01-design-schools.md` |
+| Design tokens, palette & color extraction | `references/commands/tokens.md` | `commands/tokens.md` + `memory/02-design-tokens.md` |
+| Asset hygiene, media & image optimization | `references/commands/assets.md` | `commands/assets.md` + `memory/10-python-tooling.md` |
+| Macrostructure layout archetype selection | `references/commands/layout.md` | `commands/layout.md` + `memory/13-layout-archetypes.md` |
+| Navigation (N1-N9) & Footer (Ft1-Ft8) systems | `references/commands/nav-footer.md` | `commands/nav-footer.md` + `memory/14-nav-footer-catalog.md` |
+| Add content/marketing page or app screen | `references/commands/page.md` | `workflows/init-prototype.md` + `memory/05-component-anatomy.md` |
+| Manage shared UI components & 8-state catalog | `references/commands/components.md` | `commands/components.md` + `memory/05-component-anatomy.md` |
+| Core Component Matrices (Eyebrow, Hero, Cards, CTA, Seams, Metrics) | `references/commands/components.md` | `memory/21-eyebrow-kicker-matrix.md` through `28-shared-motion-primitives.md` |
+| Shared animations, scroll & motion recipes | `references/commands/motion.md` | `commands/motion.md` + `memory/04-motion-principles.md` + `memory/28-shared-motion-primitives.md` |
+| Interactive prototype navigation flow | `references/commands/flow.md` | `commands/flow.md` + `memory/09-prototype-flow.md` |
+| Arabic/RTL localization & bidirectional UI | `references/commands/i18n.md` | `commands/i18n.md` + `memory/08-arabic-bilingual.md` |
+| Asset performance budget & size verification | `references/commands/perf.md` | `commands/perf.md` + `memory/15-performance-budget.md` |
+| Structural consistency audit & quality bar | `references/commands/audit.md` | `workflows/audit-prototype.md` + `memory/06-quality-bar.md` |
+| Extract design system from external URL/clone | `references/commands/clone.md` | `workflows/clone-prototype.md` + `memory/03-narrative-conversion.md` |
+| Unify drifted prototype under design system | `references/commands/retrofit.md` | `workflows/retrofit-prototype.md` + `memory/07-consistency-contract.md` |
+| Developer handoff specs & CSS variable map | `references/commands/handoff.md` | `commands/handoff.md` + `memory/11-brand-json-v2.md` |
+| Local preview and static deployment | `references/commands/deploy.md` | `commands/deploy.md` + `memory/06-quality-bar.md` |
Read only the command file that matches the request. Do not load all commands simultaneously.
@@ -47,8 +46,11 @@ Read only the command file that matches the request. Do not load all commands si
## Tooling Scope (Rule 10)
-- **Languages**: Python 3 (stdlib, Pillow/rembg for asset optimization)
-- **Mutations**: Read-only audits (`audit_design`), file creation (`extract_palette`), image processing (`optimize_assets`)
-- **Network**: None required
-- **Companion MCP**: Invocable via `tidyfactor-brain`'s `run_skill_tool(skill_id="tidyfactor-design", ...)`
+- **Languages**: Python 3 (stdlib, Pillow, rembg)
+- **Mutations**: Read-only audits (`audit_design`), palette token generation (`extract_palette`), image optimization (`optimize_media`)
+- **Network**: None required (100% offline deterministic execution)
+
+## Skill vs MCP Boundary (Rule 12)
+- **Inside Skill**: Static design tokens, typography pairings, layout archetypes, component matrices (21–28), and zero-build CSS templates.
+- **MCP Layer**: Companion MCP tools invocable via `tidyfactor-brain`'s `run_skill_tool(skill_id="tidyfactor-design", ...)`; live remote asset scraping and database operations delegate to external MCP servers.
diff --git a/brand.json b/brand.json
index 30ff51b..a59f4ae 100644
--- a/brand.json
+++ b/brand.json
@@ -1,6 +1,6 @@
{
"name": "TidyFactor Design",
- "version": "1.8.0",
+ "version": "1.9.0",
"schemaVersion": "brand-core-v2",
"meta": {
"product": "TidyFactor Design System",
diff --git a/brand.yaml b/brand.yaml
new file mode 100644
index 0000000..987a89e
--- /dev/null
+++ b/brand.yaml
@@ -0,0 +1,238 @@
+name: TidyFactor Design
+version: 1.9.0
+schemaVersion: brand-core-v2
+meta:
+ product: TidyFactor Design System
+ tagline: Code-Native Interactive Prototyping Engine
+ description: A zero-bundler, framework-free design system and UI prototyping engine
+ with pluggable CSS foundations and full Arabic/RTL support.
+ version: 1.8.0
+ lastUpdated: '2026-09-02'
+identity:
+ logo:
+ full: assets/logo.svg
+ fullDark: assets/logo-dark.svg
+ mark: assets/logo-mark.svg
+ favicon: assets/favicon.svg
+ minClearSpace: 1x logo-mark height on all sides
+ minSizePx: 24
+ socialPreview:
+ ogImage: assets/og-default.png
+ ogDimensions: 1200x630
+voice:
+ tone: confident, direct, teacher-not-salesperson
+ personality:
+ - direct
+ - practical
+ - warm
+ - no-fluff
+ registers:
+ professional: Direct, precise, clear, task-focused for transactions and settings
+ casual: Warm, encouraging, inviting for onboarding and feature discovery
+ error: Empathetic, clear fix provided, zero blame
+ success: Celebratory, concise, clear next step
+ readingLevel: plain language, avoid jargon unless audience is technical
+ doNotUse:
+ - synergy
+ - leverage (as a verb)
+ - revolutionary
+ - game-changing
+ - simply/just/easily
+ preferredPerson: second person (you)
+colors:
+ light:
+ background: '#FFFFFF'
+ surface: '#F8FAFC'
+ surface2: '#F1F5F9'
+ border: '#E2E8F0'
+ text: '#0F172A'
+ textMuted: '#64748B'
+ primary: '#4F46E5'
+ primaryForeground: '#FFFFFF'
+ secondary: '#06B6D4'
+ secondaryForeground: '#FFFFFF'
+ accent: '#F59E0B'
+ success: '#12B76A'
+ warning: '#F79009'
+ danger: '#EF4444'
+ info: '#4F46E5'
+ codeBackground: '#F8FAFC'
+ dark:
+ background: '#0F172A'
+ surface: '#1E293B'
+ surface2: '#334155'
+ border: '#475569'
+ text: '#F8FAFC'
+ textMuted: '#94A3B8'
+ primary: '#818CF8'
+ primaryForeground: '#0F172A'
+ secondary: '#22D3EE'
+ secondaryForeground: '#0F172A'
+ accent: '#FBBF24'
+ success: '#34D399'
+ warning: '#FBBF24'
+ danger: '#F87171'
+ info: '#818CF8'
+ codeBackground: '#1E293B'
+ chartPalette:
+ - '#4F46E5'
+ - '#06B6D4'
+ - '#F59E0B'
+ - '#12B76A'
+ - '#EF4444'
+ - '#8B5CF6'
+ contrastPolicy: WCAG AA minimum (4.5:1 body text, 3:1 large text/UI) in both light
+ and dark themes
+typography:
+ families:
+ heading:
+ primary: El Messiri
+ fallback: Georgia, serif
+ body:
+ primary: Tajawal
+ fallback: Inter, system-ui, sans-serif
+ display:
+ primary: Outfit
+ fallback: system-ui, sans-serif
+ mono:
+ primary: JetBrains Mono
+ fallback: Menlo, monospace
+ arabicHeading: El Messiri
+ arabicBody: Tajawal
+ weights:
+ light: 300
+ regular: 400
+ medium: 500
+ semibold: 600
+ bold: 700
+ scale:
+ xs: 12px
+ sm: 14px
+ base: 16px
+ lg: 18px
+ xl: 20px
+ 2xl: 24px
+ 3xl: 30px
+ 4xl: 36px
+ 5xl: 48px
+ 6xl: 60px
+ lineHeight:
+ tight: 1.2
+ normal: 1.5
+ relaxed: 1.75
+ letterSpacing:
+ tight: -0.02em
+ normal: '0'
+ wide: 0.02em
+ googleFontsUrl: https://fonts.googleapis.com/css2?family=El+Messiri:wght@400;600;700&family=Outfit:wght@400;500;600;700&family=Tajawal:wght@300;400;500;700&family=JetBrains+Mono:wght@400;500&display=swap
+spacing:
+ baseUnit: 4px
+ scale:
+ '0': 0px
+ '1': 4px
+ '2': 8px
+ '3': 12px
+ '4': 16px
+ '6': 24px
+ '8': 32px
+ '12': 48px
+ '16': 64px
+ '24': 96px
+radius:
+ none: 0px
+ sm: 6px
+ md: 12px
+ lg: 16px
+ xl: 24px
+ full: 9999px
+ default: 12px
+shadows:
+ sm: 0 1px 2px rgba(0,0,0,0.06)
+ md: 0 4px 12px rgba(0,0,0,0.10)
+ lg: 0 12px 32px rgba(0,0,0,0.16)
+ focusRing: 0 0 0 3px color-mix(in srgb, var(--primary) 40%, transparent)
+motion:
+ duration:
+ fast: 120ms
+ base: 200ms
+ slow: 400ms
+ easing:
+ standard: cubic-bezier(0.4,0,0.2,1)
+ emphasized: cubic-bezier(0.2,0,0,1)
+ spring: cubic-bezier(0.34,1.56,0.64,1)
+ reducedMotion: 'honor prefers-reduced-motion: disable scroll-driven and parallax
+ effects, keep only opacity/color transitions'
+ scope: cinematic/scroll-driven motion is reserved for marketing surfaces only —
+ never in docs, dashboard, or transactional UI
+breakpoints:
+ sm: 640px
+ md: 768px
+ lg: 1024px
+ xl: 1280px
+ 2xl: 1536px
+iconography:
+ set: lucide
+ strokeWidth: 1.75
+ sizes:
+ sm: 16px
+ md: 20px
+ lg: 24px
+ rule: never mix icon sets on the same surface
+components:
+ button:
+ radius: radius.md
+ paddingX: spacing.4
+ paddingY: spacing.2
+ primaryBg: colors.primary
+ primaryFg: colors.primaryForeground
+ hoverOpacity: 0.9
+ disabledOpacity: 0.5
+ input:
+ radius: radius.sm
+ border: colors.border
+ focusRing: shadows.focusRing
+ background: colors.surface
+ card:
+ radius: radius.lg
+ border: colors.border
+ background: colors.surface
+ shadow: shadows.sm
+ codeBlock:
+ background: colors.codeBackground
+ radius: radius.md
+ fontFamily: typography.families.mono
+localization:
+ defaultLocale: en
+ supportedLocales:
+ - en
+ - ar
+ rtl: true
+ rtlLocales:
+ - ar
+ mirrorOnRtl:
+ - sidebar
+ - breadcrumb
+ - tableOfContents
+ - iconsWithDirection
+ dateFormat:
+ en: MMM D, YYYY
+ ar: D MMMM YYYY
+accessibility:
+ minTouchTarget: 44px
+ focusVisible: always visible, never suppressed with outline:none without a replacement
+ altTextPolicy: required on every meaningful image; decorative images use alt=''
+foundation: native
+school: minimalist
+usage:
+ sharedBy:
+ - tidyfactor-design
+ - tidyfactor-cinematic
+ - future kits (Dashboard, Admin, LMS, Commerce)
+ rules:
+ - Every surface reads tokens from this file — never hardcode a hex value or font
+ name inline.
+ - Brand colors (primary, logo) do not change between light/dark modes — only surface,
+ background, border, and text tokens do.
+ - If this file changes, regenerate dependent surfaces rather than manually patching
+ colors.
+ - Extend by adding new tokens, not by overriding existing ones per-surface.
diff --git a/dist/tidyfactor-design.skill b/dist/tidyfactor-design.skill
deleted file mode 100644
index 9c49cd7..0000000
Binary files a/dist/tidyfactor-design.skill and /dev/null differ
diff --git a/dist/tidyfactor-design/.tidyfactor b/dist/tidyfactor-design/.tidyfactor
deleted file mode 100644
index 085507c..0000000
--- a/dist/tidyfactor-design/.tidyfactor
+++ /dev/null
@@ -1,52 +0,0 @@
-{
- "ecosystem": "tidyfactor",
- "track": "design",
- "name": "tidyfactor-design",
- "version": "1.8.0",
- "npmPackage": "@alwkala/tidyfactor-design",
- "github": "https://github.com/TidyFactor/Design",
- "skillFile": "../tidyfactor-design-v1.8.0.skill",
- "category": "design-system",
- "type": "interactive-prototyping",
- "outputs": [
- "design-system/",
- "pages/"
- ],
- "foundations": [
- "native",
- "tailwind",
- "daisyui",
- "hybrid"
- ],
- "commands": [
- "brief",
- "init",
- "school",
- "tokens",
- "palette",
- "assets",
- "components",
- "page",
- "dashboard",
- "motion",
- "states",
- "flow",
- "i18n",
- "audit",
- "clone",
- "retrofit",
- "deploy"
- ],
- "visionRef": "../TidyFactor-VISION.md",
- "sibling": [
- "tidyfactor-html",
- "tidyfactor-php",
- "tidyfactor-js",
- "tidyfactor-htmx",
- "tidyfactor-cinematic"
- ],
- "commercialPartner": "alwkala",
- "website": "https://tidyfactor.com",
- "docs": "https://tidyfactor.com/documentation",
- "license": "Apache-2.0"
-}
diff --git a/dist/tidyfactor-design/AGENTS.md b/dist/tidyfactor-design/AGENTS.md
deleted file mode 100644
index 1c22e5c..0000000
--- a/dist/tidyfactor-design/AGENTS.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# AGENTS.md — TidyFactor Design System & Full UI Design Lifecycle Engine
-
-Build **interactive, code-native HTML/CSS/JS design prototypes** (Figma alternative) with strict structural visual consistency across all pages. Zero per-page CSS/JS, zero inline `