رفتن به محتوای اصلی
  • معرفی
  • نصب
  • Tailwind
  • وب کامپوننت‌ها (بدون React)
  • دوزبانه، فارسی و انگلیسی
  • پلاگین‌های فیگما
  • استفاده با هوش مصنوعی
  • آیکون‌ها
  • راهنمای آیکون‌ها
  • سفارشی‌سازی و تم
  • حرکت و ریزتعامل‌ها
  • حالت‌های کامپوننت‌ها
  • فونت و تایپوگرافی
  • دسترس‌پذیری
  • نوشتن متن رابط
  • رنگ‌ها
  • برند کاشی
  • مقایسه با دیگران
  • نسخه‌ها
  • سیاست تغییرات
  • مهاجرت به ۲.۰
  • امنیت
  • حجم کامپوننت‌ها
  • فیلد فارسی
  • دیت‌پیکر شمسی
  • کد تأیید (OTP)
  • بازهٔ تاریخ شمسی
  • انتخاب ماه
  • شمارش معکوس
  • هیت‌مپ فعالیت
  • انتخاب استان
  • نقشهٔ ایران
  • فرم نشانی
  • انتخاب نوبت
  • ویرایش نگارشی
  • نمایش مبلغ
  • بازهٔ قیمت
  • کارت بانکی
  • رسید پرداخت
  • برگ تقویم
  • لوگوی بانک‌ها
  • ابزارهای فارسی
  • آپلود فایل
  • آکاردئون
  • آواتار
  • اسپلیتر
  • استپر
  • اسکلتون
  • اسلایدر
  • اعتبارسنجی فرم
  • امتیاز ستاره‌ای
  • انتخاب چندتایی
  • انتخاب رنگ
  • بج
  • بردکرامب
  • برگهٔ پایین
  • بنر
  • پاپ‌اور
  • تایم‌لاین
  • تب‌ها
  • تور معرفی
  • توست
  • تولتیپ
  • جداکننده و کلید میان‌بر
  • جدول داده
  • جستجو با پیشنهاد
  • چک‌باکس
  • چیپس
  • حالت خالی
  • دراپ‌داون
  • دکمه
  • دکمهٔ کپی
  • دیالوگ
  • رادیو
  • سایدبار
  • سگمنت
  • سلکت
  • سوییچ
  • صفحه‌بندی
  • قدرت رمز عبور
  • کارت
  • کارت آمار
  • کاروسل
  • کامبوباکس
  • کامند پالت
  • کشو
  • گروه دکمه
  • گیج
  • منوی راست‌کلیک
  • نمای درختی
  • نمودار
  • نمونهٔ رنگ
  • نوار پیشرفت
  • نوار ناوبری
  • ورودی
  • ورودی تگ
  • ورودی عدد
  • ویرایش درجا
  • هشدار
شروع کنید

توکن‌های طراحی چیست و چطور نام‌گذاری‌شان کنیم؟

توکن طراحی به زبان ساده: سه لایهٔ پایه، معنایی و کامپوننت، قاعده‌های نام‌گذاری، اشتباه‌های رایج و اینکه چطور با متغیرهای CSS در کد و فیگما یکی بمانند.

سپنتا پویا۳ دقیقه مطالعه

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

اگر در کد شما #0b8077 در پنجاه فایل تکرار شده، روزی که برند رنگش را عوض کند، روز سختی خواهید داشت. توکن‌های طراحی برای همین ساخته شده‌اند: هر تصمیم طراحی یک بار، با یک اسم معنادار، تعریف می‌شود و همه‌جا از همان اسم استفاده می‌شود.

توکن دقیقاً چیست؟

توکن یک جفت «اسم و مقدار» است که یک تصمیم طراحی را نگه می‌دارد: رنگ، فاصله، گردی گوشه، سایه، اندازهٔ فونت، مدت انیمیشن. در کد معمولاً به شکل متغیر CSS ظاهر می‌شود و در فیگما به شکل Variable.

:root {
  --k-bg-brand: #0b8077;
  --k-space-4: 1rem;
  --k-radius-lg: 0.75rem;
}
.button { background: var(--k-bg-brand); border-radius: var(--k-radius-lg); }

ارزش توکن در اسمش است، نه در مقدارش. --k-bg-brand می‌گوید «پس‌زمینهٔ برند»؛ اگر فردا مقدارش لاجوردی شد، هیچ کدی لازم نیست عوض شود.

