Tailwind CSS v4: الدليل الشامل للإعداد عبر CSS أولاً، والترحيل، والميزات الجديدة

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
 
export default defineConfig({
  plugins: [react(), tailwindcss()],
});

/* src/index.css */
@import "tailwindcss";

npx create-next-app@latest my-app
cd my-app
npm install tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

/* app/globals.css */
@import "tailwindcss";

/* app/globals.css */
@import "tailwindcss";
 
@theme {
  /* الألوان — تُولّد bg-brand، text-brand، border-brand، إلخ. */
  --color-brand: #3b82f6;
  --color-brand-light: #93c5fd;
  --color-brand-dark: #1e40af;
 
  /* الخطوط — تُولّد font-display، font-body */
  --font-display: "Cal Sans", "Inter", sans-serif;
  --font-body: "Inter", ui-sans-serif, system-ui, sans-serif;
 
  /* المسافات — تُولّد p-18، m-18، gap-18، إلخ. */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
 
  /* نقاط التوقف — تُولّد 3xl: متغير متجاوب */
  --breakpoint-3xl: 1920px;
 
  /* الظلال — تُولّد shadow-soft */
  --shadow-soft: 0 2px 15px -3px rgb(0 0 0 / 0.07);
 
  /* نصف قطر الحدود — تُولّد rounded-pill */
  --radius-pill: 9999px;
 
  /* الرسوم المتحركة — تُولّد animate-fade-in */
  --animate-fade-in: fade-in 0.5s ease-out;
 
  /* التسهيل — تُولّد ease-spring */
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
}
 
@keyframes fade-in {
  from { opacity: 0; transform: translateY(-8px); }
  to { opacity: 1; transform: translateY(0); }
}

<h1 class="font-display text-brand text-4xl">Welcome</h1>
<p class="font-body text-gray-600">Body text here</p>
<div class="p-18 shadow-soft rounded-pill">Custom spacing and shadow</div>
<button class="animate-fade-in transition-all ease-spring">Smooth</button>

@theme {
  /* إزالة جميع الألوان الافتراضية، الاحتفاظ بألوانك فقط */
  --color-*: initial;
  --color-primary: oklch(0.6 0.2 260);
  --color-secondary: oklch(0.7 0.15 180);
  --color-neutral-50: #fafafa;
  --color-neutral-100: #f5f5f5;
  --color-neutral-900: #171717;
}

@theme inline {
  --color-primary: #3b82f6;
}

.custom-card {
  background: var(--color-brand);
  font-family: var(--font-display);
  padding: var(--spacing-6);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-soft);
}

<!-- تحديد عنصر كحاوية -->
<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4 gap-4">
    <div class="p-4 bg-white rounded-lg shadow-sm">بطاقة 1</div>
    <div class="p-4 bg-white rounded-lg shadow-sm">بطاقة 2</div>
    <div class="p-4 bg-white rounded-lg shadow-sm">بطاقة 3</div>
    <div class="p-4 bg-white rounded-lg shadow-sm">بطاقة 4</div>
  </div>
</div>

<div class="@container/sidebar">
  <nav class="@md/sidebar:flex-col @md/sidebar:gap-4 flex gap-2">
    <!-- يستجيب لحاوية sidebar -->
  </nav>
</div>

<div class="@container">
  <div class="@max-sm:flex-col flex gap-4">
    <!-- يتراص عموديًا عندما تكون الحاوية ضيقة -->
  </div>
</div>

<!-- تأثير قلب البطاقة -->
<div class="group perspective-800">
  <div class="relative transition-transform duration-500 group-hover:rotate-y-180"
       style="transform-style: preserve-3d;">
    <div class="absolute inset-0 backface-hidden bg-blue-500 rounded-xl p-6">
      <p class="text-white">وجه البطاقة الأمامي</p>
    </div>
    <div class="absolute inset-0 backface-hidden rotate-y-180 bg-purple-500 rounded-xl p-6">
      <p class="text-white">وجه البطاقة الخلفي</p>
    </div>
  </div>
