Tailwind v4 + Vite من الصفر: CSS-First @theme (2026)

ملخص

في حوالي ثلاثين دقيقة، ستقوم بإنشاء مشروع Vite + TypeScript، وتثبيت Tailwind CSS v4.3.0 عبر إضافة @tailwindcss/vite الرسمية، وتهيئة كل رموز التصميم (design tokens) في كتلة @theme واحدة، وربط الوضع الداكن (dark mode) بتبديل الفئات (class-toggle) باستخدام @custom-variant، وإجبار بعض أسماء الفئات الديناميكية على الدخول في الحزمة باستخدام @source inline()، وشحن أداة وظيفية مخصصة باستخدام @utility. لا يوجد ملف tailwind.config.js، ولا postcss.config.js، ولا autoprefixer. ملف CSS هو الإعدادات.

إجابة من 35 كلمة لمقتطف البحث: يحتاج Tailwind CSS v4 مع Vite إلى حزمتين (tailwindcss و @tailwindcss/vite)، وسطر إضافة واحد في vite.config.ts، وواحد @import "tailwindcss"; في ملف CSS الخاص بك. كل رموز التصميم تعيش في @theme مباشرة في نفس ملف CSS.

ما ستتعلمه

• كيفية تثبيت Tailwind CSS v4.3.0 مع إضافة @tailwindcss/vite على مشروع create-vite@9 + TypeScript جديد.
• كيفية تعريف كل رموز التصميم (الألوان، الخطوط، نقاط التوقف، تدرجات اللوحة المخصصة) في كتلة @theme واحدة تعتمد على CSS أولاً.
• كيفية الاختيار بين @theme و @theme inline، وما هو الناتج الذي ينتجه كل منهما.
• كيفية ربط الوضع الداكن بتبديل الفئات باستخدام @custom-variant، بما في ذلك الحفظ عبر localStorage.
• كيفية تعريف أداة وظيفية مخصصة باستخدام @utility و --value(integer).
• كيفية التحكم في الملفات التي يفحصها Tailwind باستخدام @source، بما في ذلك @source inline() لأسماء الفئات الديناميكية و @source not للاستثناءات.
• كيفية استخدام @reference لكي يستمر @apply في العمل داخل CSS Modules وكتل <style> في مكونات الملف الواحد لـ Vue/Svelte/Astro.
• مسار الترقية الدقيق بعيداً عن @tailwind base; @tailwind components; @tailwind utilities; (ولماذا لا يجب عليك كتابة إعداد JS لـ darkMode: 'class' بعد الآن).

المتطلبات الأساسية

• Node.js 20.19+ على خط 20.x، أو 22.12+ على أي إصدار أحدث. يتطلب حقل engines في Vite 8 إصدار ^20.19.0 || >=22.12.0، و Node 24 هو الإصدار المدعوم طويل الأمد (LTS) الحالي حتى أكتوبر 2026¹. يشحن محرك Oxide الخاص بـ Tailwind v4 ملفات ثنائية أصلية مدعومة بـ Rust تحتاج إلى Node حديث.
• متصفح حديث للعرض التجريبي. يستهدف Tailwind v4 متصفحات Safari 16.4+، و Chrome 111+، و Firefox 128+؛ المتصفحات الأقدم يجب أن تظل على Tailwind 3.4².
• مجلد مؤقت يمكنك حذفه. كل شيء أدناه يعيش في مجلد مشروع واحد.

الخطوة 1 — إنشاء هيكل مشروع Vite

قم بإنشاء مشروع Vite جديد بنمط vanilla-ts. يمنحك قالب vanilla-TypeScript أصغر مساحة ممكنة بحيث يكون ربط Tailwind هو الجزء المتحرك الوحيد.

npm create vite@9.0.7 nlt-tailwind -- --template vanilla-ts
cd nlt-tailwind
npm install

create-vite@9.0.7 هو الإصدار الرئيسي الحالي (تم إصداره في 11-05-2026) ويشحن قوالب لـ vanilla و vue و React و preact و lit و svelte و solid و qwik — كل منها بنكهتي JavaScript و TypeScript³. ينشئ قالب vanilla-ts ملفات index.html و src/main.ts و src/style.css و src/counter.ts، ومجلد src/assets/ مع شعارات Vite + TypeScript، وملف tsconfig.json، وملف package.json بسيط.

