رنگ‌ها

سیستم رنگ‌بندی سمانتیک پرتو — رنگ‌های متن، پس‌زمینه، حاشیه، و توکن‌های دامنه

سیستم رنگ‌بندی پرتو مجموعه‌ای از کلاس‌های کاربردی ارائه می‌دهد که استفاده از رنگ‌ها را ساده، یکپارچه، و قابل دسترس می‌کند. تمام رنگ‌ها سمانتیک هستند — یعنی هر کلاس معنا دارد نه فقط ظاهر.

تغییر تم

برای مشاهده رنگ‌ها در تم‌های مختلف (روشن و تاریک)، از سوئیچ زیر استفاده کنید:

اصول پایه

هدف سیستم رنگ‌بندی

  1. یکپارچگی: تمام کامپوننت‌ها از یک منبع رنگی استفاده می‌کنند
  2. دسترسی‌پذیری: تمام ترکیب‌های رنگی استانداردهای WCAG را رعایت می‌کنند
  3. قابلیت تم‌بندی: پشتیبانی کامل از تم روشن و تاریک
  4. سمانتیک: هر رنگ معنای خاصی دارد و برای موارد خاص استفاده می‌شود

قوانین اجباری

قوانین زیر چکیدهٔ لازم‌الاجرای این صفحه هستند؛ جزئیات و استدلال کامل هر قانون در بخش‌های بعدی همین صفحه آمده است.

فقط کلاس سمانتیک — هرگز رنگ خام Tailwind

// ✅ درست — کلاس سمانتیک، در هر دو تم رنگ درست می‌گیرد
<span className="text-destructive">ارسال گزارش ناموفق بود</span>

// ❌ غلط — رنگ خام Tailwind، خارج از سیستم توکن
<span className="text-red-500">ارسال گزارش ناموفق بود</span>
ارسال گزارش ناموفق بود
درست — text-destructive در هر دو تم رنگ درست و کنتراست کافی دارد
ارسال گزارش ناموفق بود
نادرست — رنگ خام به تم وصل نیست و با تغییر تم عوض نمی‌شود

رنگ‌های خام Tailwind به CSS Variables متصل نیستند؛ با تغییر تم به‌روز نمی‌شوند و یکپارچگی سیستم را می‌شکنند.

روی bg-brand، bg-warning و bg-destructive همیشه text-on-*

// ✅ درست — توکن «متن همراه»، کنتراست در هر دو تم تضمین‌شده
<div className="bg-brand text-on-brand">رونمایی محصول جدید</div>

// ❌ غلط — متن سفید روی سبز روشن (ratio ~2.7:1) WCAG AA را رد می‌کند
<div className="bg-brand text-white">رونمایی محصول جدید</div>
رونمایی محصول جدید
درست — text-on-brand کنتراست تضمین‌شده دارد
رونمایی محصول جدید
نادرست — سفید روی سبز روشن (حدود 2.7:1) خوانا نیست

این سه رنگ پایه روشن هستند؛ text-on-X تنها ترکیب تضمین‌شده است و ESLint rule parto/no-low-contrast-text هر text-white روی پس‌زمینهٔ روشن را در زمان build خطا می‌دهد.

سطح مخصوص عناصر شناور — bg-overlay برای منو، bg-dialog برای دیالوگ

// ✅ درست — منوی شناور روی سطح توپُر overlay، دیالوگ روی توکن اختصاصی خودش
<div className="bg-overlay border border-overlay">منوی کشویی</div>
<Dialog className="bg-dialog">تایید عملیات</Dialog>

// ❌ غلط — surface-200 پوشش نیمه‌شفاف است و محتوای پشت منو از آن رد می‌شود
<div className="bg-surface-200">منوی کشویی</div>
<Dialog className="bg">تایید عملیات</Dialog>

گزارش هفتگی کمپین تخفیف فصلی: 12 هزار منشن، نرخ تعامل بالاتر از هفتهٔ پیش و بازخورد مثبت دربارهٔ بسته‌بندی.

ویرایش
اشتراک‌گذاری
حذف
درست — bg-overlay سطح توپُر شناور است

گزارش هفتگی کمپین تخفیف فصلی: 12 هزار منشن، نرخ تعامل بالاتر از هفتهٔ پیش و بازخورد مثبت دربارهٔ بسته‌بندی.

ویرایش
اشتراک‌گذاری
حذف
نادرست — surface-200 نیمه‌شفاف است و متن پشت منو پیداست

bg-surface-200 یک پوشش تطبیقی نیمه‌شفاف است که با هر چیزی که پشتش باشد ترکیب می‌شود؛ عناصر شناور به سطح توپُر اختصاصی خود نیاز دارند.

سلسله‌مراتب متن با سطوح foreground — رنگ تاکیدی فقط در موارد ضروری

