Tailwind CSS on kenji.blog

تخصيص سمة Hugo: كيفية إدراج Tailwind CSS

Sun, 13 Sep 2026 03:00:00 +0900

مقدمة: التآزر القوي بين مولد المواقع الثابتة Hugo و Tailwind CSS

في تطوير الواجهات الأمامية للويب الحديث، يعد تحقيق التوازن بين الأداء وتجربة المطور (DX: Developer Experience) أحد أهم التحديات في كل مشروع. الجمع بين Hugo، الذي يتميز بسرعات بناء من بين الأسرع عالمياً في مولدات المواقع الثابتة (SSG)، و Tailwind CSS، الذي جلب نموذجاً مبتكراً يعطي الأولوية للخدمات (Utility-first)، يمكن اعتباره حلاً جذرياً لهذا التحدي.

تمت كتابة Hugo بلغة Go، ولديه أداء مذهل يتيح له إكمال بناء موقع يحتوي على آلاف الصفحات في ثوانٍ معدودة، أو حتى في أجزاء من الثانية. من ناحية أخرى، من خلال كتابة عدد لا يحصى من فئات الخدمات المعرفة مسبقًا (مثل flex, text-center, mt-4) مباشرة في HTML، يقضي Tailwind CSS على الحاجة للتبديل بين ملفات CSS و HTML، مما يسرع عملية تكرار التصميم.

في هذا المقال، سنشرح بالتفصيل الدقيق ومن وجهة نظر شاملة - بدءًا من أساسيات البنية المعمارية وصولاً إلى منظور التحسين الرياضي للأداء - خطوات إدراج Tailwind CSS في سمة Hugo، وبناء مسار موارد متقدم (Hugo Pipes) باستخدام PostCSS.

1. فئات الخدمات لـ CSS وتطور التوجه القائم على المكونات

قبل الدخول في خطوات إدراج Tailwind CSS، من المفيد جداً أن نفهم بعمق تاريخ وتطور فلسفة تصميم CSS التي تكمن وراء سبب وجوب استخدامنا لـ Tailwind CSS.

حدود تصميم CSS التقليدي (BEM و OOCSS)

في تطوير الويب سابقاً، كان من أفضل الممارسات إعطاء أسماء فئات ذات دلالات (Semantic). على سبيل المثال، عند إنشاء مكون بطاقة (Card)، كنا نفصل بين HTML و CSS كالتالي:

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">العنوان</h2>
 <p class="card__description">النص التوضيحي يكتب هنا.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* تستمر الأنماط التفصيلية لاحقاً */

مثل هذا التصميم القائم على BEM (Block Element Modifier) يعمل جيداً عندما يكون حجم المشروع صغيراً، ولكنه يميل إلى التسبب في المشاكل التالية:

استنفاد وإرهاق في التسمية: في كل مرة تنشئ فيها مكوناً مشابهاً، عليك التفكير في أسماء فئات جديدة (مثل: card-news، card-featured).
تضخم CSS: مع إضافة كل ميزة جديدة، يزداد عدد أسطر CSS. وبمجرد كتابة CSS، نادراً ما يتم حذفه بسبب الخوف من “عدم معرفة أين يتم استخدامه”، مما يؤدي إلى تراكم الأكواد الميتة.
تبديل السياق: نظرًا لأنه يتم إدارة بنية HTML وأنماط CSS في ملفات منفصلة، فإن عدد مرات التبديل بين علامات التبويب في المحرر يزداد بشكل كبير.

التحول النموذجي بواسطة Tailwind CSS

يحل Tailwind CSS هذه المشاكل من خلال نهج “دمج فئات الخدمات”. يبدو مكون البطاقة المذكور أعلاه كالتالي عند استخدام Tailwind CSS:

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">العنوان</h2>
 <p class="mt-2 text-gray-600">النص التوضيحي يكتب هنا.</p>
 </div>
</div>

نظراً لأن اسم الفئة نفسه يمثل القيمة الدقيقة للنمط (مثل p-6 تعني padding: 1.5rem;)، يمكنك التنبؤ بنتيجة العرض النهائية بمجرد النظر إلى HTML. علاوة على ذلك، من خلال مترجم JIT (Just-In-Time) الخاص بـ Tailwind، يتم استخراج الفئات المستخدمة بالفعل فقط إلى ملف CSS المخصص للإنتاج، مما يقلل حجم ملف CSS إلى أدنى حد ممكن.

2. بنية Hugo Pipes و PostCSS

لدمج Tailwind CSS في Hugo، تحتاج إلى فهم مسار معالجة الموارد الذي يُسمى Hugo Pipes. تعد Hugo Pipes ميزة قوية تنجز جميع العمليات المتعلقة بالموارد داخلياً في Hugo، مثل تجميع Sass/SCSS، وحزم ودمج (Minify) JavaScript، وتنفيذ PostCSS الذي سنستخدمه في هذا المقال.