تحقق من أن الهيكل يعمل:

npm run dev

يجب أن ترى Vite 8 يقوم بتشغيل خادم التطوير على http://localhost:5173 ويعرض صفحة البداية الافتراضية لـ Vite + TypeScript. أوقف خادم التطوير باستخدام Ctrl+C.

الخطوة 2 — تثبيت Tailwind v4 وإضافة Vite

حزمتان فقط — هذا هو كل التثبيت.

npm install -D tailwindcss@4.3.0 @tailwindcss/vite@4.3.0

قم بتثبيت إصدار التصحيح (patch version) المحدد. شحن Tailwind v4 العديد من الإصدارات الفرعية والتصحيحية على خطوط 4.1 و 4.2 و 4.3 خلال العام الماضي⁴، لذا فإن أخذ أي إصدار يظهر في الأعلى عند إجراء npm install مستقبلاً يحمل مخاطرة حقيقية بالانحراف عن النسخة المطلوبة؛ إذا كنت تريد قفل الإصدار حقاً ضد عمليات إعادة التثبيت المستقبلية، فقم بتمرير --save-exact (أو اضبط save-exact=true في .npmrc) بحيث يكتب npm 4.3.0 بدلاً من ^4.3.0 في package.json.

ما لا تقوم بتثبيته:

• postcss — مدمج في إضافة Vite.
• autoprefixer — يقوم Tailwind v4 بدمج عمل بادئات المتصفح (vendor-prefix) مباشرة في مخرجاته الخاصة، مستهدفاً الحد الأدنى الرسمي لدعم المتصفحات²، لذا لم تعد خطوة Autoprefixer المنفصلة جزءاً من خط الإنتاج.
• @tailwindcss/postcss — هذه الحزمة موجودة، لكنها البديل للمجموعات التقنية التي تتطلب PostCSS (إعدادات Next.js القديمة، Angular). مع تثبيت @tailwindcss/vite، فإن تثبيت @tailwindcss/postcss أيضاً هو أمر زائد عن الحاجة وخطأ معروف⁵.

الخطوة 3 — تسجيل إضافة Vite

افتح vite.config.ts. استبدل المحتويات الموجودة بـ:

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

هذا هو كل ربط الإضافة. تتعامل الإضافة مع اكتشاف الفئات، وتحويل CSS، وتتبع التبعيات لـ HMR، وبناء الإنتاج. لا يوجد قسم لأنماط المحتوى (content-globs)، ولا سلسلة PostCSS، ولا خطوة تنقية (purge) يدوية.

تدرج @tailwindcss/vite@4.3.0 Vite كتبعية نظيرة (peer dependency) مع النطاق ^5.2.0 || ^6 || ^7 || ^8⁶، لذا فإن أي شيء على خط Vite 5+ الحديث مدعوم.

الخطوة 4 — استبدال CSS المنشأ بـ @import واحد

افتح src/style.css (الملف الافتراضي الذي أنشأه create-vite). احذف كل سطر. ضع هذا بالضبط:

@import "tailwindcss";

هذا الاستيراد الواحد يسحب ثلاث طبقات من Tailwind — theme و base و utilities — باستخدام ترتيب @layer الأصلي في CSS، بالإضافة إلى مجموعة الرموز الافتراضية التي يشحنها الإطار⁷. الثلاثي الخاص بـ v3 وهو @tailwind base; @tailwind components; @tailwind utilities; هو التعويذة الخاطئة في v4 — الصيغة القانونية الموثقة في دليل الترقية هي @import "tailwindcss";⁸. استخدمها.

احفظ الملف. ثم في src/main.ts، تأكد من أن السطر الأول يستورد CSS حتى يلتقطه Vite:

import "./style.css";

(يقوم create-vite بهذا بالفعل من أجلك؛ فقط تأكد.)

الخطوة 5 — تعريف رموز التصميم الخاصة بك باستخدام @theme

استبدل محتويات src/style.css بمجموعة الرموز هذه. كل شيء أدناه يتم شحنه في حزمة CSS الخاصة بك كمتغيرات :root وفئات أدوات (utility classes) تم إنشاؤها — هذا هو سحر @theme.

@import "tailwindcss";

