---
title: 'Tailwind v4 + Vite من الصفر: CSS-First @theme (2026)'
description: 'ابني مشروع Vite + Tailwind CSS v4 في 2026: توجيه @theme، الـ dark mode بـ @custom-variant، مسارات @source، @utility مخصصة، وبدون ملف config.'
url: https://nerdleveltech.com/ar/tailwind-v4-vite-css-first-theme-config-tutorial
language: ar
date: '2026-05-26'
category: frontend
tags:
  - tailwind css
  - tailwind v4
  - vite
  - css first config
  - dark mode
  - typescript
  - frontend
markdown_url: https://nerdleveltech.com/ar/tailwind-v4-vite-css-first-theme-config-tutorial.md
attribution: 'Source: NerdLevelTech — https://nerdleveltech.com/ar/tailwind-v4-vite-css-first-theme-config-tutorial'
terms: https://nerdleveltech.com/llms.txt
---

# 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[^node-lts]. يشحن محرك Oxide الخاص بـ Tailwind v4 ملفات ثنائية أصلية مدعومة بـ Rust تحتاج إلى Node حديث.
- **متصفح حديث للعرض التجريبي.** يستهدف Tailwind v4 متصفحات Safari 16.4+، و Chrome 111+، و Firefox 128+؛ المتصفحات الأقدم يجب أن تظل على Tailwind 3.4[^compat].
- مجلد مؤقت يمكنك حذفه. كل شيء أدناه يعيش في مجلد مشروع واحد.

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

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

```bash
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[^create-vite]. ينشئ قالب `vanilla-ts` ملفات `index.html` و `src/main.ts` و `src/style.css` و `src/counter.ts`، ومجلد `src/assets/` مع شعارات Vite + TypeScript، وملف `tsconfig.json`، وملف `package.json` بسيط.

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

```bash
npm run dev
```

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

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

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

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

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

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

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

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

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

```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-peer]، لذا فإن أي شيء على خط Vite 5+ الحديث مدعوم.

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

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

```css
@import "tailwindcss";
```

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

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

```ts
import "./style.css";
```

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

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

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

```css
@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].
- **يجب أن يكون `@theme` في المستوى الأعلى.** تتطلب وثائق Tailwind تعريف متغيرات السمة في المستوى الأعلى — وليس متداخلة تحت محددات (selectors) أو استعلامات وسائط[^theme]. كتل `@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-inline]. قارن المخرجات:

```css
/* @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 أخرى، حيث تحتاج إلى القيمة النهائية مدمجة في الأداة بدلاً من مرجع غير مباشر[^theme-inline].

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

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

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

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

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

```css
.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) بدلاً من الفئة، فاستبدل المتغير بـ:

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

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

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

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

```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) بـ:

```html
<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()`[^functions].

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

```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`:

```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-*)`) تحل اللاحقة مقابل مساحة أسماء السمة[^functions].

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

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

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

1. **`@source inline("...")`** — إجبار اسم فئة حرفي (أو مجموعة موسعة بين أقواس) على الدخول في الحزمة:
   ```css
   @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 تجاهلها:
   ```css
   @source not "../legacy/**";
   ```
   يمكنك أيضاً نفي أسماء الفئات المضمنة باستخدام `@source not inline("...")` لمنع الأدوات التي كان سيتم توليدها لولا ذلك[^source].

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

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

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

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

```css
/* 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 العالمي الخاص بك[^compat].

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

## التحقق

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

```bash
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[^compat].

**يتم تجميع 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}");` (أو أسماء الفئات المحددة التي تحسبها في وقت التشغيل) بحيث يتم توليدها حتى لو لم يتمكن الفاحص الثابت من رؤيتها[^source].

**`@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` لمراجعة كل تغيير قبل الاعتماد[^upgrade].

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

- اجمع بين هذا الإعداد وطبقة نماذج مكتوبة (typed form layer): راجع [البرنامج التعليمي لنماذج Astro Actions الآمنة من حيث النوع](https://nerdleveltech.com/astro-actions-type-safe-forms-tutorial) لنمط نموذج تم التحقق منه بواسطة Zod والذي يندمج مباشرة في مشروع Tailwind v4.
- قم بتوصيل Tailwind v4 في قاعدة أكواد Next.js 16 تستخدم بالفعل App Router و React 19 Server Actions — راجع [Next.js 16 Server Actions و React 19 Optimistic UI](https://nerdleveltech.com/nextjs-16-server-actions-react-19-optimistic-ui-tutorial). إعداد Tailwind متطابق (تكوين CSS أولاً)، لكن Next.js يوجه حاليًا من خلال `@tailwindcss/postcss` بدلاً من إضافة Vite.
- اقرأ [منشور إصدار Tailwind v4 الرسمي](https://tailwindcss.com/blog/tailwindcss-v4) للحصول على القائمة الكاملة للتغييرات المعمارية؛ تغطي ملاحظات إصدار 4.3 أحدث أدوات شريط التمرير المساعدة وإضافات الخصائص المنطقية الجديدة[^v4-3].

## المراجع

[^node-lts]: جدول 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`.

[^compat]: وثيقة توافق Tailwind CSS، <https://tailwindcss.com/docs/compatibility> — يحتاج إطار العمل الأساسي إلى Safari 16.4، Chrome 111، Firefox 128. يحدد أيضًا قاعدة `@reference` للأنماط المحدودة.

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

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

[^postcss-pkg]: تثبيت Tailwind CSS مع PostCSS، <https://tailwindcss.com/docs/installation/using-postcss> — متى تختار `@tailwindcss/postcss` مقابل `@tailwindcss/vite`.

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

[^functions]: دوال وتوجيهات Tailwind CSS، <https://tailwindcss.com/docs/functions-and-directives> — تغطي `@import "tailwindcss"`، و `@theme`، و `@utility`، و `@apply`، و `--value()`، و `@custom-variant`، والبقية.

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

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

[^theme-inline]: مناقشة GitHub رقم 18560، <https://GitHub.com/tailwindlabs/tailwindcss/discussions/18560> — الفرق في المخرجات بين `@theme` و `@theme inline`.

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

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