@tera-system/core 0.1.0

package/core/tera-system/design-system/DESIGN_REVIEW_STANDARDS.md

@@ -0,0 +1,241 @@
+# DESIGN_REVIEW_STANDARDS.md
+
+## الغرض
+
+هذا الملف هو **قاعدة المعايير** التي يستخدمها DesignReviewer (ناقد) كمرجع قبل وأثناء كل مراجعة تصميم. يحتوي على قوائم تفتيش قابلة للتنفيذ تغطي جميع جوانب مراجعة الواجهات.
+
+**العلاقة:** هذا ملف **مرجع معرفي** (Reference)، وليس Source of Truth لهوية العميل. Source of Truth هو `.opencode/agents/design-reviewer.md`.
+
+**الاستخدام:** يقرأ ناقد هذا الملف قبل كل مراجعة ويطبق القوائم المناسبة حسب Phase المراجعة (Pre-Implementation / Post-Implementation).
+
+---
+
+## الفهرس
+
+| القسم | المحتوى |
+|-------|---------|
+| §1 | اكتمال الحالات والسيناريوهات (Functional & Edge Case Completeness) |
+| §2 | الاتساق البصري (Visual Consistency) |
+| §3 | الجودة البصرية (Visual Quality Principles) |
+| §3.1 | راحة العين ووضوح المحتوى (Visual Comfort & Readability Safety) |
+| §4 | نظافة التصميم (Design Hygiene) |
+| §5 | تجربة المستخدم (UX Principles) |
+| §6 | الاستجابة والعرض المتعدد (Responsive) |
+| §7 | التدقيق الخاص بالعربية و RTL (RTL & Arabic Review) |
+| §8 | فحص التوكينز (Design Token Verification) |
+| §9 | الاتساق الوظيفي (Functional Consistency) |
+| §10 | حيوية البروتوتايب والطاقة البصرية (Visual Vitality & Polish) |
+
+---
+
+## §1. اكتمال الحالات والسيناريوهات (Functional & Edge Case Completeness)
+
+```
+1.1 Empty/Loading/Error States
+[ ] هل كل شاشة تعرض حالة "فارغ" (Empty) بشكل مناسب؟
+[ ] هل هناك مؤشر تحميل (Loader/Skeleton) أثناء جلب البيانات؟
+[ ] هل رسائل الخطأ مفهومة وودية — لا "Error 500" بل "تعذر الاتصال بالخادم"؟
+[ ] هل الحالات القصوى مغطاة: 0 نتائج، 1000+ نتيجة، إدخال فارغ؟
+
+1.2 Edge Cases
+[ ] ماذا يحدث عند إدخال نصوص طويلة جداً؟
+[ ] ماذا يحدث عند إدخال رموز خاصة أو emojis؟
+[ ] ماذا يحدث عند فقدان الاتصال بالإنترنت أثناء معاملة؟
+[ ] ماذا يحدث عند محاولة إجراء بدون صلاحية؟
+[ ] ماذا يحدث عند إعادة تحميل الصفحة (Refresh) — هل الحالة محفوظة؟
+```
+
+## §2. الاتساق البصري (Visual Consistency)
+
+```
+[ ] الألوان: جميعها من التوكينز المعتمدة — لا ألوان عشوائية
+[ ] الخطوط: نوع خط واحد للعناوين، واحد للنصوص — لا خلط
+[ ] المسافات (Spacing): تتبع مقياساً موحداً (4px-8px-12px-16px-24px-32px)
+[ ] الزوايا (Border-radius): موحّدة لكل نوع عنصر (أزرار 8px، بطاقات 12px، إلخ)
+[ ] الظلال (Shadows): موحّدة لكل مستوى (رفيع، متوسط، عالي)
+[ ] الأيقونات: من مجموعة واحدة، حجم واحد لكل استخدام
+
+2.1 Modal Consistency
+[ ] كل المودالات: عنوان + محتوى + أزرار إجراء في نفس الترتيب
+[ ] كل المودالات: نفس العرض والحجم النسبي
+[ ] كل المودالات: زر إغلاق في نفس المكان
+[ ] التغطية: Open → Close → Error → Blocking (خلفية معتمة)
+
+2.2 Table Consistency
+[ ] هيدر مثبت عند التمرير
+[ ] صفوف متناوبة (Stripped rows)
+[ ] Hover effect على الصفوف
+[ ] فرز (Sort) متاح على الأعمدة الرئيسية
+[ ] هل الجدول يتصرف بشكل جيد على الشاشات الصغيرة؟ (scroll أفقي أو تحويل لبطاقات)
+
+2.3 Button Consistency
+[ ] Primary button: لون واحد، حجم واحد، شكل واحد في كل التطبيق
+[ ] Secondary button: نمط واحد مختلف عن Primary
+[ ] Danger button: لون خطر واحد لكل تأكيدات الحذف
+[ ] Disabled state: موجود لجميع الأزرار
+[ ] Loading state: موجود للأزرار التي تنفذ إجراءات
+```
+
+## §3. الجودة البصرية (Visual Quality Principles)
+
+```
+[ ] التدرج الهرمي البصري واضح: عنوان الصفحة > عنوان القسم > عنوان البطاقة > النص
+[ ] المسافات البيضاء مناسبة: لا ازدحام، لا فراغات مهدرة
+[ ] المحتوى منظم بتجميع منطقي: العناصر المرتبطة قريبة من بعضها
+[ ] التناقض اللوني (Contrast): النصوص مقروءة على خلفياتها (WCAG AA minimum)
+[ ] المحتوى غير مكرر بدون سبب
+```
+
+## §3.1 راحة العين ووضوح المحتوى (Visual Comfort & Readability Safety)
+
+```
+[ ] لا يوجد نص شبه أبيض على خلفية شبه بيضاء
+[ ] لا يوجد نص باهت أو منخفض التباين على خلفية فاتحة
+[ ] لا توجد طبقات Blur/Opacity تُضعف قراءة المحتوى الأساسي
+[ ] لا تُستخدم الألوان المشبعة بكثافة في مساحات واسعة تُرهق العين
+[ ] أزرار/عناوين/مؤشرات الحالة واضحة فور النظر دون مجهود
+[ ] العناصر المهمة تظل مقروءة في أول ثانية من المشاهدة
+[ ] لا توجد واجهة تبدو جميلة فقط لكنها متعبة بصريًا
+[ ] إذا كان العنصر Modal / Overlay / Glassmorphism: يجب التحقق بصورة فعلية (Screenshot) وليس Snapshot فقط
+[ ] إذا احتاجت القراءة إلى تحديق أو تقريب الذهن: فشل فوري
+[ ] إذا تسربت الخلفية إلى النص أو قلّ الفصل البصري: فشل فوري
+[ ] إذا كان المحتوى “مرئيًا” لكنه غير “مريحًا”: فشل
+```
+
+## §4. نظافة التصميم (Design Hygiene)
+
+```
+[ ] لا معلومات برمجية ظاهرة (Stack traces, console.log, debug text)
+[ ] لا نصوص وهمية (Lorem ipsum, dummy content متروك)
+[ ] لا أيقونات/صور Broken (placeholder متروك)
+[ ] لا نصوص تقنية في واجهة المستخدم (مثل "User ID: 123" بدلاً من "اسم المستخدم")
+[ ] لا أزرار/روابط تؤدي إلى nowhere
+[ ] لا أخطاء إملائية في النصوص العربية أو الإنجليزية
+```
+
+## §5. تجربة المستخدم (UX Principles)
+
+```
+[ ] النماذج الطويلة مجزّأة: خطوات (Wizard) أو تبويبات (Tabs)
+[ ] كل إجراء مهم له تأكيد: حذف، إلغاء، حفظ، إرسال
+[ ] رسائل النجاح/الخطأ واضحة وقابلة للتنفيذ
+[ ] التغذية الراجعة الفورية: Loader, Toast, Confirmation
+[ ] تكبير الأهداف اللمسية (Touch targets): 44×44px minimum
+[ ] العناصر القابلة للنقر واضحة: أزرار، روابط، أيقونات تفاعلية
+[ ] الـ Navigation منطقي: عدد الخطوات للوصول للهدف قليل
+[ ] البحث: متاح وفعّال حيثما توجد كميات كبيرة من البيانات
+```
+
+## §6. الاستجابة والعرض المتعدد (Responsive)
+
+```
+[ ] المحتوى لا يخرج عن الشاشة في أي حجم
+[ ] الجداول تتصرف جيداً على الشاشات الصغيرة
+[ ] القوائم (Nav/Sidebar) لا تتراكض
+[ ] الأزرار الرئيسية لا تختفي ولا تصبح غير قابلة للنقر
+[ ] الـ Forms قابلة للاستخدام على الموبايل
+[ ] الصور تتكيف مع حجم الشاشة
+[ ] تم الاختبار على: 360px, 768px, 1024px, 1440px (كحد أدنى)
+```
+
+## §7. التدقيق الخاص بالعربية و RTL (RTL & Arabic Review)
+
+```
+[ ] layout: dir="rtl" مضبوط على <html> وليس فقط بعض العناصر
+[ ] CSS Logical Properties: margin-inline-start/end بدلاً من margin-left/right
+[ ] padding-inline / margin-inline / inset-inline مستخدمة بدلاً من البدائل الفيزيائية
+[ ] text-align: start | end بدلاً من left | right
+[ ] Flexbox/Grid: الاعتماد على auto-flow وليس تحديد أعمدة hardcoded
+
+7.1 Icon Mirroring
+[ ] الأسهم وchevrons: mirror (scaleX(-1)) في RTL
+[ ] أزرار الـ navigation (السابق/التالي): mirror
+[ ] Breadcrumb arrows: mirror
+[ ] أيقونات عالمية (search, checkmark, gear, star, bell): لا تلمس
+[ ] استخدام class .icon-directional مع [dir="rtl"] selector
+
+7.2 Arabic Typography
+[ ] Font size: الخط العربي أكبر 10-15% من الإنجليزي (مثلاً 16px EN → 18px AR)
+[ ] Line height: 1.8 كحد أدنى للنصوص العربية (لوجود التشكيل)
+[ ] Font selection: Cairo, Tajawal, Noto Sans Arabic, IBM Plex Sans Arabic
+[ ] تجنب justified text (text-align: justify) في العربية — يسبب فراغات غير منتظمة
+
+7.3 Form Fields in RTL
+[ ] حقول الإيميل ورقم الهاتف والـ URL: dir="ltr" صراحة
+[ ] الـ placeholders: اختبار عكسي في RTL
+[ ] Validation messages: محاذاتها صحيحة (تبدأ من اليمين)
+[ ] Mixed content: استخدام dir="auto" للنصوص غير المعروفة الاتجاه
+
+7.4 Animations
+[ ] Animations: استخدام CSS logical properties أو متغيرات (custom properties) بدلاً من translateX- المباشر
+[ ] Slide-in/slide-out panels: الاتجاه معكوس في RTL
+[ ] Progress bars: flexbox من البداية، ليس width- على element واحد
+
+7.5 Common RTL Mistakes Checklist
+[ ] Physical margin/padding → استخدام inline-start/end
+[ ] text-align: left → استخدام text-align: start
+[ ] Physical position (left:0, right:0) → استخدام inset-inline-start/end
+[ ] translateX في animations → استخدام CSS custom property
+[ ] flex-direction: row-reverse لأغراض LTR → استخدام row + direction auto
+[ ] Hardcoded LTR icons → mirror باستخدام scaleX(-1) في RTL
+[ ] dir attribute missing → موجود على <html>
+[ ] Email/phone fields ترث RTL → dir="ltr" صراحة
+[ ] لا يوجد RTL test locale → إضافة ar/he لبيئة الاختبار
+[ ] استخدام أعلام الدول لاختيار اللغة → استخدام أسماء اللغات أو الرموز
+```
+
+## §8. فحص التوكينز (Design Token Verification)
+
+```
+[ ] مصدر التوكينز محدّد: tailwind.config / variables.css / tokens.json / DESIGN.md
+[ ] القائمة المعتمدة مستخرجة: colors, spacing, fonts, radii, shadows
+[ ] الـ grep كشف: أي hardcoded values بدلاً من التوكينز؟
+[ ] المكونات المتشابهة تستخدم نفس التوكينز؟
+[ ] هل بنية التوكينز منظمة في 3 طبقات؟ (للمشاريع المتوسطة والكبيرة)
+
+8.1 Primitive Tokens (القيم الخام)
+مثال: --color-blue-500: #3B82F6
+
+8.2 Semantic Tokens (المعنى السياقي)
+مثال: --color-primary: var(--color-blue-500)
+القاعدة: المكونات تشير إلى Semantic tokens وليس Primitive مباشرة
+
+8.3 Component Tokens (مستوى المكون — اختياري)
+مثال: --btn-primary-bg: var(--color-primary)
+```
+
+## §9. الاتساق الوظيفي (Functional Consistency)
+
+```
+[ ] هل جميع الـ tooltips تتصرف بنفس الطريقة؟ (hover/mouseover/timeout)
+[ ] هل جميع الـ toasts تختفي بعد نفس المدة؟
+[ ] هل جميع الـ drawers تفتح/تغلق بنفس الآلية؟
+[ ] هل كل نموذج له زر "حفظ" و "إلغاء" في نفس الترتيب؟
+[ ] هل الضغط على ESC يغلق جميع المودالات والقوائم المنسدلة؟
+[ ] هل الـ validation trigger (عند التركيز/عند الخروج/عند الإرسال) موحّد؟
+```
+
+## §10. حيوية البروتوتايب والطاقة البصرية (Visual Vitality & Polish)
+
+```
+[ ] ✅ / N/A — هل يحتوي التطبيق على Skeleton Loading (Shimmer) أثناء تحميل البيانات؟
+[ ] ✅ / N/A — هل تظهر Toast Notifications عند الإجراءات (تحديث، خطأ، نجاح)؟
+[ ] ✅ / N/A — هل يوجد مؤشر اتصال/حالة (Online/Offline or Connected/Disconnected)؟
+[ ] ✅ / N/A — هل الجداول تدعم Search حقيقي؟
+[ ] ✅ / N/A — هل العناصر تظهر بتأثيرات متدرجة (Stagger) أو Skeleton أولاً؟
+[ ] ✅ / N/A — هل البيانات تبدو واقعية (أسماء، أرقام، تواريخ، تفاصيل حقيقية)؟
+[ ] ✅ / N/A — هل يوجد Empty States للأقسام الخالية من البيانات؟
+[ ] ✅ / N/A — هل الـ Micro-interactions موجودة (hover، pulse، number counter، entrance)؟
+[ ] ✅ / N/A — هل التطبيق يعطي إحساس "حية" وليس "ساكن"؟
+
+**حالات الإجابة:**
+- ✅ = تم التنفيذ بنجاح
+- N/A = لا ينطبق على هذه الشاشة/المهمة + يجب وجود تبرير مسجل في ملف المهمة
+
+**القواعد:**
+- إذا كان البروتوتايب "يعمل" لكنه "بارد" = فشل مراجعة.
+- إذا كان الزبون يحتاج أن يتخيل كيف سيعمل التطبيق = فشل.
+- إذا كان التطبيق لا يحاكي الحياة (بدون Skeleton، Toast، Connection Status) = فشل.
+- البند N/A بدون تبرير = يُطلب التبرير قبل القبول.
+- البند §10 يتجاوز §1-9 في الأهمية — البروتوتايب الميت بصرياً مرفوض حتى لو كل التفاصيل الفنية سليمة.
+```

