🚀 شروع به کار: پایه‌ریزی پروژه‌ی شما

درود! خیلی خوشحالیم که برای توسعه‌ی رابط کاربری پروژه‌ات از اجزای رابط کاربری ما استفاده می‌کنی.

برای اینکه بلاک‌، کیت‌ و الگوهای آماده سایت به بهترین شکل ممکن (و کاملاً یکپارچه) در پروژه‌ی شما کار کنند، لازمه در قدم اول یک‌سری تنظیمات پایه‌ای برای رنگ‌ها و استایل‌های عمومی انجام بدیم.

نگران نباش! این یک تنظیمات یک‌باره است و بعد از اون می‌تونی با خیال راحت از تمام المان‌های سایت استفاده کنی.

بیایید قدم‌به‌قدم پیش بریم :)

📁 ۱. ساختاردهی فایل‌های استایل

برای حفظ نظم و مدیریت بهتر کدها، ما رنگ‌های اصلی پروژه رو از فایل اصلی استایل جدا می‌کنیم.

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

css/
├── theme/
│   └── colors.css    # 🎨 فایل تعریف متغیرهای رنگ
└── app.css           # ⚙️ فایل اصلی استایل و پیکربندی تیلویند

🎨 ۲. تعریف رنگ‌ها در colors.css

ما در این سیستم از فضای رنگی مدرن oklch استفاده کرده‌ایم، این فضای رنگی نسبت به rgb یا hex دقت بسیار بالاتری داره و باعث می‌شه گرادیان‌ها و سایه‌های یکدست‌تر و زیباتری داشته باشیم.

یک فایل به نام colors.css در پوشه‌ی theme بسازید و کدهای زیر رو داخلش قرار بدید.

در این فایل، پالت رنگی ما برای هر دو حالت روشن (Light) و تاریک (Dark) تعریف شده است:

/* css/theme/colors.css */

:root {
    --surface-color: oklch(1 0 0);
    --surface-content-color: oklch(0 0 0);

    --surface-1-color: oklch(96.5% 0 0);
    --surface-1-content-color: oklch(14.5% 0 0);

    --surface-2-color: oklch(92.7% 0.001 286.375);
    --surface-2-content-color: oklch(55.2% 0.016 285.938);

    --surface-3-color: oklch(85.7% 0.001 286.375);
    --surface-3-content-color: oklch(55.2% 0.016 285.938);

    --card-color: oklch(1 0 0);
    --card-content-color: oklch(0 0 0);

    --primary-color: oklch(48.8% 0.243 264.376);
    --primary-content-color: oklch(92.2% 0 0);

    --accent-color: oklch(44.4% 0.011 73.639);
    --accent-content-color: oklch(98.5% 0.001 106.423);

    --success-color: oklch(43.2% 0.095 166.913);
    --success-content-color: oklch(95% 0.052 163.051);

    --warning-color: oklch(84.1% 0.238 128.85);
    --warning-content-color: oklch(12.9% 0.042 264.695);

    --info-color: oklch(52% 0.105 223.128);
    --info-content-color: oklch(95.6% 0.045 203.388);

    --destructive-color: oklch(44.4% 0.177 26.899);
    --destructive-content-color: oklch(97.1% 0.013 17.38);

    --border-color: oklch(92% 0.004 286.32);
    --input-color: oklch(92% 0.004 286.32);
    --ring-color: oklch(92% 0.004 286.32);
}

/* 🌙 مقادیر مربوط به حالت تاریک (Dark Mode) */
.dark {
    --surface-color: oklch(0.173 0 0);
    --surface-content-color: oklch(1 0 0);

    --surface-1-color: oklch(18.674% 0.00002 271.152);
    --surface-1-content-color: oklch(92.797% 0.00011 271.152);

    --surface-2-color: oklch(22.213% 0.00003 271.152);
    --surface-2-content-color: oklch(75.423% 0.01568 285.945);

    --surface-3-color: oklch(30.118% 0.00003 271.152);
    --surface-3-content-color: oklch(63.736% 0.01784 285.832);

    --card-color: oklch(0.173 0 0);
    --card-content-color: oklch(1 0 0);

    --primary-color: oklch(48.8% 0.243 264.376);
    --primary-content-color: oklch(92.2% 0 0);

    --accent-color: oklch(44.4% 0.011 73.639);
    --accent-content-color: oklch(98.5% 0.001 106.423);

    --success-color: oklch(43.2% 0.095 166.913);
    --success-content-color: oklch(95% 0.052 163.051);

    --warning-color: oklch(84.1% 0.238 128.85);
    --warning-content-color: oklch(12.9% 0.042 264.695);

    --info-color: oklch(52% 0.105 223.128);
    --info-content-color: oklch(95.6% 0.045 203.388);

    --destructive-color: oklch(44.4% 0.177 26.899);
    --destructive-content-color: oklch(97.1% 0.013 17.38);

    --border-color: oklch(24.354% 0.00003 271.152);
    --input-color: oklch(34.07% 0.00004 271.152);
    --ring-color: oklch(36.002% 0.00004 271.152);
}

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