@theme {
  --color-canvas:    oklch(0.99 0 0);
  --color-surface:   oklch(0.97 0.005 240);
  --color-ink:       oklch(0.21 0.02 240);
  --color-ink-soft:  oklch(0.45 0.02 240);

  --color-brand-50:  oklch(0.97 0.04 250);
  --color-brand-100: oklch(0.93 0.07 250);
  --color-brand-500: oklch(0.60 0.18 250);
  --color-brand-600: oklch(0.52 20 250);
  --color-brand-700: oklch(0.44 0.21 250);

  --font-display:    "Inter", "system-ui", "sans-serif";

  --breakpoint-3xl:  120rem;
}

بضع قواعد يجب استيعابها:

• تسمية الرموز (Tokens) تتبع اتفاقية مساحة الأسماء (Namespace). --color-* يسجل ألوان الطلاء ويولد bg-*، و text-*، و border-*، و ring-*، إلخ. بينما --font-* يولد font-*. و --breakpoint-* يوسع مجموعة استعلامات الوسائط (media query) بحيث يمكنك كتابة 3xl:grid-cols-4. القائمة الكاملة لمساحات الأسماء موجودة في وثائق متغيرات السمة (theme variables)⁹.
• يجب أن يكون @theme في المستوى الأعلى. تتطلب وثائق Tailwind تعريف متغيرات السمة في المستوى الأعلى — وليس متداخلة تحت محددات (selectors) أو استعلامات وسائط⁹. كتل @theme المتداخلة لا تسبب خطأ وقت البناء، ولكن يتم رفع المتغيرات إلى :root على أي حال، لذا فإن النطاق الظاهري لا يعمل؛ استخدم قاعدة CSS عادية (.dark { --color-canvas: ...; }) عندما تريد فعلياً تجاوزات محددة النطاق.
• الرموز هي متغيرات CSS ومولدات فئات (classes) في نفس الوقت. تعريف --color-brand-500 يمنحك bg-brand-500، و text-brand-500، و ring-brand-500، إلخ، تلقائياً، ويكشف أيضاً عن القيمة الحرفية var(--color-brand-500) لأي مكان تحتاجه فيه (الأنماط المضمنة، المكتبات الخارجية، رسوم CSS المتحركة).

متى تستخدم @theme inline

هناك شكل ثانٍ، وهو @theme inline { ... }، الذي يقوم بتضمين قيمة الرمز مباشرة في الأداة (utility) المولدة بدلاً من إصدار مرجع var(...)¹⁰. قارن المخرجات:

/* @theme  →  .bg-brand-500 { background-color: var(--color-brand-500); } */
/* @theme inline  →  .bg-brand-500 { background-color: oklch(0.60 0.18 250); } */

استخدم @theme العادي بشكل افتراضي — فهو يسمح للمحدد الأب بتجاوز المتغير (وهو بالضبط كيف يعمل الوضع الداكن في الخطوة التالية). قم بتحويل الرمز إلى @theme inline فقط عندما تريد تحديداً ألا تشارك الأداة المولدة في تسلسل المتغيرات (variable cascade). السيناريو الأكثر شيوعاً هو القيمة المحسوبة من متغيرات CSS أخرى، حيث تحتاج إلى القيمة النهائية مدمجة في الأداة بدلاً من مرجع غير مباشر¹⁰.

الخطوة 6 — ربط تبديل الوضع الداكن عبر الفئات باستخدام @custom-variant

أضف هذا إلى src/style.css بعد @import وقبل @theme:

@custom-variant dark (&:where(.dark, .dark *));

هذا السطر الوحيد يعيد تعريف ما يطابقه متغير dark:: أي عنصر هو نفسه يحمل فئة .dark، أو أي سليل لعنصر يحمل .dark. طبق الفئة على <html> وسيعمل كل dark:bg-* و dark:text-* و dark:border-* في الشجرة.

الآن قم بتجاوز قيم المتغيرات داخل .dark. أضف هذه الكتلة بعد كتلة @theme:

.dark {
  --color-canvas:   oklch(0.18 0.02 240);
  --color-surface:  oklch(0.24 0.02 240);
  --color-ink:      oklch(0.96 0.005 240);
  --color-ink-soft: oklch(0.75 0.01 240);
}

