رفتن به محتوای اصلی
  • معرفی
  • نصب
  • Tailwind
  • وب کامپوننت‌ها (بدون React)
  • دوزبانه، فارسی و انگلیسی
  • پلاگین‌های فیگما
  • استفاده با هوش مصنوعی
  • آیکون‌ها
  • راهنمای آیکون‌ها
  • سفارشی‌سازی و تم
  • حرکت و ریزتعامل‌ها
  • حالت‌های کامپوننت‌ها
  • فونت و تایپوگرافی
  • دسترس‌پذیری
  • نوشتن متن رابط
  • رنگ‌ها
  • برند کاشی
  • مقایسه با دیگران
  • نسخه‌ها
  • سیاست تغییرات
  • مهاجرت به ۲.۰
  • امنیت
  • حجم کامپوننت‌ها
  • فیلد فارسی
  • دیت‌پیکر شمسی
  • کد تأیید (OTP)
  • بازهٔ تاریخ شمسی
  • انتخاب ماه
  • شمارش معکوس
  • هیت‌مپ فعالیت
  • انتخاب استان
  • نقشهٔ ایران
  • فرم نشانی
  • انتخاب نوبت
  • ویرایش نگارشی
  • نمایش مبلغ
  • بازهٔ قیمت
  • کارت بانکی
  • رسید پرداخت
  • برگ تقویم
  • لوگوی بانک‌ها
  • ابزارهای فارسی
  • آپلود فایل
  • آکاردئون
  • آواتار
  • اسپلیتر
  • استپر
  • اسکلتون
  • اسلایدر
  • اعتبارسنجی فرم
  • امتیاز ستاره‌ای
  • انتخاب چندتایی
  • انتخاب رنگ
  • بج
  • بردکرامب
  • برگهٔ پایین
  • بنر
  • پاپ‌اور
  • تایم‌لاین
  • تب‌ها
  • تور معرفی
  • توست
  • تولتیپ
  • جداکننده و کلید میان‌بر
  • جدول داده
  • جستجو با پیشنهاد
  • چک‌باکس
  • چیپس
  • حالت خالی
  • دراپ‌داون
  • دکمه
  • دکمهٔ کپی
  • دیالوگ
  • رادیو
  • سایدبار
  • سگمنت
  • سلکت
  • سوییچ
  • صفحه‌بندی
  • قدرت رمز عبور
  • کارت
  • کارت آمار
  • کاروسل
  • کامبوباکس
  • کامند پالت
  • کشو
  • گروه دکمه
  • گیج
  • منوی راست‌کلیک
  • نمای درختی
  • نمودار
  • نمونهٔ رنگ
  • نوار پیشرفت
  • نوار ناوبری
  • ورودی
  • ورودی تگ
  • ورودی عدد
  • ویرایش درجا
  • هشدار
شروع کنید

مهاجرت به ۲.۰

کاشی ۲.۰ ظاهر یکپارچه و مینیمال تازه دارد؛ هیچ prop یا کلاسی حذف نشده. اینجا می‌بینید چه چیزی عوض شده و اگر لازم شد، چطور ظاهر قبلی را برگردانید.

کاشی ۲.۰ یک بازطراحی بصری است: همهٔ کامپوننت‌ها یکدست‌تر، ساده‌تر و آرام‌تر شده‌اند. طبق سیاست تغییرات، تغییر ظاهر پیش‌فرض فقط در نسخهٔ اصلی می‌آید؛ برای همین این نسخه ۲ است. هیچ prop، کلاس CSS، تگ یا تابعی حذف یا تغییر نام نداده است و کد شما بدون تغییر کار می‌کند.

به‌روزرسانی

npm i @kashi-ui/react@^2 @kashi-ui/css@^2

همهٔ پکیج‌های کاشی را با هم به ۲ ببرید (@kashi-ui/elements، @kashi-ui/persian، @kashi-ui/tailwind و…)؛ نسخه‌ها یکی‌اند. اگر با shadcn نصب کرده‌اید، کامپوننت‌هایی را که دارید دوباره اضافه کنید.

