دليل تحسين الأسلوب

يوثّق هذا الدليل رموز نظام التصميم وفئات المكونات المُطبَّقة في styles/custom.css. يُعدّ مرجعًا للرموز المتعلقة بالحدود، والأسطح، والظلال، ونصف القطر، والأزرار، والتدرجات، والانتقالات، والتركيز، والطباعة المستخدمة عبر السمة.

الحالة: جميع رموز التصميم وفئات المكونات الموضحة أدناه مُطبَّقة ومتاحة للاستخدام.

كيفية قراءة هذا الدليل

يوثّق كل قسم فئة من فئات الرموز:

1. تعريفات الرموز — خصائص CSS المخصصة بقيم الوضع الفاتح/الداكن
2. تعيين المكونات — مكونات السمة التي تستخدم كل رمز
3. ملاحظات التطبيق — إرشادات الاستخدام واعتبارات إمكانية الوصول

تنقسم جداول الرموز بين الوضع الفاتح والوضع الداكن عند اختلاف القيم.

---

1. نظام الألوان

الحدود الشفافة بقناة ألفا

تستخدم السمة الحدود الشفافة بقناة ألفا بدلًا من الألوان الرمادية الصلبة، مما يُتيح للحدود التكيّف بصورة طبيعية مع أي خلفية.

/* نمط الحدود الشفافة بقناة ألفا */
border: 1px solid var(--f5-border-default);  /* محايد عند شفافية 20% */

رموز الحدود

/* الوضع الفاتح */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 عند شفافية 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 عند شفافية 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 عند شفافية 40% */
}

/* الوضع الداكن */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 عند شفافية 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 عند شفافية 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 عند شفافية 40% */
}

حالات استخدام الحدود

الرمز	الشفافية	حالة الاستخدام
--f5-border-faint	10%	الفواصل الخفية، صفوف الجداول
--f5-border-default	20%	الحدود الافتراضية، حدود البطاقات
--f5-border-strong	40%	الحدود البارزة، الحالات النشطة

الحالة: مكتمل — مُطبَّق في styles/custom.css.

ألوان الأسطح التفاعلية

رموز الأسطح الدلالية لحالتَي التحوّم والنشاط.

أسطح الوضع الفاتح

الرمز	القيمة	الغرض
--f5-white	#ffffff	الخلفيات الرئيسية
--f5-white-1	#faf9f7	الشريط الجانبي، المناطق الخفية
--f5-white-2	#f5f5f5	الأسطح المرتفعة
--f5-surface-hover	var(--f5-white-2)	تعبئة التحوّم
--f5-surface-active	var(--f5-white-3)	تعبئة الضغط/النشاط

أسطح الوضع الداكن

الرمز	القيمة	الغرض
--f5-black	#000000	الخلفيات الرئيسية
--f5-black-4	#222222	الشريط الجانبي، المناطق الخفية
--f5-surface-hover	var(--f5-black-3)	تعبئة التحوّم
--f5-surface-active	var(--f5-black-2)	تعبئة الضغط/النشاط

تعريفات رموز الأسطح

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

الحالة: مكتمل — مُطبَّق في styles/custom.css.

---

2. نظام الارتفاع والظلال

مقياس الظلال

تستخدم السمة ظلالًا بقناة ألفا ذات تدرج محايد بقيم مزدوجة الطبقات لإضفاء عمق طبيعي. يستخدم الوضع الفاتح --f5-black-3 (#343434) كقاعدة للتدرج؛ بينما يستخدم الوضع الداكن #cccccc.

ظلال الوضع الفاتح

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

ظلال الوضع الداكن

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

تعيين ظلال المكونات

المكوّن	مستوى الظل
.swatch، .icon-card	--f5-shadow-low (في حالة الراحة)
.starlight-aside	--f5-shadow-low
.expressive-code .frame	--f5-shadow-mid
.mermaid-container	--f5-shadow-mid
البطاقات عند التحوّم	--f5-shadow-mid
القوائم المنسدلة، النوافذ المنبثقة	--f5-shadow-high
النوافذ الحوارية	--f5-shadow-higher

الحالة: مكتمل — جميع مستويات الظل (inset، low، mid، high، higher) مُطبَّقة في styles/custom.css.

---

3. مقياس نصف قطر الحدود

رموز نصف القطر

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — الشارات، التسميات */
  --f5-radius-sm: 0.3125rem;   /* 5px — عناصر التنقل، عناصر التحكم الصغيرة */
  --f5-radius-md: 0.375rem;    /* 6px — البطاقات، كتل الكود */
  --f5-radius-lg: 0.5rem;      /* 8px — النوافذ الحوارية، الحاويات الكبيرة */
  --f5-radius-full: 999px;     /* حبوب، تدوير كامل */
}

