Design 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 أحد “أفضل الخيارات” لأي مشروع، من المدونات التقنية الشخصية إلى مواقع الشركات الضخمة. تأكد من الاستفادة من سلسلة الأدوات القوية هذه واستمتع بتجربة تطوير ويب مريحة!

أساسيات هندسة البرمجيات: ما هي البنية النظيفة (Clean Architecture)؟

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

في تطوير البرمجيات الحديثة، يعد بناء “نظام مقاوم للتغيير” تحديًا دائمًا. التغييرات في متطلبات العمل، ظهور أطر عمل جديدة، تجديد واجهة المستخدم، وترحيل قواعد البيانات. استجابةً لكل هذه التغييرات، هناك حاجة إلى بنية يمكنها التكيف بمرونة دون إعادة بناء النظام بأكمله. كأحد الإجابات على ذلك، تم اقتراح البنية النظيفة (Clean Architecture) بواسطة Robert C. Martin (المعروف باسم العم بوب، Uncle Bob).

في هذه المقالة، سنتعمق في جوهر البنية النظيفة من خلال تاريخها، الغرض منها، تفاصيل الطبقات الأربع، قاعدة التبعية، وأمثلة تنفيذية محددة. سنقدم شرحًا تقنيًا عميقًا ومفصلاً للغاية.

1. مشاكل البنى التقليدية وتاريخ البنية النظيفة

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

ومع ذلك، كان هناك مشكلة رئيسية في البنية التقليدية ثلاثية الطبقات. وهي أن “المجال (منطق العمل) يعتمد على قاعدة البيانات وأطر العمل”.

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

كحلول لهذه المشكلة، تم ابتكار البنى التالية:

البنية السداسية (Ports and Adapters) - Alistair Cockburn
بنية البصلة (Onion Architecture) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

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

قام Robert C. Martin بدمج مفاهيم هذه البنى الممتازة وتلخيصها في قاعدة عملية واحدة أسماها “البنية النظيفة (Clean Architecture)”.

2. الغرض من البنية النظيفة وخصائصها

النظام الذي يعتمد البنية النظيفة يتمتع بالخصائص التالية:

الاستقلالية عن أطر العمل (Independent of Frameworks): لا تعتمد البنية على وجود مكتبات برمجية غنية بالميزات. يتيح ذلك استخدام أطر العمل كـ “أدوات”، دون الحاجة إلى إجبار النظام على التوافق مع قيود إطار العمل.
قابلية الاختبار (Testable): يمكن اختبار قواعد العمل دون واجهة المستخدم، قاعدة البيانات، خادم الويب، أو أي عنصر خارجي آخر.
الاستقلالية عن واجهة المستخدم (Independent of UI): يمكن تغيير واجهة المستخدم بسهولة دون تغيير بقية النظام. على سبيل المثال، يمكن استبدال واجهة مستخدم الويب بواجهة مستخدم تعتمد على وحدة التحكم (Console UI) دون تغيير قواعد العمل.
الاستقلالية عن قاعدة البيانات (Independent of Database): يمكنك تغيير Oracle أو SQL Server إلى Mongo أو BigTable أو CouchDB وما إلى ذلك. قواعد العمل ليست مقيدة بقاعدة البيانات.
الاستقلالية عن أي وكيل خارجي (Independent of any external agency): في الواقع، قواعد العمل لا تعرف شيئًا عن العالم الخارجي.

3. الطبقات الأربع للبنية النظيفة (Layers)

