راهنمای مهاجرت

راهنمای گام‌به‌گام مهاجرت پروژه‌های فرانت‌اند به Parto Design System

پیش‌نیازها

قبل از شروع مهاجرت، مطمئن شوید:

پروژه از React ≥ 18 استفاده می‌کند
Tailwind CSS نصب و پیکربندی شده
پروژه از TypeScript استفاده می‌کند (توصیه‌شده)

مراحل مهاجرت

۱. نصب و راه‌اندازی

# نصب پکیج
pnpm add @partodata/ui

# یا با npm
npm install @partodata/ui

۲. وارد کردن استایل‌ها

روی Tailwind v4 (مسیر پیشنهادی) فقط یک خط لازم است — همان یک import، استایل کامپوننت‌ها، نگاشت نقش‌ها، و متغیر dark: را با هم می‌آورد:

/* app/globals.css */
@import 'tailwindcss';
@import '@partodata/ui/tailwind.css';

روی Tailwind v3 به‌جای آن، styles.css را قبل از دایرکتیوهای Tailwind بیاورید و از preset استفاده کنید (گام ۳). برای جزئیات کامل هر دو مسیر، راهنمای نصب را ببینید.

۳. تنظیم Tailwind (فقط v3)

روی Tailwind v4، پیکربندی JS لازم نیست. روی Tailwind v3 با preset و content glob پیکربندی کنید:

// tailwind.config.ts (Tailwind v3)
import partoConfig from '@partodata/ui/tailwind.config'
import type { Config } from 'tailwindcss'

const config: Config = {
  presets: [partoConfig],
  darkMode: ['class', '[data-theme="dark"]'],
  content: [
    './src/**/*.{ts,tsx}',
    // اسکن کلاس‌های کامپایل‌شده‌ی DS تا purge نشوند
    './node_modules/@partodata/ui/dist/**/*.{js,cjs}',
  ],
}

export default config

۴. پیکربندی Next.js (اگر از Next.js استفاده می‌کنید)

// next.config.mjs
const config = {
  transpilePackages: ['@partodata/ui'],
  // ...
}

۵. جایگزینی کامپوننت‌ها

ترتیب پیشنهادی

مهاجرت را از پایین‌ترین سطح شروع کنید و به بالا بروید:

ابتدا Primitive‌ها — Button, Input, Badge, Label, Separator
سپس Form Controls — Select, Checkbox, Radio, Switch, Textarea
سپس Feedback — Toast, Alert, Dialog, Tooltip, Progress
سپس Data Display — Card, Table, Skeleton, Avatar
سپس Navigation — Tabs, Breadcrumb, Pagination, Sidebar
سپس Composed — FilterBar, DataTable, MetricCard, Empty, ErrorState

الگوی جایگزینی

برای هر کامپوننت:

// قبل
import { Button } from '@/components/ui/button'

// بعد
import { Button } from '@partodata/ui'

تفاوت‌های کلیدی API

کامپوننت	shadcn محلی	Parto DS	تغییر مورد نیاز
Button	`variant: 'default'`	`variant: 'primary'`	بروزرسانی variant‌ها
Button	`size: 'default'`	`size: 'sm'`	سایز پیش‌فرض `sm` است
Card	فقط `default`	`default`, `outlined`, `elevated`, `interactive`	بدون تغییر لازم
Badge	`variant: 'default'`	همان + `success`, `warning`, `brand`	variant‌های جدید در دسترس
Select	بدون سایز	سایزهای `xs` تا `xl`	می‌توانید سایز اضافه کنید

۶. حذف کامپوننت‌های محلی

بعد از جایگزینی هر کامپوننت:

از تمام importها مطمئن شوید که به DS اشاره می‌کنند
فایل محلی کامپوننت را حذف کنید
اگر فایل components/ui/ خالی شد، کل دایرکتوری را حذف کنید

۷. حذف وابستگی‌های اضافی

بعد از مهاجرت کامل، این وابستگی‌ها را می‌توانید حذف کنید:

# وابستگی‌های Radix UI تکراری
pnpm remove @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-select
# ... و سایر پکیج‌های @radix-ui

# ابزارهای استایل
pnpm remove class-variance-authority clsx tailwind-merge
# (فقط اگر در جای دیگری استفاده نمی‌شوند)