PostCSS هي أداة لتحويل CSS باستخدام إضافات JavaScript. في الواقع، يعمل Tailwind CSS نفسه كإضافة لـ PostCSS.

آلية تحويل AST (شجرة بناء الجملة المجردة) عبر PostCSS

إن فهم كيفية معالجة PostCSS لملفات CSS مفيد للغاية عند استكشاف الأخطاء وإصلاحها. يوضح مخطط Mermaid التالي المسار من قراءة PostCSS لملف CSS، وتحويله عبر الإضافات، حتى إخراج ملف CSS النهائي.

flowchart TD
A["Raw CSS (styles.css)"] -->|Parser| B["AST (شجرة بناء الجملة المجردة)"]
B --> C["إضافة 1: Tailwind CSS"]
C --> D["إضافة 2: Autoprefixer"]
D --> E["إضافة N: cssnano"]
E -->|Stringifier| F["Compiled & Optimized CSS"]

Parser (المحلل): يقوم بتحليل سلسلة CSS الخام المدخلة ويحولها إلى شجرة بناء الجملة المجردة (AST)، وهي بنية بيانات يمكن معالجتها برمجيًا.
Plugins (مجموعة الإضافات):
- Tailwind CSS: يمسح ملفات القالب (HTML أو Markdown) ويستخرج فئات الخدمات المستخدمة كعقد إضافية على شجرة AST. كما أنه يوسع التوجيهات مثل @tailwind.
- Autoprefixer: يراجع قاعدة بيانات Can I Use ويضيف البادئات الخاصة بالمتصفحات (مثل -webkit-, -moz-) إلى خصائص AST عند الحاجة.
Stringifier (محول السلاسل): بعد اكتمال التحويل، يقوم بتحويل شجرة AST مرة أخرى إلى سلاسل CSS يمكن للمتصفح فهمها لإخراجها.

3. إعداد البيئة والمتطلبات الأساسية

دعونا نبدأ بخطوات الإدراج الفعلية. أولاً، تحقق مما إذا كانت البرامج الضرورية مثبتة.

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

Hugo Extended Version (النسخة الموسعة من Hugo): بدلاً من الإصدار العادي من Hugo، تعد النسخة الموسعة التي تتضمن وظيفة معالجة Sass/SCSS وميزات دعم PostCSS مدمجة ضرورية. قم بتشغيل الأمر التالي في الطرفية (Terminal) وتأكد من أن السلسلة extended متضمنة في معلومات الإصدار.
1 2 3

hugo version # مثال للإخراج المتوقع: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js و npm: تعمل حزم التبعيات مثل Tailwind CSS و PostCSS على بيئة Node.js. تأكد من تثبيت Node.js (يُفضل إصدار الدعم طويل الأمد LTS).
1 2

node -v npm -v

تثبيت حزم npm

قم بتهيئة npm في دليل الجذر للمشروع (الدليل الذي يحتوي على ملف إعداد Hugo hugo.toml)، وقم بتثبيت الحزم المطلوبة.

1
2
3
4
5


# إنشاء ملف package.json
npm init -y

# تثبيت Tailwind CSS، و PostCSS، و Autoprefixer كتبعيات تطوير
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] إذا لم يتم تثبيت postcss-cli، فقد تحدث أخطاء عند استدعاء PostCSS من داخل Hugo. تستخدم Hugo Pipes برنامج postcss-cli داخلياً، لذا تأكد من تثبيته.

4. بناء ملفات التكوين (PostCSS و Tailwind CSS)

بعد اكتمال تثبيت الحزم، سننشئ ملفي تكوين مهمين يتحكمان في سلوك المشروع. ضعهما في دليل الجذر للمشروع.

إنشاء ملف tailwind.config.js

قم بتنفيذ الأمر التالي في الطرفية لإنشاء ملف التكوين الافتراضي.

1

npx tailwindcss init

افتح ملف tailwind.config.js الذي تم إنشاؤه في المحرر، وقم بإعداد خاصية content. هذا الجزء مهم جداً. بناءً على المسارات المحددة هنا، يقوم Tailwind بتحليل الملفات واستخراج الفئات المستخدمة. وفقاً لهيكلية مشروع Hugo، حدد ملفات التخطيط والمحتوى بدقة.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // تحديد الملفات المراد مسحها وفقًا لهيكل دليل Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // إذا كنت تستخدم سمة مخصصة، يجب تضمين دليل السمة أيضًا
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // قم بإضافة الألوان والخطوط المخصصة هنا
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // أضف الإضافات الرسمية حسب الحاجة (مثل: Typography plugin)
 // require('@tailwindcss/typography'),
 ],
}

إنشاء ملف postcss.config.js

بعد ذلك، قم بإنشاء ملف postcss.config.js في جذر المشروع لتعريف أي الإضافات سينفذها PostCSS وبأي ترتيب.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

باستخدام هذا الإعداد، عندما يقوم Hugo باستدعاء PostCSS، ستتم معالجة Tailwind CSS أولاً، تليها إضافة Autoprefixer للبادئات الخاصة بالمتصفحات.

