پرتوپرتو

توکن‌های طراحی

مرجع کامل CSS variables سیستم طراحی پرتو — رنگ‌ها، فضابندی، سایه، و توکن‌های دامنه

اصل

توکن‌های طراحی متغیرهای CSS هستند که تمام مقادیر بصری سیستم (رنگ، فاصله، سایه، اندازه) را در یک مکان مرکزی تعریف می‌کنند. هر کامپوننت از این توکن‌ها استفاده می‌کند — نه مقادیر hardcoded.

مزایا

  • یکپارچگی: تغییر یک توکن در تمام کامپوننت‌ها اعمال می‌شود
  • تم‌بندی: تم روشن و تاریک فقط مقادیر توکن‌ها را تغییر می‌دهند، نه کد کامپوننت‌ها
  • دامنه‌محور: توکن‌های اختصاصی برای نرخ تعامل، احساسات، و پلتفرم اجتماعی

نمونه بصری

پرکاربردترین توکن‌ها با توضیح نقششان. برای فهرست کاملِ تولیدشده، بخش «مرجع کامل» پایین‌تر را ببینید.

روی هر توکن کلیک کنید تا نام متغیر CSS کپی شود. رنگ‌ها به صورت زنده از تم فعلی خوانده می‌شوند.

پس‌زمینه (Background)

متن (Foreground)

حاشیه (Border)

برند (Brand)

هشدار و خطا

نمودار (Chart)

بلاک کد (Code Block)

مرجع کامل (تولیدشده)

این فهرست از شیت می‌آید، نه از دست

globals.css امروز 489 متغیر CSS اعلام می‌کند. این بخش همه‌ی توکن‌های معنایی را با مقدار زنده‌شان در هر دو تم نشان می‌دهد و از globals.css تولید می‌شود، پس عقب نمی‌ماند. گیت check-design-tokens هم اجبار می‌کند هر توکن معنایی به یک خانوادهٔ نام‌دار برسد — افزودن توکن به شیت بدون گرفتن تصمیم مستندسازی، ممکن نیست.

این فهرست از globals.css تولید می‌شود، پس هرگز از شیت عقب نمی‌ماند. مقدار دوم، مقدار تم پایه (تیره) است و «روشن» فقط جایی می‌آید که تم روشن آن را بازنویسی کند. توکنی که رنگ نیست (مدت، z-index، اندازه) به‌جای swatch یک × می‌گیرد.

احساس (سه‌کلاسه)8

مثبت، منفی، خنثی و ترکیبی. برای بَج خلاصه، کارت فشرده و نمای فهرستی. مقیاس نه‌عاطفه‌ای جداست.

عواطف (نه‌گانه)18

خشم، ترس، غم، شادی، انزجار، شگفتی، اعتماد، انتظار و خنثی. برای تحلیل عمیق و تفکیک عاطفه.

موضع مخاطب10

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

سطح تعامل19

شش سطح از «عالی» تا «ضعیف»، هر کدام با حالت hover و رنگ متن.

شدت12

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

وضعیت8

بحرانی (با pulse انیمیشن)، هشدار و عادی.

امتیاز10

طیف امتیاز از «بحرانی» تا «عالی»، هر کدام با یک نسخهٔ پس‌زمینه (`-bg`).

نوع کنش21

کنش‌های تعاملی روی پست (لایک، کامنت، اشتراک‌گذاری، دایرکت…) با حالت روشن (`-on`) و رنگ متن.

پلتفرم14

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

پالت نمودار8

دنبالهٔ رنگ سری‌های نمودار. نمودارها این‌ها را در زمان اجرا با `useRootStyles()` می‌خوانند، نه در زمان build.

برند11

سبز پرتو در پله‌های ۲۰۰ تا ۶۰۰ به‌همراه حالت‌های نام‌دار و لایه‌های آلفا.

رنگ‌های بازخورد38

چهار خانوادهٔ معنایی خطا، هشدار، اطلاع و موفقیت — هر کدام با پله‌های عددی و لایه‌های آلفا.

پس‌زمینه و سطوح62

لایه‌های سطح از canvas تا dialog. تم پایه تیره است؛ مقدار روشن فقط جایی هست که بلوک light بازنویسی کند.

متن7

رنگ متن در چهار درجهٔ خوانایی، به‌همراه رنگ متن روی سطح رنگی (`contrast`).

حاشیه26

رنگ و ضخامت حاشیه‌ها به‌تفکیک نقش (کنترل، دکمه، overlay) و شدت.

گوشه1

مقیاس شعاع گوشه. توجه: `rounded-sm` تِیلویند با `rounded-token-sm` این سیستم یکی نیست.

عمق و سایه7