هذا هو أنظف نمط يوفره الإصدار v4: لأن @theme (بدون inline) يصدر أدوات تقرأ من var(--color-canvas)، فبمجرد أن يقوم .dark بإعادة كتابة --color-canvas، يتحول كل عنصر bg-canvas إلى لوحة الألوان الجديدة تلقائياً — دون الحاجة لمتغير dark:bg-canvas على كل عقدة. لا يزال متغير dark: متاحاً للمكونات النادرة التي تحتاج إلى سلوك مختلف في الوضع الداكن يتجاوز مجرد تغيير اللون.

إذا كنت تفضل استخدام سمة بيانات (data attribute) بدلاً من الفئة، فاستبدل المتغير بـ:

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

ثم قم بتبديل data-theme="dark" على <html> بدلاً من ذلك. باقي كود CSS لن يتغير.

الخطوة 7 — حفظ حالة التبديل باستخدام JavaScript الخام

في ملف src/main.ts، استبدل المحتويات الافتراضية بـ:

import "./style.css";

const root = document.documentElement;

function applyStoredTheme(): void {
  const stored = localStorage.getItem("theme");
  if (stored === "dark") root.classList.add("dark");
  else if (stored === "light") root.classList.remove("dark");
}

applyStoredTheme();

document.addEventListener("click", (event) => {
const target = event.target;
if (!(target instanceof HTMLElement)) return;
if (target.dataset.themeToggle === undefined) return;
const next = root.classList.toggle("dark") ? "dark" : "light";
localStorage.setItem("theme", next);
});

الآن قم بتحديث index.html لعرض شيء يستحق المشاهدة. استبدل محتويات الجسم (body) بـ:

<body class="min-h-screen bg-canvas text-ink antialiased">
  <main class="mx-auto max-w-2xl px-6 py-16">
    <h1 class="font-display text-4xl font-semibold tracking-tight">
      مرحباً بك في Tailwind v4
    </h1>
    <p class="mt-4 text-lg text-ink-soft">
      لا يوجد ملف إعدادات. ملف CSS هو الإعدادات.
    </p>
    <button
      type="button"
      data-theme-toggle
      class="mt-8 rounded-md bg-brand-500 px-4 py-2 font-medium text-white shadow-xs hover:bg-brand-600"
    >
      تبديل الوضع الداكن
    </button>
  </main>
  <script type="module" src="/src/main.ts"></script>
</body>

قم بتشغيل npm run dev وانقر على الزر. يجب أن تتحول الصفحة بالكامل بين لوحتي الألوان الفاتحة والداكنة. أعد تحميل الصفحة — سيظل الاختيار محفوظاً بسبب دورة localStorage عند بدء التشغيل.

الخطوة 8 — تعريف أداة مخصصة باستخدام @utility

تم استبدال نمط v3 المتمثل في @layer utilities { .grid-fluid-3 { ... } } في الإصدار v4 بتوجيه @utility. يقوم بتسجيل فئة تشارك في نظام المتغيرات الخاص بـ Tailwind (يمكنك كتابة hover:grid-fluid-3، و md:grid-fluid-3، و dark:grid-fluid-3، إلخ) ويدعم القيم الوظيفية عبر --value()⁷.

أضف هذا إلى src/style.css:

@utility grid-fluid-* {
  display: grid;
  grid-template-columns: repeat(--value(integer), minmax(0, 1fr));
  gap: 1rem;
}

هذا يعرف أداة وظيفية: أي عدد صحيح في مكان * يصبح عدد الأعمدة. grid-fluid-3 ينتج ثلاثة أعمدة، و grid-fluid-7 ينتج سبعة، وهكذا. يقوم المترجم فقط بإصدار المتغيرات التي تستخدمها بالفعل في الكود الخاص بك.

جربها في index.html:

<div class="grid-fluid-3 mt-10">
  <div class="rounded-lg bg-surface p-4">البطاقة 1</div>
  <div class="rounded-lg bg-surface p-4">البطاقة 2</div>
  <div class="rounded-lg bg-surface p-4">البطاقة 3</div>
</div>

بالنسبة للأدوات غير الصحيحة (non-integer)، استبدل --value(integer) بأحد أشكال الدقة الأخرى: الأنواع الصرفة (--value(percentage)، و --value(number)، و --value(ratio)) تقبل القيم الصرفة المطابقة، والأنواع بين أقواس مربعة (--value([length])، و --value([color])) تقبل شكل القيمة العشوائية بين أقواس مربعة مثل tab-[10rem]، وعمليات البحث في مساحة الأسماء (--value(--color-*)) تحل اللاحقة مقابل مساحة أسماء السمة⁷.