package/core/tera-system/design-system/DESIGN_SOURCE_PROTOCOL.md

@@ -0,0 +1,61 @@
+# Design Source Protocol
+
+## Purpose
+
+Determine the visual design source before any frontend/UI execution planning or implementation.
+
+## Mandatory Rule
+
+```text
+No Frontend Execution Planning without Design Source Decision.
+No UI Implementation without project-preparation/28_UI_UX_GUIDELINES.md when visual style matters.
+```
+
+## Design Source Modes
+
+| Mode | Use When | Required Output |
+|---|---|---|
+| `INTERNAL_TERA_KIT` | No external source; admin/ERP/CRM/dashboard default | Compact or full `28_UI_UX_GUIDELINES.md` from internal kit |
+| `GETDESIGN_MD` | A suitable `getdesign.md` DESIGN.md exists | Raw DESIGN.md + conversion into `28_UI_UX_GUIDELINES.md` |
+| `FIGMA_DESIGN_FILE` | Client provides a Figma design file with frames, components, tokens, or auto-layout | Figma analysis → extracted tokens → `28_UI_UX_GUIDELINES.md` |
+| `USER_PROVIDED_REFERENCE` | Client provides screenshots, colors, CSS, brand notes, or informal sketches | Raw source notes + extracted executable rules |
+| `EXTERNAL_URL_ANALYSIS` | Client provides reference website and analysis is available/approved | Analysis report + executable rules |
+| `HYBRID` | Combine internal kit with client colors or external reference | Explicit precedence rules |
+| `NO_UI` | API/backend-only or no visual UI in current phase | Record `No UI` in plan/task |
+| `N/A` | Design decision does not apply to the current record | Record reason |
+
+## Activation by Phase
+
+| Phase | Design Responsibility |
+|---|---|
+| Phase 1 | Collect preferences, screenshots, brand colors, references, RTL/LTR needs — owned by مُهندس (SCP-2026-07-28-118) |
+| Phase 3 | Decide whether `28_UI_UX_GUIDELINES.md`, design-source files, or UIVisualDesignerAgent are required — owned by مُهندس |
+| Phase 4 | Generate/activate UIVisualDesignerAgent only when design governance is needed now — owned by مُهندس |
+| Phase 5 | Block frontend TASK-COD generation until Design Source Decision exists |
+| Phase 6 | EngineeringAgent follows `28_UI_UX_GUIDELINES.md` and UI Acceptance Gate |
+
+## Selection Rules
+
+1. If the user provides a specific reference, use `USER_PROVIDED_REFERENCE` or `EXTERNAL_URL_ANALYSIS`.
+2. If the user provides a Figma design file (link, file, or detailed screenshots with component structure), use `FIGMA_DESIGN_FILE`.
+3. If the user asks for a known style direction and `getdesign.md` has a suitable DESIGN.md, use `GETDESIGN_MD` as a source, not as final scope.
+4. If the project is internal admin/ERP/CRM/dashboard without a design source, use `INTERNAL_TERA_KIT` starting with `KIT_ADMIN_DASHBOARD.md`.
+5. If the project has no UI, record `NO_UI` and do not create design files.
+6. Do not mention famous brands to clients as identity promises. Describe style qualities instead.
+
+When `FIGMA_DESIGN_FILE` is selected as the official design source, Tera must use `FIGMA_INTEGRATION.md` and ask the user for the required official Figma adoption inputs. The user is not expected to remember that checklist.
+
+## Required Decision Record
+
+Every UI project must record:
+
+```text
+Design Source Mode:
+Selected Source:
+Why selected:
+What will be used:
+What will not be used:
+Client overrides:
+Risk of brand imitation:
+Final executable file: project-preparation/28_UI_UX_GUIDELINES.md
+```