چه چیزی عوض شده

  • کنترل‌ها تخت‌اند. دکمه‌ها، فیلدها و انتخاب‌ها سایهٔ اسکئومورفیک و برق لبه ندارند. توکن‌های --k-shadow-skeuomorphic، --k-highlight و --k-shadow-xs هنوز هستند ولی مقدارشان خالی است.
  • گوشه‌ها نرم‌تر و دو نقش ثابت دارند. پلهٔ گردی: sm ۶، md ۱۲، lg ۱۶، xl ۲۰ و 2xl ۲۸ پیکسل (قبلاً ۴، ۸، ۱۲، ۱۶ و ۲۴). دو توکن معنایی تازه: --k-radius-control برای دکمه، فیلد، انتخاب و سگمنت، و --k-radius-surface برای کارت، آکاردئون و پنجره.
  • یک حاشیه برای همهٔ کنترل‌ها. توکن تازهٔ --k-border-control حاشیهٔ فیلد، انتخاب، دکمهٔ ثانویه، OTP و ورودی برچسب است؛ دیگر کنترل‌های کنار هم دو رنگ حاشیهٔ متفاوت ندارند.
  • سلکت در React فهرست کاشی را باز می‌کند، نه فهرست بومی مرورگر؛ با صفحه‌کلید کامل و یک <select> بومیِ پنهان برای فرم. API همان است. برای فهرست بومی native بدهید. در HTML ساده (k-select) همان فهرست بومی می‌ماند.
  • سگمنت و زبانه‌های segmented ریل پُرزمینه بدون حاشیه دارند و گزینهٔ انتخاب‌شده فقط زمینهٔ روشن‌تر می‌گیرد (توکن‌های تازهٔ --k-bg-muted و --k-bg-raised).
  • آکاردئون هر بخش را یک کارت نرم و جدا نشان می‌دهد. flush همان فهرست ساده با خط جداکننده است.
  • دکمهٔ danger-secondary نرم است: زمینهٔ قرمز کم‌رنگ، بدون حاشیه.
  • جدول، منو و راهنمای نمودار گوشهٔ بزرگ‌تر، سرستون آرام‌تر و راهنمای نمودار با ردیف سری در زمینهٔ نرم دارند.

حرکت و ریزتعامل‌ها

در ۲.۰ هر کامپوننت با یک حرکت کوتاه به کاربر می‌گوید چه شد. این حرکت‌ها فقط CSS‌اند، به کد شما چیزی اضافه نمی‌کنند و با «کاهش حرکت» سیستم‌عامل خاموش می‌شوند. روی این‌ها کلیک کنید:

کد ملی باید ۱۰ رقم باشد.

<Button variant="primary">ادامه</Button>
<CopyButton value="npm i @kashi-ui/react@^2" />
<Switch label="اعلان‌ها" />
<Checkbox label="مرا به خاطر بسپار" />
<SegmentedControl options={…} />
<Input label="کد ملی" error="…" />
کامپوننت در ۱.x در ۲.۰
دکمه فقط تغییر رنگ با کلیک کمی فشرده می‌شود؛ فلش انتها با hover جلو می‌رود
دکمهٔ کپی متن عوض می‌شد تیک سبز با جهش
سوییچ دستگیره جابه‌جا می‌شد دستگیره هنگام فشردن کش می‌آید و با فنر جا می‌افتد
چک‌باکس، رادیو، چیپ تیک فوری تیک از مرکز با جهش؛ کنترل هنگام کلیک فشرده می‌شود
سگمنت و زبانه‌ها گزینه می‌پرید دستگیره بین گزینه‌ها می‌لغزد
فیلد با خطا پیام فوری ظاهر می‌شد فیلد یک بار می‌لرزد و پیام نرم می‌آید
سلکت، منو، تقویم ظاهر شدن ساده از سمت فیلد با کمی بزرگ شدن باز می‌شوند
آکاردئون و پنجره فقط باز شدن متن نرم ظاهر می‌شود؛ پنجره سریع و نرم بسته می‌شود

دو توکن تازه هم اضافه شده: --k-ease-spring برای بازخورد کوچک با کمی جهش و --k-ease-exit برای بسته شدن. همهٔ توکن‌ها و قاعده‌ها در حرکت و ریزتعامل‌ها هستند.