5. بناء مسار موارد CSS في Hugo

بعد إتمام الإعدادات، سنقوم بدمج Tailwind CSS في جانب سمة Hugo.

5-1. إنشاء ملف CSS كنقطة إدخال

في الدليل assets/css/ (قم بإنشائه إن لم يكن موجوداً)، قم بإنشاء ملف CSS ليكون نقطة الإدخال. هنا سنسميه main.css.

مسار الملف: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* استيراد الأنماط الأساسية لـ Tailwind (مثل إعادة تعيين CSS) */
@tailwind base;

/* استيراد فئات المكونات */
@tailwind components;

/* استيراد فئات الخدمات */
@tailwind utilities;

/* إذا كنت بحاجة إلى كتابة CSS مخصص، يمكنك إضافته هنا،
 ولكن يفضل استخدام extend في tailwind.config.js قدر الإمكان */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. تعديل ملف التخطيط (head.html)

بعد ذلك، ستقوم بقراءة ملف CSS أعلاه من قوالب Hugo، وكتابة المسار لمعالجته بواسطة PostCSS. عادةً يتم تعديل القالب الجزئي الذي يُعرّف داخل الوسم <head> (مثل: layouts/partials/head.html).

مسار الملف: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- جلب assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- تعريف خيارات PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- مسار تحسين الموارد لبيئة الإنتاج (Production) -->
 {{ if hugo.IsProduction }}
 <!-- 1. الضغط (Minify) -->
 {{ $css = $css | minify }}
 <!-- 2. البصمة (إضافة تجزئة لكسر ذاكرة التخزين المؤقت - Fingerprint) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. إخراج الوسم مع تكامل الموارد الفرعية (SRI) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- في بيئة التطوير (Development)، أخرجه كما هو بدون ضغط (لأولوية سرعة البناء) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

شرح المسار ورسمه التوضيحي باستخدام Mermaid

يوضح الرسم التالي كيف يقوم كود قوالب Go المذكور أعلاه بمعالجة ملف CSS في سلسلة من عمليات المسار.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo Memory Space"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT Process"]
C --> D{"hugo.IsProduction ?"}
D -- "نعم (بيئة الإنتاج)" --> E["minify (حذف المسافات والأسطر الفارغة)"]
E --> F["fingerprint (حساب التجزئة)"]
F --> G["public/css/main.[hash].css (مع SRI)"]
D -- "لا (بيئة التطوير)" --> H["public/css/main.css"]

resources.Get: يبحث عن الملف المحدد داخل دليل assets، ويقوم بتحميله ككائن موارد في الذاكرة.
resources.PostCSS: يشير إلى ملف postcss.config.js في جذر المشروع ويُطبق عمليات Tailwind CSS و Autoprefixer على الكود المصدري لـ CSS. في بيئة التطوير (hugo server)، يعمل وضع JIT، الذي يقوم بإنشاء الفئات الضرورية بسرعة فائقة فقط عند تعديل الملفات.
minify: عند بناء نسخة بيئة الإنتاج (مثلاً عبر hugo --environment production)، يتم حذف المسافات والتعليقات غير الضرورية، وتقليل حجم الملف إلى أدنى حد ممكن.
fingerprint: يقوم بحساب تجزئة SHA بناءً على محتوى الملف ويضيفها إلى اسم الملف (مثل: main.ab12cd...css). هذا يحقق “كسر ذاكرة التخزين المؤقت” حيث يتم التأكد من أن المتصفح يحمل ملفاً جديداً عند تحديث CSS، مع الاستفادة من ميزة التخزين المؤقت القوية للمتصفح.
integrity: يستخدم قيمة التجزئة المحسوبة عبر البصمة لإخراج خاصية SRI لمنع التلاعب من قبل شبكات توصيل المحتوى (CDN) وغيرها.

6. التحليل الرياضي للأداء في تحسين CSS

تعتبر إحدى أكبر ميزات إدراج Tailwind CSS هي تقليل حجم ملف CSS المرسل إلى أدنى حد. دعونا نحلل كمياً كيف يؤثر ذلك على أداء الويب (وخاصة على First Contentful Paint: FCP) باستخدام نماذج رياضية.

نموذج تقليل حجم ملف CSS

في أطر عمل CSS التقليدية (مثل Bootstrap)، يميل حجم الملف $S_{original}$ إلى أن يكون كبيراً (حوالي 150 كيلوبايت - 200 كيلوبايت) لأنه يتم تحميل جميع الأنماط، بما في ذلك تلك غير المستخدمة. إذا رمزنا لحجم الملف بعد إزالة الفئات غير المستخدمة بواسطة مترجم JIT الخاص بـ Tailwind كـ $S_{purged}$، وباستخدام نسبة التقليل $R_{purge}$، يمكن التعبير عنها كما يلي:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