تعيين نصف قطر المكونات

المكوّن	رمز نصف القطر
.swatch	--f5-radius-md (6px)
.icon-card	--f5-radius-md (6px)
.starlight-aside	--f5-radius-md (6px)
.expressive-code .frame	--f5-radius-md (6px)
.mermaid-container	--f5-radius-lg (8px)
.edit-link	--f5-radius-full (حبة)
عناصر تنقل الشريط الجانبي	--f5-radius-sm (5px)
الشارات	--f5-radius-xs (3px)

الحالة: مكتمل — مقياس نصف القطر (xs، sm، md، lg، full) مُطبَّق في styles/custom.css.

---

4. تنسيق تنقل الشريط الجانبي

أنماط عناصر الشريط الجانبي

/* عناصر تنقل الشريط الجانبي */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* تحوّم الوضع الفاتح */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* تحوّم الوضع الداكن */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* مؤشر الصفحة النشطة */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 فاتح */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → اضبط للقراءة */
}

مؤشر التأكيد الأيسر

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* تعويض عن الحد */
}

الحالة: مكتمل — تحوّم الشريط الجانبي والحالة النشطة ومؤشر التأكيد مُطبَّقة في styles/custom.css.

---

5. نظام الأزرار

متغيرات الأزرار

/* الأساسي — استخدام الأحمر F5 كإجراء علامة تجارية */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* الثانوي — نمط مخطط تفصيلي */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* الثالثي — شبح/نص فقط */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

مقياس حجم الأزرار

الحجم	الحشو	حجم الخط	الحد الأدنى للارتفاع
صغير	0.375rem 0.75rem	0.8125rem (13px)	32px
متوسط (افتراضي)	0.625rem 1rem	0.875rem (14px)	40px
كبير	0.75rem 1.5rem	1rem (16px)	48px

الحالة: مكتمل — جميع متغيرات الأزرار (primary، secondary، tertiary، critical) ومقياس الحجم (sm، افتراضي، lg) مُطبَّقة في styles/custom.css.

---

6. خلفيات Hero والرأس

تدرجات Hero

باستخدام لوحة ألوان العلامة التجارية F5:

/* تدرج hero الأساسي — أزرق River */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* غسيل صفحة خفيف — نبرة دافئة خفية */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* متغير Eggplant لصفحات الميزات */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* متغير العلامة التجارية الأحمر للإعلانات */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

تقنيات تراكب التدرج

/* تأثير الظل الشعاعي للعمق */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* تلاشٍ سفلي إلى خلفية الصفحة */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

الحالة: مكتمل — تدرجات hero (primary، eggplant، red، faint) والتراكبات (hero-fade، hero-vignette) مُطبَّقة في styles/custom.css.

---

7. تأثيرات التحوّم والانتقالات

رموز الانتقال

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

الرمز	المدة	التخفيف	حالة الاستخدام
--f5-transition-fast	0.15s	ease	معظم حالات التحوّم، تغييرات الألوان
--f5-transition-base	0.2s	ease	تعبئة الخلفية، تغييرات الحدود
--f5-transition-bounce	0.2s	cubic-bezier(0.68, -0.2, 0.265, 1.15)	المفاتيح، التبديل
--f5-transition-decelerate	0.6s	cubic-bezier(0.5, 1, 0.89, 1)	مؤشرات علامات التبويب، اللوحات الانزلاقية
--f5-transition-spring	0.2s	cubic-bezier(0.54, 1.5, 0.38, 1.11)	التلميحات، دخول النوافذ المنبثقة

ما يجب تحريكه

الخاصية	آمن للتحريك	ملاحظات
background-color	نعم	معياري لتعبئة التحوّم
color	نعم	تغييرات لون النص
border-color	نعم	تأكيد الحد عند التحوّم
box-shadow	نعم	تغييرات الارتفاع (استخدم will-change عند التقطع)
transform	نعم	التحجيم، الإزاحة للتغذية الراجعة
opacity	نعم	التلاشي للداخل/الخارج
width، height	تجنّب	يسبب إعادة تدفق التخطيط
padding، margin	تجنّب	يسبب إعادة تدفق التخطيط

