دليل Open Claude UI: بناء واجهة محادثة بالذكاء الاصطناعي عالية الدقة وحركات تفاعلية بمستوى الإنتاج

مقدمة على المشروع

open-claude-ui هي مكتبة مفتوحة المصدر ديال مكوّنات واجهة المستخدم ومحرك ديال المؤثرات الحركية، موجهة لعملاء الذكاء الاصطناعي العصريين على سطح المكتب. المشروع مبني على إطار الهندسة العكسية REA، وكيجمع بين التحليل الساكن ديال AST، وفكّ التعمية ديال الكود داخل الإغلاقات، والتتبع وقت التشغيل، وتفكيك موارد ASAR، ومن بعد كينظم نتائج البحث فشكل مكوّنات React قابلة لإعادة الاستعمال، وHooks، وأنماط للثيمات، ووثائق تقنية.

ماشي غير إعادة نسخ لشكل الواجهة، بل كيركز حتى على استرجاع الآليات الهندسية اللي كتأثر على جودة التفاعل، بحال معاملات النوابض الفيزيائية، وحماية إدخال CJK، والتلاشي التدريجي فحواف التمرير، والتحكم فتمرير الرسائل المتدفقة، والتكبير المرتكز على المؤشر، ومنطقة منع السحب، وأصوات التنبيه المركبة باستعمال Web Audio.

ملاحظة على الامتثال: المشروع ما كيوزعش الخطوط التجارية ولا ملفات التسجيل ولا الأصول الثنائية الخاصة، وكيستعمل بلاصتها حزمة الخطوط الاحتياطية ديال النظام ومؤثرات صوتية مبرمجة بالكامل عبر Web Audio API. المشروع خاضع لـ MIT License، والنتائج المرتبطة به مخصصة للتعلم والبحث والتبادل الهندسي.

شنو المشاريع اللي مناسب ليها

إلى كنت كتطور عميل دردشة بالذكاء الاصطناعي، أو لوحة تحكم للنماذج، أو واجهة للموافقة على استدعاء الأدوات، أو مساعد على سطح المكتب، أو عارض للوسائط، أو فضاء للتعاون بين عدة وكلاء، تقدر تدخل المكوّنات من هاد المستودع حسب الحاجة، بلا ما تعاود تضبط بوحدك الرموز البصرية والتفاعلات المعقدة.

• تطبيقات الذكاء الاصطناعي على الويب: استعمل فقاعات المحادثة، ومربعات إدخال النص الغني، ومبدّل النماذج، ولوحة قياس Token.
• واجهات التوليد المتدفق: استعمل دبوس التمرير، وطيّ مراحل التفكير، والقناع المتلاشي.
• تطبيقات سطح المكتب: استعمل مصنع نوافذ Electron، وشريط العنوان ديال macOS، وحل مواد Vibrancy.
• تطبيقات Artifacts والوسائط المتعددة: استعمل السحب بين الأعمدة، وصندوق عرض الوسائط، والانتقالات بالعناصر المشتركة، وجسر iframe المعزول.
• تطبيقات الولوجية: استعمل Hook ديال التنقل فالبؤرة Roving TabIndex، وفق مبادئ WAI-ARIA.

الخصائص الرئيسية

رموز التصميم والنظام البصري

المشروع كيوفر تدرج سطوح منخفض التباين من Surface 0 حتى Surface 3، ولون برتقالي طيني #d97757، وتعويض الحواف الرفيعة للشاشات عالية الكثافة، وحزمة الخطوط الاحتياطية ديال النظام، ومصفوفة ديال الزوايا المستديرة مخصصة للأزرار واللوحات والفقاعات ومربعات الإدخال. متغيرات الثيم العامة والإطارات المفتاحية مجموعين فـ code-examples/cds-theme.css.

30 وحدة كود مستقلة