// ✅ درست — سلسله‌مراتب با سطوح متن، بدون رنگ تاکیدی اضافه
<div>
  <h2 className="text-foreground">بازخورد بسته‌بندی</h2>
  <p className="text-light">خلاصهٔ نظرات مشتریان دربارهٔ کمپین تخفیف فصلی</p>
  <small className="text-lighter">به‌روزرسانی: امروز</small>
</div>

// ❌ غلط — رنگ تاکیدی به‌جای سلسله‌مراتب؛ معنای «خطا» و «برند» از بین می‌رود
<div>
  <h2 className="text-destructive">بازخورد بسته‌بندی</h2>
  <p className="text-brand">خلاصهٔ نظرات مشتریان دربارهٔ کمپین تخفیف فصلی</p>
</div>
بازخورد بسته‌بندیخلاصهٔ نظرات مشتریان دربارهٔ کمپین تخفیف فصلیبه‌روزرسانی: امروز
درست — سلسله‌مراتب با سطوح متن
بازخورد بسته‌بندیخلاصهٔ نظرات مشتریان دربارهٔ کمپین تخفیف فصلی
نادرست — رنگ خطا و برند برای تزئین؛ معنایشان از دست می‌رود

رنگ‌های تاکیدی معنای سمانتیک دارند (خطا، هشدار، برند)؛ استفادهٔ تزئینی از آن‌ها هم بار بصری اضافه می‌سازد و هم اثر معنای واقعی‌شان را در جای درست کم می‌کند.

یک کد برای هر دو تم — بدون فورک دستی رنگ

// ✅ درست — توکن‌ها theme-aware هستند؛ همین کد در هر دو تم درست کار می‌کند
<div className="bg-surface-100 text-foreground border border-default">محتوا</div>

// ❌ غلط — فورک دستی تم با رنگ ثابت، خارج از سیستم توکن
<div className="bg-white dark:bg-zinc-900 text-black dark:text-white">محتوا</div>
محتوا
درست — توکن‌ها خودشان با تم عوض می‌شوند
محتوا
نادرست — رنگ ثابت؛ در تم تیره یک جعبهٔ سفید بیرون می‌زند

تم‌ها از طریق CSS Variables به صورت خودکار تغییر می‌کنند؛ فورک دستی dark: با رنگ ثابت دو منبع حقیقت می‌سازد که دیر یا زود از هم فاصله می‌گیرند.

بخش اول: استفاده از رنگ

این بخش نحوه استفاده صحیح از کلاس‌های رنگی در کامپوننت‌ها و صفحات را توضیح می‌دهد.

رنگ‌های متن (Text)

از رنگ‌های متن برای ایجاد سلسله‌مراتب بصری در محتوا استفاده کنید. از رنگ‌های تاکیدی (مثل text-destructive، text-warning) به ندرت و فقط در مواقع ضروری استفاده کنید تا از بار بصری بیش از حد جلوگیری شود.

نمونه متنtext
نمونه متنtext-light
نمونه متنtext-lighter
نمونه متنtext-muted
نمونه متنtext-contrast
نمونه متنtext-destructive
نمونه متنtext-warning
نمونه متنtext-brand-600

سطوح مختلف متن

کلاسکاربردمثال
text-foreground یا textمتن پیش‌فرض برای عناوین و محتوای اصلی<h1 className="text-foreground">عنوان</h1>
text-foreground-light یا text-lightمتن بدنه و توضیحات<p className="text-light">توضیحات</p>
text-foreground-lighter یا text-lighterمتن کم‌رنگ و راهنما<span className="text-lighter">راهنما</span>
text-foreground-muted یا text-mutedمتن غیرفعال<span className="text-muted">غیرفعال</span>
text-destructiveمتن خطا<span className="text-destructive">خطا</span>
text-warningمتن هشدار<span className="text-warning">هشدار</span>
text-brand-600متن و پیوند به رنگ برند<span className="text-brand-600">برند</span>

نمونه کد

// عناوین و متن‌های اصلی
<h1 className="text">عنوان اصلی</h1>
<h1 className="text-foreground">عنوان اصلی (معادل)</h1>

// متن‌های بدنه و توضیحات
<p className="text-light">این یک متن توضیحی است</p>
<p className="text-foreground-light">این یک متن توضیحی است (معادل)</p>

// متن‌های ثانویه
<span className="text-lighter">اطلاعات ثانویه</span>

// متن‌های کم‌رنگ
<small className="text-muted">متادیتا یا تاریخ</small>

// متن برجسته (در پس‌زمینه تیره)
<span className="text-contrast">متن با کنتراست بالا</span>

رنگ‌های سمانتیک متن

// برند — متن به رنگ برند پلهٔ 600 است؛ خود سبز برند رنگ متن نیست
<span className="text-brand-600">پیام برند</span>

// هشدار
<span className="text-warning">این عملیات قابل بازگشت نیست</span>

// خطا و حذف
<span className="text-destructive">خطا: عملیات ناموفق بود</span>