</div>
 
<!-- ميل ثلاثي الأبعاد دقيق -->
<div class="hover:rotate-x-2 hover:rotate-y-3 transition-transform duration-300">
  بطاقة تفاعلية مع ميل ثلاثي الأبعاد
</div>

<!-- تدرج شعاعي -->
<div class="bg-radial from-blue-500 to-purple-500 h-64 rounded-xl"></div>
 
<!-- تدرج مخروطي (عجلة ألوان) -->
<div class="bg-conic from-red-500 via-yellow-500 to-green-500 h-64 rounded-full"></div>
 
<!-- موضع التدرج -->
<div class="bg-radial-[at_top_left] from-pink-500 to-transparent h-64"></div>

/* صنف ثابت */
@utility content-auto {
  content-visibility: auto;
}
 
/* الآن يمكنك استخدام: content-auto، hover:content-auto، md:content-auto */

/* صنف حاوية مخصص (يستبدل إعداد container في v3) */
@utility container {
  margin-inline: auto;
  padding-inline: 2rem;
  max-width: 80rem;
}

/* صنف توازن النص */
@utility text-balance {
  text-wrap: balance;
}
 
/* صنف إخفاء شريط التمرير */
@utility scrollbar-none {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* الوضع الداكن القائم على الأصناف */
@custom-variant dark (&:where(.dark, .dark *));
 
/* متغيرات خصائص البيانات */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
 
/* متغيرات الحالة */
@custom-variant loading (&:where([data-loading="true"]));

<div class="bg-white dark:bg-gray-900 dark:text-white">
  دعم الوضع الداكن
</div>
 
<div class="theme-midnight:bg-indigo-950 theme-midnight:text-indigo-100">
  سمة مخصصة
</div>
 
<button class="loading:opacity-50 loading:pointer-events-none" data-loading="true">
  إرسال
</button>

<!-- خافت عند عدم التحويم -->
<div class="not-hover:opacity-60 transition-opacity">
  حوّم للكشف
</div>
 
<!-- هامش لجميع العناصر ما عدا الأخير -->
<ul>
  <li class="not-last:mb-4">العنصر 1</li>
  <li class="not-last:mb-4">العنصر 2</li>
  <li class="not-last:mb-4">العنصر 3</li>
</ul>

<div class="starting:opacity-0 starting:scale-95 transition-all duration-300">
  هذا العنصر يتلاشى ويتضخم عند ظهوره
</div>
 
<!-- حركة الحوار -->
<dialog class="starting:opacity-0 starting:translate-y-4 transition-all duration-200 backdrop:bg-black/50">
  <p>حوار متحرك بسلاسة</p>
</dialog>

<div class="inert:opacity-30 inert:pointer-events-none" inert>
  هذا القسم معطّل وخافت
</div>

<textarea class="field-sizing-content border rounded-lg p-3"
          placeholder="هذه المنطقة تنمو مع محتواك...">
</textarea>

<html class="scheme-dark">
  <!-- أشرطة تمرير داكنة أصلية، عناصر تحكم النماذج، إلخ. -->
</html>

npx @tailwindcss/upgrade

# إزالة الحزم القديمة
npm uninstall tailwindcss postcss autoprefixer @tailwindcss/container-queries
 
# للمشاريع القائمة على Vite
npm install tailwindcss @tailwindcss/vite
 
# لـ Next.js / المشاريع القائمة على PostCSS
npm install tailwindcss @tailwindcss/postcss

/* قبل (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
/* بعد (v4) */
@import "tailwindcss";

module.exports = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
        accent: "#8b5cf6",
      },
      fontFamily: {
        display: ["Satoshi", "sans-serif"],
      },
      borderRadius: {
        "4xl": "2rem",
      },
    },
  },
  plugins: [require("@tailwindcss/typography")],
};