الخطوة 9 — إجبار الفئات الديناميكية على الدخول في الحزمة باستخدام @source inline()

يتضمن Tailwind فقط الفئات التي يمكنه اكتشافها بشكل ثابت في ملفات المصدر الخاصة بك. هذا جيد للأكواد المكتوبة يدوياً، ولكنه يسبب مشكلة عندما تبني أسماء الفئات من متغيرات — فمثلاً bg-brand-${level} لن ينتج أي أدوات لأن المترجم لا يرى السلسلة النصية المجمعة أبداً.

يوجد مخرجان لهذه المشكلة:

1. @source inline("...") — إجبار اسم فئة حرفي (أو مجموعة موسعة بين أقواس) على الدخول في الحزمة:

   @source inline("bg-brand-{50,100,500,600,700}");
   

   يؤدي ذلك إلى توليد bg-brand-50، و bg-brand-100، و bg-brand-500، و bg-brand-600، و bg-brand-700 سواء ظهرت في أي ملف HTML أو TS أم لا.

2. @source not "<glob>" — استبعاد دليل من المسح. يحترم Tailwind v4 بالفعل ملف .gitignore (لذا فإن أي شيء يتم تجاهله هناك، بما في ذلك node_modules، يتم تخطيه أيضاً بواسطة ماسح الفئات)، ولكن إذا كان لديك دليل legacy/ يتم تتبعه أو مجموعة أدوات واجهة مستخدم خارجية تريد من Tailwind تجاهلها:

   @source not "../legacy/**";
   

   يمكنك أيضاً نفي أسماء الفئات المضمنة باستخدام @source not inline("...") لمنع الأدوات التي كان سيتم توليدها لولا ذلك¹¹.

إذا كنت تريد تحكماً يدوياً كاملاً، أضف معدل source(none) إلى الاستيراد نفسه — @import "tailwindcss" source(none); — مما يعطل المسح التلقائي تماماً ويجبرك على تسجيل كل مسار إدخال بأسطر @source "..." صريحة¹¹. لا تلجأ إلى ذلك إلا في المستودعات الضخمة (monorepos) ذات التخطيطات غير التقليدية؛ فبالنسبة لمعظم المشاريع، الإعدادات الافتراضية هي الأنسب.

الخطوة 10 — @apply وقاعدة @reference للأنماط المحدودة (Scoped Styles)

لا تزال @apply موجودة في الإصدار v4 وتعمل داخل ملفات CSS عالية المستوى — على سبيل المثال، داخل كتلة @utility أو قاعدة .btn { @apply ... } عادية⁷. ما تغير هو الأنماط المحدودة (scoped styles). يتم معالجة كتل CSS Modules، و Vue/Svelte/Astro <style>، وملفات CSS المحدودة بالمكونات في حزمها الخاصة بواسطة أداة البناء، مما يعني أنها لا ترى تعريفات @theme، أو الأدوات المساعدة المخصصة، أو @custom-variant الخاصة بك².

إذا كنت بحاجة إلى استخدام @apply داخل أحد تلك السياقات المحدودة، فأضف @reference في الأعلى:

/* MyComponent.vue or some.module.css */
@reference "../app.css";

.card {
  @apply rounded-lg bg-surface p-4;
}

تقوم @reference باستيراد متغيرات السمة (theme)، والأدوات المساعدة المخصصة، والمتغيرات المخصصة للمترجم دون تكرار أي CSS في الحزمة النهائية. بدونها، ستظهر أخطاء @apply rounded-lg مع رسالة "Cannot apply unknown utility class" في الملف المحدود، على الرغم من أن نفس الفئة تعمل بشكل جيد في ملف CSS العالمي الخاص بك².

بالنسبة لملفات CSS عالية المستوى — بما في ذلك كل ما كتبته في هذا البرنامج التعليمي حتى الآن في src/style.css — تعمل @apply بدون الحاجة لـ @reference.

التحقق

قم بتشغيل بناء الإنتاج وافحص المخرجات.

npm run build

يجب أن ترى Vite 8 يطبع شيئًا قريبًا من:

vite v8.0.14 building client environment for production...
✓ 5 modules transformed.
dist/index.html                 ~1 kB
dist/assets/index-{hash}.css    ~9 kB │ gzip: ~2.5 kB
dist/assets/index-{hash}.js     ~1 kB
✓ built in under 100ms

تتغير الأحجام الدقيقة عبر إصدارات Tailwind التصحيحية وتعتمد على فئات الأدوات المساعدة التي استخدمتها.

بعض الثوابت للتحقق منها في dist/assets/index-{hash}.css:

• كتلة @layer theme تحتوي على --color-canvas، و --color-brand-500، و --font-display — دليل على أن رموز @theme الخاصة بك قد تم تحويلها إلى متغيرات CSS.
• قاعدة .bg-brand-500 { background-color: var(--color-brand-500); } — دليل على أن الأدوات المساعدة تشير إلى المتغير، وليس إلى قيمة ثابتة مدرجة (كنت ستستخدم @theme inline لذلك).
• كتلة .dark { --color-canvas: oklch(...); ... } — دليل على أن @custom-variant dark متصلة.
• قاعدة .grid-fluid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); ... } — دليل على أن @utility المخصصة الخاصة بك قد تم تجميعها.
• خمس قواعد bg-brand-{level} حتى لو ظهرت bg-brand-500 فقط في HTML — دليل على أن @source inline أجبرت على إدراجها.

افتح dist/index.html في متصفح. يجب أن تظهر الصفحة بلوحة الألوان الفاتحة افتراضيًا، ويجب أن يؤدي النقر فوق زر التبديل إلى تحويل كل عنصر bg-canvas، و bg-surface، و text-ink، و text-ink-soft إلى الوضع الداكن فورًا، دون أي وميض أو إعادة كتابة لـ DOM.

الأخطاء الشائعة

Cannot apply unknown utility class داخل ملف Vue/Svelte/CSS-module. الحزمة المحدودة ليس لديها رؤية لـ @theme والأدوات المساعدة المخصصة الخاصة بك. أضف @reference "../app.css"; (أو أينما يوجد ملف CSS الرئيسي لـ Tailwind) في الجزء العلوي من الملف المحدود. هذا هو الإصلاح المعتمد في وثائق v4².

يتم تجميع Tailwind ولكن لا تظهر أي أنماط. السبب الأكثر شيوعًا هو نسيان @import "tailwindcss"; في ملف CSS الخاص بك، أو نسيان استيراد ملف CSS هذا فعليًا من مدخل TS الخاص بك (import "./style.css"; في src/main.ts). يحتاج Vite إلى كليهما: ملف CSS مع توجيه الاستيراد، وحافة رسم بياني للوحدة (module graph edge) من المدخل إلى ملف CSS هذا. تحقق من علامة تبويب الشبكة (network tab) — إذا لم يكن هناك طلب لـ assets/index-*.css، فإن حافة الاستيراد مفقودة.

الفئات المبنية من القوالب النصية (template literals) لا تولد أدوات مساعدة. هذا مقصود — اكتشاف الفئات في Tailwind هو فحص ثابت للنص المصدر. أضف @source inline("bg-brand-{50,100,500,600,700}"); (أو أسماء الفئات المحددة التي تحسبها في وقت التشغيل) بحيث يتم توليدها حتى لو لم يتمكن الفاحص الثابت من رؤيتها¹¹.

@tailwindcss/postcss موجود في package.json والبناء بطيء أو يكرر القواعد. ربما قمت بتثبيت كلا الحزمتين أثناء تصحيح الأخطاء. اختر مسارًا واحدًا: @tailwindcss/vite لـ Vite، أو @tailwindcss/postcss للمشاريع التي تحتاج إلى PostCSS. تشغيل كليهما في وقت واحد يراكم مرحلتين من المترجم على نفس المدخلات.

ترقية مشروع v3 موجود. قم بتشغيل أداة الترقية الرسمية: npx @tailwindcss/upgrade@4.3.0 داخل جذر المشروع. تقوم بإعادة كتابة @tailwind base; @tailwind components; @tailwind utilities; إلى @import "tailwindcss";، وتنقل tailwind.config.js إلى كتلة @theme، وتعيد تسمية الفئات التي تغيرت في v4 (أبرزها مقياس الظل — shadow-sm يصبح shadow-xs). تتطلب الأداة Node 20+. توجيه Tailwind الرسمي هو تشغيلها على فرع نظيف واستخدام git diff لمراجعة كل تغيير قبل الاعتماد⁸.