package/core/tera-system/design-system/DESIGN_SYSTEM_OVERVIEW.md

@@ -0,0 +1,66 @@
+# Tera Design System Overview
+
+## Purpose
+
+This layer governs visual design, UI style, layout rules, design tokens, component rules, and UI acceptance inside Tera projects.
+
+It prevents Tera or EngineeringAgent from inventing random UI styling during implementation.
+
+## Core Rule
+
+```text
+Design Governance Layer exists always.
+Full activation is conditional.
+```
+
+Tera chooses the design level by project type:
+
+| Project Type | Design Governance Level |
+|---|---|
+| API only / backend only | No UI Design Layer required |
+| Simple internal CRUD | Internal Kit + compact `28_UI_UX_GUIDELINES.md` |
+| ERP / CRM / dashboard | Full Design Governance |
+| SaaS / public UI / design-sensitive app | Full Design Governance + `getdesign.md` when useful |
+| Client provides Figma design file | `FIGMA_DESIGN_FILE` — requires structured extraction into `28_UI_UX_GUIDELINES.md` |
+| Client screenshots / reference website / brand notes | `USER_PROVIDED_REFERENCE` or `EXTERNAL_URL_ANALYSIS` |
+
+## Source to Execution Flow
+
+```text
+Design Source Decision
+-> Raw design source saved in project-preparation/design-source/
+-> Converted into project-preparation/28_UI_UX_GUIDELINES.md
+-> EngineeringAgent implements from 28_UI_UX_GUIDELINES.md only
+-> UI_ACCEPTANCE_GATE verifies result
+```
+
+## Official Files
+
+| File | Role |
+|---|---|
+| `DESIGN_SOURCE_PROTOCOL.md` | Design source modes and activation rules |
+| `DESIGN_MD_INTEGRATION.md` | `getdesign.md` / DESIGN.md protocol |
+| `EXTERNAL_REFERENCE_ANALYSIS.md` | Screenshots, URLs, brand notes, user references |
+| `FIGMA_INTEGRATION.md` | Figma design file protocol (when FIGMA_DESIGN_FILE is active) |
+| `INTERNAL_KITS_INDEX.md` | Internal fallback kits |
+| `DESIGN_TOKENS_SCHEMA.md` | Approved token schema |
+| `COMPONENT_LIBRARY_SCHEMA.md` | Component rule schema |
+| `LAYOUT_PATTERNS.md` | Layout patterns |
+| `RTL_LTR_RULES.md` | Arabic/English direction rules |
+| `ACCESSIBILITY_RULES.md` | Accessibility baseline |
+| `UI_ACCEPTANCE_GATE.md` | UI task acceptance gate |
+| `kits/KIT_ADMIN_DASHBOARD.md` | First internal kit |
+
+## Final Project Output
+
+The final executable UI design decision is always:
+
+```text
+project-preparation/28_UI_UX_GUIDELINES.md
+```
+
+Raw sources such as DESIGN.md, Figma files/exports, screenshots, color palettes, and external references belong in:
+
+```text
+project-preparation/design-source/
+```