@import "tailwindcss";
 
@plugin "@tailwindcss/typography";
 
@custom-variant dark (&:where(.dark, .dark *));
 
@theme {
  --color-brand: #3b82f6;
  --color-accent: #8b5cf6;
  --font-display: "Satoshi", sans-serif;
  --radius-4xl: 2rem;
}

<!-- v3 -->
<button class="focus:ring focus:ring-offset-2">
 
<!-- v4 — حدّد العرض واللون بوضوح -->
<button class="focus:ring-3 focus:ring-blue-500 focus:ring-offset-2">

<!-- نمط v3 -->
<div class="flex flex-col space-y-4">
 
<!-- موصى به في v4 -->
<div class="flex flex-col gap-4">

@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "./my-custom-plugin.js";

@source "../node_modules/@my-ui-lib/src/**/*.html";

@source inline("underline bg-red-500 text-white");

/* styles/globals.css */
@import "tailwindcss";
 
@custom-variant dark (&:where(.dark, .dark *));
 
@theme {
  /* ألوان العلامة التجارية باستخدام oklch للتوحيد الإدراكي */
  --color-primary-50: oklch(0.97 0.01 260);
  --color-primary-100: oklch(0.93 0.03 260);
  --color-primary-200: oklch(0.86 0.06 260);
  --color-primary-300: oklch(0.76 0.1 260);
  --color-primary-400: oklch(0.66 0.17 260);
  --color-primary-500: oklch(0.55 0.22 260);
  --color-primary-600: oklch(0.48 0.22 260);
  --color-primary-700: oklch(0.4 0.2 260);
  --color-primary-800: oklch(0.33 0.16 260);
  --color-primary-900: oklch(0.27 0.12 260);
 
  /* لوحة ألوان محايدة */
  --color-surface: #ffffff;
  --color-surface-raised: #f8fafc;
  --color-surface-overlay: #f1f5f9;
  --color-text: #0f172a;
  --color-text-muted: #64748b;
  --color-border: #e2e8f0;
 
  /* الطباعة */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-display: "Cal Sans", "Inter", sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
 
  /* الظلال للارتفاع */
  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.03);
  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.06), 0 1px 2px -1px rgb(0 0 0 / 0.06);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.07), 0 2px 4px -2px rgb(0 0 0 / 0.07);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.07), 0 4px 6px -4px rgb(0 0 0 / 0.07);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.08), 0 8px 10px -6px rgb(0 0 0 / 0.08);
 
  /* الحركة */
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
  --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
  --animate-fade-in: fade-in 0.4s var(--ease-smooth);
  --animate-slide-up: slide-up 0.3s var(--ease-spring);
  --animate-scale-in: scale-in 0.2s var(--ease-smooth);
}
 
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}
 
@keyframes slide-up {
  from { opacity: 0; transform: translateY(12px); }
  to { opacity: 1; transform: translateY(0); }
}
 
@keyframes scale-in {
  from { opacity: 0; transform: scale(0.95); }
  to { opacity: 1; transform: scale(1); }
}

/* أصناف مخصصة لنظام التصميم */
@utility text-balance {
  text-wrap: balance;
}
 
@utility scrollbar-none {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}
 
@utility glass {
  background: rgb(255 255 255 / 0.8);
  backdrop-filter: blur(12px) saturate(180%);
  border: 1px solid rgb(255 255 255 / 0.3);
}

<!-- شريط التنقل مع تأثير الزجاج -->
<nav class="glass fixed top-0 inset-x-0 z-50">
  <div class="mx-auto max-w-7xl px-6 flex items-center justify-between h-16">
    <span class="font-display text-xl text-text">MyApp</span>
    <div class="flex gap-6">
      <a href="#" class="text-text-muted hover:text-primary-500 transition-colors">الميزات</a>
      <a href="#" class="text-text-muted hover:text-primary-500 transition-colors">التسعير</a>
    </div>
  </div>