# ابزارهای UI
pnpm remove lucide-react cmdk vaul sonner
# (فقط اگر مستقیماً استفاده نمی‌شوند — DS آن‌ها را re-export می‌کند)

هوک‌ها

DS هوک‌های آماده‌ای دارد که معادل هوک‌های محلی پروژه‌تان هستند:

هوک محلی	معادل DS	توضیح
`useMobile()` / `useIsMobile()`	`useIsMobile()`	نکته: در SSR مقدار `undefined` برمی‌گرداند
`useDebounce()`	`useDebounce()`	debounce مقدار
`useLocalStorage()`	`useLocalStorage()`	sync با localStorage
`useScrollLock()`	`useScrollLock()`	قفل اسکرول body
`useToast()`	`useToast()`	re-export از Sonner
`useInfiniteScroll()`	`useInfiniteScroll()`	تشخیص رسیدن به انتهای لیست

توابع کمکی

تابع محلی	معادل DS	توضیح
`cn()`	`cn()`	ادغام کلاس‌ها (clsx + tailwind-merge)
`formatNumber()`	`formatNumber()`	فرمت عدد با locale
`toPersianNumber()`	— (حذف کنید)	ارقام از فونت می‌آیند؛ برای جداکننده `formatNumber`

توکن‌های رنگ

نگاشت رنگ‌ها

الگوی shadcn	معادل Parto DS
`bg-background`	`bg-background` یا `bg`
`text-foreground`	`text-foreground` یا `text`
`border-border`	`border-border-default` یا `border`
`bg-muted`	`bg-background-muted` یا `bg-muted`
`text-muted-foreground`	`text-foreground-muted` یا `text-muted`
`bg-primary`	`bg-brand`
`text-primary`	`text-brand`
`bg-destructive`	`bg-destructive`
`bg-card`	`bg-background-surface-100`

رنگ‌های اضافی DS

DS توکن‌هایی دارد که در shadcn پیش‌فرض وجود ندارند:

Score Tiers: bg-score-excellent, text-score-critical, bg-score-moderate-bg
Engagement: bg-engagement-excellent, text-engagement-poor
Sentiment: text-sentiment-positive, bg-sentiment-negative
Elevation: shadow-elevation-1 تا shadow-elevation-4
Surface Levels: bg-surface-75 تا bg-surface-400 — این‌ها یک نردبان تخت و یکنواخت نیستند: surface-75/100/300 سطوح توپُر (solid) هستند، اما surface-200 و surface-400 لایه‌های نیمه‌شفاف تطبیقی‌اند که روی پس‌زمینهٔ پشت خود ترکیب می‌شوند و با آن بالا می‌آیند

تم‌ها

DS دو تم دارد: Light و Dark.

اگر پروژه‌تان از next-themes استفاده می‌کند، DS خودش next-themes را به‌عنوان optional peer dependency پشتیبانی می‌کند.

// Dark mode خودکار
<div className="dark:bg-background-surface-100">

نکات مهم

RTL

DS بر اساس CSS Logical Properties ساخته شده:

// اشتباه
className = 'ml-4 mr-2 pl-3 pr-1 left-0 text-left border-l'

// درست
className = 'ms-4 me-2 ps-3 pe-1 start-0 text-start border-s'

سایز پیش‌فرض

سایز پیش‌فرض در DS همیشه "sm" است (۳۴ پیکسل)، نه "default" یا "md". همه‌ی سایزهای نام‌دار (xs/sm/md/lg/xl) در دسترس‌اند؛ xs برای کانتکست‌های فشرده (نوار ابزار، جدول‌های فشرده) همچنان گزینه‌ی درستی است.

آیکون‌ها

DS آیکون‌های Lucide را re-export می‌کند. اگر آیکون خاصی را لازم دارید:

// آیکون‌های re-export شده از DS
import { Icons } from '@partodata/ui'
;<Icons.search className="size-4" />

// اگر آیکونی در DS نبود، مستقیماً از lucide-react وارد کنید
import { SpecificIcon } from 'lucide-react'

`"use client"`

تمام کامپوننت‌های تعاملی DS دارای "use client" هستند — نیازی به اضافه کردن مجدد ندارید.