مستندات

شروع سریع

وایب‌فارسی پکیج npm نیست. هر قطعه به‌صورت فایل داخل پروژه نوشته می‌شود؛ از همان لحظه مال خودتان است و آزادانه تغییرش می‌دهید. شروع دو راه دارد: خودکار با CLI، یا دستی با کپی همان فایل‌ها. خروجی هر دو یکی است.

کامپوننت‌هادکمه، فرم، جدول؛ از پایه راست‌چین۵۹ بلاک‌هابخش‌های آماده: هیرو، قیمت، پرسش‌های متداول۸ انیمیشن‌هاحرکت با CSS و React؛ بدون کتابخانه‌ی اضافه۳۹ پس‌زمینه‌هاالگو و نور کم‌کنتراست؛ متن خوانا می‌ماند۳۲ قالب‌هاصفحه‌های کامل، از همین قطعه‌ها۲۴ سیستم‌های طراحیتوکن رنگ و شعاع؛ هر وقت بخواهید عوض می‌شود۶

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

در پروژه‌ی Next.js یا Vite با Tailwind v4، دو دستور CLI فونت، جهت و توکن‌ها را می‌نویسد. اگر CLI نمی‌خواهید یا ساختار پروژه فرق دارد، راه دستی همان فایل‌ها را نشان می‌دهد تا خودتان بگذارید.

خودکارپیشنهادی

با CLI

دو دستور. init پروژه را راست‌چین و فارسی می‌کند؛ add قطعه‌ها را با وابستگی‌هایشان می‌آورد.

Next.js یا Vite · Tailwind v4راهنما

دستی

کپی فایل‌ها

چند فایل پایه را خودتان می‌نویسید؛ کد هر قطعه را از تب «کد» صفحه‌اش کپی می‌کنید. بدون ابزار اضافه.

هر پروژه‌ی React · Tailwind v4راهنما

راه اول · خودکار

نصب خودکار با CLI

داخل پروژه‌ی React با Tailwind v4 اجرا کنید. CLI فایل‌ها را می‌نویسد و پکیج‌های لازم را با همان مدیر پکیج پروژه نصب می‌کند: npm، pnpm، yarn یا bun.

۱
پروژه را آماده کنید
یک‌بار در ریشه‌ی پروژه اجرا کنید.
$npx vibefarsi init
این دستور این فایل‌ها را می‌نویسد
- lang="fa" dir="rtl" روی <html>؛ در Next.js داخل app/layout.tsx و در Vite داخل index.html
- فونت Vazirmatn: در Next.js فایل app/fonts.ts و کلاس آن روی html؛ در بقیه‌ی پروژه‌ها import از Google Fonts داخل CSS
- توکن‌های تم گرافیت و نگاشت Tailwind در globals.css
- lib/utils.ts و lib/jalali.ts از رجیستری
- vibefarsi.json و مسیر @/* در tsconfig
نکتهاگر پروژه پوشه‌ی src دارد، همه‌ی این فایل‌ها داخل src نوشته می‌شوند. globals.css و layout.tsx فقط وصله می‌شوند، از نو نوشته نمی‌شوند. فایل‌های lib اگر از قبل باشند دست نمی‌خورند، مگر با --overwrite.
۲
قطعه‌ها را اضافه کنید
هر قطعه با وابستگی‌هایش می‌آید؛ مثلاً calendar فایل lib/jalali.ts را هم می‌آورد و پکیج‌های npm لازم نصب می‌شوند. بعد از نوشتن، فایل مال خودتان است؛ آزادانه تغییرش دهید.
$npx vibefarsi add button calendar price
مقصد فایل‌ها
- کامپوننتcomponents/ui/
- بلاکcomponents/blocks/
- انیمیشنcomponents/animations/
- پس‌زمینهcomponents/backgrounds/
- قالبcomponents/templates/
- تمglobals.css
اسم قطعه‌ها
slug انگلیسی هر قطعه کنار عنوان صفحه‌اش آمده. فهرست کامل:
$npx vibefarsi list

گزینه‌ها (اختیاری)

هر دو دستور این گزینه‌ها را می‌گیرند.

گزینه	کار
`--font iransans`	اگر `IRANSans-Reg.woff` در `/fonts` یا `/public` باشد، همان را به‌جای Vazirmatn وصل می‌کند
`--theme saffron`	تم دیگری به‌جای گرافیت. بعداً هم با `npx vibefarsi add saffron` عوضش کنید
`--registry http://localhost:3000/r`	رجیستری همین ماشین، وقتی روی خود مخزن کار می‌کنید
`--dry-run`	فقط نشان می‌دهد چه فایل‌هایی نوشته می‌شوند؛ چیزی تغییر نمی‌کند
`--overwrite`	فایل‌های موجود را جایگزین می‌کند
`--no-install`	پکیج‌های npm را نصب نمی‌کند

راه دوم · دستی

نصب دستی

همان چیزی که init می‌نویسد، این‌جا فایل‌به‌فایل آمده. هر بلوک را کپی کنید و در مسیر گفته‌شده بگذارید. پیش‌نیاز React با Tailwind v4 است.

جهت و فونت

روی html، dir="rtl" و lang="fa" بگذارید و فونت را با یک متغیر CSS وصل کنید. نمونه‌ی Next.js با Vazirmatn از Google Fonts:

app/layout.tsx

1// app/layout.tsx2import { Vazirmatn } from "next/font/google"3import "./globals.css"45const vazirmatn = Vazirmatn({6  subsets: ["arabic", "latin"],7  variable: "--font-vazirmatn",8  display: "swap",9})1011export default function RootLayout({ children }) {12  return (13    <html lang="fa" dir="rtl" className={vazirmatn.variable}>14      <body className="bg-background text-foreground font-sans">{children}</body>15    </html>16  )17}

نکتهبرای IRANSans، فایل‌های woff را در /fonts بگذارید و با next/font/local همان متغیر را بسازید. در Vite به‌جای next/font، این خط را بالای CSS بگذارید:

globals.css (فقط Vite)

1@import url("https://fonts.googleapis.com/css2?family=Vazirmatn:wght@400;500;600;700&display=swap");

توکن‌های تم

کامپوننت‌ها رنگ‌شان را فقط از این متغیرها می‌گیرند. این بلوک را در globals.css بگذارید.

app/globals.css (تم گرافیت)

1/* گرافیت، پیش‌فرض. این بلوک را در :root بگذارید. */2:root {3  color-scheme: dark;4  --background: oklch(0.115 0.002 285);5  --foreground: oklch(0.975 0 0);6  --card: oklch(0.14 0.002 285);7  --card-foreground: oklch(0.975 0 0);8  --popover: oklch(0.16 0.002 285);9  --popover-foreground: oklch(0.975 0 0);10  --primary: oklch(0.975 0 0);11  --primary-foreground: oklch(0.13 0 0);12  --secondary: oklch(0.2 0.002 285);13  --secondary-foreground: oklch(0.975 0 0);14  --muted: oklch(0.175 0.002 285);15  --muted-foreground: oklch(0.63 0.004 285);16  --accent: oklch(0.2 0.002 285);17  --accent-foreground: oklch(0.975 0 0);18  --destructive: oklch(0.65 0.2 25);19  --success: oklch(0.75 0.16 160);20  --warning: oklch(0.82 0.16 80);21  --border: oklch(1 0 0 / 8%);22  --input: oklch(1 0 0 / 11%);23  --ring: oklch(0.7 0 0);24  --brand: oklch(0.8 0.165 65);25  --brand-foreground: oklch(0.22 0.06 60);26  --radius: 0.625rem;27}