</nav>
 
<!-- قسم البطل -->
<section class="pt-32 pb-20 px-6">
  <div class="mx-auto max-w-3xl text-center animate-fade-in">
    <h1 class="font-display text-5xl text-text text-balance">
      ابنِ بشكل أسرع مع الأدوات المناسبة
    </h1>
    <p class="mt-6 text-lg text-text-muted text-balance">
      كل ما تحتاجه لإطلاق مشروعك القادم، بدون التعقيد.
    </p>
    <div class="mt-10 flex justify-center gap-4">
      <button class="bg-primary-500 hover:bg-primary-600 text-white px-6 py-3 rounded-lg
                     shadow-md hover:shadow-lg transition-all ease-smooth font-medium">
        ابدأ الآن
      </button>
      <button class="bg-surface-raised hover:bg-surface-overlay text-text px-6 py-3
                     rounded-lg border border-border transition-all ease-smooth font-medium">
        اعرف المزيد
      </button>
    </div>
  </div>
</section>
 
<!-- بطاقات الميزات مع استعلامات الحاوية -->
<section class="px-6 py-20">
  <div class="mx-auto max-w-6xl @container">
    <div class="grid grid-cols-1 @md:grid-cols-2 @xl:grid-cols-3 gap-6">
      <div class="bg-surface-raised border border-border rounded-xl p-6
                  hover:shadow-lg hover:-translate-y-1 transition-all ease-spring
                  animate-slide-up">
        <div class="w-10 h-10 bg-primary-100 text-primary-600 rounded-lg
                    flex items-center justify-center text-lg">
          ⚡
        </div>
        <h3 class="mt-4 font-display text-lg text-text">سرعة البرق</h3>
        <p class="mt-2 text-text-muted">
          مبني على محرك Rust لبناء فوري.
        </p>
      </div>
      <!-- المزيد من البطاقات... -->
    </div>
  </div>
</section>

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  يتبع تفضيل النظام تلقائيًا
</div>

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

// تبديل الوضع الداكن
document.documentElement.classList.toggle("dark");
 
// أو بناءً على تفضيل المستخدم مع localStorage
const theme = localStorage.getItem("theme") || "system";
if (theme === "dark" || (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches)) {
  document.documentElement.classList.add("dark");
}

<html class="dark scheme-dark">
  <!-- المتصفح يعرض أشرطة تمرير داكنة، مربعات اختيار، إلخ. -->
</html>

<div class="@container">
  <article class="flex @sm:flex-row flex-col gap-4">
    <img class="@sm:w-48 w-full rounded-lg object-cover" src="..." alt="..." />
    <div>
      <h2 class="font-display text-lg">عنوان المقال</h2>
      <p class="@sm:block hidden text-text-muted mt-2">
        وصف يظهر فقط في الحاويات الأوسع.
      </p>
    </div>
  </article>
</div>

@custom-variant theme-ocean (&:where([data-theme="ocean"] *));
@custom-variant theme-sunset (&:where([data-theme="sunset"] *));
@custom-variant theme-forest (&:where([data-theme="forest"] *));

<div data-theme="ocean">
  <div class="bg-white theme-ocean:bg-sky-50 theme-sunset:bg-orange-50 theme-forest:bg-green-50">
    هذا يتكيف مع السمة النشطة
  </div>
</div>

@source "../node_modules/@headlessui/react/dist/**/*.js";
@source "../node_modules/my-design-system/components/**/*.tsx";

@import "tailwindcss" prefix(tw);

// postcss.config.mjs — Tailwind يجب أن يكون الإضافة الوحيدة
export default {
  plugins: {
    "@tailwindcss/postcss": {},
    // احذف autoprefixer — Tailwind v4 يتعامل معه
    // احذف postcss-import — Tailwind v4 يتعامل معه
  },
};