package/core/tera-system/design-system/DESIGN_TOKENS_SCHEMA.md

@@ -0,0 +1,66 @@
+# Design Tokens Schema
+
+## Purpose
+
+Define the required structure for executable design tokens in `28_UI_UX_GUIDELINES.md`.
+
+## Token Groups
+
+```yaml
+colors:
+  background:
+  surface:
+  surface-muted:
+  border:
+  border-strong:
+  text:
+  text-muted:
+  primary:
+  primary-hover:
+  secondary:
+  accent:
+  success:
+  warning:
+  danger:
+  info:
+
+typography:
+  font-family-ar:
+  font-family-en:
+  h1:
+  h2:
+  h3:
+  body:
+  small:
+  button:
+  line-height:
+
+spacing:
+  base-unit: 4px
+  scale: [4, 8, 12, 16, 24, 32, 48, 64]
+
+radius:
+  sm:
+  md:
+  lg:
+  xl:
+  full:
+
+shadow:
+  none:
+  sm:
+  md:
+  lg:
+
+motion:
+  duration-fast:
+  duration-normal:
+  easing-standard:
+```
+
+## Rules
+
+- Tokens must be explicit before UI implementation.
+- If a token is unknown, record it as an Open Design Gap.
+- EngineeringAgent must not invent missing tokens.
+- Client branding overrides must be recorded separately from base kit tokens.