تعيين انتقالات المكونات

/* عناصر تنقل الشريط الجانبي */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* البطاقات — رفع الظل عند التحوّم */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* الأزرار */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* الروابط */
a {
  transition: color var(--f5-transition-fast);
}

الحالة: مكتمل — جميع رموز الانتقال الخمسة (fast، base، bounce، decelerate، spring) وانتقالات المكونات مُطبَّقة في styles/custom.css.

---

8. نظام حلقة التركيز

رموز حلقة التركيز

تستخدم السمة نمط الحلقة المزدوجة مع حلقة داخلية مدمجة وتوهّج خارجي:

/* تركيز الإجراء — باستخدام الأزرق F5 River */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* تطبيق على العناصر التفاعلية */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* المتغير الحرج للأزرار التدميرية */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

ملاحظات إمكانية الوصول

• يستوفي نمط الحلقة المزدوجة متطلبات WCAG 2.2 لمظهر التركيز (حد أدنى 2px مخطط تفصيلي متباين)
• يتيح استخدام box-shadow بدلًا من outline احترام نصف قطر الحدود
• يضمن :focus-visible ظهور الحلقة للتنقل بلوحة المفاتيح فقط، دون النقر بالفأرة

الحالة: مكتمل — نمط التركيز ذو الحلقة المزدوجة (action، critical) وأنماط :focus-visible مُطبَّقة في styles/custom.css.

---

9. الطباعة

مكدس الخطوط

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

مقياس النص

المقياس	الحجم	ارتفاع السطر	الاستخدام
Display 500	1.875rem (30px)	1.267	--sl-text-h1
Display 400	1.5rem (24px)	1.333	--sl-text-h2
Display 300	1.125rem (18px)	1.333	--sl-text-h3
Display 200	1rem (16px)	1.5	--sl-text-h4
Display 100	0.8125rem (13px)	1.385	نص العنوان العلوي
Body 300	1rem (16px)	1.5	النص الأساسي
Body 200	0.875rem (14px)	1.429	نص الشريط الجانبي، التعليقات التوضيحية
Body 100	0.8125rem (13px)	1.385	النص الصغير

الخصائص الرئيسية

الجانب	القيمة	ملاحظات
ارتفاع سطر العناوين	1.1	عناوين مضغوطة لتأثير العلامة التجارية؛ فكّر في 1.2 للقراءة
ارتفاع سطر النص	1.5 (افتراضي Starlight)	مناسب جدًا للقراءة
عائلة الخطوط	خطوط العلامة التجارية المخصصة	proximaNova (النص)، neusaNextProWide (العناوين)
أوزان العناوين	h1-h2: 700، h3: 500، h4-h6: 700 بالأحرف الكبيرة	مدروس لاتساق العلامة التجارية

الأولوية: لا توجد تغييرات مطلوبة. الطباعة الحالية محددة جيدًا ومناسبة للعلامة التجارية. التعديل الطفيف لارتفاع سطر العنوان (1.1 إلى 1.2) اختياري.

---

10. سجل التغييرات التطبيقية

طُبِّقت جميع رموز التصميم عبر خمسة سباقات:

السباق	النطاق	الرموز المضافة
1. الأساس	الظلال + نصف قطر الحدود	--f5-shadow-* (5 مستويات)، --f5-radius-* (5 مستويات)
2. الشريط الجانبي + الأسطح	التنقل + الرموز التفاعلية	--f5-surface-hover، --f5-surface-active، --f5-border-* (3 مستويات)، --f5-transition-fast
3. الأزرار	نظام المكونات	.btn-primary، .btn-secondary، .btn-tertiary، .btn-critical، متغيرات الحجم
4. تدرجات Hero	أدوات الخلفية	.hero-gradient-primary، -eggplant، -red، -faint، .hero-vignette، .hero-fade
5. التركيز + الانتقالات	إمكانية الوصول + التلميع	--f5-focus-action، --f5-focus-critical، --f5-transition-* (5 رموز)، تأثيرات تحوّم البطاقة

---

المرجع السريع: ملخص الرموز

جميع الخصائص المخصصة

:root {
  /* مقياس نصف قطر الحدود */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* توقيت الانتقال */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* حلقات التركيز */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* ظلال الوضع الداكن (افتراضي) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* حدود الوضع الداكن */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* أسطح الوضع الداكن */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* ظلال الوضع الفاتح */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* حدود الوضع الفاتح */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* أسطح الوضع الفاتح */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}