المستودع فيه 11 مكوّناً ذرياً أساسياً و19 وحدة معمارية أو تفاعلية. مصدر المكوّنات كاين فـ code-examples، ومدخل التصدير الموحد ديال TypeScript كاين فـ src/index.ts. هاد الوحدات كتشمل الأزرار، والاختيار المجزأ، ومربعات الإدخال، وفقاعات المحادثة، وبطاقات قرارات MCP، وعارض الوسائط، وDiff المتدفق، ونوافذ سطح المكتب، ولوحة متعددة الوكلاء، وغيرها.

آليات تفاعل بمستوى الإنتاج

• 4 إعدادات مسبقة للنوابض الفيزيائية، وهي Bouncy وSnappy وGentle وHeavy Snap.
• مناطق التمرير كتستعمل قناع Alpha غير خطي من 7 درجات، وكتتبدل ديناميكياً حسب واش وصلات لأعلى المنطقة أو لأسفلها.
• مربع الإدخال كيحمي إدخال CJK بجوج شروط: isComposing وkeyCode === 229.
• الإخراج المتدفق كيستعمل تسامح سفلي قدره 40px وفترة تهدئة للتمرير اليدوي قدرها 150ms، باش ما ياخدش التمرير التلقائي السيطرة على منفذ العرض.
• موجة الميكروفون كتستعمل عتبة ضجيج قدرها 8% وضغط Gamma بقوة 0.7.
• تفاعلات السحب والمعرض فيها منطقة منع حركة للمؤشر قدرها 4px، باش تصفي الاهتزازات الخفيفة ديال اليد.

معاينة المكوّنات بلا اتصال

المستودع مرفوق بقصة تفاعلية فملف واحد docs/claude-components-storybook.html. ما كاينش داعي تشغل خادم تطوير محلي باش تشوف نظام الألوان الطيني، والوضع الداكن، وتغذية الأزرار الراجعة، والكبسولات المجزأة، وحركة النوابض، وبلاطات المرفقات، وحركة حالة النسخ.

التثبيت وتحضير البيئة

تأكد من حزمة التقنيات

حسب المعطيات ديال المستودع، من المستحسن يكون المشروع مجهز بالبيئة التالية:

• React 18 أو إصدار أحدث.
• TypeScript 5.5 أو إصدار أحدث.
• Tailwind CSS 3.4 أو إصدار أحدث.
• Framer Motion 11 أو إصدار أحدث.

الـ README ما عطاش أمر تثبيت خاص بمدير حزم معين. قبل البداية، خاصك، حسب مساحة العمل ديالك أو اعتماديات Git أو طريقة نشر الحزم، تخلي المشروع يقدر يوصل للمسار open-claude-ui، وتتأكد باللي حزمة التقنيات المذكورة فوق مضبوطة كاملة.

شوف القصة التفاعلية بلا اتصال أولا

إلى كنت حصلتي على مصدر المستودع، تقدر تفتح ملف المعاينة مباشرة:

open docs/claude-components-storybook.html

هاد الخطوة كتعاونك تتأكد من الشكل البصري للمكوّنات، والثيم الداكن، والحركات التفاعلية، بلا ما تبدل مشروعك التجاري.

إعداد أنماط الثيم

إدخال CSS العام

دخل ملف ثيم CDS فمدخل الأنماط العامة ديال التطبيق. فيه خصائص CSS المخصصة والإطارات المفتاحية اللي كيحتاجها كل مكوّن:

@import "open-claude-ui/code-examples/cds-theme.css";

هاد الثيم كيوفر ألوان السطوح، ولون العلامة الطيني، والحدود، والظلال، والأساس ديال الحركات. باش تبقى المكوّنات منسجمة، من الأفضل تستعمل متغيرات CSS الموجودة أولا، وما تعاودش تكتب الألوان بشكل ثابت فكل مكوّن.

وسّع إعدادات Tailwind

حمّل توسعة الثيم اللي كيوفرها المستودع فـ tailwind.config.js ديال المشروع:

const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      ...cdsTheme.theme.extend
    }
  }
};

خاص مصفوفة content تشمل مصدر التطبيق ديالك والملفات اللي فيها أسماء أصناف Tailwind داخل open-claude-ui. إلا ما درتيش هاد الشي، ممكن ما يتولدوش فالبناء الإنتاجي أصناف الأدوات اللي كيستعملوها المكوّنات.