رنگ‌های پس‌زمینه (Background)

bg-200
bg
bg-alternative-200
bg-alternative
bg-selection
bg-control
bg-surface-75
bg-surface-100
bg-surface-200
bg-surface-300
bg-surface-400
bg-overlay
bg-overlay-hover
bg-muted
bg-button
bg-dialog
bg-dash-sidebar
bg-dash-canvas

پس‌زمینه اپلیکیشن

ما از پس‌زمینه به 2 روش مختلف استفاده می‌کنیم:

/**
 * پس‌زمینه سایت مستندات
 * این پس‌زمینه تیره‌تر است و عمق بیشتری ایجاد می‌کند
 */
<body className="bg">{children}</body>

/**
 * پس‌زمینه استودیو (داشبورد)
 */
<body className="bg-studio">{children}</body>

پس‌زمینه‌ها و سطوح (Surfaces)

کدام بلوک روی کدام سطح؟ و چرا توکن عوض نمی‌شود

هر بلوک محصورِ صفحه (جدول، نمودار، شاخص، فرم، نخ، پنل فیلتر) یک ظرف L1 است: bg-surface-100 + border + rounded-lg

  • shadow-sm، هر چهار با هم. bg-background، bg-transparent و bg-sidebar رنگ خود بوم‌اند و پوستهٔ بلوک نیستند. اختلاف پرکنندهٔ L1 با بوم در پرتو با Studio یکی است (تیره) یا قوی‌تر (روشن)؛ جدایی از ترکیب می‌آید، نه از روشن‌تر کردن توکن. نردبان لایه‌ها با اعداد زنده، جدول تصمیم و جفت‌های درست/نادرست در گرامر بصری.

سطوح در سایت مستندات و وب‌سایت

توکن‌های سطح دو دستهٔ متفاوت هستند و مثل یک نردبان تخت و یکنواخت که هر پله روشن‌تر از قبلی باشد رفتار نمی‌کنند:

  • سطوح تودرتوی توپُر (solid): bg-surface-75، bg-surface-100، bg-surface-300، به‌همراه bg-overlay و bg-dialog. این‌ها رنگ ثابت و کامل دارند. در تم فعلی، surface-75 و surface-100 دقیقاً یک رنگ‌اند (هر دو hsl(150deg 4% 9.8%))، پس اختلاف بصری بین این دو انتظار نداشته باشید.
  • پوشش‌های نیمه‌شفاف تطبیقی (adaptive): bg-surface-200، bg-surface-400، bg-muted، bg-control، bg-selection، bg-overlay-hover و کل مقیاس حاشیه‌ها. این‌ها به‌جای رنگ ثابت، یک لایهٔ نیمه‌شفاف از رنگ foreground هستند (color-mix(in oklch, var(--foreground) N%, transparent)) که روی هر پس‌زمینه‌ای که پشت‌شان باشد ترکیب می‌شوند و همیشه یک پله بالاتر از همان پس‌زمینه می‌نشینند — روی صفحه، روی کارت، یا روی overlay به‌یک اندازه دیده می‌شوند.
app backgroundbg
content panelbg-surface-75border-muted
// پس‌زمینه اصلی صفحه
<body className="bg">
  // سطح توپُر - کارت‌ها و پنل‌های اصلی
  <div className="bg-surface-100">
    <h2>محتوای اصلی</h2>
  </div>
  // پوشش تطبیقی - یک پله بالاتر از هر پس‌زمینه‌ای که پشتش باشد
  <div className="bg-surface-200">
    <p>ناحیهٔ برجسته روی کارت</p>
  </div>
  // سطح توپُر عمیق‌تر
  <div className="bg-surface-300">
    <span>محتوای عمیق</span>
  </div>
</body>

// دراپ‌داون و پاپ‌اوور از سطح مخصوص overlay استفاده می‌کنند (نه surface-200)
<div className="bg-overlay border border-overlay">منوی کشویی</div>

// دیالوگ توکن اختصاصی خودش را دارد
<Dialog className="bg-dialog">محتوای دیالوگ</Dialog>

سطوح در داشبورد (Studio)

برای داشبورد ما می‌توانیم از سطوح توپُر bg-surface-100 و bg-surface-300 (کارت‌ها و پنل‌ها) و پوشش تطبیقی bg-surface-200 (ناحیهٔ برجسته روی کارت) استفاده کنیم. برای منوهای شناور از bg-overlay استفاده کنید، نه از surface-200:

app backgroundbg-studio
content panelbg-surface-100border
content panelbg-surface-200border
content panelbg-surface-300border
// پس‌زمینه اصلی داشبورد
<body className="bg-studio">
  // کارت‌ها و پنل‌ها (سطح توپُر)
  <div className="bg-surface-100">
    <h2>پنل داشبورد</h2>
  </div>
  // ناحیهٔ برجسته روی کارت (پوشش تطبیقی)
  <div className="bg-surface-200">
    <p>بخش تودرتو</p>
  </div>