اگر تست تصویری دارید: فشردن و لرزش ممکن است در لحظهٔ عکس گرفتن دیده شوند. در Playwright reducedMotion: "reduce" بدهید تا همه‌چیز فوری عوض شود.

چه چیزی تازه است

برگرداندن ظاهر نسخهٔ ۱

اگر به‌خاطر هماهنگی با بقیهٔ محصول فعلاً ظاهر قبلی را می‌خواهید، این چند خط را بعد از CSS کاشی بگذارید. هر کدام را جدا هم می‌شود برداشت.

:root {
  /* گوشه‌های نسخهٔ ۱ */
  --k-radius-sm: calc(0.25rem * var(--k-radius-factor));
  --k-radius-md: calc(0.5rem * var(--k-radius-factor));
  --k-radius-lg: calc(0.75rem * var(--k-radius-factor));
  --k-radius-xl: calc(1rem * var(--k-radius-factor));
  --k-radius-2xl: calc(1.5rem * var(--k-radius-factor));
}
/* آکاردئون جعبه‌ای با خط جداکننده */
.k-accordion { gap: 0; border: 1px solid var(--k-border-secondary); border-radius: var(--k-radius-xl); overflow: hidden; }
.k-accordion__item { border-radius: 0; }
.k-accordion__item + .k-accordion__item { border-block-start: 1px solid var(--k-border-secondary); }
/* حرکت آرام بدون جهش فنری (ریزتعامل‌ها می‌مانند، فقط جهش ندارند) */
:root { --k-ease-spring: var(--k-ease-standard); }

و برای سلکت، native بدهید.

مهاجرت به ۱.۰

کاشی ۱.۰ همان کاشی ۰.۲۶ است با قولِ پایداری: از این نسخه، هر تغییر ناسازگار فقط در نسخهٔ اصلی بعدی و پس از دوره‌ای «منسوخ» می‌آید (سیاست تغییرات).

به‌روزرسانی

npm i @kashi-ui/react@^1 @kashi-ui/css@^1

همهٔ پکیج‌های کاشی را با هم به ۱ ببرید (@kashi-ui/elements، @kashi-ui/persian، @kashi-ui/tailwind و…)؛ نسخه‌ها یکی‌اند.

تغییر کدی لازم نیست. هیچ prop، کلاس CSS، تگ یا تابعی حذف یا تغییر نام نداده است و متن‌ها و ظاهر پیش‌فرض همان فارسیِ قبل‌اند.

اگر با shadcn نصب کرده‌اید

کامپوننت‌ها حالا متن‌هایشان را از KashiProvider می‌خوانند. پس از به‌روزرسانی، کامپوننت‌هایی را که دارید دوباره اضافه کنید تا فایل تازهٔ components/kashi/KashiProvider.tsx هم بیاید:

npx shadcn@latest add @kashi/kashi-provider @kashi/date-picker

اگر در کد کامپوننت‌ها تغییری داده‌اید، پیش از دوباره اضافه کردن آن را نگه دارید؛ shadcn فایل را بازنویسی می‌کند.

چه چیزهایی تازه بود

  • دوزبانه: با <KashiProvider locale="en"> یا setLocale("en") همهٔ متن‌های داخلی، ارقام و نام ماه‌ها انگلیسی می‌شوند.
  • سیاست تغییرات و امنیت: قول‌های مکتوب برای پایداری و رفع آسیب‌پذیری.
  • حجم کامپوننت‌ها: حجم هر کامپوننت در صفحهٔ خودش و سقفی که تست نمی‌گذارد از آن بیشتر شود.
  • تست تصویری از همهٔ کامپوننت‌ها در دو تم.
  • ابزارهای فارسی گزینهٔ locale: "en" گرفته‌اند و bankName و operatorName برای نام انگلیسی بانک و اپراتور اضافه شده‌اند.

نکته‌های کوچک

  • defaultPasswordRules و defaultRangePresets همچنان فارسی‌اند. اگر rules یا presets ندهید، کامپوننت شرط‌ها و میان‌برها را به زبان KashiProvider می‌سازد.
  • formatBytes در React و وب کامپوننت‌ها با زبان انگلیسی واحدها را KB و MB می‌نویسد.