# Kashi (کاشی)

> Kashi is an open-source, RTL-first Persian design system: accessible React components (@kashi-ui/react), framework-agnostic CSS (@kashi-ui/css), design tokens, 4500 icons in six styles and Persian utilities such as Jalali dates and national ID, IBAN and card validation. MIT licensed.

Setup: `npm i @kashi-ui/react @kashi-ui/css`, import "@kashi-ui/css" once at the app root and set `<html lang="fa" dir="rtl">`. Without React, use the `k-*` CSS classes from each page's HTML example. In Tailwind projects, `@kashi-ui/tailwind` exposes the same tokens as classes (`bg-secondary`, `border-brand`, `rounded-lg`).

For coding assistants, the Kashi MCP server gives the same docs plus icon search, tokens and Persian utilities as tools: `npx -y @kashi-ui/mcp` (https://kashi.sepantapouya.com/docs/ai/).

## کامپوننت‌ها

- [آکاردئون (Accordion, AccordionItem)](https://kashi.sepantapouya.com/docs/components/accordion/): بخش‌های جمع‌شونده برای محتوای طولانی، مثل پرسش‌های متداول؛ روی details بومی.
- [هشدار (Alert)](https://kashi.sepantapouya.com/docs/components/alert/): پیامی مهم دربارهٔ وضعیت سیستم یا نتیجهٔ یک عمل، با آیکون شاخص و عمل‌های اختیاری.
- [آواتار (Avatar, AvatarGroup)](https://kashi.sepantapouya.com/docs/components/avatar/): نمایش تصویر یا حروف اول یک شخص، با وضعیت حضور و گروه‌بندی.
- [بج (Badge)](https://kashi.sepantapouya.com/docs/components/badge/): برچسب کوچک برای وضعیت، دسته‌بندی یا شمارش.
- [بنر (Banner)](https://kashi.sepantapouya.com/docs/components/banner/): پیام سطح صفحه مثل نسخهٔ جدید، پایان اشتراک یا اختلال سرویس، با دکمهٔ عمل و بستن.
- [بردکرامب (Breadcrumb)](https://kashi.sepantapouya.com/docs/components/breadcrumb/): نشان می‌دهد کاربر کجای ساختار سایت است.
- [گروه دکمه (ButtonGroup, Button)](https://kashi.sepantapouya.com/docs/components/button-group/): دکمه‌های چسبیده به هم برای عمل‌های مرتبط، مثل «روز / هفته / ماه» یا «قبلی / امروز / بعدی».
- [دکمه (Button)](https://kashi.sepantapouya.com/docs/components/button/): برای اجرای یک عمل. شش گونه برای سلسله‌مراتب بصری، چهار اندازه و حالت بارگذاری دسترس‌پذیر.
- [کارت (Card, CardHeader, CardTitle, CardDescription, CardBody, CardFooter)](https://kashi.sepantapouya.com/docs/components/card/): ظرفی برای گروه‌بندی محتوای مرتبط، با سربرگ، بدنه و پانویس.
- [کاروسل (Carousel)](https://kashi.sepantapouya.com/docs/components/carousel/): نمایش چند کارت یا تصویر در یک ردیف قابل‌پیمایش، مثل محصولات پیشنهادی.
- [نمودار (BarChart, BarList, LineChart, PieChart, ProportionBar, Sparkline)](https://kashi.sepantapouya.com/docs/components/charts/): نمودار ستونی، انباشته، خطی، دایره‌ای و دونات، میله‌ای افقی، سهم از کل و خط روند؛ با ارقام فارسی و جدول هم‌ارز برای صفحه‌خوان.
- [چک‌باکس (Checkbox)](https://kashi.sepantapouya.com/docs/components/checkbox/): برای انتخاب یک یا چند گزینه، یا تأیید یک مورد. روی input بومی ساخته شده است.
- [چیپس (ChipGroup)](https://kashi.sepantapouya.com/docs/components/chips/): فیلترهای روشن و خاموش‌شونده با تعداد نتیجه، بالای فهرست یا جدول.
- [انتخاب رنگ (ColorPicker)](https://kashi.sepantapouya.com/docs/components/color-picker/): انتخاب رنگ برند یا برچسب با نمونه‌رنگ‌ها، پنل انتخاب دلخواه و کد hex، همراه کنتراست متن.
- [کامبوباکس (Combobox)](https://kashi.sepantapouya.com/docs/components/combobox/): فیلد جستجو با فهرست پیشنهادها (Combobox)؛ برای فهرست‌های بلند مثل شهر، کاربر یا محصول.
- [کامند پالت (CommandPalette)](https://kashi.sepantapouya.com/docs/components/command-palette/): جستجوی سریع صفحه‌ها و عملیات با Ctrl+K، به سبک ابزارهای حرفه‌ای.
- [منوی راست‌کلیک (ContextMenu, MenuItem, MenuSeparator)](https://kashi.sepantapouya.com/docs/components/context-menu/): منوی میان‌بر روی فایل، ردیف جدول یا کارت؛ با موس و کیبورد.
- [دکمهٔ کپی (CopyButton)](https://kashi.sepantapouya.com/docs/components/copy-button/): کپی متن در کلیپ‌بورد با بازخورد «کپی شد»، برای کلید API، شماره شبا یا کد تخفیف.
- [دیالوگ (Dialog)](https://kashi.sepantapouya.com/docs/components/dialog/): پنجره‌ای روی صفحه برای کاری کوتاه یا تأیید یک تصمیم، روی dialog بومی مرورگر.
- [جداکننده و کلید میان‌بر (Divider, Kbd)](https://kashi.sepantapouya.com/docs/components/divider/): خط جداکننده با متن اختیاری، و نمایش کلیدهای صفحه‌کلید.
- [دراپ‌داون (DropdownMenu, MenuItem, MenuSeparator, MenuLabel)](https://kashi.sepantapouya.com/docs/components/dropdown-menu/): فهرستی از عمل‌ها که با یک دکمه باز می‌شود؛ با الگوی Menu Button و پیمایش کامل کیبورد.
- [حالت خالی (EmptyState)](https://kashi.sepantapouya.com/docs/components/empty-state/): وقتی داده‌ای برای نمایش نیست؛ توضیح بدهید چرا و قدم بعدی را پیشنهاد کنید.
- [آپلود فایل (FileUpload)](https://kashi.sepantapouya.com/docs/components/file-upload/): کشیدن و رها کردن یا انتخاب فایل، با بررسی نوع و حجم و نوار پیشرفت هر فایل.
- [ویرایش درجا (InlineEdit)](https://kashi.sepantapouya.com/docs/components/inline-edit/): ویرایش متن در همان جا، مثل نام پروژه یا عنوان کارت، بدون فرم جداگانه.
- [ورودی (Input, Textarea)](https://kashi.sepantapouya.com/docs/components/input/): فیلد متن تک‌خطی و چندخطی، با برچسب، متن راهنما، پیام خطا و افزونه.
- [گیج (Meter)](https://kashi.sepantapouya.com/docs/components/meter/): نمایش یک مقدار در برابر سقف، مثل فضای ذخیره، سهمیهٔ پیامک یا ظرفیت پلن.
- [انتخاب چندتایی (MultiSelect)](https://kashi.sepantapouya.com/docs/components/multi-select/): انتخاب چند گزینه از یک فهرست بلند با جستجو، مثل مسئولان پروژه یا برچسب‌های یک محصول.
- [ورودی عدد (NumberInput)](https://kashi.sepantapouya.com/docs/components/number-input/): فیلد عدد با دکمه‌های افزایش و کاهش، محدودهٔ مجاز و ارقام فارسی.
- [صفحه‌بندی (Pagination)](https://kashi.sepantapouya.com/docs/components/pagination/): پیمایش بین صفحه‌های یک فهرست، با ارقام فارسی و «…» برای صفحه‌های زیاد.
- [قدرت رمز عبور (PasswordStrength)](https://kashi.sepantapouya.com/docs/components/password-strength/): نوار قدرت رمز و فهرست شرط‌ها زیر فیلد رمز، با هشدار صفحه‌کلید فارسی.
- [پاپ‌اور (Popover)](https://kashi.sepantapouya.com/docs/components/popover/): محتوای تعاملی کوتاه کنار یک دکمه، مثل فیلتر، فرم کوچک یا توضیح.
- [نوار پیشرفت (Progress, Spinner)](https://kashi.sepantapouya.com/docs/components/progress/): نمایش پیشرفت یک کار طولانی، به‌همراه اسپینر برای انتظارهای کوتاه.
- [رادیو](https://kashi.sepantapouya.com/docs/components/radio/): انتخاب دقیقاً یک گزینه از چند گزینه؛ به شکل فهرست، افقی یا کارت‌های قابل‌انتخاب.
- [امتیاز ستاره‌ای (Rating)](https://kashi.sepantapouya.com/docs/components/rating/): دریافت یا نمایش امتیاز ۱ تا ۵، با نیم‌ستاره در حالت نمایش.
- [سگمنت (SegmentedControl)](https://kashi.sepantapouya.com/docs/components/segmented-control/): انتخاب یکی از چند گزینهٔ کوتاه کنار هم، مثل حالت نمایش یا بازهٔ زمانی گزارش.
- [سلکت (Select)](https://kashi.sepantapouya.com/docs/components/select/): انتخاب یک گزینه از فهرست بلند، روی select بومی مرورگر.
- [سایدبار (SideNav)](https://kashi.sepantapouya.com/docs/components/side-nav/): منوی کناری پنل مدیریت با گروه‌ها، زیرمنو، نشان و حالت جمع‌شده.
- [اسکلتون (Skeleton)](https://kashi.sepantapouya.com/docs/components/skeleton/): جای خالی محتوا هنگام بارگذاری؛ از پرش صفحه جلوگیری می‌کند.
- [اسلایدر (Slider)](https://kashi.sepantapouya.com/docs/components/slider/): انتخاب یک عدد یا یک بازه با کشیدن، مثل صدا، روشنایی یا بازهٔ قیمت.
- [اسپلیتر (Splitter)](https://kashi.sepantapouya.com/docs/components/splitter/): دو پنل کنار هم یا زیر هم که کاربر اندازه‌شان را با کشیدن مرز تغییر می‌دهد.
- [کارت آمار (StatCard, StatGrid)](https://kashi.sepantapouya.com/docs/components/stat-card/): نمایش شاخص‌های کلیدی (KPI) داشبورد با روند تغییر.
- [استپر (Stepper)](https://kashi.sepantapouya.com/docs/components/stepper/): نشان دادن مراحل یک فرایند چندبخشی، مثل خرید یا ثبت‌نام.
- [سوییچ (Switch)](https://kashi.sepantapouya.com/docs/components/switch/): برای روشن و خاموش کردن تنظیمی که بلافاصله اعمال می‌شود.
- [جدول داده (DataTable)](https://kashi.sepantapouya.com/docs/components/table/): جدول با مرتب‌سازی، انتخاب ردیف‌ها، ستون‌های عددی و حالت خالی.
- [تب‌ها (Tabs, TabList, Tab, TabPanel)](https://kashi.sepantapouya.com/docs/components/tabs/): نمایش بخش‌های مرتبط یک محتوا در یک فضا، با سه سبک و پیمایش کامل کیبورد.
- [ورودی تگ (TagInput)](https://kashi.sepantapouya.com/docs/components/tag-input/): نوشتن چند مقدار در یک فیلد، مثل مهارت‌ها، برچسب‌ها یا گیرندگان ایمیل.
- [تایم‌لاین (Timeline)](https://kashi.sepantapouya.com/docs/components/timeline/): نمایش رویدادها و فعالیت‌ها به ترتیب زمان، مثل تاریخچهٔ سفارش یا فعالیت تیم.
- [توست (Toaster)](https://kashi.sepantapouya.com/docs/components/toast/): پیام کوتاه و موقت پس از یک عمل، مثل «ذخیره شد»؛ با توقف هنگام hover و امکان واگرد.
- [تولتیپ (Tooltip)](https://kashi.sepantapouya.com/docs/components/tooltip/): توضیح کوتاه یک کنترل هنگام hover یا فوکوس.
- [تور معرفی (Tour)](https://kashi.sepantapouya.com/docs/components/tour/): معرفی بخش‌های تازهٔ محصول به کاربر، مرحله به مرحله، با روشن کردن همان بخش.
- [نمای درختی (TreeView)](https://kashi.sepantapouya.com/docs/components/tree-view/): نمایش ساختار سلسله‌مراتبی مثل پوشه‌ها، دسته‌بندی محصولات یا نمودار سازمانی.

## شروع

- [راهنمای آیکون‌ها](https://kashi.sepantapouya.com/docs/icons/usage/): ۴۵۰۰ آیکون نرم در شش سبک با گوشه‌های پیوسته، هم‌خانواده با کامپوننت‌های کاشی؛ برای React، HTML، هر فریم‌ورک دیگر و فیگما.
- [معرفی](https://kashi.sepantapouya.com/docs/): کاشی چیست، برای چه کسانی است و از چه بخش‌هایی تشکیل شده.
- [نصب](https://kashi.sepantapouya.com/docs/installation/): کاشی را در پروژهٔ React یا هر پروژهٔ وب دیگری راه‌اندازی کنید.
- [Tailwind](https://kashi.sepantapouya.com/docs/tailwind/): رنگ‌ها، فونت، گردی گوشه و سایه‌های کاشی به‌شکل کلاس‌های Tailwind؛ همگام با تم تیره و روشن و رنگ برند شما.
- [سفارشی‌سازی و تم](https://kashi.sepantapouya.com/docs/theming/): کاشی را با برند خود هماهنگ کنید؛ از یک رنگ تا جزئی‌ترین متغیر هر کامپوننت.
- [فونت و تایپوگرافی](https://kashi.sepantapouya.com/docs/typography/): وزیرمتن پیش‌فرض است، ولی هر فونتی، رایگان یا خریداری‌شده، با یک خط قابل‌جایگزینی است.

## فارسی

- [هیت‌مپ فعالیت (ActivityHeatmap)](https://kashi.sepantapouya.com/docs/persian/activity-heatmap/): فعالیت روزانهٔ یک سال شمسی به سبک GitHub، با ماه‌های جلالی و هفتهٔ شنبه‌تا‌جمعه.
- [کارت بانکی (BankCard)](https://kashi.sepantapouya.com/docs/persian/bank-card/): نمایش کارت بانکی با رنگ و لوگوی بانک، شمارهٔ پوشانده و تاریخ انقضای شمسی.
- [شمارش معکوس (Countdown)](https://kashi.sepantapouya.com/docs/persian/countdown/): زمان باقی‌مانده با ارقام فارسی، برای ارسال دوبارهٔ کد، پایان تخفیف یا شروع رویداد.
- [دیت‌پیکر شمسی (DatePicker, Calendar)](https://kashi.sepantapouya.com/docs/persian/date-picker/): فیلد تاریخ با تقویم شمسی؛ تایپ مستقیم یا انتخاب از تقویم، با پیمایش کامل کیبورد و پشتیبانی صفحه‌خوان.
- [بازهٔ تاریخ شمسی (DateRangePicker)](https://kashi.sepantapouya.com/docs/persian/date-range/): انتخاب بازهٔ تاریخ با تقویم جلالی و میان‌برهایی مثل «۷ روز اخیر» و «ماه قبل».
- [برگ تقویم (DateTile)](https://kashi.sepantapouya.com/docs/persian/date-tile/): کاشی تاریخ شمسی به شکل برگ تقویم، با روز هفته، مناسبت تعطیل و معادل میلادی.
- [فیلد فارسی (PersianInput)](https://kashi.sepantapouya.com/docs/persian/input/): یک کامپوننت برای همهٔ داده‌های فارسی؛ کد ملی، شناسهٔ شرکت، موبایل، تلفن، کارت، شبا، مبلغ، کد پستی، ساعت، پلاک و متن با اصلاح زبان صفحه‌کلید.
- [نمایش مبلغ (Money)](https://kashi.sepantapouya.com/docs/persian/money/): مبلغ با تومان یا ریال، حالت خلاصه مثل «۱٫۲ میلیون» و مبلغ به حروف برای صفحه‌خوان.
- [انتخاب ماه (MonthPicker)](https://kashi.sepantapouya.com/docs/persian/month-picker/): انتخاب ماه و سال شمسی برای گزارش ماهانه، صورت‌حساب یا تاریخ انقضا.
- [کد تأیید (OTP) (OtpInput)](https://kashi.sepantapouya.com/docs/persian/otp/): ورود کد پیامکی یک‌بارمصرف؛ با پر شدن خودکار از پیامک در گوشی و ارقام فارسی.
- [انتخاب استان (ProvinceSelect)](https://kashi.sepantapouya.com/docs/persian/province/): انتخاب یکی از ۳۱ استان با جستجو؛ با نام مرکز استان هم پیدا می‌شود.
- [رسید پرداخت (PaymentReceipt)](https://kashi.sepantapouya.com/docs/persian/receipt/): صفحهٔ نتیجهٔ پرداخت با وضعیت، مبلغ به حروف، کد پیگیری قابل کپی و کارت پوشانده.
- [ویرایش نگارشی (PersianTextarea)](https://kashi.sepantapouya.com/docs/persian/text-fix/): ناحیهٔ متن که «ي» و «ك» عربی، نیم‌فاصله، علامت‌های فارسی و ارقام را پیدا و با یک کلیک اصلاح می‌کند.
- [ابزارهای فارسی](https://kashi.sepantapouya.com/docs/persian/utilities/): تاریخ شمسی، ارقام فارسی، قالب‌بندی اعداد و اعتبارسنجی؛ بدون وابستگی و برای هر فریم‌ورکی.

## Optional

- [Full documentation in one file](https://kashi.sepantapouya.com/llms-full.txt)
- [Source code](https://github.com/Sepantapouya/Kashi)