</body>

// منوی کشویی روی سطح overlay می‌نشیند
<div className="bg-overlay border border-overlay">
  <ul>منوی کشویی</ul>
</div>

فضای خالی و گرید داده‌ها

گریدهای داده از یک پس‌زمینه جایگزین برای فضای خالی استفاده می‌کنند تا عمق بیشتری به طرح بدهند.

grid headerbg-surface-200border
content rowbg-200border-secondary
content rowbg-200border-secondary
content rowbg-200border-secondary
content rowbg-200border-secondary
empty frame spacebg-alternativeborder-stronger

جدول استفاده از پس‌زمینه

کلاسکاربردمثال
bg یا bg-200پس‌زمینه اصلی اپلیکیشن (توپُر)<body className="bg">
bg-surface-75سطح توپُر — هم‌رنگ surface-100<div className="bg-surface-75">
bg-surface-100سطح توپُر پنل‌ها و کارت‌ها<Card className="bg-surface-100">
bg-surface-200پوشش تطبیقی (یک پله روی پس‌زمینه)<div className="bg-surface-200">
bg-surface-300سطح توپُر عمیق‌تر<div className="bg-surface-300">
bg-surface-400پوشش تطبیقی بالاتر<div className="bg-surface-400">
bg-overlayسطح دراپ‌داون، پاپ‌اوور و منو (توپُر)<Popover className="bg-overlay">
bg-dialogسطح مودال و دیالوگ (توکن اختصاصی)<Dialog className="bg-dialog">
bg-alternativeپس‌زمینه جایگزین (معکوس)<div className="bg-alternative">
bg-selectionپس‌زمینه انتخاب شده (پوشش تطبیقی)<div className="bg-selection">
bg-controlپس‌زمینه کنترل‌ها (پوشش تطبیقی)<input className="bg-control">
bg-mutedپس‌زمینه خاموش (پوشش تطبیقی)<div className="bg-muted">
bg-buttonپس‌زمینه دکمه<button className="bg-button">

Overlay ها

ما از رنگ پس‌زمینه bg-overlay (توکن توپُر overlay-default) برای سطح دراپ‌داون‌ها، پاپ‌اوورها و منوها استفاده می‌کنیم. این را نباید با Dialog اشتباه گرفت؛ دیالوگ‌ها توکن اختصاصی خودشان bg-dialog را دارند — نه رنگ پس‌زمینهٔ سایت و نه سطح overlay.

// Overlay - سطح dropdown و popover
<div className="bg-overlay border border-overlay">
  محتوای Dropdown
</div>

// Dialog - توکن اختصاصی dialog (متمایز از پس‌زمینهٔ سایت)
<Dialog className="bg-dialog">
  محتوای Dialog
</Dialog>

پس‌زمینه‌های ویژه

// پس‌زمینه انتخاب شده (selection)
<div className="bg-selection">آیتم انتخاب شده</div>

// پس‌زمینه کنترل‌ها (input, select, etc.)
<input className="bg-control" />

// پس‌زمینه overlay و modal
<div className="bg-overlay">محتوای overlay</div>
<div className="bg-overlay-hover">hover state</div>

// پس‌زمینه دیالوگ
<div className="bg-dialog">محتوای دیالوگ</div>

// سایدبار و canvas داشبورد (قاب برنامه را ProductFrame می‌سازد؛ این‌جا برای سطوح درون یک صفحه)
<aside className="bg-dash-sidebar">فهرست کناری</aside>
<div className="bg-dash-canvas">ناحیهٔ محتوا</div>

رنگ‌های حاشیه (Border)

border
border-muted
border-secondary
border-overlay
border-control
border-alternative
border-strong
border-stronger
border-button
border-button-hover
کلاسکاربردمثال
border یا border-defaultحاشیه پیش‌فرض<div className="border">
border-mutedحاشیه خاموش<div className="border border-muted">
border-secondaryحاشیه ثانویه<div className="border border-secondary">
border-overlayحاشیه overlay<Popover className="border border-overlay">
border-controlحاشیه کنترل‌ها<input className="border border-control">
border-alternativeحاشیه جایگزین<div className="border border-alternative">
border-strongحاشیه قوی (hover، focus)<div className="border border-strong">
border-strongerحاشیه قوی‌تر (برجسته)<div className="border border-stronger">
border-buttonحاشیه دکمه<button className="border border-button">
border-button-hoverحاشیه دکمه در hover<button className="border border-button-hover">

نمونه کد

// حاشیه پیش‌فرض - برای بیشتر موارد
<div className="border border-default">کارت با حاشیه معمولی</div>

// حاشیه قوی‌تر - برای تاکید بیشتر
<div className="border border-strong">کارت با حاشیه برجسته</div>

// حاشیه خیلی قوی - برای جداسازی واضح
<div className="border border-stronger">کارت با حاشیه پررنگ</div>