الاستعمال الأساسي: بناء منطقة التحكم فالنموذج وإدخال الدردشة

المثال التالي كيجمع ثلاثة مكوّنات أساسية:

1. ScrollFadeContainer كيزيد تلاشي تدريجي فالحواف الفوقانية والتحتانية للمنطقة القابلة للتمرير.
2. ModelSwitcherWithTokenGauge كيعرض اختيار النموذج، وحالة Extended Thinking، وميزانية Token.
3. ChatComposer كيوفر إدخال الرسالة الأساسي ونداء الإرسال.

import React, { useState } from 'react';
import {
  ChatComposer,
  ModelSwitcherWithTokenGauge,
  ScrollFadeContainer
} from 'open-claude-ui';

export function App() {
  const [model, setModel] = useState<
    'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
  >('sonnet-3.5');
  const [thinking, setThinking] = useState(true);

  return (
    <div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
      <ScrollFadeContainer
        axis="vertical"
        fadeSize={32}
        className="flex-1 p-6"
      >
        <div className="mx-auto max-w-3xl space-y-4">
          <ModelSwitcherWithTokenGauge
            currentModel={model}
            onModelChange={setModel}
            extendedThinking={thinking}
            onThinkingChange={setThinking}
            tokenBudget={{
              inputTokens: 12400,
              outputTokens: 3200,
              cacheReadTokens: 48000,
              cacheWriteTokens: 16000,
              maxContextWindow: 200000
            }}
          />

          <ChatComposer
            onSend={(text) => console.log('Send message:', text)}
          />
        </div>
      </ScrollFadeContainer>
    </div>
  );
}

فهم تدبير الحالة

currentModel وextendedThinking بجوج كيتدبرو من طرف طبقة التطبيق، وبهذا يقدر مبدّل النماذج يتزامن مع إعدادات الطلبات الحقيقية ديال النماذج. tokenBudget فالمثال كيدوز للإعدادات ديال لوحة القياس عدد رموز الإدخال، والإخراج، وقراءة الذاكرة المؤقتة، وكتابتها، وأقصى حجم لنافذة السياق، كل واحد بوحدو.

الخاصية onSend ديال ChatComposer غير كتكتب سجل فالمثال. فالمشروع الحقيقي، تقدر فهاد النداء تستعمل خدمة المحادثة ديالك، وتحدّث لائحة الرسائل، وتطلق حالة الاستجابة المتدفقة.

دليل اختيار المكوّنات الشائعة

المكوّنات الأساسية

• CdsButton: كيوفر أربعة أحجام XS وSM وMD وLG، وخمسة أشكال Primary وSecondary وGhost وOutline وDanger.
• SegmentedControl: مخصص لتبديل الأوضاع، وكي support التحديد الهندسي الخالص وحل الحركة باستعمال layoutId ديال Framer Motion.
• StatusIndicators: فيه ضوء تنفس طيني، ونبض النشاط المباشر، وحركة ثلاث نقط ديال التفكير، ولمعان المسح ديال الهيكل.
• ConfirmationDialog: مخصص لتأكيد العمليات العادية أو الخطيرة، وفيه قناع ضبابي وتقييد للبؤرة عبر لوحة المفاتيح.
• AttachmentCard: كيدعم جوج طرق لعرض المرفقات: بلاطات سطح المكتب والكبسولات المضمنة فسطـر مربع الإدخال.

المحادثة واستدعاء الأدوات

• ChatMessageBubbles: كيفرق بين فقاعات المستخدم والتنسيق الشفاف ديال المساعد.
• ThinkingAccordion: كيعرض مراحل التفكير بشكل قابل للطي، ويقدر يبقى مفتوحا إجباريا أثناء التوليد.
• RichComposerWithMentions: مناسب لواجهة إدخال كتحتاج أوامر /، وسياق @، وتوقع Token.
• McpToolDecisionCard: مخصص لمسار الترخيص ديال الأدوات، وكيغطي الحالات pending_approval وrunning وsuccess وerror.