في المشاريع النموذجية، تصل نسبة $R_{purge}$ إلى ما يقرب من $0.9$ (تخفيض بنسبة 90%)، وينحصر حجم $S_{purged}$ في حوالي 10 كيلوبايت - 20 كيلوبايت فقط.

بالإضافة إلى ذلك، يتم ضغط الملف عبر Brotli أو Gzip على جانب الخادم أثناء النقل. إذا كانت نسبة الضغط $R_{compress}$ (عادة ما تكون حوالي 0.7 إلى 0.8)، يتم حساب حجم الحمولة النهائية عبر الشبكة $S_{final}$ باستخدام المعادلة التالية:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

مسار العرض الحرج وتأخير الشبكة

يمكن تقريب الوقت المستغرق حتى يرسم المتصفح المحتوى الأولي على الشاشة (FCP) عن طريق مجموع وقت تنزيل HTML، ووقت تنزيل CSS، ووقت العرض.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

حيث أن:

$RTT$: زمن الرحلة ذهاباً وإياباً (وقت تأخير الاتصال بالخادم)
$BW$: عرض النطاق الترددي للشبكة (Bandwidth)

في بيئات مثل شبكات الهاتف المحمول حيث يكون $BW$ ضيقًا و $RTT$ كبيرًا (تأخير كبير)، فإن نهج Tailwind CSS في تقليل $S_{final}$ إلى بضعة كيلوبايتات يؤدي إلى دفع قيمة $\frac{S_{final}}{BW}$ قريباً من الصفر، مما يصبح محركاً أساسياً لتحقيق درجات مذهلة في أدوات الأداء (مثل Google PageSpeed Insights).

7. تشغيل خادم التطوير والتحقق من التحديث التلقائي (Hot Reload)

بعد اكتمال جميع الإعدادات، قم بتشغيل خادم التطوير الخاص بـ Hugo وتأكد من أن Tailwind CSS يعمل بشكل صحيح.

1

hugo server -D

انتقل إلى http://localhost:1313/ عبر المتصفح وتحقق من عرض الموقع. افتح ملف محتوى Markdown أو أحد قوالب Hugo (الملفات الموجودة تحت layouts/)، وحاول إضافة فئات جديدة.

1
2
3
4
5


<!-- مثال تطبيقي لفئات Tailwind بغرض الاختبار -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">يرجى التأكد من أن التحديث التلقائي ينعكس في لمح البصر.</p>
</div>

بمجرد حفظ الملف، ستختبر المتعة حيث يعمل متتبع الملفات القوي في Hugo بالتعاون مع مترجم JIT في Tailwind معاً لإعادة بناء CSS في أجزاء من الثانية، مما يؤدي إلى إعادة تحميل المتصفح تلقائياً (التحديث التلقائي - Hot Reload).

استكشاف الأخطاء وإصلاحها: ماذا لو لم تنعكس الأنماط؟

إذا لم تنعكس التغييرات، فتحقق من النقاط التالية:

إعداد مسار content في tailwind.config.js إذا كانت مسارات الملفات المستهدفة خاطئة، فلن يتمكن Tailwind من اكتشاف الفئات المستخدمة داخلها ولن يضيفها إلى CSS. إذا كنت تستخدم سمة مخصصة خاصة، فتأكد من أن مسار دليل السمة لم يتم إسقاطه.
أخطاء PostCSS إذا رأيت خطأً في سجلات خادم Hugo في الطرفية مثل Error: failed to transform resource: PostCSS not found، فقد يعني ذلك أن الأمر npm install لم ينفذ بشكل صحيح، أو أن postcss-cli مفقود.
مسح ذاكرة التخزين المؤقت لـ Hugo في حالات نادرة، قد يتسبب التخزين المؤقت في Hugo في الإبقاء على كود CSS القديم. أوقف الخادم وابدأه باستخدام الأمر hugo server --ignoreCache، أو حاول حذف الدليل المؤقت في نظام التشغيل (مثل /tmp/hugo_cache/).

8. البناء لبيئة الإنتاج ومزيد من التحسينات

عند نشر موقعك على خادم الإنتاج (مثل Netlify، Vercel، GitHub Pages، Cloudflare Pages، إلخ)، يجب عليك تعيين متغيرات البيئة وتشغيل مسار التحسين الخاص ببيئة الإنتاج.

1
2


# مثال لأمر البناء للإنتاج
NODE_ENV=production hugo --minify --environment production

عن طريق إضافة علم --environment production، يتم تنفيذ كتلة {{ if hugo.IsProduction }} داخل ملف head.html، وتطبيق تصغير لحجم CSS (Minify) وإضافة البصمة (Fingerprint).

تنسيق Markdown باستخدام إضافة Typography

في المواقع المبنية على المدونات أو الوثائق مثل Hugo، لا يمكنك إضافة فئات مباشرة إلى عناصر HTML النقية التي يتم إنشاؤها من Markdown (مثل <h1>، <p>، <ul> وما إلى ذلك). في مثل هذه الحالات، من المفيد جدًا استخدام إضافة Typography الرسمية من Tailwind.