// حاشیه overlay - برای مدال‌ها و پاپوورها
<div className="border border-overlay">overlay با حاشیه</div>

// حاشیه کنترل‌ها
<input className="border border-control" />

// حاشیه دکمه
<button className="border border-button">دکمه با حاشیه</button>
<button className="border border-button-hover">حالت hover</button>

رنگ‌های دیگر

این رنگ‌ها شامل brand، warning، destructive و code-block هستند.

bg-destructive-200
bg-destructive-300
bg-destructive-400
bg-destructive-500
bg-destructive-600
bg-destructive
bg-warning-200
bg-warning-300
bg-warning-400
bg-warning-500
bg-warning-600
bg-warning
bg-brand-200
bg-brand-300
bg-brand-400
bg-brand-500
bg-brand-600
bg-brand
bg-brand-link
bg-_secondary-200
bg-_secondary-400
bg-_secondary
bg-code_block-1
bg-code_block-2
bg-code_block-3
bg-code_block-4
bg-code_block-5

قانون متن روی رنگ (Text-on-Color)

سطح‌های وضعیت (4.0). Banner، RateLimitBanner، Callout و toastهای Sonner دیگر پس‌زمینهٔ پررنگ ندارند. هر چهار لحن یک دستور مشترک دارند: bg-{tone}-surface، حاشیهٔ border-{tone}-border، آیکن text-{tone}-icon و متن text-foreground (لحن‌ها: info، success، warning، danger). قانونِ bg-X با text-on-X فقط برای دکمه و چیپ پررنگ است.

سبز برند پرتو، نارنجی هشدار، و قرمز اصلی، رنگ‌های روشن هستند. متن سفید روی این پس‌زمینه‌ها در تم روشن، WCAG AA را رد می‌کند (کمتر از 4.5:1).

راه‌حل ریشه‌ای — توکن‌های --on-*:

برای هر یک از این سه خانوادهٔ رنگ، یک توکن «متن همراه» تعریف شده که در هر دو تم، contrast درست را تضمین می‌کند:

--on-brand        →  text-on-brand        (متن تیره، روی سبز روشن)
--on-warning      →  text-on-warning      (متن تیره، روی نارنجی روشن)
--on-destructive  →  text-on-destructive  (متن تیره، روی قرمز روشن)

به‌جای فکر کردن دربارهٔ ratio هر بار، فقط bg-X را با text-on-X بنویسید. سیستم بقیه را خودش هندل می‌کند.

<div className="bg-brand text-on-brand">پس‌زمینه برند</div>
<div className="bg-warning text-on-warning">هشدار</div>
<div className="bg-destructive text-on-destructive">خطا</div>

این الگو در هر دو تم light/dark بدون تغییر کار می‌کند، چون این سه رنگ پس‌زمینه در دو تم تقریباً یکسان هستند (هویت برند ثابت).

برای shadeهای دیگر (-400, -500, -600 و …) که در dark theme معنای lightness‌شان وارونه می‌شود، از text-foreground (که خودش theme-aware است) یا text-white فقط روی shadeهای تیره استفاده کنید:

پس‌زمینهمتن مجازنسبت کنتراستکاربرد نمونه
bg-brand (default)text-on-brand ⭐8.98:1 ✓ (هر دو تم)Banner، CTA اصلی، سطح سبز برند
bg-brand-400 (روشن) / bg-brand-500 (تیره)text-foreground (theme-aware)13.06:1 / 6.47:1 ✓Button primary
bg-brand-600text-white فقط در تم روشن5.24:1 ✓ (روشن) · 1.57:1 ✗ (تیره)CTA تیره در تم روشن؛ در تم تیره این پله روشن است و متن تیره می‌خواهد
bg-warning (default)text-on-warning ⭐5.88:1 / 6.72:1 ✓Banner هشدار
bg-warning-{300,400,500}text-foreground (theme-aware)5+:1 ✓toast هشدار
bg-destructive (default)text-on-destructive ⭐4.63:1 ✓ (هر دو تم)Banner خطا، Alert destructive
bg-destructive-600 dark:bg-destructive-500text-white5.27:1 / 9.75:1 ✓Badge عدد notification، نقاط alarm
bg-destructive-{200,300,400,500}text-foreground (theme-aware)8+:1 ✓Toast نرم

چرا متن تیره روی سبز برند؟ سبز پرتو از نظر روشنایی، یک رنگ متوسط-روشن است و متن سفید روی آن کنتراست کافی ندارد. متن تیره روی سبز جفت رسمی برند پرتو است (رنگ در راهنمای برند) و برای محصول جدی گزارش‌محور مناسب‌تر است.

استثنای badge کوچک: برای badgeهای کوچک عدد notification که فضای متن کم است و انتظار visual «alarm» قوی‌تر داریم، الگوی bg-destructive-600 dark:bg-destructive-500 + text-white استفاده می‌شود (NotificationCenter از همین).