package/core/tera-system/design-system/EXTERNAL_REFERENCE_ANALYSIS.md

@@ -0,0 +1,52 @@
+# External Reference Analysis
+
+## Purpose
+
+Convert user-provided visual references into executable UI rules without guessing.
+
+Supported references:
+
+- screenshots
+- Figma notes or exports
+- CSS/theme files
+- brand/color files
+- website URLs
+- user descriptions of layout and colors
+- `getdesign.md` DESIGN.md files
+
+## Process
+
+1. Store or summarize raw reference in `project-preparation/design-source/`.
+2. Extract observable rules:
+   - color palette
+   - typography
+   - spacing density
+   - layout pattern
+   - component styles
+   - states and interactions
+   - RTL/LTR behavior
+   - accessibility risks
+3. Ask only for missing decisions that materially affect execution.
+4. Convert approved rules into `28_UI_UX_GUIDELINES.md`.
+5. Record open design gaps if the source is incomplete.
+
+## Screenshot Handling
+
+Screenshots are visual references, not complete specifications. Tera must infer cautiously and record uncertainty.
+
+If a screenshot lacks hover states, responsive behavior, accessibility states, or component variants, record them as `Open Design Gaps` instead of guessing.
+
+## External URL Handling
+
+External URLs may be used as inspiration or analysis input. They must not become mandatory scope or a brand-copying target.
+
+## Required Output Sections
+
+```text
+Reference Type:
+Observed Rules:
+Unknown / Missing Rules:
+Client Decisions Needed:
+Approved Conversion:
+Forbidden Styling:
+```