تثبيت الإضافة

1

npm install -D @tailwindcss/typography

إضافتها إلى tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

تطبيقها في القوالب من خلال إضافة فئة prose (ويمكنك إضافة تغيرات الحجم واللون حسب الرغبة) فقط إلى حاوية العنصر الذي يخرج محتوى المقالة، سيتم تطبيق أنماط افتراضية جميلة.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

بفضل ذلك، لم تعد هناك أي حاجة لكتابة محددات CSS معقدة يدويًا (مثل .article-content h2 { ... })، مما يضمن الحفاظ التام على نموذجية المكونات.

9. الخلاصة: اكتمال نظام واجهة أمامية عالي القابلية للصيانة

أحسنت العمل! مع هذا، اكتمل لديك مسار موارد الويب المثالي الذي يجمع بين محرك توليد المواقع الثابتة فائق السرعة لـ Hugo، وقدرات التنسيق الحديثة لـ Tailwind CSS، وقابلية التوسع لـ PostCSS.

الشيء الرائع في هذه البنية هو أنك “تحتاج إلى ضبط الإعدادات مرة واحدة فقط في البداية”. بمجرد بناء المسار، يمكن للمطورين البدء في تجميع واجهات المستخدم المعقدة بسرعة مذهلة وببساطة عبر كتابة فئات الخدمات البديهية في قوالب HTML أو Markdown، دون الحاجة لفتح ملف CSS.

علاوة على ذلك، نظراً لأن حجم CSS الناتج يكون دائماً في حده الأدنى، فإن ذلك ينعكس بشكل مباشر على تحسين درجات Core Web Vitals، مما يمنحك ميزة كبيرة من منظور تحسين محركات البحث (SEO).

يظل الجمع بين Hugo و Tailwind CSS أحد “أفضل الخيارات” لأي مشروع، من المدونات التقنية الشخصية إلى مواقع الشركات الضخمة. تأكد من الاستفادة من سلسلة الأدوات القوية هذه واستمتع بتجربة تطوير ويب مريحة!

نقاط تصميم CSS لدعم الوضع الداكن في المدونات

Sat, 12 Sep 2026 12:00:00 +0900

في تطوير الويب الحديث، تحول دعم الوضع الداكن (Dark Mode) من مجرد “ميزة إضافية جيدة” (Nice to have) إلى “متطلب أساسي” (Must have) لتحسين تجربة المستخدم (UX). خاصة في الوسائط التي تفترض قراءة النصوص لفترات طويلة مثل المدونات ومواقع الوثائق، حيث يقلل من إجهاد عين المستخدم ويحافظ على استهلاك بطارية الجهاز، لذا فإن أهمية دعم الوضع الداكن عالية جدًا.

في هذه المقالة، سنشرح بتعمق شديد من منظور مهندس الواجهة الأمامية التحديات التقنية التي لا مفر منها لدعم الوضع الداكن في المدونات، ونقاط تصميم CSS ذات القابلية العالية للصيانة. سنغطي كل شيء بدءًا من استخدام المتغيرات المخصصة (CSS Custom Properties)، والتحكم المتقدم عبر JavaScript والتكامل مع SSR لمنع FOUC (Flash of Unstyled Content)، وتصميم الألوان لضمان إمكانية الوصول (WCAG 2.1 AAA) (بما في ذلك RGB و HSL وأحدث OKLCH)، وحتى أمثلة عملية للأكواد باستخدام Tailwind CSS.

1. أساسيات تصميم السمات باستخدام متغيرات CSS (CSS Custom Properties)

النهج الأكثر قياسية وقوة حاليًا لتنفيذ الوضع الداكن هو استخدام متغيرات CSS المخصصة (CSS Custom Properties). على عكس متغيرات معالجات CSS مثل Sass (مثلاً $color) التي يتم حلها بشكل ثابت أثناء الترجمة (compile)، يتم حل متغيرات CSS والكتابة فوقها ديناميكيًا في وقت التشغيل (runtime) للمتصفح. يتيح ذلك تغيير ألوان الصفحة بالكامل فورًا بمجرد تبديل الفئة (class) عبر JavaScript.

1.1 تعريف سمة الألوان الأساسية