این قاعده توسط ESLint rule parto/no-low-contrast-text در زمان build تضمین می‌شود — هر text-white روی پس‌زمینهٔ روشن، در lint مرحلهٔ pre-commit خطا می‌دهد.

نحوه استفاده

// رنگ Brand — text-on-brand به طور خودکار رنگ درست را انتخاب می‌کند
<div className="bg-brand text-on-brand">پس‌زمینه برند</div>
<div className="bg-brand-200 text-foreground">برند 200 (تینت روشن)</div>
<div className="bg-brand-600 text-white dark:text-on-brand">برند 600 (متن سفید فقط در تم روشن)</div>

// رنگ Warning — هشدار، با متن on-warning
<div className="bg-warning text-on-warning">هشدار</div>
<div className="text-warning">متن هشدار</div>

// رنگ Destructive — متن on-destructive برای Banner/Alert
<div className="bg-destructive text-on-destructive">خطا</div>
<div className="text-destructive">متن خطا</div>

// Badge کوچک notification — استثنا، با shade تیره + متن سفید
<div className="bg-destructive-600 dark:bg-destructive-500 text-white px-2 rounded-full">5</div>

آنتی‌پترن — استفاده نکنید

// ❌ ratio ~2.7:1 — WCAG AA رد می‌شود
<div className="bg-brand text-white">نکنید</div>

// ❌ ratio ~1.8:1 — فاجعه — نارنجی روشن با سفید قابل خواندن نیست
<div className="bg-warning text-white">نکنید</div>

// ❌ ratio ~2.1:1 — destructive-500 در light theme صورتی روشن است
<div className="bg-destructive-500 text-white">نکنید</div>

// ❌ text-contrast در light theme = نزدیک سفید، روی سبز روشن fail می‌شود
<div className="bg-brand text-contrast">نکنید</div>

نمونه‌های کاربردی

کارت با سطوح مختلف

<div className="bg-surface-100 p-6 rounded-lg border border-default">
  <h2 className="text-foreground mb-2">عنوان کارت</h2>
  <p className="text-light mb-4">توضیحات کارت</p>

  <div className="bg-surface-200 p-4 rounded border border-muted">
    <span className="text-lighter">سطح دوم</span>
  </div>
</div>

فرم با validation

رنگ خطا و هشدار را خود کنترل‌ها می‌گذارند: FormRow با error حاشیه و پیام را قرمز می‌کند و aria-invalid را روی کنترل می‌گذارد. کلاس رنگ را دستی روی input خام نگذارید.

import { Input } from '@partodata/ui'
import { FormRow } from '@partodata/ui/templates'

<form>
  <FormRow label="نام کاربری">
    <Input kind="username" />
  </FormRow>
  <FormRow label="ایمیل" error="ایمیل نامعتبر است">
    <Input kind="email" />
  </FormRow>
  <FormRow label="رمز عبور" description="رمز عبور ضعیف است؛ دست‌کم 12 نویسه بنویسید">
    <Input kind="password" />
  </FormRow>
</form>

دکمه‌ها با variant های مختلف

// دکمه اصلی — متن تیره روی سبز روشن (bg-brand همیشه با text-on-brand)
<button className="bg-brand text-on-brand hover:bg-brand/90 px-4 py-2 rounded">
  ذخیره
</button>

// دکمه ثانویه
<button className="bg-surface-200 text-foreground hover:bg-surface-300 px-4 py-2 rounded">
  انصراف
</button>

// دکمه خطرناک — متن سفید روی قرمز تیره (هر دو تم safe)
<button className="bg-destructive-600 dark:bg-destructive-500 text-white hover:bg-destructive/90 px-4 py-2 rounded">
  حذف
</button>

// دکمه ghost
<button className="text-foreground hover:bg-surface-100 px-4 py-2 rounded">
  بیشتر
</button>

// دکمه outline
<button className="border border-default text-foreground hover:bg-surface-100 px-4 py-2 rounded">
  مشاهده
</button>

Modal و Overlay

// Overlay backdrop
<div className="fixed inset-0 bg-overlay/80">
  {/* Dialog */}
  <div className="bg-dialog rounded-lg p-6 border border-overlay">
    <h2 className="text-heading text-foreground mb-4">تایید عملیات</h2>
    <p className="text-light mb-6">آیا مطمئن هستید؟</p>

    <div className="flex gap-2 justify-end">
      <button className="bg-surface-100 border border-button hover:bg-surface-200 px-4 py-2 rounded">لغو</button>
      <button className="bg-brand text-on-brand hover:bg-brand/90 px-4 py-2 rounded">تایید</button>
    </div>
  </div>
</div>

نوتیفیکیشن و Alert

