شادسن

# shadcn/ui

إطار عمل لبناء واجهة المستخدم والمكونات وأنظمة التصميم. تضاف المكونات كشفرة مصدرية إلى مشروع المستخدم عبر CLI.

> **هام:** قم بتشغيل جميع أوامر CLI باستخدام مشغل الحزم الخاص بالمشروع: `npx shadcn@latest`، أو `pnpm dlx shadcn@latest`، أو `bunx --bun shadcn@latest` — بناء على `packageManager` الخاص بالمشروع. تستخدم الأمثلة أدناه `npx shadcn@latest` ولكن استبدل المشغل الصحيح للمشروع.

## سياق المشروع الحالي

```json !`npx shadcn@latest info --json` ```

يحتوي JSON أعلاه على إعدادات المشروع والمكونات المثبتة. استخدم `npx shadcn@latest docs <component>` للحصول على التوثيق وعناوين URL للأمثلة لأي مكون.

## المبادئ

1. **استخدم المكونات الموجودة أولا.** استخدم `npx shadcn@latest search` للتحقق من السجلات قبل كتابة واجهة مستخدم مخصصة. تحقق من سجلات المجتمع أيضا. 2. **ركب، لا تعيد اختراع العجلة.** صفحة الإعدادات = Tabs + Card + عناصر تحكم النموذج. لوحة التحكم = Sidebar + Card + Chart + Table. 3. **استخدم المتغيرات المدمجة قبل الأنماط المخصصة.** `variant="outline"`، `size="sm"`، إلخ. 4. **استخدم الألوان الدلالية.** `bg-primary`، `text-muted-foreground` — لا تستخدم أبدا قيما خاما مثل `bg-blue-500`.

## القواعد الأساسية

هذه القواعد **مفروضة دائما**. كل منها يرتبط بملف يحتوي على أزواج من الأكواد غير الصحيحة/الصحيحة.

### التصميم و Tailwind → [styling.md](./rules/styling.md)

- **`className` للتخطيط، وليس للتصميم.** لا تقم أبدا بتجاوز ألوان المكونات أو الطباعة. - **لا تستخدم `space-x-*` أو `space-y-*`.** استخدم `flex` مع `gap-*`. للمكدسات العمودية، `flex flex-col gap-*`. - **استخدم `size-*` عندما يكون العرض والارتفاع متساويين.** `size-10` وليس `w-10 h-10`. - **استخدم اختصار `truncate`.** وليس `overflow-hidden text-ellipsis whitespace-nowrap`. - **لا تستخدم تجاوزات الألوان اليدوية `dark:`.** استخدم الرموز الدلالية (`bg-background`، `text-muted-foreground`). - **استخدم `cn()` للفئات الشرطية.** لا تكتب تعابير ثلاثية يدوية لقوالب النصوص. - **لا تستخدم `z-index` يدويا على مكونات التراكب.** Dialog، Sheet، Popover، إلخ. تتعامل مع ترتيب التكدس الخاص بها.

### النماذج والمدخلات → [forms.md](./rules/forms.md)

- **تستخدم النماذج `FieldGroup` + `Field`.** لا تستخدم أبدا `div` خاما مع `space-y-*` أو `grid gap-*` لتخطيط النموذج. - **تستخدم `InputGroup` كل من `InputGroupInput`/`InputGroupTextarea`.** لا تستخدم أبدا `Input`/`Textarea` خاما داخل `InputGroup`. - **تستخدم الأزرار داخل المدخلات `InputGroup` + `InputGroupAddon`.** - **تستخدم مجموعات الخيارات (2-7 خيارات) `ToggleGroup`.** لا تقم بتكرار `Button` بحالة نشطة يدوية. - **`FieldSet` + `FieldLegend` لتجميع مربعات الاختيار/أزرار الراديو ذات الصلة.** لا تستخدم `div` مع عنوان. - **يستخدم التحقق من صحة الحقل `data-invalid` + `aria-invalid`.** `data-invalid` على `Field`، `aria-invalid` على عنصر التحكم. للمعطل: `data-disabled` على `Field`، `disabled` على عنصر التحكم.

### هيكل المكونات → [composition.md](./rules/composition.md)

- **العناصر دائما داخل مجموعتها.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`. - **استخدم `asChild` (radix) أو `render` (base) للمشغلات المخصصة.** تحقق من حقل `base` من `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md) - **تحتاج Dialog و Sheet و Drawer دائما إلى عنوان.** `DialogTitle`، `SheetTitle`، `DrawerTitle` مطلوبة لإمكانية الوصول. استخدم `className="sr-only"` إذا كانت مخفية بصريا. - **استخدم تركيبة Card الكاملة.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. لا تضع كل شيء في `CardContent`. - **لا يحتوي Button على `isPending`/`isLoading`.** ركب مع `Spinner` + `data-icon` + `disabled`. - **يجب أن يكون `TabsTrigger` داخل `TabsList`.** لا تعرض المشغلات مباشرة في `Tabs`. - **يحتاج `Avatar` دائما إلى `AvatarFallback`.** عندما تفشل الصورة في التحميل.

### استخدم المكونات، وليس الترميز المخصص → [composition.md](./rules/composition.md)

- **استخدم المكونات الموجودة قبل الترميز المخصص.** تحقق مما إذا كان المكون موجودا قبل كتابة `div` منسق. - **تستخدم Callouts `Alert`.** لا تبني divs منسقة مخصصة. - **تستخدم Empty states `Empty`.** لا تبني ترميزا مخصصا للحالات الفارغة. - **يتبع Toast قاعدة المشروع.** استخدم `toast` من مكون `toast` لمشاريع Base UI. استخدم `toast()` من `sonner` لمشاريع Radix و React Aria. - **استخدم `Separator`** بدلا من `<hr>` أو `<div className="border-t">`. - **استخدم `Skeleton`** للعناصر النائبة للتحميل. لا تستخدم divs مخصصة `animate-pulse`. - **استخدم `Badge`** بدلا من span منسقة مخصصة.

### الأيقونات → [icons.md](./rules/icons.md)

- **تستخدم الأيقونات في `Button` خاصية `data-icon`.** `data-icon="inline-start"` أو `data-icon="inline-end"` على الأيقونة. - **لا تستخدم فئات تحديد الحجم على الأيقونات داخل المكونات.** تتعامل المكونات مع تحديد حجم الأيقونات عبر CSS. لا تستخدم `size-4` أو `w-4 h-4`. - **مرر الأيقونات ككائنات، وليس كمفاتيح نصية.** `icon={CheckIcon}`، وليس بحثا نصيا.

### الدردشة والمراسلة → [chat.md](./rules/chat.md)

- **تركب واجهة مستخدم الدردشة من عناصر الدردشة الأولية.** تستخدم المحادثات `MessageScroller`، وتستخدم الصفوف `Message`، وتستخدم الأسطح `Bubble`. لا تستخدم أبدا divs فقاعية يدوية أو حاوية تمرير خام. - **يمتلك `MessageScroller` سلوك التمرير.**