الوضع الداكن

تشير السمة color-scheme إلى أنظمة الألوان (مثل الفاتح أو الداكن) التي تتيحها صفحتك. يُعلم هذا الإعداد المتصفّح بأنّه يمكنه تلقائيًا تطبيق مظهر على عناصر واجهة المستخدم الأصلية، مثل أشرطة التمرير وعناصر التحكّم في النماذج وخلفية لوحة الرسم التلقائية، ليتوافق مع تصميم موقعك الإلكتروني ويساعد في تقليل الومضات البيضاء أثناء التحميل الأولي.

التنفيذ

1. الإعلان عن المخططات المتوافقة في HTML

إجراء إلزامي: للمساعدة في منع "ظهور محتوى بدون مظهر" (FOUC)، ضَع علامة <meta> في <head> لضمان أن يعرف المتصفّح المظاهر التي تتيحها قبل أن يبدأ في عرضها. على الرغم من أنّ علامة <meta> هذه تساعد في تجنُّب وميض المحتوى غير المنسَّق من خلال ضبط لون اللوحة الأوّلي مبكرًا، قد لا تقضي تمامًا على الوميض في جميع المتصفّحات أو ظروف التحميل.

<!-- MANDATORY: Declare support for both light and dark themes -->
<meta name="color-scheme" content="light dark">

2. تطبيق نظام الألوان على مستوى الصفحة على CSS :root أو html

إجراء إلزامي: طبِّق السمة color-scheme على العنصر html أو الفئة الزائفة :root. تبحث المتصفّحات تحديدًا عن العنصر الجذر لتحديد المظهر الخاص بإطار العرض بالكامل، بما في ذلك أشرطة التمرير الجذرية وخلفية "اللوحة" الأولية. إذا تم تطبيق الوضع على body فقط، قد تظلّ مساحات العرض هذه في واجهة المستخدم العامة في الوضع الفاتح لأنّ body لا يتحكّم في سياق عرض النافذة.

/* MANDATORY: Apply color-scheme to :root or html for viewport-wide theming */
:root {
  /* MANDATORY: Automatically adapt native UI to user system preferences */
  color-scheme: light dark;
}

3- تحديد رموز الألوان الفاتحة والداكنة

يمكنك استخدام الدالة light-dark() لتحديد رموز الألوان التي تتكيّف تلقائيًا مع قيم color-scheme المختلفة.

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

لمزيد من التحكّم في ألوان واجهة المستخدم المضمّنة، مثل accent-color أو scrollbar-color، يمكن للمؤلفين إضافة ألوانهم الديناميكية باستخدام الخصائص المخصّصة و/أو دالة light-dark(). تختار هذه الدالة تلقائيًا اللون الصحيح استنادًا إلى السمة color-scheme المحسوبة للعنصر، وتغني عن الحاجة إلى الاستعلامات المتكررة عن الوسائط، ولكنّها ليست مطلوبة للتنفيذ الأساسي.

:root {
  --color-brand-light: oklch(45% 0.23 270);
  --color-brand-dark: oklch(85% 0.15 210);
  --color-brand-text-light: white;
  --color-brand-text-dark: oklch(40% 0.23 270);

  --color-brand: light-dark(var(--color-brand-light), var(--color-brand-dark));
  --color-brand-text: light-dark(var(--color-brand-text-light), var(--color-brand-text-dark));

  /* MANDATORY: Automatically adapt native UI to user system preferences */
  color-scheme: light dark;
}

button.primary {
  /* These automatically adapt to color scheme */
  background-color: var(--color-brand);
  color: var(--color-brand-text);
}