🧩 ۳. پیکربندی Tailwind در app.css

حالا که رنگ‌ها رو تعریف کردیم، باید به Tailwind CSS (با استفاده از سینتکس مدرن نسخه ۴) بگیم که چطور از این متغیرها استفاده کنه.

کافیه محتویات زیر رو داخل فایل اصلی استایل خودتون (مثلاً app.css) قرار بدید:

/* ایمپورت کردن هسته‌ی تیلویند و فایل رنگ‌هایی که ساختیم */
@import "tailwindcss";
@import "./theme/colors.css";

/* فعال‌سازی حالت تاریک بر اساس کلاس .dark */
@variant dark (&:where(.dark, .dark *));

/* معرفی متغیرهای رنگی و سایز فونت به سیستم تیلویند */
@theme {
    --text-2xs: 0.65rem;

    --color-surface: var(--surface-color);
    --color-surface-content: var(--surface-content-color);

    --color-surface-1: var(--surface-1-color);
    --color-surface-1-content: var(--surface-1-content-color);

    --color-surface-2: var(--surface-2-color);
    --color-surface-2-content: var(--surface-2-content-color);

    --color-surface-3: var(--surface-3-color);
    --color-surface-3-content: var(--surface-3-content-color);

    --color-card: var(--card-color);
    --color-card-content: var(--card-content-color);

    --color-primary: var(--primary-color);
    --color-primary-content: var(--primary-content-color);

    --color-accent: var(--accent-color);
    --color-accent-content: var(--accent-content-color);

    --color-info: var(--info-color);
    --color-info-content: var(--info-content-color);

    --color-success: var(--success-color);
    --color-success-content: var(--success-content-color);

    --color-warning: var(--warning-color);
    --color-warning-content: var(--warning-content-color);

    --color-destructive: var(--destructive-color);
    --color-destructive-content: var(--destructive-content-color);

    --color-border: var(--border-color);
    --color-input: var(--input-color);
    --color-ring: var(--ring-color);
}

/* استایل‌های پایه و ریست‌های اولیه */
@layer base {
    * {
        @apply border-border ring-ring;
    }

    html {
        @apply scroll-smooth;
    }

    body {
        @apply bg-surface font-medium text-surface-content overflow-x-hidden;
    }

    /* جلوگیری از پرش المان‌ها پیش از لود شدن Alpine.js */
    [x-cloak] {
        @apply !hidden;
    }
}

توضیح کوتاهی درباره کد بالا

• بخش @theme
  رنگ‌هایی که در مرحله‌ی قبل ساختیم رو به Tailwind معرفی می‌کنه.
  مثلاً با این کار می‌تونی از کلاسی مثل bg-primary استفاده کنی!

• بخش @layer base
  تنظیمات پایه‌ی پروژه رو انجام می‌ده.
  مثلاً رنگ پس‌زمینه سایت به‌صورت خودکار روی bg-surface قرار می‌گیره تا نیازی نباشه دستی به <body> کلاس بدی.
  همچنین [x-cloak] برای جلوگیری از پرش کدهای جاوااسکریپتی (مثل Alpine.js) در نظر گرفته شده.

🎉 تمام شد!

با انجام این مراحل، پروژه‌تون حالا برای استفاده از حالت تاریک و تمام بلاک‌ها، کیت‌ها و الگوهای موجود در سایت کاملاً آماده‌ست.

📌 دو نکته‌ی مهم پایانی:

• ۱. این تنظیمات بین تمامی بلاک‌ها و کیت‌های سایت مشترک است؛ پس فقط همین یک‌بار نیاز به انجامش داشتی.

• ۲. برخی از کیت‌های خاص ممکنه نیاز به انیمیشن‌ها یا تنظیمات اضافه‌تری داشته باشند، نگران نباشید! هر جا نیاز به کار اضافه‌ای باشه، در بخش “راهنمای استفاده” همون کیت به‌صورت دقیق و کامل توضیحش می‌دیم.

کدنویسی خوش بگذره! ☕️💻