پنج پلهٔ ارتفاع از سطح، به‌همراه سایه‌های اختصاصی tooltip.

حرکت9

سه مدت و سه easing. زیر `prefers-reduced-motion: reduce` هر سه مدت صفر می‌شوند، پس انیمیشن سفارشی هم باید از همین توکن‌ها بخواند.

لایه‌بندی6

مقیاس z-index. تصادم `dropdown` و `popover` روی یک مقدار عامدانه است.

حالت تعامل2

رنگ حلقهٔ فوکوس و شفافیت حالت غیرفعال — دو مقداری که هر کامپوننت تعاملی باید از آن‌ها بخواند.

تایپوگرافی20

مقیاس اندازهٔ متن با ارتفاع خط جفت‌شده، وزن‌ها و دو خانوادهٔ فونت.

فاصله9

مقیاس فاصله و padding، به‌همراه padding نام‌دار کارت.

اندازه و چگالی15

مقیاس اندازهٔ کامپوننت و آیکون. پیش‌فرض پروژه `sm` است (۳۴ پیکسل).

ابعاد پوسته5

عرض‌های ثابت پوستهٔ برنامه: نوار ناوبری در سه حالت، ستون کنارهٔ دوم، و بیشینهٔ عرض محتوا.

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

سیاه و سفید مطلق. رنگ خام را در کد محصول مستقیم به کار نبرید؛ از توکن معنایی استفاده کنید.

داخلی — به کار نبرید3

توکن‌هایی که یا از یک ابزار بیرونی به شیت نشت کرده‌اند (`variables-colors-*`) یا کمکی داخلی‌اند (`helpers-*`). به این‌ها در کد محصول تکیه نکنید؛ نامشان بی‌اطلاع قبلی عوض می‌شود.

مجموع: 351 توکن معنایی در 26 خانواده. علاوه بر این 96 پلهٔ پالت خام و 42 نام مستعار Tailwind وجود دارد که پایین‌تر می‌آیند.

نگاشت کلاس Tailwind به توکن

بلوک @theme inline در globals.css نام مستعارهای Tailwind را می‌سازد. این جدول از همان بلوک مشتق می‌شود، پس کلاسی که اینجا می‌بینید قطعاً وجود دارد و قطعاً به همان توکن اشاره می‌کند:

کلاس Tailwindتوکن
bg-200--background-200
border-alternative · divide-alternative--border-alternative
bg-alternative · text-alternative · border-alternative · ring-alternative · fill-alternative · stroke-alternative--background-alternative-default
bg-alternative-200 · text-alternative-200 · border-alternative-200 · ring-alternative-200 · fill-alternative-200 · stroke-alternative-200--background-alternative-200
border-border-destructive · divide-border-destructive--border-destructive
border-border-warning · divide-border-warning--border-warning
bg-button--background-button-default
border-button · divide-button--border-button-default
border-button-hover · divide-button-hover--border-button-hover
bg-canvas · text-canvas · border-canvas · ring-canvas · fill-canvas · stroke-canvas--background-canvas
p-card · px-card · py-card · m-card · gap-card--card-padding-x
p-content · px-content · py-content · m-content · gap-content21px
text-contrast--foreground-contrast
border-control · divide-control--border-control
bg-control · text-control · border-control · ring-control · fill-control · stroke-control--background-control
bg-dash-canvas--background-canvas
bg-dash-sidebar--background-sidebar
border-default · divide-default--border-default
bg-dialog · text-dialog · border-dialog · ring-dialog · fill-dialog · stroke-dialog--background-dialog-default
text-light--foreground-light
text-lighter--foreground-lighter
bg-media-chip · text-media-chip · border-media-chip · ring-media-chip · fill-media-chip · stroke-media-chip--media-chip
border-muted · divide-muted--border-muted
bg-muted · text-muted · border-muted · ring-muted · fill-muted · stroke-muted--background-muted
text-muted--foreground-muted
bg-on-media · text-on-media · border-on-media · ring-on-media · fill-on-media · stroke-on-media--on-media
bg-on-media-chip · text-on-media-chip · border-on-media-chip · ring-on-media-chip · fill-on-media-chip · stroke-on-media-chip--on-media-chip
border-overlay · divide-overlay--border-overlay
bg-overlay · text-overlay · border-overlay · ring-overlay · fill-overlay · stroke-overlay--background-overlay-default
bg-overlay-hover · text-overlay-hover · border-overlay-hover · ring-overlay-hover · fill-overlay-hover · stroke-overlay-hover--background-overlay-hover
bg-overlay-scrim · text-overlay-scrim · border-overlay-scrim · ring-overlay-scrim · fill-overlay-scrim · stroke-overlay-scrim--overlay-scrim
border-secondary · divide-secondary--border-secondary
bg-selection · text-selection · border-selection · ring-selection · fill-selection · stroke-selection--background-selection
bg-sidebar · text-sidebar · border-sidebar · ring-sidebar · fill-sidebar · stroke-sidebar--background-sidebar
border-strong · divide-strong--border-strong
border-stronger · divide-stronger--border-stronger
bg-studio · text-studio · border-studio · ring-studio · fill-studio · stroke-studio--background-200
bg-surface-100 · text-surface-100 · border-surface-100 · ring-surface-100 · fill-surface-100 · stroke-surface-100--background-surface-100
bg-surface-200 · text-surface-200 · border-surface-200 · ring-surface-200 · fill-surface-200 · stroke-surface-200--background-surface-200
bg-surface-300 · text-surface-300 · border-surface-300 · ring-surface-300 · fill-surface-300 · stroke-surface-300--background-surface-300
bg-surface-400 · text-surface-400 · border-surface-400 · ring-surface-400 · fill-surface-400 · stroke-surface-400--background-surface-400
bg-surface-75 · text-surface-75 · border-surface-75 · ring-surface-75 · fill-surface-75 · stroke-surface-75--background-surface-75