// اطلاعیهٔ موفقیت — رنگ موفقیت، نه رنگ برند
<div className="bg-success-200 border border-success-400 rounded-lg p-4">
  <h4 className="text-subheading text-foreground mb-1">تغییرات ذخیره شد</h4>
  <p className="text-light text-sm">گزارش هفتگی از شنبه برای 3 گیرنده فرستاده می‌شود.</p>
</div>

// هشدار
<div className="bg-warning/10 border border-warning rounded-lg p-4">
  <h4 className="text-subheading text-warning mb-1">هشدار</h4>
  <p className="text-light text-sm">این عملیات قابل بازگشت نیست</p>
</div>

// خطا
<div className="bg-destructive/10 border border-destructive rounded-lg p-4">
  <h4 className="text-subheading text-destructive mb-1">خطا</h4>
  <p className="text-light text-sm">عملیات با شکست مواجه شد</p>
</div>

بهترین روش‌ها

استفاده از کلاس‌های سمانتیک

همیشه از کلاس‌های سمانتیک استفاده کنید، نه رنگ‌های مستقیم:

// ✅ درست
<span className="text-destructive">خطا</span>

// ❌ غلط
<span className="text-red-500">خطا</span>

رعایت سلسله‌مراتب

از سطوح مختلف متن و پس‌زمینه برای ایجاد سلسله‌مراتب بصری:

// ✅ درست - سلسله‌مراتب واضح
<div>
  <h1 className="text-foreground">عنوان</h1>
  <p className="text-light">توضیحات</p>
  <small className="text-lighter">متادیتا</small>
</div>

استفاده محدود از رنگ‌های تاکیدی

از text-warning و text-destructive فقط برای موارد واقعاً مهم استفاده کنید.

کنتراست مناسب

همیشه مطمئن شوید رنگ متن و پس‌زمینه کنتراست کافی دارند (حداقل 4.5:1 برای متن عادی). راهنمای کامل کنتراست در دسترسی‌پذیری موجود است.

پشتیبانی از شفافیت (Opacity)

تمام رنگ‌ها با استفاده از شفافیت Tailwind تولید می‌شوند. این بدان معناست که می‌توانید از / برای تنظیم شفافیت استفاده کنید:

<div className="flex gap-3 items-center">
  <div className="w-12 h-12 rounded-full bg-surface-300"></div>
  <div className="w-12 h-12 rounded-full bg-surface-300/90"></div>
  <div className="w-12 h-12 rounded-full bg-surface-300/80"></div>
  <div className="w-12 h-12 rounded-full bg-surface-300/75"></div>
  <div className="w-12 h-12 rounded-full bg-surface-300/50"></div>
  <div className="w-12 h-12 rounded-full bg-surface-300/25"></div>
</div>

این برای ایجاد حالت‌های hover، disabled و overlay بسیار مفید است:

// حالت disabled
<button className="bg-brand/50 text-foreground/50" disabled>
  غیرفعال
</button>

// حالت hover
<button className="bg-brand hover:bg-brand/90">
  دکمه
</button>

// Overlay
<div className="fixed inset-0 bg-overlay/80">
  <Dialog />
</div>

ترکیب رنگ‌ها (Mixing Colors)

یکی از قدرت‌های سیستم رنگ ما این است که می‌توانید هر رنگی را در هر کلاس کاربردی استفاده کنید:

// استفاده از رنگ foreground برای پس‌زمینه
<div className="bg-foreground-light">
  <span className="text-background">متن معکوس</span>
</div>

// استفاده از رنگ surface برای حاشیه
<div className="border-2 border-surface-300">
  محتوا
</div>

// ترکیب‌های خلاقانه
<div className="bg-brand/10 border border-brand/30 text-brand-600">
  کارت با تم برند
</div>

بخش دوم: پالت‌های رنگی

برای مشاهده تمام رنگ‌های پایه و scale های رنگی موجود در سیستم، به صفحه پالت‌های رنگی مراجعه کنید.

بخش سوم: تم‌ها و تنظیمات پیشرفته

تم‌های مختلف

سیستم طراحی پرتو از 2 تم پشتیبانی می‌کند:

Light (روشن)

تم روشن استاندارد، مناسب برای استفاده روزانه و محیط‌های با نور کافی.

  • پس‌زمینه: روشن و تمیز
  • متن: تیره برای کنتراست بهتر
  • رنگ‌های برند: سبز برند در هر دو تم یکی است؛ پله‌های مقیاس در تم روشن روشن‌ترند

Dark (تاریک)

تم تاریک مدرن، ایده‌آل برای محیط‌های کم‌نور و استفاده شبانه.

  • پس‌زمینه: تیره با سطوح مختلف
  • متن: روشن برای خوانایی
  • رنگ‌های برند: سبز برند در هر دو تم یکی است؛ پله‌های مقیاس در تم تیره تیره‌ترند

نحوه استفاده

تمام رنگ‌ها به صورت خودکار در تم‌های مختلف تغییر می‌کنند و نیازی به تغییر کد نیست:

// این کد در هر 2 تم به درستی کار می‌کند
<div className="bg-surface-100 text-foreground border border-default">محتوا</div>

تم‌ها از طریق CSS Variables کنترل می‌شوند. توکن‌ها (v2+) رنگ کامل هستند (نه کانال خام) و تیره پیش‌فرضِ پایه (:root) است — روشن opt-in صریح است:

/* Dark Theme — پیش‌فرض پایه (:root) */
:root,
[data-theme='dark'],
.dark {
  --background-default: hsl(120deg 2.6% 7.6%);
  --foreground-default: hsl(150deg 5.9% 93.3%);
  /* ... */
}

/* Light Theme — انتخاب صریح */
[data-theme='light'],
.light {
  --background-default: hsl(0deg 0% 99.2%);
  --foreground-default: hsl(0deg 0% 1.2%);
  /* ... */
}

رنگ‌های Code Block

رنگ‌های مخصوص برای syntax highlighting در code block ها:

رنگکاربردمثال
--code-block-1Keywords و Operatorsfunction, const, =>
--code-block-2Strings و Text"Hello World"
--code-block-3Numbers و Values123, true, false
--code-block-4Functions و Methodsconsole.log()
--code-block-5Comments// توضیح

این رنگ‌ها نیز در هر دو تم به درستی کار می‌کنند و خوانایی کد را تضمین می‌کنند.

// نمونه استفاده - این رنگ‌ها به صورت خودکار اعمال می‌شوند
const greeting = 'سلام' // متغیر با رنگ code-block-2
function sayHello() {
  // تابع با رنگ code-block-4
  console.log(greeting) // استفاده از رنگ‌های مختلف
}

خلاصه و نکات نهایی

استفاده کنید:

  • کلاس‌های سمانتیک (text-foreground, bg-surface-100, etc.)
  • سطوح توپُر (surface-75/100/300، overlay، dialog) و پوشش‌های تطبیقی (surface-200/400، muted، control) برای ایجاد عمق
  • شفافیت برای حالت‌های مختلف (bg-brand/50)

استفاده نکنید:

  • رنگ‌های مستقیم Tailwind (text-gray-500)
  • بیش از حد رنگ تاکیدی (text-destructive همه جا)
  • ترکیب‌های با کنتراست کم

یادتان باشد:

  • تمام رنگ‌ها در سه تم کار می‌کنند
  • کنتراست حداقل 4.5:1 برای متن
  • از opacity برای ایجاد variations استفاده کنید

صفحات مرتبط

پایه‌ها

رنگ، تایپوگرافی، فضابندی، توکن‌ها و تم‌بندی — زبان بصری و قرارداد مصرف آن

پالت‌های رنگی

مرجع کامل پالت‌های رنگی پایه — scale های رنگی و نسبت کنتراست WCAG

در این صفحه

تغییر تم
اصول پایه
هدف سیستم رنگ‌بندی
قوانین اجباری
فقط کلاس سمانتیک — هرگز رنگ خام Tailwind
روی bg-brand، bg-warning و bg-destructive همیشه text-on-*
سطح مخصوص عناصر شناور — bg-overlay برای منو، bg-dialog برای دیالوگ
سلسله‌مراتب متن با سطوح foreground — رنگ تاکیدی فقط در موارد ضروری
یک کد برای هر دو تم — بدون فورک دستی رنگ
بخش اول: استفاده از رنگ
رنگ‌های متن (Text)
سطوح مختلف متن
نمونه کد
رنگ‌های سمانتیک متن
رنگ‌های پس‌زمینه (Background)
پس‌زمینه اپلیکیشن
پس‌زمینه‌ها و سطوح (Surfaces)
سطوح در سایت مستندات و وب‌سایت
سطوح در داشبورد (Studio)
فضای خالی و گرید داده‌ها
جدول استفاده از پس‌زمینه
Overlay ها
پس‌زمینه‌های ویژه
رنگ‌های حاشیه (Border)
نمونه کد
رنگ‌های دیگر
قانون متن روی رنگ (Text-on-Color)
نحوه استفاده
آنتی‌پترن — استفاده نکنید
نمونه‌های کاربردی
کارت با سطوح مختلف
فرم با validation
دکمه‌ها با variant های مختلف
Modal و Overlay
نوتیفیکیشن و Alert
بهترین روش‌ها
استفاده از کلاس‌های سمانتیک
رعایت سلسله‌مراتب
استفاده محدود از رنگ‌های تاکیدی
کنتراست مناسب
پشتیبانی از شفافیت (Opacity)
ترکیب رنگ‌ها (Mixing Colors)
بخش دوم: پالت‌های رنگی
بخش سوم: تم‌ها و تنظیمات پیشرفته
تم‌های مختلف
Light (روشن)
Dark (تاریک)
نحوه استفاده
رنگ‌های Code Block
خلاصه و نکات نهایی
صفحات مرتبط