اختياري: يتوفّر عدد من ألوان النظام التي تتكيّف تلقائيًا مع نظام الألوان المستخدَم (وغيره من أوضاع الألوان، مثل الألوان المفروضة)، مثل canvas وcanvastext وaccentcolor (يُرجى التحقّق من التوافق) وbuttonborder وما إلى ذلك. عادةً ما تكون هذه الألوان محدودة جدًا بحيث لا تكون مفيدة، باستثناء الحالات المحدّدة جدًا التي تحتاج فيها إلى مطابقة واجهة مستخدم معيّنة للمتصفّح التلقائي أو كألوان احتياطية أو تلقائية.

اختياري: تخصيص أزواج الألوان حسب السياق

حتى عند إلغاء الإعداد التلقائي للنظام، قد يكون من المفيد استخدام الاستعلام عن الوسائط prefers-color-scheme لتحديد أزواج ألوان مختلفة تأخذ في الاعتبار ألوان المتصفّح ونظام التشغيل Chrome حول الصفحة (أو الصفحة المحيطة، عندما يتم استخدام الصفحة كإطار iframe).

على سبيل المثال، يمكنك استخدام مظهر فاتح بدرجة أقل قليلاً عندما يكون إعداد النظام هو "dark"، أو مظهر داكن بدرجة تباين أعلى عندما يكون إعداد النظام هو "light"، لكي لا تطغى واجهة المستخدم المحيطة على الصفحة من الناحية المرئية.

تخصيص واجهة مستخدم المتصفّح بشكل دقيق

يؤدي ضبط الإعداد color-scheme إلى تكييف واجهة مستخدم المتصفّح مع نظام الألوان المستخدَم، ولكن سيتم استخدام الإعدادات التلقائية لنظام التشغيل و/أو ألوان النظام التي قد لا تتوافق تمامًا مع تصميم الموقع الإلكتروني. وتوفّر المتصفّحات الحديثة العديد من عناصر الربط الدقيقة لتخصيص هذه العناصر. لا تُعِد تنفيذ عناصر التحكّم الأصلية لمجرد تخصيص مظهرها بدون استنفاد عناصر التخصيص التي توفّرها المتصفّحات الحديثة.

ضبط لون التمييز

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

html {
  accent-color: light-dark(var(--color-accent-light), var(--color-accent-dark));
}

مشاكل يجب الانتباه إليها عند استخدام السمة accent-color

يختلف عرض المتصفّح لـ accent-color. بالنسبة إلى المؤشرات التي يتم رسمها بشكل عام فوق خلفية بلون تمييز، مثل علامات مربّعات الاختيار ونقاط أزرار الاختيار، قد تطبّق المتصفّحات معالجات مختلفة:

• يختار Chromium وFirefox بشكل عام لون مؤشر متباينًا.
• قد يحافظ متصفّح Safari على مؤشر أبيض في الوضع الفاتح أو مؤشر أسود في الوضع الداكن، مع تعديل لون التمييز خلفه. لا يوفّر هذا التعديل دائمًا تباينًا كافيًا لكل لون يتم توفيره، لذا اختبِر المجموعات المهمة في Safari، بما في ذلك أنظمة الألوان الفاتحة والداكنة. لا تفترض أنّ Safari سيختار تلقائيًا لون المؤشر الذي يوفّر أفضل تباين.

ألوان شريط التمرير

يمكنك استخدام scrollbar-color مع light-dark() لضبط ألوان مخصّصة لشريط التمرير تتوافق مع نظام الألوان المستخدَم.