نکتهتم‌های دیگر (فیروزه، زعفران، انار، لاجورد، کاغذ) در سیستم‌های طراحی هستند. همان ساختار را دارند و جای همین بلوک می‌نشینند.

نگاشت Tailwind

این بلوک متغیرهای بالا را به کلاس‌های Tailwind مثل bg-background و text-muted-foreground وصل می‌کند. زیر بلوک تم بگذارید. اگر اسم متغیر فونت فرق دارد، خط --font-sans را با همان عوض کنید.

app/globals.css (نگاشت Tailwind)

1/* app/globals.css */2@theme inline {3  --color-background: var(--background);4  --color-foreground: var(--foreground);5  --color-card: var(--card);6  --color-card-foreground: var(--card-foreground);7  --color-popover: var(--popover);8  --color-popover-foreground: var(--popover-foreground);9  --color-primary: var(--primary);10  --color-primary-foreground: var(--primary-foreground);11  --color-secondary: var(--secondary);12  --color-secondary-foreground: var(--secondary-foreground);13  --color-muted: var(--muted);14  --color-muted-foreground: var(--muted-foreground);15  --color-accent: var(--accent);16  --color-accent-foreground: var(--accent-foreground);17  --color-destructive: var(--destructive);18  --color-success: var(--success);19  --color-warning: var(--warning);20  --color-border: var(--border);21  --color-input: var(--input);22  --color-ring: var(--ring);23  --color-brand: var(--brand);24  --color-brand-foreground: var(--brand-foreground);25  --radius-sm: calc(var(--radius) - 4px);26  --radius-md: calc(var(--radius) - 2px);27  --radius-lg: var(--radius);28  --radius-xl: calc(var(--radius) + 4px);29  --font-sans: var(--font-vazirmatn), "Vazirmatn", ui-sans-serif, system-ui, sans-serif;30}3132@layer base {33  body {34    font-size: 16.5px;35    line-height: 1.8;36    letter-spacing: 0;37    text-rendering: optimizeLegibility;38    -webkit-font-smoothing: antialiased;39  }40}

ابزارهای کمکی

cn برای کلاس‌ها، fa و faNumber برای ارقام فارسی، formatToman برای قیمت. در lib/utils.ts بگذارید.

