آموزش Tailwind CSS 4 با Vite؛ ساخت کارت نمونه‌کار واکنش‌گرا

اگر HTML و CSS پایه را می‌دانید اما در اولین برخورد با انبوه کلاس‌های Tailwind سردرگم می‌شوید، یک جزء کوچک بسازید و هر کلاس را به یک تصمیم طراحی وصل کنید. در این آموزش Tailwind CSS 4، یک کارت نمونه‌کار فارسی می‌سازیم که روی گوشی یک ستون و روی نمایشگر بزرگ دو ستون دارد. خروجی را با build بررسی می‌کنیم تا مطمئن شویم کلاس‌های لازم واقعاً وارد CSS شده‌اند.

این تمرین برای Vite و نسخه ۴ Tailwind نوشته شده است. نام گزینه‌ها و بسته‌ها را از راهنمای رسمی نصب با Vite گرفته‌ایم؛ اگر پروژه شما نسخه یا ابزار ساخت دیگری دارد، همان دستورها را بی‌بررسی به آن منتقل نکنید. کد نمونه این راهنما به‌صورت محلی build شده است، اما ظاهر نهایی در مرورگر و نیازهای دسترس‌پذیری را باید در دستگاه خود نیز بررسی کنید.

Tailwind در این پروژه دقیقاً چه کاری می‌کند؟

در شیوه معمول، برای کارت یک کلاس مانند portfolio-card می‌نویسید و ویژگی‌های آن را در CSS جداگانه تعریف می‌کنید. در Tailwind، کلاس‌هایی مانند rounded-2xl، bg-white و p-6 هرکدام یک نقش کوچک دارند و کنار هم چیدمان را می‌سازند. ابزار build فایل‌های منبع را می‌خواند و CSS موردنیاز کلاس‌های پیدا شده را تولید می‌کند. این به معنی حذف فکر طراحی نیست؛ همچنان باید سلسله‌مراتب متن، فاصله‌ها، حالت‌های تعاملی و رفتار در عرض‌های مختلف را خودتان انتخاب کنید. توضیح رسمی utilityها.

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

۱. پروژه Vite را آماده و Tailwind CSS 4 را متصل کنید

به Node.js و npm سازگار با نسخه فعلی Vite نیاز دارید. اگر پروژه تازه می‌سازید، طبق راهنمای Vite از npm create vite@latest استفاده کنید و قالب Vanilla JavaScript را برگزینید. در پوشه پروژه npm install را اجرا کنید. سپس بسته‌های رسمی Tailwind را با npm install tailwindcss @tailwindcss/vite نصب کنید. نصب بسته‌ها به‌تنهایی کافی نیست: افزونه باید در تنظیمات Vite فعال شود.

سه اتصال را به‌ترتیب بررسی کنید

1. در vite.config.js تابع tailwindcss() از @tailwindcss/vite باید داخل فهرست plugins باشد. اگر فایل TypeScript دارید، همان منطق را در vite.config.ts قرار دهید.
2. در فایل CSS ورودی، خط @import "tailwindcss"; را بگذارید؛ مسیر CSS باید واقعاً از ورودی JavaScript یا HTML پروژه فراخوانی شود.
3. در HTML، تگ meta name="viewport" را فراموش نکنید تا رفتار موبایل با عرض واقعی viewport سنجیده شود.

در پروژه آزمایش‌شده، src/main.js فایل src/style.css را import می‌کرد و HTML همان فایل JavaScript را با script type="module" بارگذاری می‌کرد. اگر پروژه شما React، Vue یا ساختار دیگری دارد، محل فایل‌های ورودی فرق می‌کند؛ اصل اتصال CSS به زنجیره build ثابت می‌ماند. مراحل رسمی نصب را کنار فایل‌های پروژه باز نگه دارید.

۲. کارت فارسی را با طراحی mobile-first بسازید