:root {
  --color-scrollbar-track: light-dark(#eee, #222);
  --color-scrollbar-thumb: light-dark(#999, #666);
  scrollbar-color: var(--color-scrollbar-thumb) var(--color-scrollbar-track);
}

المشاكل التي يجب الانتباه إليها عند استخدام scrollbar-color

• يُرجى عدم استخدام صور متحركة أو تأثيرات انتقال في scrollbar-color. يتسبب خطأ في WebKit في وميض شريط التمرير في كل مرة يتغير فيها scrollbar-color.
• على نظام التشغيل macOS، يتم تجاهل السمتَين scrollbar-color (العادية) و::-webkit-scrollbar (القديمة) تلقائيًا لأنّ نظام التشغيل macOS يستخدم أشرطة تمرير "تراكب" أصلية. يجب إقران الألوان المخصّصة بـ scrollbar-width (مثل thin أو auto) لفرض عرضها على نظام التشغيل macOS.
• حتى مع تطبيق scrollbar-width، تعرض أشرطة التمرير في تراكب macOS المسار (الهامش) على أنّه شفاف تلقائيًا. إذا كان التصميم يتطلّب لون خلفية مرئيًا للمسار على نظام التشغيل MacOS، يجب تطبيق scrollbar-gutter: stable; على الحاوية القابلة للتمرير، ولكن يُرجى العِلم أنّه لا يظهر إلا بعد أن يمرّر المستخدم مؤشر الماوس فوق شريط التمرير.
• حتى مع تفعيل scrollbar-gutter: stable، قد يكون المسار شفافًا على نظام التشغيل MacOS. يجب ألا يعتمد شريط التمرير على لون المسار ليكون مرئيًا.

مزيد من التخصيص

تعرض معظم واجهات المستخدم في المتصفّحات عناصر زائفة لتخصيص مظهرها بالكامل، مثل:

• ::placeholder
• ::spelling-error
• ::grammar-error
• ::selection
• ::search-text
• ::target-text
• ::file-selector-button

يمكنك استخدام ألوان light-dark() على أي من هذه العناصر لتطبيق ألوان تتوافق مع نظام الألوان المستخدَم.

4. صور مختلفة للوضعَين الفاتح والداكن

بالنسبة إلى صور CSS، يمكن أيضًا استخدام light-dark() لتقديم قيم مختلفة للصور.

ملاحظة مهمة: يجب أن تكون كلتا القيمتَين في light-dark() من النوع نفسه. لا يمكنك الجمع بين لون وصورة. إذا كان يجب أن يكون أحدهما صورة، استخدِم image(<color>) لتضمين قيمة اللون.

رصد المظهر المستنِد إلى JavaScript

يجب إجراء معظم عمليات تفريع أنظمة الألوان في CSS، والتي تتكيّف تلقائيًا مع التغييرات.

يجب أن يتعامل أي رمز JS يقرأ matchMedia("(prefers-color-scheme: dark)").matches أيضًا مع الحدث change لأنّ الإعدادات المفضّلة للنظام يمكن أن تتغيّر في أي وقت.

اختياري: تنفيذ زر تبديل الألوان

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

اختياري: عمليات إلغاء خاصة بالمكوّنات

يمكنك إلغاء المظهر العام لعناصر معيّنة من خلال ضبط السمة color-scheme عليها.

لمزيد من المعلومات والملاحظات، يُرجى الاطّلاع على المظاهر الفاتحة/الداكنة الخاصة بالمكوّنات.

المشاكل المعروفة التي يجب الانتباه إليها

المشاكل التي يجب الانتباه إليها عند استخدام color-scheme

• يستجيب متصفّحا Chrome وFirefox لسمة color-scheme في إطارات iframe، إذ يعرضان الصفحات المضمّنة بنظام الألوان الصحيح ويعدّلان الاستعلام عن الوسائط prefers-color-scheme في الصفحة المضمّنة ليعكس سمة color-scheme في سياق التضمين. لا يتيح Safari ذلك، ويحلّ prefers-color-scheme في إعدادات النظام حتى داخل إطارات iframe.
  • إذا كنت تتحكّم في كل من الصفحة الرئيسية وiframe: يمكنك تمرير نظام الألوان الخاص بالصفحة الرئيسية إلى iframe بشكل صريح، إما من خلال مَعلمة عنوان URL (?theme=dark) في وقت إنشاء iframe، أو من خلال postMessage() (الذي يتيح لك أيضًا التفاعل مع التغييرات في وقت التشغيل). في إطار iframe، اضبط فئة على <html> (و/أو color-scheme على :root) من تلك الإشارة بدلاً من الاعتماد على prefers-color-scheme.
  • إذا كنت تتحكّم في الصفحة المضمّنة فقط: لا تتوفّر طريقة موثوقة لرصد color-scheme سياق التضمين من داخل إطار iframe في Safari. اعرض مَعلمة مظهر صريحة في واجهة برمجة التطبيقات المضمّنة (مثل سلسلة طلب بحث أو بروتوكول postMessage) ووثِّقها لمستخدمي التضمين.

استراتيجيات احتياطية

الخيارات الاحتياطية وتوافق المتصفّحات مع color-scheme

سمة color-scheme هي تحسين تدريجي. وستتجاهل المتصفّحات التي لا تتوافق مع هذه السمة وتستخدم واجهة المستخدم التلقائية في الوضع الفاتح.

للتكيّف مع الإعدادات المفضّلة للمستخدم في المتصفّحات القديمة، استخدِم الاستعلامات عن الوسائط prefers-color-scheme لتوفير ألوان مختلفة عندما يكون الوضع الداكن مفضّلاً.

• استخدِم الاستعلام عن الوسائط لتبديل السمات المخصّصة في :root أو html
• تجنَّب استخدام الاستعلام عن الوسائط على مكوّنات فردية ما لم يتطلّب المكوّن نوعًا محدّدًا جدًا من تخصيص الوضع الداكن يتجاوز الألوان.

:root {
  /* Define brand colors for each mode */
  --color-brand-light: #0056b3;
  --color-brand-dark: #00e5ff;
  --color-brand: var(--color-brand-light);

  /* MANDATORY: Fallback for browsers without light-dark support */
  @media (prefers-color-scheme: dark) {
    --color-brand: var(--color-brand-dark);
  }

  /* Ignored in older browsers */
  color-scheme: light dark;
}

button.primary {
    background-color: var(--color-brand);
}

الخيارات الاحتياطية وتوافق المتصفّح مع دالة light-dark()‎

بالنسبة إلى المتصفّحات التي تتيح استخدام color-scheme ولكنّها لا تتيح استخدام light-dark() بعد، يجب أولاً تحديد نُسخ الألوان الفاتحة والداكنة كخصائص مخصّصة، ويجب استخدام الاستعلام عن الوسائط prefers-color-scheme لضبط الألوان للوضع المعنيّ كما في المثال أدناه:

:root {
  /* Define browser UI accent color for each mode */
  --brand-accent-light: #0056b3;
  --brand-accent-dark: #00e5ff;
  --accent-color: var(--brand-accent-light);

  /* MANDATORY: Fallback for browsers without light-dark support */
  @media (prefers-color-scheme: dark) {
    --accent-color: var(--brand-accent-dark);
  }

  /* OPTIONAL: use light-dark() for more control of built-in UI colors */
  @supports (color: light-dark(white, black)) {
    --accent-color: light-dark(var(--brand-accent-light), var(--brand-accent-dark));
  }

  /* MANDATORY: Automatically adapt native UI to user system preferences */
  color-scheme: light dark;

  /* Example inherited color property */
  accent-color: var(--accent-color);
}

pre, code {
  color-scheme: dark;

  /* **Mandatory**: any inherited color properties must be set again, even if to the same design tokens */
  accent-color: var(--accent-color);
}

القيم الاحتياطية وتوافق المتصفّحات مع قيم الصور light-dark()‎

بالنسبة إلى المتصفّحات التي لا تتيح استخدام السمة light-dark() للصور، استخدِم السمة image-set() كمفتاح تبديل: امنح كل خيار السمة type() من خاصية مخصّصة، واضبط الخيار غير النشط على نوع MIME غير متوافق ليتجاهل المتصفّح هذا الخيار. يحصل الخيار النشط على قيمة فارغة، لذا فهو خيار image-set() عادي بدون type().

حدِّد مفتاح التحكّم مرة واحدة على :root. بعد ذلك، يحتاج كل موقع استخدام إلى الصورتَين المضمّنتَين فقط، مثل light-dark().

:root {
  --light-type: ;
  --dark-type: type("image/do-not-use");

  /* MANDATORY: Fallback for browsers without light-dark() image support */
  @media (prefers-color-scheme: dark) {
    --light-type: type("image/do-not-use");
    --dark-type: ;
  }
}

.hero {
  background-image: image-set(url(hero-light.png) var(--light-type), url(hero-dark.png) var(--dark-type));

  @supports (background-image: light-dark(url("a"), url("b"))) {
    background-image: light-dark(url(hero-light.png), url(hero-dark.png));
  }
}

• يتم تنزيل الصورة المحدّدة فقط.
• لا تزال الحلول تعمل: image-set(url(a-1x.png) 1x var(--light-type), url(a-2x.png) 2x var(--light-type), url(b-1x.png) 1x var(--dark-type), url(b-2x.png) 2x var(--dark-type)).
• لا تستخدِم type("") للخيار النشط. تتعامل المتصفحات مع السلسلة الفارغة على أنّها غير متوافقة وتتجاهل كل خيار.
• على عكس light-dark()، لا يتّبع مفتاح التبديل color-scheme الذي تم ضبطه على شجرة فرعية. يجب أيضًا أن يؤدي زر التبديل اليدوي أو أي شجرة فرعية تضبط color-scheme إلى تبديل --light-type و--dark-type.

بديل: خاصية مخصّصة واحدة لكل صورة

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

:root {
  --hero-image: url(hero-light.png);

  @media (prefers-color-scheme: dark) {
    --hero-image: url(hero-dark.png);
  }

  @supports (background-image: light-dark(url("a"), url("b"))) {
    --hero-image: light-dark(url(hero-light.png), url(hero-dark.png));
  }
}

.hero {
  background-image: var(--hero-image);
}

الخيارات الاحتياطية وتوافق المتصفّح مع image()‎

استخدِم تدرجًا مع نقطة توقف لون واحدة وبدون مواضع، مثل linear-gradient(blue).

لإتاحة استخدام المتصفّحات على نطاق أوسع، يمكنك تقديم مواضع 0 100% بشكل صريح لنقطة توقّف اللون الواحد، مثل linear-gradient(blue 0 100%).

الخيارات الاحتياطية وتوافق المتصفّح مع scrollbar-color

هذه الميزة هي تحسين تدريجي ولا تتطلب دائمًا إجراءات احتياطية.

إذا كان التنسيق مهمًا وكان هدف Baseline للمستخدم هو "Baseline Widely Available" أو إصدار أقدم، يجب تضمين العناصر الزائفة ::-webkit-scrollbar غير العادية كبدائل.

يمكنك تضمين العناصر الاحتياطية القديمة في مجموعة @supports not (scrollbar-color: auto) لمنع حدوث تعارضات بين السمات العادية ومحدّدات WebKit القديمة في المتصفحات التي تتيح كليهما بشكلٍ أصلي.

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

/* Legacy fallback for WebKit/Blink browsers */
@supports not (scrollbar-color: auto) {
  .scroller::-webkit-scrollbar {
    /* Must define base size in WebKit for custom colors to be visual */
    width: 12px;
    height: 12px;
  }

  .scroller::-webkit-scrollbar-thumb {
    background: var(--scrollbar-thumb);
  }

  .scroller::-webkit-scrollbar-track {
    background: var(--scrollbar-track);
  }
}

الخيارات الاحتياطية وتوافق المتصفّح مع السمة accent-color

سمة accent-color هي تحسين تدريجي. وستتجاهل المتصفّحات التي لا تتوافق مع هذه السمة هذه السمة وتستخدم ألوان واجهة المستخدم التلقائية.