lib/utils.ts

1export type ClassValue = string | number | bigint | null | undefined | false | ClassValue[];23/** Minimal class joiner (swap for clsx + tailwind-merge when the library grows). */4export function cn(...inputs: ClassValue[]): string {5  const out: string[] = [];6  for (const i of inputs) {7    if (!i) continue;8    if (Array.isArray(i)) {9      const nested = cn(...i);10      if (nested) out.push(nested);11    } else {12      out.push(String(i));13    }14  }15  return out.join(" ");16}1718const FA_DIGITS = ["۰", "۱", "۲", "۳", "۴", "۵", "۶", "۷", "۸", "۹"];1920/** Convert Latin digits in a string/number to Persian digits: 1405 -> ۱۴۰۵ */21export function fa(value: string | number): string {22  return String(value).replace(/\d/g, (d) => FA_DIGITS[Number(d)]);23}2425/** Persian digits back to Latin (for parsing user input). */26export function en(value: string): string {27  return value.replace(/[۰-۹]/g, (d) => String(FA_DIGITS.indexOf(d))).replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660));28}2930/** Thousands-separated Persian number: 12450000 -> ۱۲٬۴۵۰٬۰۰۰ */31export function faNumber(value: number): string {32  return fa(Math.round(value).toLocaleString("en-US")).replace(/,/g, "٬");33}3435/** Amount in toman with unit: 12450000 -> ۱۲٬۴۵۰٬۰۰۰ تومان */36export function formatToman(value: number): string {37  return `${faNumber(value)} تومان`;38}3940/** Percent with Persian digits and the Persian percent sign: 18 -> ۱۸٪ */41export function faPercent(value: number, digits = 0): string {42  return `${fa(value.toFixed(digits))}٪`;43}4445/** File size in Persian: 1258291 -> ۱٫۲ مگابایت */46export function faFileSize(bytes: number): string {47  if (bytes < 1024) return `${fa(bytes)} بایت`;48  if (bytes < 1024 ** 2) return `${fa((bytes / 1024).toFixed(0))} کیلوبایت`;49  return `${fa((bytes / 1024 ** 2).toFixed(1)).replace(".", "٫")} مگابایت`;50}

نکتهتقویم و انتخاب تاریخ به lib/jalali.ts هم نیاز دارند؛ از /r/lib/jalali.json بردارید.

۵
قطعه‌ها
در صفحه‌ی هر قطعه، تب «کد» را کپی کنید و در components/ui/<slug>.tsx بگذارید. پکیج‌های npm لازم و پیش‌نیازها در بخش «نصب» همان صفحه آمده‌اند. همه‌ی قطعه‌ها به lucide-react نیاز دارند.
$npm i lucide-react
کامپوننت‌هااز دکمه و ورودی شروع کنید

کار با هوش مصنوعی

هر صفحه تب «پرامپت» دارد: توضیح همان قطعه به انگلیسی، با قوانین راست‌چین، فونت، ارقام و توکن‌ها. آن را در Cursor، Claude Code یا Windsurf بچسبانید تا مدل همان قطعه را با سبک پروژه بسازد.
اگر خروجی چپ‌چین شد یا ارقام لاتین ماند، همان پرامپت را یک‌بار دیگر بفرستید و بگویید re-check the Persian RTL rules. قوانین داخل همان پرامپت است.
نسخه‌ی ماشین‌خوان هر مورد در /r/<بخش>/<slug>.json است؛ CLI همان را می‌خواند.

سرور MCP

ابزارهای هوش مصنوعی به انگلیسی فکر می‌کنند. این پنج ابزار قوانین فارسی و کد رجیستری را به Cursor، Claude Code و Windsurf می‌دهند تا به‌جای Inter و چیدمان چپ‌چین، قطعه‌ی وایب‌فارسی بسازند.

mcp.json

1{2  "mcpServers": {3    "vibefarsi": {4      "command": "npx",5      "args": ["-y", "@vibefarsi/mcp"]6    }7  }8}

get_design_rules قوانین راست‌چین، فونت، ارقام، فرم و توکن. این را قبل از ساخت هر صفحه صدا بزنید.
search_registry جست‌وجو در کامپوننت، بلاک، انیمیشن، پس‌زمینه، قالب و تم؛ فارسی یا انگلیسی.
get_component کد، پرامپت و مسیر نصب یک یا چند قطعه، به‌همراه وابستگی‌هایی مثل jalali.
get_theme توکن‌های CSS تم (پیش‌فرض: گرافیت). مدل نباید رنگ از خودش بگذارد.
scaffold_page از توضیح صفحه (پرداخت، ورود پیامکی، نوبت شمسی) یک ترکیب آماده می‌سازد.

تا وقتی پکیج روی npm منتشر نشده، در همین مخزن npm run mcp را به ادیتور بدهید. فهرست ماشین‌خوان: /r/<بخش>/<slug>.json.