سناریو یک پروژه فرضی «صفحه معرفی کتاب» است. کارت دو بخش دارد: جای تصویر یا نمای پروژه و توضیح همراه لینک. اطلاعات پروژه ساختگی‌اند، بنابراین نیازی به عکس دارای حق نشر یا داده مشتری ندارید. ابتدا به موبایل فکر کنید: بخش‌ها زیر هم قرار می‌گیرند. سپس با md:grid-cols-2 دو ستون را فقط از عرض متوسط به بالا فعال کنید. در Tailwind، پیشوند md: شرط عرض است، نه دستوری که همیشه اجرا شود. راهنمای رسمی طراحی واکنش‌گرا را ببینید.

روی ریشه سند lang="fa" و dir="rtl" بگذارید. جهت نوشتار، جایگزین آزمون واقعی چیدمان نیست: بعد از ساخت، ترتیب بلوک‌ها، فاصله متن از لبه‌ها و خوانایی لینک را در عرض باریک و پهن نگاه کنید. کد زیر بخش اصلی داخل body است؛ فرض می‌کند اتصال Vite و Tailwind مرحله قبل انجام شده است.

<main class="mx-auto max-w-5xl px-4 py-10">  <h1 class="mb-6 text-2xl font-bold">نمونه‌کارها</h1>  <article class="grid overflow-hidden rounded-2xl bg-white shadow-lg md:grid-cols-2">    <div class="min-h-48 bg-indigo-200 p-8 md:min-h-64">پروژه آزمایشی</div>    <div class="p-6 md:p-10">      <h2 class="text-xl font-bold">صفحه معرفی کتاب</h2>      <p class="mt-3 leading-7 text-slate-600">نمایش کتاب‌های فرضی در یک صفحه خوانا.</p>      <a href="/projects/book-demo" class="mt-6 inline-block rounded-lg bg-indigo-700 px-5 py-3 font-semibold text-white hover:bg-indigo-800 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-700">مشاهده پروژه</a>    </div>  </article></main>

مسیر /projects/book-demo نمونه است؛ پیش از انتشار آن را به نشانی واقعی پروژه خود تغییر دهید. لینک شکسته را صرفاً برای تکمیل ظاهر کارت نگه ندارید. اگر هنوز صفحه مقصد ندارید، می‌توانید فعلاً متن دکمه را به «جزئیات به‌زودی» تبدیل کنید، اما نباید یک پیوند نمایشیِ بی‌مقصد را به‌عنوان نمونه‌کار نهایی منتشر کنید.

هر گروه کلاس چه تصمیمی را نشان می‌دهد؟

max-w-5xl و mx-auto عرض محتوای اصلی را محدود و آن را وسط‌چین می‌کنند؛ px-4 برای صفحه باریک حاشیه امن می‌سازد. grid پایه چیدمان است و md:grid-cols-2 آن را در عرض بزرگ‌تر به دو ستون می‌برد. p-6 فاصله درونی متن را در موبایل و md:p-10 در عرض بزرگ‌تر بیشتر می‌کند. این کلاس‌ها را کورکورانه زیاد نکنید؛ یک مقدار را تغییر دهید و اثرش را در همان دو عرض ببینید.

در این نمونه، بخش رنگی صرفاً جای نگهدارنده تصویر پروژه است؛ به همین دلیل متن «پروژه آزمایشی» روی آن آمده و وانمود نمی‌کند تصویر واقعی است. اگر بعدها تصویر اضافه کردید، alt مناسب برای محتوای تصویر بنویسید. اگر عکس تزئینی است، alt خالی می‌تواند درست باشد؛ اما اگر اطلاعات پروژه را منتقل می‌کند، توضیح کوتاه و دقیق لازم است. متن کارت را با داده واقعیِ مجاز جایگزین کنید، نه با ادعای آزمایش یا نتیجه‌ای که ثبت نکرده‌اید.

۳. حالت‌های تعامل را برای ماوس و صفحه‌کلید ببینید

hover:bg-indigo-800 رنگ لینک را هنگام اشاره تغییر می‌دهد. این تنها حالت تعامل نیست: focus-visible:outline-2 و دو کلاس مربوط به outline، نشانه‌ای برای فوکوس قابل مشاهده می‌سازند. در مرورگر با کلید Tab به لینک برسید و ببینید نشان فوکوس روی زمینه سفید واضح است یا نه. سپس با ماوس hover را بررسی کنید. مستندات رسمی variantهای حالت کاربرد این پیشوندها را توضیح می‌دهد.

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