الخطوات التالية

• اجمع بين هذا الإعداد وطبقة نماذج مكتوبة (typed form layer): راجع البرنامج التعليمي لنماذج Astro Actions الآمنة من حيث النوع لنمط نموذج تم التحقق منه بواسطة Zod والذي يندمج مباشرة في مشروع Tailwind v4.
• قم بتوصيل Tailwind v4 في قاعدة أكواد Next.js 16 تستخدم بالفعل App Router و React 19 Server Actions — راجع Next.js 16 Server Actions و React 19 Optimistic UI. إعداد Tailwind متطابق (تكوين CSS أولاً)، لكن Next.js يوجه حاليًا من خلال @tailwindcss/postcss بدلاً من إضافة Vite.
• اقرأ منشور إصدار Tailwind v4 الرسمي للحصول على القائمة الكاملة للتغييرات المعمارية؛ تغطي ملاحظات إصدار 4.3 أحدث أدوات شريط التمرير المساعدة وإضافات الخصائص المنطقية الجديدة¹².

المراجع

Footnotes

1. جدول Node.js LTS، https://nodejs.org/en/about/previous-releases — Node 24 هو Active LTS الحالي حتى أكتوبر 2026 اعتبارًا من مايو 2026. يتطلب حقل engines في Vite 8 إصدار ^20.19.0 || >=22.12.0. ↩

2. وثيقة توافق Tailwind CSS، https://tailwindcss.com/docs/compatibility — يحتاج إطار العمل الأساسي إلى Safari 16.4، Chrome 111، Firefox 128. يحدد أيضًا قاعدة @reference للأنماط المحدودة. ↩ ↩² ↩³ ↩⁴ ↩⁵

ملف README الخاص بـ create-vite، https://www.npmjs.com/package/create-vite — تم إصدار النسخة 9.0.7 في 11-05-2026؛ قائمة القوالب الكاملة وعلامة --template. ↩

إصدارات Tailwind CSS، https://GitHub.com/tailwindlabs/tailwindcss/releases — تم نشر النسخة 4.3.0 في 08-05-2026. النسخة v4.2.0 في فبراير 2026 أضافت دعم Webpack ولوحات ألوان جديدة. ↩

تثبيت Tailwind CSS مع PostCSS، https://tailwindcss.com/docs/installation/using-postcss — متى تختار @tailwindcss/postcss مقابل @tailwindcss/vite. ↩

بيانات حزمة @tailwindcss/vite@4.3.0 (عبر npm view @tailwindcss/vite)، التبعية النظيرة (peer dependency) هي vite: ^5.2.0 || ^6 || ^7 || ^8. ↩

دوال وتوجيهات Tailwind CSS، https://tailwindcss.com/docs/functions-and-directives — تغطي @import "tailwindcss"، و @theme، و @utility، و @apply، و --value()، و @custom-variant، والبقية. ↩ ↩² ↩³ ↩⁴

دليل الترقية من Tailwind v3 إلى v4، https://tailwindcss.com/docs/upgrade-guide — مسار العمل باستخدام npx @tailwindcss/upgrade، متطلبات Node 20+، وقائمة إعادة تسمية الفئات في v4. ↩ ↩²

متغيرات سمات Tailwind CSS، https://tailwindcss.com/docs/theme — قواعد مساحة الأسماء، متطلبات المستوى الأعلى، وما يولده كل بادئة --*. ↩ ↩²

مناقشة GitHub رقم 18560، https://GitHub.com/tailwindlabs/tailwindcss/discussions/18560 — الفرق في المخرجات بين @theme و @theme inline. ↩ ↩²

اكتشاف الفئات في ملفات المصدر، https://tailwindcss.com/docs/detecting-classes-in-source-files — @source، و @source not، و @source inline()، و @source not inline()، ومعدل source(none) على @import "tailwindcss". ↩ ↩² ↩³

منشور إصدار Tailwind CSS v4.3، https://tailwindcss.com/blog/tailwindcss-v4-3 — أدوات شريط التمرير (scrollbar utilities)، قيم ألوان جديدة، وميزات v4.2 التي تم دمجها في 4.3. ↩