تُمثل البنية النظيفة عمومًا برسم بياني لدوائر متحدة المركز. كلما اقتربت من المركز، أصبحت البرمجيات سياسات عالية المستوى (قواعد عمل عالية التجريد). وكلما اتجهت نحو الخارج، أصبحت آليات (تفاصيل محددة).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["الويب"]
B["واجهة المستخدم"]
C["قاعدة البيانات"]
D["واجهات برمجة التطبيقات الخارجية"]
end
subgraph "Interface Adapters"
E["وحدات التحكم"]
F["البوابات"]
G["مقدمو العرض"]
end
subgraph "Application Business Rules (Use Cases)"
H["متفاعلات حالات الاستخدام"]
end
subgraph "Enterprise Business Rules (Entities)"
I["الكيانات"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. الكيانات (Entities)

تغلف الكيانات قواعد العمل على مستوى المؤسسة (Enterprise Business Rules). يمكن أن يكون الكيان كائنًا يحتوي على طرق، أو يمكن أن يكون مجموعة من هياكل البيانات والدوال. إنها القواعد الأكثر عمومية وعالية المستوى والتي يمكن إعادة استخدامها في تطبيقات مختلفة متعددة داخل الشركة. حتى لو كنت تنشئ تطبيقًا واحدًا فقط، فإن الكيانات هي كائنات العمل لهذا التطبيق. الكيانات لا تتأثر أبدًا بالتغييرات الخارجية (مثل التغييرات في تنقل الصفحات أو التغييرات في الأمان).

3.2. حالات الاستخدام (Use Cases)

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

3.3. محولات الواجهات (Interface Adapters)

طبقة محولات الواجهات عبارة عن مجموعة من المحولات التي تقوم بتحويل البيانات من التنسيق المناسب لحالات الاستخدام والكيانات، إلى التنسيق المناسب للوكلاء الخارجيين مثل قاعدة البيانات والويب. على سبيل المثال، تنتمي عناصر بنية MVC (نموذج-عرض-تحكم) الخاصة بـ GUI في عالم الويب إلى هنا. تتلقى وحدة التحكم إدخال المستخدم، وتمرره إلى حالة الاستخدام، ويتلقى مقدم العرض المخرجات من حالة الاستخدام ويقوم بتنسيقها للعرض (واجهة المستخدم). كما أن دور هذه الطبقة هو تحويل البيانات إلى التنسيق الذي يمكن لقاعدة البيانات (مثل SQL) فهمه. يجب ألا يعرف الكود الموجود داخل هذه الطبقة أي شيء عن قاعدة البيانات.

3.4. أطر العمل والمحركات (Frameworks & Drivers)

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

4. قاعدة التبعية (The Dependency Rule)

لجعل البنية النظيفة تعمل، هناك قاعدة واحدة بالغة الأهمية يجب عدم كسرها أبدًا. وهي “قاعدة التبعية (The Dependency Rule)”.

يجب أن تتجه تبعيات الكود المصدري دائمًا نحو الداخل (نحو السياسات عالية المستوى).

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

graph LR
A["أطر العمل والمحركات"] -->| اعتماد | B["محولات الواجهات"]
B -->| اعتماد | C["حالات الاستخدام"]
C -->| اعتماد | D["الكيانات"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

للتعبير عن ذلك رياضيًا، إذا كان مؤشر الطبقة هو $L_i$، وحددنا $i=0$ للكيانات (الطبقة الأعمق) و $i=3$ لأطر العمل (الطبقة الأبعد)، ففي حال وجود تبعية من طبقة $L_m$ إلى $L_n$، يجب أن تتحقق المتباينة التالية دائمًا:

$$ m > n $$

بمعنى آخر، يتجه متجه التبعية $\vec{D}$ دائمًا نحو المركز.

5. عبور الحدود: مبدأ انعكاس التبعية (DIP)

عند محاولة الالتزام بقاعدة التبعية، ستواجه سريعًا مشكلة كبيرة واحدة. “ماذا تفعل عندما تحتاج حالة الاستخدام إلى جلب بيانات من قاعدة البيانات؟”

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

ما يحل هذه المشكلة هو الحرف “D” في مبادئ SOLID (مبدأ انعكاس التبعية: Dependency Inversion Principle).

تعريف مبدأ انعكاس التبعية (DIP)

يجب ألا تعتمد الوحدات عالية المستوى على الوحدات منخفضة المستوى. يجب أن يعتمد كلاهما على التجريدات.
يجب ألا تعتمد التجريدات على التفاصيل. يجب أن تعتمد التفاصيل على التجريدات.

لتحقيق ذلك، نُعرّف واجهة (تجريد) في طبقة حالات الاستخدام، ونقوم بـ تنفيذ تلك الواجهة في الطبقة الخارجية (محولات الواجهات). تعتمد طبقة حالات الاستخدام فقط على الواجهة التي حددتها، ولا تعتمد على التنفيذ الملموس في الخارج.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Depends on (يعتمد على)"
UserRepositoryImpl ..|> UserRepository : "Implements (ينفذ)"
note for UseCaseInteractor "الطبقة الداخلية (حالة الاستخدام)"
note for UserRepository "الطبقة الداخلية (حالة الاستخدام)"
note for UserRepositoryImpl "الطبقة الخارجية (محولات الواجهات)"

في الرسم البياني أعلاه، يكون تدفق التحكم (Control Flow) أثناء وقت التشغيل هو UseCaseInteractor $\rightarrow$ UserRepositoryImpl. ومع ذلك، فإن تبعية الكود المصدري (Source Code Dependency) هي UserRepositoryImpl $\rightarrow$ UserRepository (نحو الداخل). باستخدام تعدد الأشكال (Polymorphism)، تمكنا من توجيه تبعية الكود المصدري في الاتجاه المعاكس لتدفق التحكم. هذا هو سبب تسميته بـ “انعكاس التبعية”.

6. مثال تنفيذي محدد باستخدام TypeScript

هنا، نوضح مثالًا بسيطًا لتنفيذ البنية النظيفة (ميزة تسجيل المستخدم) باستخدام TypeScript.

6.1. الكيانات (Entities)

قواعد العمل الأكثر مركزية.

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


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // قواعد العمل الخاصة بالكيان (مثل التحقق من طول الاسم)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. حالات الاستخدام (Use Cases)

في طبقة حالات الاستخدام، نحدد هياكل بيانات الإدخال والإخراج (DTO)، وواجهة المستودع لعكس التبعية.

 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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// الواجهة المحددة بواسطة طبقة حالات الاستخدام
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // يعتمد على التجريد (الواجهة). لا يعتمد على التنفيذ الملموس.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // يستدعي عملية الحفظ في قاعدة البيانات الخارجية، لكن التبعية تتجه للداخل (للواجهة)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. محولات الواجهات (Interface Adapters)

نقوم بإنشاء عملية الوصول المحددة لقاعدة البيانات (تنفيذ المستودع) ووحدة التحكم التي تعالج طلبات HTTP.

 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
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// نفترض عميل قاعدة البيانات كطبقة خارجية (Driver)
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. المكون الرئيسي (حقن التبعية: DI)

عند بدء تشغيل التطبيق، نقوم ببناء جميع التبعيات (الربط). يُطلق على هذا اسم Composition Root.

 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


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. تهيئة المحرك
const dbClient = new DatabaseClient(/* معلومات الاتصال */);

// 2. تهيئة المحول (إنشاء كائن من الفئة الملموسة)
const userRepository = new PostgresUserRepository(dbClient);

// 3. تهيئة حالة الاستخدام (حقن الفئة الملموسة في الواجهة = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. تهيئة وحدة التحكم
const userController = new UserController(registerUserUseCase);

// التوجيه
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

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

7. اعتبارات رياضية حول الاقتران والتماسك

في هندسة البرمجيات، هناك مقاييس لتقييم جودة البنية وهي الاقتران (Coupling) و التماسك (Cohesion).

يمثل الاقتران $C$ قوة التبعية بين الوحدات (Modules). إذا كانت الوحدة $A$ تعتمد على الوحدة $B$، وافترضنا أن إجمالي عدد التبعيات في النظام هو $N_{dep}$، وعدد الوحدات هو $N_{mod}$، فإن أحد المقاييس التي تشير إلى التعقيد يمكن التعبير عنه على النحو التالي:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

في البنية النظيفة، من خلال تطبيق DIP، نوجه سهم التبعية المادية نحو التجريد. تم تصميم وتيرة تغيير التجريد (الواجهة) (عدم الاستقرار: Instability $I$) لتكون منخفضة للغاية.

يُحسب عدم الاستقرار $I$ بالصيغة التالية (كما عرفه Robert C. Martin):

$C_e$ (Efferent Coupling): الاقتران الخارجي (عدد التبعيات الصادرة)
$C_a$ (Afferent Coupling): الاقتران الداخلي (عدد التبعيات الواردة)

$$ I = \frac{C_e}{C_e + C_a} $$

عندما يكون $I = 0$، يكون المكون مستقرًا تمامًا (لا يعتمد على أحد، ويعتمد عليه الآخرون).
عندما يكون $I = 1$، يكون المكون غير مستقر تمامًا (لا يعتمد عليه أحد، ويعتمد هو على الآخرين).

نظرًا لأن “طبقة الكيانات” في البنية النظيفة لها $C_e = 0$ (لا تعتمد على الخارج)، فإنها تصبح $I = 0$. بعبارة أخرى، إنها الطبقة الأكثر استقرارًا. على العكس من ذلك، “طبقة واجهة المستخدم” أو “طبقة قاعدة البيانات” يكون لها $C_a \approx 0$ و $C_e > 0$، لذلك تصبح $I \approx 1$، مما يجعلها طبقات سهلة التغيير (طبقات غير مستقرة).

ينص المبدأ المهم للبنية SDP (Stable Dependencies Principle: مبدأ التبعيات المستقرة) على أن “التبعية يجب أن تتجه نحو مكون أكثر استقرارًا (مكون ذو قيمة $I$ أصغر)”. الدوائر متحدة المركز للبنية النظيفة هي تصور دقيق لـ SDP، وهي مصممة بحيث تتجه التبعيات من الخارج ($I=1$) إلى الداخل ($I=0$).

8. استراتيجية الاختبار والبنية النظيفة

إحدى أكبر مزايا البنية النظيفة هي سهولة الاختبار. نظرًا لفصل الطبقات، يمكنك كتابة اختبارات لكل طبقة بشكل مستقل.

8.1. اختبار الكيانات (Unit Test)

نظرًا لأنه منطق نقي خالٍ من أي تبعيات خارجية، فليس هناك حاجة لقاعدة بيانات أو كائنات وهمية (mocks). إنه أسرع اختبار موثوق يمكنك تشغيله.

8.2. اختبار حالات الاستخدام (Unit Test with Mocks)

نظرًا لأن التبعيات الخارجية مثل المستودعات يتم تعريفها جميعًا كواجهات، فإن كل ما عليك فعله أثناء الاختبار هو حقن (DI) كائنات وهمية أو تنفيذ في الذاكرة (Fake) مخصص للاختبار. لا داعي لتشغيل قاعدة بيانات فعلية. يتيح لك ذلك اختبار التفرعات المعقدة لمنطق العمل ومعالجة الاستثناءات بسرعات عالية.

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


// مثال لاختبار حالة الاستخدام (بافتراض Jest)
test('محاولة التسجيل ببريد إلكتروني موجود مسبقًا يجب أن ينتج عنها خطأ', async () => {
 // إنشاء مستودع مزيف (Fake)
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // إرجاع مستخدم موجود
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // تنفيذ حالة الاستخدام والتأكد من الخطأ
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. اختبار المحولات (Integration Test)

تختبر فئات تنفيذ المستودع فعليًا الاتصال بقاعدة البيانات وما إذا كان SQL صحيحًا. يختبر اختبار وحدة التحكم تلقي طلب HTTP وإرجاع JSON. هنا لا نقوم بالتحقق المفصل من منطق العمل، بل نكتفي بتأكيد صحة “التحويل” و"الاتصال".

9. عيوب البنية النظيفة ومتى يجب اعتمادها

البنية النظيفة التي تبدو قادرة على كل شيء ليست رصاصة فضية. هناك عيوب (مفاضلات) مثل ما يلي:

زيادة تكلفة التعلم الأولية وتكلفة التطوير: يزداد عدد الملفات والواجهات (التجريدات) بشكل كبير. سيكون هناك الكثير من “الأكواد النمطية (boilerplate code)” مثل إعادة حزم DTOs.
مبالغة في المشاريع الصغيرة: في النماذج الأولية التي يتم إنشاؤها في أيام قليلة أو الأدوات التي تُستخدم لمرة واحدة والتي نادرًا ما تتغير، غالبًا ما تكون هذه البنية تكلفة مهدرة. إنها أيضًا غير مناسبة لواجهات برمجة التطبيقات البسيطة التي تقوم فقط بعمليات CRUD.

متى يجب اعتمادها:

المنتجات التي يُتوقع الحفاظ عليها وتشغيلها لفترة طويلة (عدة سنوات أو أكثر).
الأنظمة ذات قواعد العمل المعقدة حيث تتغير المتطلبات بشكل متكرر.
عندما ترغب في تقسيم العمل في فرق تطوير كبيرة (الواجهة الأمامية، الخلفية، البنية التحتية، إلخ).
عندما تريد تصميم مجال عمل معقد بالتزامن مع التصميم المدفوع بالمجال (DDD: Domain-Driven Design).

10. الخلاصة

البنية النظيفة هي فلسفة تصميم لحماية جوهر النظام المسمى “قواعد العمل” من “التفاصيل” مثل واجهة المستخدم وقاعدة البيانات وأطر العمل.

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

الأمر المهم ليس التقليد الأعمى لهيكل أدلة البنية النظيفة، بل فهم جوهر أسئلة مثل “لماذا نقسمها بهذه الطريقة” و"أين تشير أسهم التبعية"، وتطبيقها بشكل مناسب وفقًا لحجم مشروعك ومدى تعقيده.

مرجع: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” بقلم Robert C. Martin

نقاط تصميم 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> لمزامنة العناصر بخلاف النصوص مع السمة الداكنة.

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