أولاً، نستخدم الفئة الزائفة :root لتعريف لوحة ألوان الوضع الفاتح (الافتراضي). ثم النمط التصميمي الشائع هو الكتابة فوق تلك المتغيرات عند إضافة سمة مثل [data-theme='dark'] (أو فئة .dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* تعريف متغيرات الوضع الفاتح (الافتراضي) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* الكتابة فوق المتغيرات في الوضع الداكن */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* التطبيق الفعلي */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

بهذه الطريقة، من خلال الفصل التام بين التخطيط والطباعة من جهة وتحديد الألوان (السمة) من جهة أخرى، تتحسن قابلية صيانة CSS بشكل كبير.

1.2 الاستفادة من @media (prefers-color-scheme: dark)

إذا تم تعيين الوضع الداكن على مستوى نظام التشغيل، فمن المستحسن من منظور تجربة المستخدم تطبيق السمة الداكنة تلقائيًا منذ الزيارة الأولى للموقع. الاستعلام الإعلامي (media query) @media (prefers-color-scheme: dark) يحقق ذلك.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* حل بديل عندما يكون إعداد بيئة نظام التشغيل هو الوضع الداكن */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

في هذا التدوين، طالما أن المستخدم لم يختر الوضع الفاتح صراحةً (data-theme='light')، فسيتم احترام إعداد الوضع الداكن لنظام التشغيل والكتابة فوق المتغيرات.

2. فهم مساحات الألوان وإمكانية الوصول (WCAG 2.1 AAA)

في تصميم ألوان الوضع الداكن، لا يكفي مجرد “جعل الخلفية سوداء والنص أبيض”. إذا كان التباين قويًا جدًا، فسيؤدي ذلك إلى توهج (halation) ويجعل القراءة أصعب، وإذا كان منخفضًا جدًا، فستتأثر الرؤية. تحدد إرشادات إمكانية الوصول لمحتوى الويب (WCAG) بدقة نسبة التباين المطلوبة لضمان الرؤية الواضحة.

2.1 معادلة حساب نسبة التباين في WCAG

تُعرف نسبة التباين (Contrast Ratio) $CR$ في WCAG باستخدام الإضاءة النسبية (Relative Luminance) للون الخلفية ولون المقدمة على النحو التالي:

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

حيث أن $L_{lighter}$ هو الإضاءة النسبية للون الأفتح، و $L_{darker}$ هو الإضاءة النسبية للون الأغمق (نطاق القيم من 0.0 إلى 1.0). لتحقيق مستوى AAA في WCAG 2.1، يلزم نسبة تباين تبلغ 7:1 أو أكثر للنصوص العادية، و 4.5:1 أو أكثر للنصوص الكبيرة.

تُحسب الإضاءة النسبية $L$ من قيم RGB في مساحة ألوان sRGB باستخدام المعادلة المعقدة التالية:

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

كل مكون ($R, G, B$) يستخدم القيمة المُطبعة (normalized value) عن طريق قسمة القيمة الأصلية ذات الـ 8 بت ($R_{sRGB}$) على 255، ويقوم بالتحويل التالي لفك تصحيح جاما:

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

من الصعب إجراء هذه الحسابات يدويًا، ولكن باستخدام أدوات تصميم الألوان، يمكنك تلقائيًا تحديد الألوان التي تلبي نسبة تباين 7:1 ($CR \ge 7.0$).

2.2 HSL مقابل RGB مقابل OKLCH

عند إنشاء لوحات الألوان، كانت RGB و HSL هي السائدة في الماضي. ولكن هذه النماذج بها عيوب كبيرة فيما يتعلق بـ “التوحيد الإدراكي” (perceptual uniformity).

RGB: هي ألوان الضوء الأساسية الآلية، ومن الصعب على البشر إجراء تعديلات بديهية مثل “جعله أفتح” أو “جعله أغمق”.
HSL: تستخدم تدرج اللون (Hue)، والتشبع (Saturation)، والإضاءة (Lightness)، لكن “الإضاءة (L)” في HSL لا تتطابق مع السطوع الإدراكي للعين البشرية. على سبيل المثال، الأصفر النقي والأزرق النقي بإضاءة 50% في HSL لهما نفس السطوع عدديًا، ولكن الأصفر يبدو أكثر سطوعًا للعين البشرية بشكل هائل.
OKLCH: هي أحدث مساحة ألوان تم تقديمها في CSS Color Module Level 4. وتتكون من الإضاءة الإدراكية (Lightness)، والتشبع (Chroma)، وتدرج اللون (Hue)، وهي تتطابق تمامًا مع الخصائص البصرية البشرية (موحدة إدراكيًا).

باستخدام OKLCH، يمكنك الحفاظ على نفس الإضاءة الإدراكية (Lightness) حتى لو قمت بتغيير تدرج اللون (Hue)، مما يجعل إنشاء لوحات ألوان الوضع الداكن قابلة للتنبؤ وآمنة للغاية.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* مثال على تعريف متغيرات CSS باستخدام OKLCH */
:root {
 /* في الوضع الفاتح، تكون الإضاءة الأساسية عالية والتشبع منخفض */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* في الوضع الداكن، بمجرد عكس الإضاءة يسهل الحفاظ على التباين الإدراكي */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* جعله أفتح قليلاً للوضع الداكن لضمان الرؤية */
}

من خلال تبني OKLCH بهذه الطريقة، يمكنك ببساطة بناء منطق يضمن نسبة تباين متسقة (بمستوى WCAG AAA) عبر سمات متعددة.

3. منع FOUC (وميض المحتوى غير المنسق) و SSR Hydration

المشكلة الأكبر التي تزعج المطورين عند دعم الوضع الداكن هي مشكلة وميض الشاشة المعروفة باسم FOUC (Flash of Unstyled Content).

3.1 فخ تبديل السمات عبر Client-Side JS

في SPA مثل React أو Vue (أو المواقع الثابتة عبر SSG)، من الشائع حفظ إعدادات المستخدم في localStorage وقراءتها بواسطة JavaScript لتبديل السمة. ومع ذلك، إذا تم هذا الإجراء في useEffect في React، فستحدث المشكلات التالية:

يقوم المتصفح بعرض HTML/CSS في الوضع الفاتح.
يتم تحميل حزمة JS وتنفيذها.
يقرأ إعداد dark من localStorage.
تتم إضافة فئة dark إلى HTML، وتصبح الشاشة داكنة فجأة (وميض).

3.2 الحل المثالي لمنع FOUC: استخدام ملفات تعريف الارتباط (Cookies) و SSR

أفضل ممارسة لمنع FOUC تمامًا ومنع أخطاء الـ hydration هي حفظ إعدادات سمة المستخدم في document.cookie، وإرجاع HTML مع الفئة المناسبة المُضافة بالفعل أثناء مرحلة العرض من جانب الخادم (SSR).

يوضح مخطط التسلسل التالي التدفق المثالي لتهيئة السمة باستخدام ملفات تعريف الارتباط.

sequenceDiagram
participant User as "المستخدم"
participant Browser as "متصفح نظام التشغيل"
participant Server as "خادم SSR"
participant DOM as "عميل DOM"
User->>Browser: "طلب الصفحة"
Browser->>Server: "طلب GET مع ملف تعريف الارتباط (theme=dark)"
Server-->>Browser: "إرجاع HTML مع <html data-theme='dark'>"
Browser->>DOM: "عرض HTML الأولي (بدون FOUC)"
DOM->>DOM: "تنفيذ نص الـ Hydration"
alt "لا يوجد ملف تعريف ارتباط (الزيارة الأولى)"
DOM->>Browser: "التحقق من prefers-color-scheme لنظام التشغيل"
Browser-->>DOM: "نتيجة matchMedia (مثلاً dark)"
DOM->>DOM: "تعيين data-theme='dark' عبر نص برمجي حاجز مضمن"
end

3.3 خط الدفاع عبر النصوص البرمجية المضمنة (للمواقع الثابتة التي لا تستخدم Cookies)

في حالة المدونات التي تستخدم SSG (توليد المواقع الثابتة) فقط حيث يكون SSR غير ممكن (مثل Hugo أو Gatsby أو التصدير الثابت لـ Astro)، من الضروري وضع نص JavaScript مضمن يُنفذ بشكل يحظر العرض (blocking) داخل وسم <head> لإضافة الفئة قبل رسم DOM مباشرةً.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- يوضع في نهاية <head> -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

هذا النص الصغير يحظر عرض المتصفح ويُنفذ على الفور، لذلك بحلول وقت رسم الشاشة، تكون سمة data-theme قد تم تعيينها بالفعل، مما يمنع وميض الشاشة (FOUC) بشكل كامل.

4. أساليب التنفيذ باستخدام Tailwind CSS و Raw SCSS/CSS

عند دمج الوضع الداكن في مشاريع فعلية، يجب فهم أسلوب كل أداة.

4.1 الوضع الداكن في Tailwind CSS

يوفر Tailwind CSS بشكل افتراضي متغير dark:، مما يجعل تنفيذ الوضع الداكن أمرًا سهلاً للغاية. يمكنك تعيين خاصية darkMode في ملف الإعدادات (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (يعتمد على إعداد نظام التشغيل) أو 'class' (يمكن تبديله يدويًا)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* توسيع لوحة ألوان Tailwind باستخدام متغيرات CSS */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

في جانب HTML، ما عليك سوى إضافة الفئات كما يلي.

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">مرحبا بالعالم</h1>
 <p class="mt-2">يجعل Tailwind الوضع الداكن سهلاً بشكل لا يصدق.</p>
</div>

ومع ذلك، كتابة dark:bg-xxx على كل عنصر يمكن أن يتسبب في تضخم المكونات. بالنسبة للمدونات والتطبيقات واسعة النطاق، يُوصى بتصميم هجين (تصميم الألوان الدلالية) يعتمد على متغيرات CSS، ويشير Tailwind إلى تلك المتغيرات.

فيما يلي مخطط فئة يوضح وراثة متغيرات CSS وطبقة التطبيق.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "تطبيق فئات المنفعة"

4.2 التنفيذ باستخدام Raw SCSS/CSS (الاستفادة من Mixin)

في المشاريع التي لا تستخدم Tailwind وتكتب SCSS بشكل مخصص، نستخدم @mixin لتغليف أنماط الوضع الداكن.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* تعريف SCSS Mixin */
@mixin dark-mode {
 /* يدعم كلاً من سمة [data-theme='dark'] أو إعدادات نظام التشغيل */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* مثال الاستخدام */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

هذه الطريقة بديهية، ولكن نظرًا لأن حجم ملف CSS النهائي يميل إلى التضخم (يتم تكرار media query لكل محدد)، فإن الاتجاه الحالي هو الانتقال إلى تصميم يتمحور حول متغيرات CSS (Custom Properties).

5. تحسين الوضع الداكن للصور (Image) و SVG

حتى لو اكتمل تصميم ألوان النصوص والخلفية، إذا ظلت الصور والأيقونات (SVG) الموضوعة كمحتوى في وضعها الفاتح، فستبدو ساطعة للغاية وبارزة بشكل مزعج في الوضع الداكن. يعد تحسين هذه العناصر أيضًا أمرًا بالغ الأهمية.

5.1 فلتر CSS لتقليل إضاءة الصور

الصور النقطية مثل الصور الفوتوغرافية يمكن أن تكون ساطعة جدًا إذا تم عرضها كما هي في الوضع الداكن. باستخدام خاصية filter في CSS، يمكنك تقليل الإضاءة (brightness) والتباين (contrast) قليلاً، مما يسمح لها بالاندماج بشكل طبيعي في واجهة المستخدم للسمة الداكنة.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* تقليل الإضاءة وزيادة التباين قليلاً */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* استعادة السطوع الأصلي عند التمرير (إذا كان المستخدم يريد رؤية التفاصيل) */
 filter: brightness(1) contrast(1);
}

5.2 عرض الصور باستخدام وسم `<picture>`

لا يمكن التعامل مع صور الشعارات أو الرسوم التوضيحية (مثل صور JPEG ذات الخلفية البيضاء الثابتة) باستخدام الفلاتر فقط. في هذه الحالة، الحل الصحيح هو استخدام عنصر <picture> في HTML مع استعلامات الوسائط (media queries) لتبديل وعرض ملف صورة مختلف للوضع الداكن.

1
2
3
4
5
6


<picture>
 <!-- عرض هذا للمستخدمين ذوي إعداد نظام التشغيل للوضع الداكن -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- الافتراضي (الوضع الفاتح) -->
 <img src="/img/logo-light.png" alt="شعار الموقع">
</picture>

※ ومع ذلك، لا ترتبط هذه الطريقة بالتبديل اليدوي من خلال أشياء مثل localStorage (إنها تعتمد فقط على إعداد نظام التشغيل). إذا قمت بتنفيذ التبديل اليدوي، فستحتاج إما إلى إعادة كتابة الـ src للصور ديناميكيًا باستخدام JS، أو تبديل display: none باستخدام فئات CSS.

5.3 دعم `currentColor` في أيقونات SVG

بالنسبة لرسومات SVG المضمنة المستخدمة كأيقونات وغيرها، فإن أذكى طريقة هي ربط لون التعبئة بلون النص الخاص بالعنصر الأصل. حدد currentColor في سمة fill أو stroke الخاصة بـ SVG.

1
2
3
4


<!-- يتم تطبيق قيمة خاصية color في CSS (مثل var(--text-primary)) تلقائيًا -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

من خلال هذا، عند التبديل إلى الوضع الداكن ويصبح لون نص العنصر الأصل أبيض، ستتغير أيقونة SVG تلقائيًا أيضًا إلى اللون الأبيض.

6. الخلاصة: نحو تصميم مستدام للوضع الداكن

لتنفيذ وضع داكن عالي الجودة في المدونات وتطبيقات الويب، لا غنى عن تصميم CSS يغطي النقاط التالية:

استخدام CSS Custom Properties: تجنب الترميز الثابت (hardcoding) للألوان، وقم بتجريدها إلى أسماء متغيرات دلالية (مثل: --bg-primary).
اعتماد مساحة الألوان OKLCH: صمم منطقيًا نسبة تباين عالية الوصول (7:1 أو أكثر) تلبي معايير WCAG 2.1 AAA ضمن مساحة ألوان موحدة إدراكيًا.
تنفيذ تدابير FOUC بصرامة: تخلص تمامًا من وميض الشاشة عند التحميل الأولي من خلال التنسيق بين SSR وملفات تعريف الارتباط (Cookies)، أو باستخدام نصوص برمجية حاجبة مضمنة داخل <head>.
تحسين الوسائط والأصول: استخدم filter: brightness() و currentColor وعلامات <picture> لمزامنة العناصر بخلاف النصوص مع السمة الداكنة.

هذا الاهتمام الدقيق بالتفاصيل الذي يتجاوز مجرد “عكس الألوان” هو ما يصنع الفارق في تجربة المستخدم، وهو شرط أساسي لمدونة حديثة توفر تجربة قراءة ممتازة ومريحة للعين وتحظى بتقدير طويل الأمد. نأمل أن يستخدم المطورون الذين يخططون لإضافة الوضع الداكن أنماط التصميم المذكورة في هذه المقالة كمرجع.