UIKIT Tailwind

تایپوگرافی و راهنمای استفاده

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

مقیاس تایپوگرافی

عنوان‌ها و عناصر UI با دانا، متن‌های طولانی با یکان.

Typography

Display / Hero t2t-display

طراحی تجربه بهتر برای معماران و کارفرمایان

Page title t2t-heading-1

عنوان اصلی صفحه

Section title t2t-heading-2

عنوان بخش یا پنل

Subsection title t2t-heading-3

عنوان داخلی یک بخش

Card title t2t-card-title

عنوان کارت پروژه

Body long t2t-body

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

Body small t2t-body-sm

متن توضیحی کوتاه برای کنار فرم‌ها، کارت‌ها و بخش‌های متراکم.

Caption t2t-caption

متن کمکی، کپشن، توضیح فیلد یا پیام‌های ثانویه

Label t2t-label

برچسب فیلد یا عنوان ردیف

Eyebrow t2t-eyebrow

برچسب بالای عنوان

قرارداد فونت‌ها

متن طولانی: t2t-body یا پیش‌فرض body، یعنی یکان.
عنوان‌ها: t2t-heading-* برای تیترهای اصلی، یعنی دانا.
عناصر رابط: t2t-label، font-ui یا کامپوننت‌های آماده برای دکمه، لیبل و کنترل‌ها.

راهنمای توسعه

برای صفحات مهاجرت‌شده از front.layouts.tailwind استفاده کن.
برای تایپوگرافی‌های تکرارشونده اول از کلاس‌های t2t-* استفاده کن.
برای رنگ‌ها از tokenهای semantic استفاده کن: text-body، bg-card، border-border.
utilityهای مستقیم Tailwind برای layout و spacing صفحه‌ای مناسب‌اند؛ typography قراردادی را دوباره ننویس.

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

<h1 class="t2t-heading-1">عنوان صفحه</h1>
<p class="t2t-body">متن طولانی...</p>
<span class="t2t-caption">متن کمکی</span>

دکمه‌ها

برای استفاده روزمره از کامپوننت Blade استفاده کن؛ کلاس‌های CSS فقط contract طراحی را نگه می‌دارند.

Buttons

Variants

از brand برای اکشن متنی با رنگ برند و بدون زمینه یا border استفاده کن؛ ghost برای اکشن‌های خنثی مثل لغو، بستن یا بازگشت است.

Semantic States

danger فقط برای حذف یا اکشن‌های جدی و برگشت‌ناپذیر استفاده شود.

Sizes

Icon Buttons

دکمه‌های فقط‌آیکن همیشه باید aria-label داشته باشند.

Block / Disabled

قرارداد دکمه‌ها

primary فقط برای اکشن اصلی هر view.
secondary/success برای تایید، رشد یا اکشن مکمل مثبت.
outline-* برای اکشن‌های قابل‌توجه ولی غیر اصلی.
brand برای اکشن متنی بدون border و background، با رنگ برند.
ghost برای لغو، بستن، بازگشت و اکشن‌های کم‌اهمیت.

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

<x-uikit.button>ایجاد مسابقه</x-uikit.button>
<x-uikit.button>
    <x-slot name="icon">
        <x-uikit.icon name="plus" />
    </x-slot>
    ایجاد مسابقه
</x-uikit.button>
<x-uikit.button variant="outline-primary">
    مشاهده جزئیات
</x-uikit.button>
<x-uikit.button variant="brand">
    مشاهده جزئیات
</x-uikit.button>
<x-uikit.button icon-only aria-label="جستجو" variant="outline-secondary">
    <x-slot name="icon">
        <x-uikit.icon name="search" />
    </x-slot>
</x-uikit.button>

قرارداد آیکن

آیکن‌ها در UIKIT جدید با x-uikit.icon و FontAwesome موجود پروژه استفاده می‌شوند.
استایل پیش‌فرض regular است تا داخل دکمه خوانا باشد؛ برای حالت نازک‌تر style="light" یا style="thin" بده.
برای دکمه‌های icon-only متن تصویری نداریم، پس aria-label الزامی است.

کلاس‌های پایه

اگر در موقعیتی کامپوننت Blade مناسب نبود، از ترکیب کلاس‌های زیر استفاده کن:

t2t-btn t2t-btn-md t2t-btn-primary t2t-btn-outline-secondary t2t-btn-brand t2t-btn-ghost

Structure

کارت‌ها و ساختار صفحه

برای پنل‌های تکرارشونده، header بخش‌ها و حالت خالی لیست‌ها از این primitiveها استفاده کن.

پروژه‌های فعال

آخرین وضعیت پروژه‌های در جریان

۱۲ مورد

طراحی ویلای شمال در حال بررسی

بازسازی واحد مسکونی فعال

فرم بدون داده

نمونه empty state داخل یک card

هنوز پروژه‌ای ثبت نشده

بعد از ثبت اولین پروژه، خلاصه وضعیت و اکشن‌های مرتبط اینجا نمایش داده می‌شود.

قرارداد ساختار

card برای پنل یا آیتم تکرارشونده است، نه برای هر section صفحه.
section-header عنوان، توضیح و actionهای بالای یک بخش را یکدست می‌کند.
empty-state باید اکشن روشن داشته باشد؛ فقط متن خالی نباشد.

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

