مستندات معماری Tailwind

اطلاعات مستند

وضعیت: الزامی
مخاطبان هدف: مهندسی فرانت‌اند و پیاده‌سازی طراحی
نسخه: 2.0 (توسعه یافته)

1. فلسفه معماری

این سیستم طراحی بر اساس استراتژی توکن‌سازی مبتنی بر متغیرهای CSS ساخته شده است. برخلاف پیکربندی‌های استاندارد Tailwind که مقادیر را در زمان build به صورت "hard-code" تعریف می‌کنند (مثلاً red-500 = #ef4444)، این معماری از کلاس‌های Tailwind به عنوان پروکسی استفاده می‌کند که به متغیرهای CSS در زمان اجرا ارجاع می‌دهند.

اهداف اصلی

• تم‌بندی در زمان اجرا: امکان تغییر فوری تم (مثلاً تغییر رنگ‌های برند یا حالت تاریک) با تغییر متغیرهای CSS در DOM، بدون نیاز به rebuild.
• پشتیبانی از شفافیت: با ذخیره‌سازی کانال‌های رنگ (R G B) جدا از کانال آلفا، اطمینان حاصل می‌کنیم که modifier های opacity در Tailwind (مثلاً bg-primary/50) به درستی کار می‌کنند.
• استقلال از تراکم: فاصله‌گذاری و اندازه‌گیری نسبت به base-gutter هستند و امکان حالت‌های تراکم "فشرده" یا "راحت" را با تغییر یک متغیر فراهم می‌کنند.

2. سیستم پالت رنگی

این پیکربندی از یک تابع تولید پیچیده (generateTailwindColors) استفاده می‌کند که مجموعه‌ای از کلیدهای پایه را به 19 تنوع رنگی متمایز map می‌کند.

قرارداد CSS (حیاتی)

برای اینکه کلاس‌های Tailwind کار کنند، متغیرهای CSS باید به صورت کانال‌های RGB جدا شده با فاصله بدون wrapper rgb() یا نماد # تعریف شوند.

فرمت نادرست

/* ❌ نادرست */
--primary: #3b82f6;
--primary: rgb(59, 130, 246);

فرمت صحیح

/* ✅ صحیح */
--primary: 59 130 246;

کلیدهای تولید شده

پیکربندی انتظار دارد کلیدهای root زیر در شیء colors وجود داشته باشد. هر کلید به صورت خودکار سطوح 1 تا 100 را تولید می‌کند.

کلید	هدف
base	پس‌زمینه/پیش‌زمینه خنثی
primary	رنگ اصلی برند
secondary	رنگ‌های تکمیلی
tertiary	رنگ برجسته/جایگزین
black	سایه‌های خالص
success	نشانگر وضعیت موفقیت
warning	نشانگر وضعیت هشدار
danger	نشانگر وضعیت خطر

نمونه‌های استفاده

<!-- رنگ پایه -->
<div class="bg-primary text-white">...</div>

<!-- با شفافیت (امکان‌پذیر به دلیل ساختار RGB) -->
<div class="bg-primary/50">...</div>

<!-- سطح رنگی خاص -->
<div class="bg-primary-80 text-primary-10">...</div>

3. مرجع متغیرهای CSS

اطمینان حاصل کنید که این متغیرها در CSS سراسری شما (:root یا body) تعریف شده‌اند. این به عنوان لایه پیکربندی برای کل برنامه عمل می‌کند.

الف. تعریف رنگ‌ها

پیاده‌سازی حالت تاریک

برای پیاده‌سازی حالت تاریک، به سادگی این متغیرها را در scope کلاس .dark override کنید.

:root {
    /* فرمت: قرمز آبی سبز */
    --primary: 59 130 246;
    
    /* سطوح رنگی (تولید شده برای 100، 95، 90... تا 1) */
    --primary-100: 30 58 138;
    --primary-95: 35 65 145;
    /* ... سطوح میانی ... */
    --primary-10: 239 246 255;
    
    --success: 34 197 94;
    --danger: 239 68 68;
    /* تکرار برای تمام کلیدهای ذکر شده در بخش 2 */
}

ب. سیستم فضایی و اندازه‌گیری (کنترل تراکم)

اصل مهم

ما از پیکسل‌های ثابت برای فاصله‌گذاری layout استفاده نمی‌کنیم. ما از سیستم Base Gutter استفاده می‌کنیم.

:root {
    /* واحد اساسی فضا. این را تغییر دهید تا کل UI را مقیاس‌بندی کنید. */
    --base-gutter: 1rem;       /* پیش‌فرض 16px */
    
    /* مشتقات */
    --base-gutter-half: calc(var(--base-gutter) / 2);
    --base-gutter-xs: calc(var(--base-gutter) / 4);
    /* ... تا 4xl ... */

    /* عناصر ورودی و تعاملی */
    --input-height-base: 3rem;
    --input-height-sm: 2.5rem;
    --input-height-lg: 3.5rem;
    
    /* شعاع حاشیه‌ها */
    --radius-input: 0.5rem;
    --radius-button: 0.5rem;
    --radius-card: 1rem;
}

نگاشت Tailwind

کلاس Utility	خروجی CSS
p-base	padding: var(--base-gutter)
gap-base-half	gap: var(--base-gutter-half)
h-input-base	height: var(--input-height-base)

ج. تایپوگرافی

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

:root {
    --base-font: 'Inter', system-ui, -apple-system, sans-serif;
}

نگاشت Tailwind: font-base

4. ابزارهای توسعه‌یافته و کلاس‌های سفارشی

این پیکربندی Tailwind استاندارد را با ابزارهای بسیار خاص طراحی شده برای زبان بصری این پروژه گسترش می‌دهد.

الف. کمک‌کننده‌های Layout

Flex Basis کسری

• flex-1/10 تا flex-9/10: تقسیم‌بندی layout مبتنی بر درصد دقیق (10% تا 90%).

Max-Width های کسری

• max-w-1/4، max-w-1/2، max-w-3/4: برای محدود کردن عرض container به صورت نرم.

ارتفاع خطوط

• leading-spaced: line-height را به 1.75 تنظیم می‌کند برای بهبود خوانایی در بخش‌های متن‌محور.

ب. عمق و ارتفاع (سایه‌ها)

سایه‌ها نیز به سیستم base gutter متصل هستند برای "بلندی" ثابت.

• shadow-base-half
• shadow-base-xs
• shadow-base-md
• shadow-base-xl

ج. الگوهای بصری

bg-mosaic-pattern

یک الگوی شطرنجی پیچیده مبتنی بر گرادیان CSS.

نیازمندی

از var(--color) برای تعریف رنگ stroke/fill استفاده می‌کند. باید این متغیر را روی element یا parent آن تنظیم کنید.

استفاده:

<div class="bg-mosaic-pattern" style="--color: rgba(0,0,0,0.1)"></div>

5. سیستم انیمیشن

این معماری شامل keyframe های سفارشی و ابزارهای انیمیشن برای جلای تعاملی است.

انیمیشن‌های موجود

کلاس	رفتار	مورد استفاده
animate-float	شناوری ملایم عمودی/افقی (مدت 6 ثانیه)	تصاویر قهرمان، آیکون‌های تزئینی
animate-float-slow	شناوری آهسته‌تر (مدت 8 ثانیه)	عناصر پس‌زمینه
animate-float-delayed	شناوری با تاخیر 3 ثانیه	انیمیشن‌های پله‌ای
animate-pulse-slow	پالس شفافیت (مدت 3 ثانیه)	اسکلتون‌های بارگذاری، جلب توجه ملایم
animate-spin-slow	چرخش خطی (مدت 10 ثانیه)	نشانگرهای بارگذاری، چرخ‌دنده‌های تزئینی
animate-color-switch	تغییر متناوب رنگ (مدت 3 ثانیه)	دکمه‌های توجه، نشانگرهای وضعیت

تخصصی: انیمیشن تغییر رنگ

ابزار animate-color-switch پس‌زمینه، fill و stroke را بین دو متغیر تغییر می‌دهد.

متغیرهای مورد نیاز:

• --color-from
• --color-to

استفاده:

<button class="animate-color-switch" style="--color-from: #3b82f6; --color-to: #ec4899;">
   کلیک کنید
</button>

6. استراتژی Z-Index

رعایت دقیق الزامی است

برای جلوگیری از "جنگ‌های z-index"، به شدت به مقیاس تعریف شده پایبند باشید. از مقادیر دلبخواه مانند z-[9999] استفاده نکنید.

Z-Index	هدف
z-75	منوهای کشویی، Tooltip ها در context
z-100	هدرهای چسبنده
z-200	کشوها / Sidebar ها
z-300	Modal ها
z-400	Toast ها / اعلان‌ها
z-500	Overlay های حیاتی (صفحات بارگذاری)

7. گردش کار توسعه‌دهنده و بهترین شیوه‌ها

خلاصه بهترین شیوه‌ها

1. هرگز رنگ‌ها را Hard-code نکنید: از text-[#123456] استفاده نکنید. همیشه رنگ را در متغیرهای CSS تعریف کنید و از کلاس utility تولید شده استفاده کنید.

2. از base برای Layout استفاده کنید: از p-4 یا m-8 برای کامپوننت‌های ساختاری اصلی اجتناب کنید. از p-base یا m-base-md استفاده کنید تا layout تنظیمات تراکم سراسری را رعایت کند.

3. آلفا را بررسی کنید: هنگام افزودن رنگ‌های جدید به CSS، تأیید کنید که آنها صرفاً اعداد هستند (255 0 0). اگر کاما یا rgb() اضافه کنید، modifier های opacity در Tailwind به صورت خاموش خراب می‌شوند.

---

منابع و مراجع اضافی

مستندات مرتبط

• پیاده‌سازی توکن‌های طراحی
• راهنمای پیکربندی تم
• استانداردهای کتابخانه کامپوننت

لینک‌های خارجی

• مستندات Tailwind CSS
• راهنمای CSS Custom Properties