نحوه استفاده

در Tailwind (توصیه‌شده)

بیشتر توکن‌ها به کلاس‌های Tailwind نگاشت شده‌اند:

// پس‌زمینه
<div className="bg-surface-100">...</div>

// متن
<p className="text-foreground">...</p>
<p className="text-light">...</p>

// حاشیه
<div className="border border-default">...</div>

// برند
<button className="bg-brand text-contrast">...</button>

مستقیم با CSS Variables

توکن‌ها (v2+) رنگ کامل هستند؛ مقدار را مستقیم بنویسید و هرگز داخل hsl() نپیچید. وقتی به مقدار خام نیاز دارید (مثلاً canvas، SVG، یا کتابخانه‌های third-party):

// در className — var() خام
<div className="bg-[var(--background-surface-100)]">...</div>

// با opacity — از /alpha استفاده کنید (چون توکن رنگ واقعی است)
<div className="bg-brand/10">...</div>

// در inline style
<div style={{ color: 'var(--foreground-default)' }}>...</div>

در JavaScript (برای نمودارها)

import { useChartTheme } from '@partodata/ui'

function MyChart() {
  const { chartColors, getColor } = useChartTheme()

  // رنگ‌های نمودار آماده
  const color1 = chartColors[0]

  // خواندن هر CSS variable
  const brandColor = getColor('--brand-default', 'hsl(153.1 60.2% 52.7%)')
}

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

✅className="bg-surface-100 text-foreground border-default"
❌className="bg-gray-900 text-white border-gray-700"
✅className="bg-brand/10"
❌style={{ backgroundColor: "#22c55e" }}

موارد استفاده رایج

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

<div className="bg-surface-100 border border-default rounded-lg p-6">
  <h2 className="text-foreground font-semibold">عنوان</h2>
  <p className="text-light mt-1">توضیحات</p>

  <div className="bg-surface-200 border border-muted rounded-md p-4 mt-4">
    <span className="text-lighter">محتوای تو در تو</span>
  </div>
</div>

نمایشگر احساسات

<div className="flex gap-2">
  <Badge style={{ backgroundColor: 'var(--sentiment-positive)' }}>مثبت</Badge>
  <Badge style={{ backgroundColor: 'var(--sentiment-negative)' }}>منفی</Badge>
  <Badge style={{ backgroundColor: 'var(--sentiment-neutral)' }}>خنثی</Badge>
</div>

چه نکنیم

  • رنگ‌های مستقیم Tailwind (bg-gray-900, text-white) — از توکن‌ها استفاده کنید
  • مقادیر hex/rgb hardcoded (#22c55e, rgb(34, 197, 94)) — توکن‌ها در تم تاریک شکسته می‌شوند
  • ساخت توکن جدید بدون هماهنگی — توکن‌های موجود ۹۹٪ نیازها را پوشش می‌دهند

صفحات مرتبط

ویرایش در GitHub

قالب‌بندی عدد و تاریخ

تقویم شمسی، جداکنندهٔ عدد و مقدار مختصر — کدام تابع برای کدام کار، و کدام تله‌ها واقعی‌اند

کلاس‌های Tailwind

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

در این صفحه

اصل
مزایا
نمونه بصری
مرجع کامل (تولیدشده)
نگاشت کلاس Tailwind به توکن
نحوه استفاده
در Tailwind (توصیه‌شده)
مستقیم با CSS Variables
در JavaScript (برای نمودارها)
قوانین اجباری
موارد استفاده رایج
کارت با سطوح مختلف
نمایشگر احساسات
چه نکنیم
صفحات مرتبط