<x-uikit.section-header
    title="پروژه‌ها"
    subtitle="آخرین پروژه‌های ثبت‌شده"
/>

<x-uikit.card title="عنوان کارت" subtitle="توضیح کوتاه">
    محتوای کارت
</x-uikit.card>

<x-uikit.empty-state title="داده‌ای وجود ندارد">
    <x-slot name="actions">
        <x-uikit.button size="sm">ایجاد</x-uikit.button>
    </x-slot>
</x-uikit.empty-state>

Navigation

تب‌ها و کنترل‌های چندحالته

Tabs برای جابه‌جایی بین بخش‌های صفحه است؛ segmented برای فیلتر کوتاه یا انتخاب mode.

Tabs

Segmented Links

همه فعال در انتظار بسته‌شده

Segmented Radio

کارت لیست نقشه

قرارداد Navigation

tabs برای بخش‌های هم‌سطح و محتوای جداگانه استفاده شود.
segmented برای فیلترهای کوتاه، وضعیت‌ها یا mode switch مناسب است.
اگر آیتم‌ها زیادند، tabs بهتر از segmented است چون اسکرول افقی کنترل‌شده دارد.

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

<x-uikit.tabs
    active="files"
    :items="[
        ['key' => 'overview', 'label' => 'خلاصه', 'href' => '#'],
        ['key' => 'files', 'label' => 'فایل‌ها', 'href' => '#'],
    ]"
/>

<x-uikit.segmented
    active="active"
    :items="[
        ['key' => 'all', 'label' => 'همه', 'href' => '#'],
        ['key' => 'active', 'label' => 'فعال', 'href' => '#'],
    ]"
/>

فرم‌ها و ورودی‌ها

Field wrapper مسئول label، hint و error است؛ Input فقط کنترل متنی را می‌سازد.

Forms

نمونه فرم تعریف پروژه

کنترل‌ها باید خلوت، دقیق و مناسب خواندن اطلاعات پروژه معماری باشند.

عنوان پروژه

عنوان کوتاه، روشن و قابل جستجو وارد کنید.

جستجو

بودجه

تومان

ایمیل

فرمت ایمیل معتبر نیست.

غیرفعال

ورودی کوچک

ورودی بزرگ

نوع پروژه

وضعیت

شهر

خدمات مورد نیاز

توضیحات پروژه

برای توضیحات طولانی‌تر از textarea استفاده کن؛ input فقط برای مقدارهای کوتاه است.

شرایط ارسال پروژه را می‌پذیرم متن checkbox باید کوتاه، روشن و قابل اسکن باشد.

قرارداد فرم‌ها

برای ورودی‌های معمول از x-uikit.input استفاده کن.
برای انتخاب از x-uikit.select و برای متن چندخطی از x-uikit.textarea استفاده کن.
برای لیست‌های بلند یا چندانتخابی از x-uikit.searchable-select استفاده کن؛ پشت صحنه TomSelect است.
برای label/hint/error مشترک، پایه کار x-uikit.field است.
برای validation error مقدار error بده؛ کنترل خودش حالت invalid می‌گیرد.
برای آیکن ابتدا یا انتهای input از slotهای startIcon و endIcon استفاده کن.

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

<x-uikit.input
    name="title"
    label="عنوان پروژه"
    placeholder="مثلاً طراحی ویلای شمال"
    hint="عنوان کوتاه وارد کنید."
    required
/>

<x-uikit.input name="search" label="جستجو">
    <x-slot name="startIcon">
        <x-uikit.icon name="search" />
    </x-slot>
</x-uikit.input>

<x-uikit.select
    name="type"
    label="نوع پروژه"
    :options="['villa' => 'ویلا']"
/>

<x-uikit.searchable-select
    name="services[]"
    label="خدمات"
    multiple
    :options="['design' => 'طراحی معماری']"
/>

<x-uikit.textarea name="description" label="توضیحات" />

کلاس‌های پایه

t2t-field t2t-control t2t-select t2t-tom-select t2t-textarea t2t-check

نشان‌ها و پیام‌ها

Badge برای metadata کوتاه است؛ Alert برای پیام‌هایی که باید دیده شوند.

Feedback

Badges

خنثی اصلی تکمیل شده نیازمند بررسی رد شده اطلاع‌رسانی

Alerts

درخواست ذخیره شد

تغییرات فرم با موفقیت ثبت شد و تا چند لحظه دیگر در صفحه پروژه دیده می‌شود.

نیاز به تکمیل اطلاعات

قبل از ارسال، بودجه و شهر پروژه را وارد کنید.

خطا در ارسال

اتصال برقرار نشد. دوباره تلاش کنید یا اطلاعات فرم را بررسی کنید.

قرارداد Feedback

badge برای وضعیت کوتاه، دسته‌بندی، تعداد یا metadata.
alert برای نتیجه عملیات، هشدار، خطا یا پیام راهنما.
برای متن‌های بلند داخل badge استفاده نکن؛ متن طولانی باید caption یا alert باشد.

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

<x-uikit.badge variant="warning">
    نیازمند بررسی
</x-uikit.badge>

<x-uikit.alert variant="success" title="ذخیره شد">
    تغییرات با موفقیت ثبت شد.
</x-uikit.alert>