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

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

پیش‌نیازها

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

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

مراحل مهاجرت

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

# نصب پکیج
pnpm add @parto-system-design/ui

# یا با npm
npm install @parto-system-design/ui

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

در فایل اصلی CSS (مثلاً globals.css یا index.css)، استایل‌های DS را وارد کنید:

@import '@parto-system-design/ui/styles.css';

مهم: این import باید قبل از import‌های Tailwind شما باشد تا توکن‌ها و متغیرهای CSS به‌درستی بارگذاری شوند.

۳. تنظیم Tailwind

پیکربندی Tailwind را برای استفاده از تنظیمات DS به‌روز کنید:

// tailwind.config.ts
import partoConfig from '@parto-system-design/ui/tailwind.config'
import type { Config } from 'tailwindcss'

const config: Config = {
  // ادغام تنظیمات DS با تنظیمات خودتان
  presets: [partoConfig],
  content: [
    './src/**/*.{ts,tsx}',
    // اضافه کردن مسیر node_modules برای اسکن کلاس‌های DS
    './node_modules/@parto-system-design/ui/dist/**/*.{js,cjs}',
  ],
  // تنظیمات خاص پروژه‌تان
  theme: {
    extend: {
      // ...
    },
  },
}

export default config

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

// next.config.mjs
const config = {
  transpilePackages: ['@parto-system-design/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 '@parto-system-design/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()`	`convertToLocalNumbers()`	تبدیل ارقام

توکن‌های رنگ

نگاشت رنگ‌ها

الگوی shadcn	معادل Parto DS
`bg-background`	`bg-background-default` یا `bg`
`text-foreground`	`text-foreground-default` یا `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-default`
`text-primary`	`text-brand-default`
`bg-destructive`	`bg-destructive-default`
`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-background-surface-75 تا bg-background-surface-400

تم‌ها

DS سه تم دارد: Light, Dark, Classic 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" (small) است، نه "default" یا "md".

آیکون‌ها

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

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

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

`"use client"`

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