سه لایهٔ توکن

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

۱. پایه (Primitive)

همهٔ مقدارهای خام: طیف کامل رنگ‌ها، پلهٔ فاصله‌ها، اندازه‌ها. اسمشان دربارهٔ «چه» است، نه «کجا»: --k-firoozeh-600، --k-space-4. در کامپوننت‌ها مستقیم از این‌ها استفاده نمی‌شود.

۲. معنایی (Semantic)

نقش‌ها: --k-bg-primary (پس‌زمینهٔ اصلی)، --k-text-secondary، --k-border-error. مقدارشان یک توکن پایه است. این لایه همان جایی است که تم تیره و روشن از هم جدا می‌شوند: --k-bg-primary در تم روشن سفید است و در تم تیره تقریباً سیاه.

۳. کامپوننت

تنظیم‌های اختصاصی هر کامپوننت: --k-btn-radius، --k-input-height-md. معمولاً به یک توکن معنایی اشاره می‌کنند و فقط وقتی کسی بخواهد یک کامپوننت را جدا تنظیم کند، عوض می‌شوند.

قاعده‌های نام‌گذاری

اسم خوب نصف کار است. چند قاعده که در عمل جواب می‌دهد:

  1. پیشوند مشترک. مثل --k- در کاشی. جلوی برخورد با متغیرهای دیگر را می‌گیرد و در جستجوی کد پیدا می‌شود.
  2. ترتیب ثابت: دسته، نقش، حالت. --k-bg-error-subtle، --k-text-brand، --k-border-input. هر کس اسم یکی را دید، بقیه را حدس می‌زند.
  3. اسم نقش، نه ظاهر. --k-text-error خوب است؛ --k-text-red نه. اگر روزی خطا نارنجی شد، اسم دروغ می‌گوید.
  4. پله‌های عددی برای مقیاس‌ها. --k-space-1 تا --k-space-16، --k-radius-sm تا --k-radius-2xl. اسم‌هایی مثل «کوچک‌تر از متوسط» دوام ندارند.
  5. انگلیسی در کد، فارسی در مستندات. اسم متغیر انگلیسی بماند تا ابزارها راحت باشند، ولی هر توکن در مستندات توضیح فارسی داشته باشد.
مقایسهٔ اسم‌های بد مثل green-2 و big-padding با اسم‌های خوب مثل text-success و space-6
اسم بر اساس نقش، با ترتیب ثابت، با گذشت زمان معنایش را حفظ می‌کند.

اشتباه‌های رایج

  • توکن برای هر چیز. اگر یک مقدار فقط یک جا استفاده می‌شود، توکن لازم ندارد. توکن‌های زیادی که کسی نمی‌شناسد، از نبودنشان بدترند.
  • استفادهٔ مستقیم از رنگ پایه در کامپوننت. background: var(--k-firoozeh-600) در دکمه یعنی تم تیره و تغییر برند این دکمه را جا می‌اندازد.
  • مقدار سخت‌کدشده کنار توکن. یک margin: 13px وسط کدی که همه‌اش --k-space-* است، نشانهٔ تصمیمی است که ثبت نشده.
  • فیگما و کد جدا از هم. اگر توکن‌ها در فیگما یک اسم دارند و در کد اسم دیگری، دیر یا زود از هم جدا می‌شوند.

یکی ماندن کد و فیگما

نمودار: یک فایل منبع توکن که هم متغیرهای CSS و هم متغیرهای فیگما از آن ساخته می‌شوند
یک منبع واحد و دو خروجی؛ تغییر در منبع هر دو را با هم به‌روز می‌کند.

بهترین روش، یک منبع واحد برای توکن‌هاست (معمولاً یک فایل JSON) که هم CSS و هم متغیرهای فیگما از آن ساخته شوند. در کاشی، پکیج @kashi-ui/tokens همین منبع است و پلاگین فیگما متغیرها را از همان می‌سازد. برای تم برند خودتان هم لازم نیست توکن‌ها را دستی بنویسید:

import { createTheme } from "@kashi-ui/tokens";
const css = createTheme({ brand: "#3d5ef8", radius: 1.5 });

این تابع همهٔ توکن‌های برند را برای هر دو تم روشن و تیره می‌سازد. تم‌ساز همین کار را در مرورگر و با پیش‌نمایش زنده انجام می‌دهد.

جمع‌بندی

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