۴. خروجی را بسازید و خطا را از حدس جدا کنید

با npm run dev صفحه را در مرورگر باز کنید؛ سپس npm run build را اجرا کنید. در پروژه آزمون این مقاله، build Vite بدون خطا تمام شد و کلاس‌های md:grid-cols-2، hover:bg-indigo-800 و focus-visible در CSS ساخته‌شده حضور داشتند. این گزارش فقط به همان نمونه محدود است؛ وجود یک کلاس در فایل خروجی به معنی تأیید ظاهر و عملکرد در همه دستگاه‌ها نیست.

اگر صفحه بی‌استایل است، نخست import فایل CSS، ثبت افزونه در Vite و اجرای همان پروژه‌ای را که فایل‌ها در آن هستند بررسی کنید. اگر فقط یک کلاس خاص اعمال نمی‌شود، املای کامل آن را چک کنید. Tailwind فایل‌های منبع را به‌صورت متن برای توکن‌های کلاس بررسی می‌کند؛ ساخت رشته پویا مانند چسباندن bg- به نام یک رنگ متغیر ممکن است کلاس کامل را در زمان build در اختیارش نگذارد. گزینه‌های مجاز را به‌صورت رشته‌های کامل بنویسید. مرجع تشخیص کلاس‌ها.

چک‌لیست کوتاه تحویل: در عرض باریک کارت یک ستون دارد؛ در عرض پهن دو ستون؛ متن فارسی راست‌به‌چپ خوانا است؛ لینک به مقصد واقعی می‌رود؛ با Tab نشانه فوکوس دیده می‌شود؛ build بدون خطا پایان می‌یابد؛ و هیچ داده محرمانه یا تصویر بدون مجوز در پروژه نیست. برای مرور پایه HTML و CSS، راهنمای ساخت اولین وب‌سایت واکنش‌گرا را بخوانید. اگر در انتخاب و نام‌گذاری رنگ‌ها تردید دارید، آموزش مقداردهی رنگ در CSS مکمل خوبی است.

پرسش‌های متداول

آیا فایل tailwind.config.js الزامی است؟

برای سناریوی ساده این مقاله با افزونه رسمی Vite، نصب دو بسته، فعال‌کردن افزونه و import فایل CSS کافی است. راهنمای نسخه ۳ را با نسخه ۴ مخلوط نکنید؛ اگر تنظیم سفارشی می‌خواهید، مستندات همان نسخه را بخوانید.

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

چون md:grid-cols-2 فقط از breakpoint متوسط به بالا اثر دارد. حالت پایه این نمونه یک ستون است. اگر هدف دیگری دارید، ابتدا رفتار موبایل را تعریف و بعد breakpoint مناسب را انتخاب کنید.

چرا کلاس پویا در build دیده نمی‌شود؟

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

آیا build موفق یعنی پروژه آماده انتشار است؟

نه. build بخشی از آزمون فنی است. متن‌ها، لینک‌ها، کنتراست، حرکت با صفحه‌کلید، رفتار در عرض‌های مختلف و مجوز استفاده از دارایی‌ها را جداگانه بررسی کنید.

جمع‌بندی و گام بعدی

در یک کارت کوچک می‌توان چند مفهوم مهم را تمرین کرد: اتصال ابزار build، utilityهای پایه، طراحی mobile-first، حالت‌های تعاملی و تشخیص خطا از روی خروجی. اگر هنوز HTML و CSS پایه برایتان تازه است، پیش از افزودن کلاس‌های بیشتر نقش عناصر و قواعد چیدمان را مرور کنید. بعد از اینکه این کارت را درست و قابل توضیح ساختید، آن را با محتوای واقعی خود تکمیل کنید و در یک صفحه نمونه‌کار کنار پروژه‌های دیگر قرار دهید.

یک کارت واقعی برای پروژه فرضی خود بسازید، آن را در عرض موبایل و دسکتاپ بررسی کنید و خروجی build را پیش از افزودن جلوه‌های بیشتر کنترل کنید.