package/core/tera-system/design-system/FIGMA_INTEGRATION.md

@@ -0,0 +1,138 @@
+# Figma Integration Protocol
+
+## Purpose
+
+Define how Tera handles a Figma design file as a formal design source when `Design Source Mode = FIGMA_DESIGN_FILE`.
+
+## Core Rule
+
+```text
+No frontend implementation directly from Figma.
+Always extract executable rules into 28_UI_UX_GUIDELINES.md first.
+```
+
+## When to Use FIGMA_DESIGN_FILE
+
+Use `FIGMA_DESIGN_FILE` instead of `USER_PROVIDED_REFERENCE` when the client provides:
+
+- A Figma file (link, `.fig` file, or exported frames).
+- Structured screenshots showing component variants, states, or auto-layout.
+- Figma variables or design tokens.
+- A design system or component library defined in Figma.
+
+Do NOT use `FIGMA_DESIGN_FILE` for:
+
+- A single screenshot without structure (use `USER_PROVIDED_REFERENCE`).
+- A reference website or inspiration link (use `EXTERNAL_URL_ANALYSIS`).
+
+## Flow
+
+```text
+Client provides Figma file / link / structured exports
+        ↓
+Tera records Design Source Mode = FIGMA_DESIGN_FILE
+        ↓
+UIVisualDesignerAgent analyzes the Figma source:
+  - Extracts colors, typography, spacing
+  - Maps frames/pages to project screens
+  - Documents component variants and states
+  - Identifies layout patterns and constraints
+  - Notes responsive assumptions
+  - Records missing or unclear design areas as Design Gaps
+        ↓
+Updates project-preparation/28_UI_UX_GUIDELINES.md with:
+  - Section 3: Figma file reference
+  - Section 15: Figma Source Mapping
+  - Sections 5-8: Tokens, components, layout, RTL rules
+        ↓
+EngineeringAgent implements from 28_UI_UX_GUIDELINES.md only
+        ↓
+UI Acceptance Gate verifies against Figma-derived rules
+```
+
+## Required User Input for Official Figma Adoption
+
+When the user says that Figma is the official design source for a project, Tera must ask for the following information before analysis or UI execution planning:
+
+```text
+I will treat Figma as the official design source only after you provide or confirm:
+
+1. Figma link / file / exported frames:
+2. Approved pages / frames / screens:
+3. Frames that must NOT be used:
+4. Commitment level: exact / close match / guided adaptation:
+5. Interface direction: RTL Arabic / LTR English / both:
+6. What to extract: colors, typography, spacing, layout rules, component rules, states, responsive assumptions, RTL/LTR behavior:
+7. Missing states to check: empty / loading / error / disabled / mobile / tablet:
+8. Restrictions: no API, no MCP, no plugin, no direct EngineeringAgent implementation from Figma:
+9. Any project identity or brand overrides that should override Figma:
+```
+
+Tera must not expect the user to remember this checklist. If `FIGMA_DESIGN_FILE` is selected and any required item is missing, Tera asks only for the missing items.
+
+## Official Figma Adoption Prompt
+
+Tera may offer the user this ready-to-fill prompt:
+
+```text
+أريد اعتماد Figma كمصدر تصميم رسمي لهذا المشروع.
+
+Design Source Mode:
+FIGMA_DESIGN_FILE
+
+رابط Figma:
+[ضع الرابط هنا]
+
+نطاق التصميم المعتمد:
+- الصفحات/Frames المطلوبة: [اكتب أسماء الصفحات أو الشاشات]
+- لا تعتمد أي Frames أخرى خارج هذه القائمة إلا بعد سؤالي.
+
+درجة الالتزام:
+- استخدم Figma كمصدر تصميم أساسي للواجهة.
+- لا تنفذ منه مباشرة.
+- استخرج منه القواعد إلى project-preparation/28_UI_UX_GUIDELINES.md.
+- يجب أن يبقى 28_UI_UX_GUIDELINES.md هو المرجع التنفيذي النهائي.
+
+المطلوب استخراجه من Figma:
+- الألوان
+- الخطوط
+- spacing
+- layout rules
+- component rules
+- buttons
+- forms
+- tables
+- sidebar/topbar إن وجدت
+- component states مثل hover / active / disabled إن وجدت
+- responsive assumptions
+- RTL/LTR behavior
+
+اللغة والاتجاه:
+- الواجهة: [RTL عربي / LTR إنجليزي / الاثنين]
+- إذا كان التصميم في Figma باتجاه مختلف، سجّل ذلك كـ Design Gap ولا تخمّن.
+
+قيود مهمة:
+- لا تضف Figma API أو MCP أو Plugin الآن.
+- لا تسمح لـ EngineeringAgent بتنفيذ UI مباشرة من Figma.
+- إذا كانت هناك حالات ناقصة في التصميم مثل empty/loading/error/disabled/mobile، سجّلها في Open Design Gaps.
+- بعد التحليل أعطني ملخصًا بما تم اعتماده، وما هي Design Gaps قبل بدء تنفيذ الواجهة.
+```
+
+## UIVisualDesignerAgent Responsibilities
+
+When `FIGMA_DESIGN_FILE` is active, UIVisualDesignerAgent must:
+
+1. Reference the Figma file in `project-preparation/design-source/`.
+2. Extract all available design tokens (colors, typography, spacing).
+3. Map Figma components to project components.
+4. Document component variants, states (hover, focus, disabled, loading, error, empty).
+5. Note responsive behavior if the Figma includes multiple frame sizes.
+6. Record any missing design details as Design Gaps.
+7. Never copy the Figma file as executable spec — the final output is always `28_UI_UX_GUIDELINES.md`.
+
+## Restrictions
+
+- EngineeringAgent must NOT open or read Figma files directly.
+- EngineeringAgent must NOT implement UI from Figma screenshots without extracted rules.
+- Figma fonts that are not available in the project stack must be noted as Design Gaps.
+- Figma components that cannot be replicated exactly in the chosen UI framework must be noted with alternatives.

package/core/tera-system/design-system/INTERNAL_KITS_INDEX.md

@@ -0,0 +1,26 @@
+# Internal Tera Design Kits Index
+
+## Purpose
+
+Internal kits provide stable fallback design systems when the user has no external visual source.
+
+They are starting points, not mandatory final identities.
+
+## Available Kits
+
+| Kit | File | Best For | Status |
+|---|---|---|---|
+| Admin Dashboard | `kits/KIT_ADMIN_DASHBOARD.md` | ERP, CRM, admin panels, internal dashboards | Active |
+
+## Planned Kits
+
+| Kit | Best For | Status |
+|---|---|---|
+| SaaS App | SaaS products, subscription tools | Deferred |
+| Public Website | company websites, landing pages | Deferred |
+| Mobile First App | responsive/mobile-heavy apps | Deferred |
+| Data Dense ERP | complex tables and data-heavy ERP | Deferred |
+
+## Selection Rule
+
+Use the weakest sufficient kit. Do not activate full design governance for backend-only or API-only projects.