الوسائط والكود وArtifacts

• MediaLightboxViewer: كيوفر مسار معرض بعرض 75vw، وPan/Zoom مرتكز على المؤشر، ومنطقة منع السحب، والتكبير بعجلة Ctrl.
• ArtifactsSplitPaneResizer: كيتكلف بتغيير حجم العمودين، وطي الحواف، والالتصاق بنسبة 50/50 بالنقر المزدوج، والتداخل ديال أحداث المؤشر مع iframe.
• EpitaxyIframeBridge: كيربط صندوق المعاينة المعزول عبر التحقق من Origin وبروتوكول RPC منفصل مبني على postMessage.
• StreamingDiffViewer: كيدعم الإضافة التدريجية المتدفقة، ووضعَي Diff الموحد والمنقسم.
• CodeBlock: كيوفر حاوية للكود، وتلاشي حالة النسخ بعد 2.5 ثانية.

ممارسات متقدمة

حماية إدخال اللغات الصينية واليابانية والكورية

إلى كان خاص خانة الدردشة توسّع أحداث لوحة المفاتيح بوحدها، خاص نحافظو على الحماية ديال تركيب الإدخال. ملي المستخدم يضغط على Enter فنافذة اقتراحات البينيين ولا الكانا، ما خاصّوش يرسل الرسالة. المشروع كيعتمد على جوج ديال الفحوصات:

const composing =
  event.nativeEvent.isComposing || event.keyCode === 229;

if (event.key === 'Enter' && !composing) {
  // إرسال الرسالة
}

وبالنسبة لزر Escape، خاص حتى هو ما يخليش الحدث يكمل الانتشار ملي كتسدّ طبقة اقتراحات الإدخال، باش ما يتسدّاش نافذة الحوار بالغلط.

تجنّب أن الإخراج المتدفق يختطف موضع التمرير

يمكن استعمال useClaudeScrollPinning لتدبير الـ Token اللي كيزيد باستمرار. الاستراتيجية الأساسية كتضم هامش 40px فالقاع، وفترة تهدئة ديال 150ms من بعد التمرير اليدوي، ومخزن مرن بحجم 35vh. ملي المستخدم كيبقى قريب للقاع، تقدر الواجهة تتبع الإخراج؛ ولكن منين كيبدا يقلب يدويًا فالرسايل القديمة، ما خاصّش التمرير التلقائي يرجّع نافذة العرض للقاع مباشرة.

استعمال إعدادات الحركة الموحّدة

المشروع كيوفّر فـ ClaudeMotionPresets.ts أربعة ديال إعدادات النوابض مضبوطة بعناية. ملي كتطوّر مكوّن جديد، فضّل تعاود تستعمل Bouncy أو Snappy أو Gentle أو Heavy Snap، عوض ما تضبط القساوة والتخميد بشكل عشوائي لكل حركة. بهاد الطريقة، الأزرار واللوحات والتثبيت بالسحب وانتقالات العناصر المشتركة كيبقاو محافظين على نفس اللغة الفيزيائية.

التعامل الصحيح مع سحب تقسيمات iframe

ملي كتدوز شريط التقسيم فوق iframe، يقدر الـ iframe يعترض أحداث المؤشر ويتسبب فإيقاف السحب. كيقوم ArtifactsSplitPaneResizer بتفعيل آلية لمنع ابتلاع الأحداث وقتاش كيكون السحب مفعّل، وكيجمع بينها وبين منطقة ميتة للحركة بحجم 4px، وقيود الحواف، والتثبيت فالوسط بالنقر المزدوج. إلا كان التطبيق فيه معاينة Artifacts، خاص إعطاء الأولوية لإعادة استعمال هاد المكوّن، عوض الاكتفاء بمراقبة أحداث الفأرة ديال شريط التقسيم بوحدو.

الحفاظ على تنقّل كامل لمستخدمي لوحة المفاتيح

كيدعم useClaudeRovingFocus التنقّل بمفاتيح الاتجاه فبعد واحد ولا جوج، والانتقال لحدود Home وEnd، وقلب الاتجاهات فـ RTL. ملي كتبني شبكة ديال النماذج، ولا لائحة المرفقات، ولا مجموعة ديال بطاقات الأدوات، خاصك تحافظ فالنفس الوقت على دلالات ARIA الصحيحة وعلى حالة التركيز اللي باينة.

التعامل مع تحديد معدل النماذج وأعطال الخدمة

موجّه useRateLimitBackoff لاستجابات 429 و503، وكيوفّر تراجعًا أُسّيًا مقطوعًا، وإدخال التذبذب، وآلية استرجاع تلقائي من فتح الدارة بعد ثلاث محاولات. مناسب لطبقة طلبات النموذج، ولكن من مسؤولية منطق العمل يحدد، حسب البنية الخاصة باستجابات API ديالو، فوقاش يعاود المحاولة، وفوقاش يبيّن الخطأ، وفوقاش يسمح للمستخدم بالاسترجاع اليدوي.

التعلّم المتعمق باستعمال الدليل التقني

إضافةً إلى مصدر المكوّنات، المستودع كيوفّر حتى دليلًا تقنيًا لنظام التصميم فيه أكثر من 3,000 سطر. كننصحو تقراه بهاد الترتيب:

1. قرا أولًا فلسفة التصميم، وسُلّم ألوان Surface، ومصفوفة الزوايا المدورة، وقواعد الحدود الدقيقة.
2. من بعد تعلّم الأزرار، وعناصر التحكم المقسّمة، ومؤشرات الحالة، ومربعات حوار التأكيد.
3. ثم درس إدخال المحادثة، وحماية CJK، وتبديل النموذج، وآلة حالات MCP.
4. إلى احتجتي حركات معقدة، راجع من بعد معاملات النوابض، والضوء المحيط، وأقنعة التمرير.
5. ملي كتطوّر تطبيقًا لسطح المكتب، ولا أداة وسائط، ولا فضاءً للتعاون، قرا الفصول المعمارية الخاصة بالنظام.

الدليل الكامل كاين فـ docs/Claude Design System (CDS).md. وخدمة التحليل العكسي ديال المشروع تدار بالاعتماد على REA.

التعاون مع AI Coding Agent

المستودع كيوفّر الملفات AGENTS.md وCLAUDE.md و.cursorrules وملفات تعليمات Copilot. ملي كتستعمل أدوات بحال Cursor ولا Claude Code ولا GitHub Copilot لتوليد واجهة جديدة، تقدر تطلب من Agent يتبع التوكنات الموجودة فالمستودع، وإعدادات النوابض، ومبادئ الحدود، وقواعد حماية إدخال اللغات الآسيوية.

مثال على prompt: عافاك تبع بدقة القواعد الموجودة فـ AGENTS.md ديال هاد المستودع، وبني المكوّن الحالي باستعمال توكنات تصميم CDS الطينية وإعدادات النوابض ClaudeMotionPresets.

الخلاصة

open-claude-ui كيجمع التوكنات البصرية ديال عملاء الذكاء الاصطناعي، وعناصر التحكم فالمحادثة، وفيزياء الحركة، والتفاعلات متعددة الوسائط، ومعمارية سطح المكتب فموديولات قابلة لإعادة الاستعمال. أحسن طريقة للدمج هي تتأكد أولًا من النتيجة عبر Storybook بلا اتصال، ومن بعد تدخل CSS ديال السمة وتوسعات Tailwind، وفالأخير تبدا تركّب من المكوّنات الأساسية بحال خانة الدردشة، ومبدّل النموذج، وحاويات التمرير. فالحالات المعقدة بحال الإخراج المتدفق، وإدخال CJK، وسحب iframe، والتنقّل بلوحة المفاتيح، حاول قدر الإمكان تعاود تستعمل Hooks وآلات الحالات الموجودة فالمستودع، عوض غير نسخ الأنماط السطحية.