bilingual-jekyll-resume-theme 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a160407a794060fef19ecf9df069af68dd152f04903fca2df9be92e6739a0e1
-  data.tar.gz: 6d8df24a03c4031c201789dafd68785e83841e15c61c096ded7981e431957008
+  metadata.gz: 6e8574055be713050db1441e0981a7b13b74baf53ea093a39f25879a41ae059b
+  data.tar.gz: 13d1c501de2bc80f4873f07f352d9d592d01e6ee63ed9d359bfc99a8d62f4477
 SHA512:
-  metadata.gz: fd7ac5fa5738962bf6a1a2f52b0d76809b7d7ceb195b8e16b6d06ea6767b3e8230520f940654cfb33c09d8b56cfca1dfe552fd7707cde23ce46a6ea97f14abd6
-  data.tar.gz: e9acabde4734416d1350a24a0aab3356da47bec4f6f37c56752760a667a3387d2eaa2aab57605f35d352a9ef9e25b2a249a7366050b1beacd998f5d5a086a0d8
+  metadata.gz: fa85fa7fd0aa1d84fa61e7b59f5ad3d4927c22bde26f4e1cc77503ccfea4fdfd50c8a05e15ce0417b06b8750d5dc40bdefe6271fee76bd92b3dbedc83430ada6
+  data.tar.gz: 1a40a6c189b45e7ebd34683da30c9daf720ed342b6662a3f2c33bfd9dce22869daffd133b604791b2aaaa5ff15b267d6a0f38e4d50e989b91c65c6c71ff1fadf

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.6.0] - 2026-08-21
+
+### Added
+* Add CLAUDE.md for AI coding assistant guidance and project documentation ([`d68bb03`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/d68bb031043eb88dc7bc6eaaa30a00867f7f7afc))
+
+
+### Changed
+* Add dark mode toggle with system preference detection ([`2dcb813`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/2dcb8135817d05f97d8705ea09bfb326d244cd3d))
+
+* Enhance CLAUDE.md with comprehensive project documentation and guidance for AI assistants ([`b3facba`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/b3facba6cac2caf853d3f70243dd8a9a2f87ab53))
+
+* Revise SECURITY.md with version support and monitoring ([`34c78a0`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/34c78a08ee5e96fd0667b9896c07f6e18e380dd0))
+
+* Potential fix for code scanning alert no. 1: Workflow does not contain permissions ([`915f9e7`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/915f9e77982a962e3eda844263d65b5a4ffb849b))
+
 ## [0.5.2] - 2026-05-09
 
 ### Added
@@ -143,7 +158,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Initial commit (New Theme Template) ([`00af662`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/00af6628dfec7aefe0ef7d7083bf98c9713a5ffd))
 
-[0.5.2]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.1...0.5.2
+[0.6.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.2...v0.6.0
+[0.5.2]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.3.1...v0.4.0

data/_includes/dark-mode-toggle.html

@@ -0,0 +1,177 @@
+<!-- Dark Mode Toggle Button (Two-state: System Default vs Pinned Override) -->
+<button
+  id="dark-mode-toggle"
+  class="dark-mode-toggle no-print"
+  type="button"
+  aria-label="Switch to dark mode"
+  title="Switch to dark mode"
+  aria-pressed="false"
+  data-pinned="false"
+>
+  <!-- Sun Icon: Visible in dark mode / indicates switching to light mode -->
+  <svg
+    class="dark-mode-icon dark-mode-icon-sun"
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <circle cx="12" cy="12" r="5"></circle>
+    <line x1="12" y1="1" x2="12" y2="3"></line>
+    <line x1="12" y1="21" x2="12" y2="23"></line>
+    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+    <line x1="1" y1="12" x2="3" y2="12"></line>
+    <line x1="21" y1="12" x2="23" y2="12"></line>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+  </svg>
+
+  <!-- Moon Icon: Visible in light mode / indicates switching to dark mode -->
+  <svg
+    class="dark-mode-icon dark-mode-icon-moon"
+    xmlns="http://www.w3.org/2000/svg"
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"></path>
+  </svg>
+</button>
+
+<script>
+  (function () {
+    var toggleBtn = document.getElementById('dark-mode-toggle');
+    if (!toggleBtn) return;
+
+    var metaTheme = document.querySelector('meta[name="color-scheme"]');
+
+    function getSystemTheme() {
+      if (window.matchMedia) {
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      return 'light';
+    }
+
+    function getSavedTheme() {
+      try {
+        var val = localStorage.getItem('color-scheme');
+        if (val === 'dark' || val === 'light') {
+          return val;
+        }
+        return null;
+      } catch (e) {
+        return null;
+      }
+    }
+
+    function isArabicRTL() {
+      var docEl = document.documentElement;
+      var dir = docEl.getAttribute('dir');
+      var lang = docEl.getAttribute('lang') || docEl.lang;
+      return dir === 'rtl' || lang === 'ar';
+    }
+
+    function syncState() {
+      var saved = getSavedTheme();
+      if (saved !== null) {
+        document.documentElement.setAttribute('data-color-scheme', saved);
+        document.documentElement.setAttribute('data-theme', saved);
+        if (metaTheme) {
+          metaTheme.setAttribute('content', saved);
+        }
+      } else {
+        document.documentElement.removeAttribute('data-color-scheme');
+        document.documentElement.removeAttribute('data-theme');
+        if (metaTheme) {
+          metaTheme.setAttribute('content', 'light dark');
+        }
+      }
+    }
+
+    function updateUI() {
+      var saved = getSavedTheme();
+      var isPinned = (saved !== null);
+      var effectiveTheme = isPinned ? saved : getSystemTheme();
+      var isRTL = isArabicRTL();
+      var label = '';
+
+      toggleBtn.setAttribute('data-pinned', isPinned ? 'true' : 'false');
+      toggleBtn.setAttribute('aria-pressed', isPinned ? 'true' : 'false');
+      toggleBtn.setAttribute('data-current-theme', effectiveTheme);
+
+      if (isPinned) {
+        label = isRTL
+          ? 'إعادة ضبط المظهر إلى الوضع التلقائي للنظام'
+          : 'Reset to system theme';
+      } else {
+        var nextTheme = (effectiveTheme === 'dark') ? 'light' : 'dark';
+        if (isRTL) {
+          label = (nextTheme === 'dark')
+            ? 'تبديل إلى الوضع الداكن'
+            : 'تبديل إلى الوضع الفاتح';
+        } else {
+          label = (nextTheme === 'dark')
+            ? 'Switch to dark mode'
+            : 'Switch to light mode';
+        }
+      }
+
+      toggleBtn.setAttribute('aria-label', label);
+      toggleBtn.setAttribute('title', label);
+    }
+
+    function toggleTheme() {
+      var saved = getSavedTheme();
+      if (saved !== null) {
+        // Currently pinned -> reset to system default
+        try {
+          localStorage.removeItem('color-scheme');
+        } catch (e) {}
+        syncState();
+      } else {
+        // Currently unpinned -> pin opposite of current system setting
+        var systemTheme = getSystemTheme();
+        var targetTheme = (systemTheme === 'dark') ? 'light' : 'dark';
+        try {
+          localStorage.setItem('color-scheme', targetTheme);
+        } catch (e) {}
+        syncState();
+      }
+      updateUI();
+    }
+
+    toggleBtn.addEventListener('click', toggleTheme);
+
+    if (window.matchMedia) {
+      var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      var mqListener = function () {
+        if (!getSavedTheme()) {
+          updateUI();
+        }
+      };
+      if (darkQuery.addEventListener) {
+        darkQuery.addEventListener('change', mqListener);
+      } else if (darkQuery.addListener) {
+        darkQuery.addListener(mqListener);
+      }
+    }
+
+    syncState();
+    updateUI();
+  })();
+</script>

data/_includes/shared-head.html

@@ -1,6 +1,24 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<script>
+  (function() {
+    try {
+      var saved = localStorage.getItem('color-scheme');
+      if (saved === 'dark' || saved === 'light') {
+        document.documentElement.setAttribute('data-color-scheme', saved);
+        document.documentElement.setAttribute('data-theme', saved);
+        var meta = document.querySelector('meta[name="color-scheme"]');
+        if (meta) {
+          meta.setAttribute('content', saved);
+        }
+      }
+    } catch (e) {
+      // Graceful fallback if localStorage is restricted (private browsing / iframe sandboxing)
+    }
+  })();
+</script>
 
 <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
 <link rel="icon" href="favicon.ico" type="image/x-icon">

data/_layouts/resume-ar.html

@@ -159,6 +159,10 @@ resume_data.experience == site.data['2025-06']['20250621-PM'].experience
     <body class="theme-{% if site.resume_theme %}{{ site.resume_theme }}{% endif %}">
 
         <div class="wrapper" itemscope itemtype="http://schema.org/Person">
+            {% if site.resume_dark_mode == "enabled" %}
+                {% include dark-mode-toggle.html %}
+            {% endif %}
+
             <meta itemprop="telephone" content="{{ site.contact_info.phone }}" />
             <meta itemprop="address" content="{{ site.contact_info.address }}" />
 

data/_layouts/resume-en.html

@@ -159,6 +159,10 @@ resume_data.experience == site.data['2025-06']['20250621-PM'].experience
     <body class="theme-{% if site.resume_theme %}{{ site.resume_theme }}{% endif %}">
 
         <div class="wrapper" itemscope itemtype="http://schema.org/Person">
+            {% if site.resume_dark_mode == "enabled" %}
+                {% include dark-mode-toggle.html %}
+            {% endif %}
+
             <meta itemprop="telephone" content="{{ site.contact_info.phone }}" />
             <meta itemprop="address" content="{{ site.contact_info.address }}" />
 

data/_sass/_all-pages.scss

@@ -2,35 +2,25 @@
 
 .svg-icon,
 svg {
-  fill: #BBB;
+  fill: var(--icon-fill-muted, #BBB);
   width: 30px;
 }
 
 .svg-icon:hover,
 svg:hover {
-  fill: #000;
+  fill: var(--icon-fill-dark, #000);
 }
 
 /* Following only apply to the resume header contact info icons */
 .header-contact-info>p>svg {
   width: 20px;
-  fill: #000;
+  fill: var(--icon-fill-dark, #000);
   vertical-align: middle;
 }
 
 
 /* Footer */
 
-/* Old
-footer {
-    color: rgba(0, 0, 0, 1);
-    width: 100%;
-    margin: 50px auto;
-    text-align: center;
-    flex: none;
-}
-*/
-
 footer,
 .page-footer {
   padding-top: 1.5rem;
@@ -41,11 +31,11 @@ footer,
   .copyright {
     margin: 0;
     font-size: .875rem;
-    color: #999;
+    color: var(--text-muted, #999);
 
     >a {
       font-weight: 700;
-      color: #333;
+      color: var(--link-color, #333);
     }
   }
 }

data/_sass/_base.scss

@@ -11,12 +11,12 @@
 }
 
 html {
-  background: variables.$white;
+  background: var(--bg-color, variables.$white);
 }
 
 body {
   @include mixins.serif;
-  color: variables.$text_color;
+  color: var(--text-color, variables.$text_color);
   font-size: 16px;
   line-height: 1.5;
 }
@@ -56,13 +56,13 @@ body {
 }
 
 ::-moz-selection {
-  background: rgba(51, 51, 51, .8);
-  color: #fff;
+  background: var(--selection-bg, rgba(51, 51, 51, .8));
+  color: var(--selection-color, #fff);
   text-shadow: none;
 }
 
 ::selection {
-  background: rgba(51, 51, 51, .8);
-  color: #fff;
+  background: var(--selection-bg, rgba(51, 51, 51, .8));
+  color: var(--selection-color, #fff);
   text-shadow: none;
 }

data/_sass/_dark-mode.scss

@@ -0,0 +1,365 @@
+// ==========================================================================
+// Dark Mode System Tokens & Overrides
+// bilingual-jekyll-resume-theme
+// ==========================================================================
+
+:root {
+  color-scheme: light dark;
+
+  // --- Background & Primary Typography ---
+  --bg-color: #ffffff;
+  --text-color: #333;
+  --text-muted: #999;
+  --text-light: #646464;
+  --border-color: #c7c7c7;
+  --card-bg: #efefef;
+
+  // --- Links & Navigation ---
+  --link-color: #333;
+  --link-hover: #9c9c9c;
+  --link-hover-color: var(--link-hover);
+
+  // --- Accent & Brand Colors ---
+  --accent-color: #3064a9;
+  --accent-hover: #307EA9;
+  --accent-hover-color: var(--accent-hover);
+  --social-hover-color: var(--accent-hover);
+  --about-color: var(--text-light);
+
+  // --- Footer ---
+  --footer-text-color: var(--text-muted);
+  --footer-link-color: var(--link-color);
+
+  // --- Icons & Graphics ---
+  --icon-fill: #333;
+  --icon-fill-muted: #BBB;
+  --icon-fill-dark: #000;
+  --icon-hover-fill: var(--icon-fill-dark);
+  --header-icon-fill: var(--icon-fill-dark);
+
+  // --- Buttons (.contact-button, .cv-button) ---
+  --button-bg: #efefef;
+  --button-text: #333;
+  --button-hover-bg: #333;
+  --button-hover-text: #fff;
+
+  // --- Text Selection ---
+  --selection-bg: rgba(51, 51, 51, .8);
+  --selection-color: #fff;
+
+  // --- Dark Mode Toggle Component Tokens ---
+  --toggle-btn-bg: transparent;
+  --toggle-btn-border: var(--border-color);
+  --toggle-btn-color: var(--text-color);
+  --toggle-btn-hover-bg: var(--button-bg);
+  --toggle-btn-focus-ring: var(--accent-color);
+}
+
+// --------------------------------------------------------------------------
+// Automatic System Dark Mode (@media prefers-color-scheme)
+// --------------------------------------------------------------------------
+@media (prefers-color-scheme: dark) {
+  :root:not([data-color-scheme="light"]):not([data-theme="light"]) {
+    --bg-color: #121212;
+    --text-color: #e0e0e0;
+    --text-muted: #888888;
+    --text-light: #aaaaaa;
+    --border-color: #333333;
+    --card-bg: #1e1e1e;
+
+    --link-color: #e0e0e0;
+    --link-hover: #ffffff;
+    --link-hover-color: var(--link-hover);
+
+    --accent-color: #6ba4e8;
+    --accent-hover: #8cbcf3;
+    --accent-hover-color: var(--accent-hover);
+    --social-hover-color: var(--accent-hover);
+    --about-color: var(--text-light);
+
+    --footer-text-color: var(--text-muted);
+    --footer-link-color: var(--link-color);
+
+    --icon-fill: #e0e0e0;
+    --icon-fill-muted: #666666;
+    --icon-fill-dark: #ffffff;
+    --icon-hover-fill: var(--icon-fill-dark);
+    --header-icon-fill: var(--icon-fill-dark);
+
+    --button-bg: #2a2a2a;
+    --button-text: #e0e0e0;
+    --button-hover-bg: #444444;
+    --button-hover-text: #ffffff;
+
+    --selection-bg: rgba(107, 164, 232, .5);
+    --selection-color: #ffffff;
+
+    --toggle-btn-border: var(--border-color);
+    --toggle-btn-color: var(--text-color);
+    --toggle-btn-hover-bg: var(--button-bg);
+    --toggle-btn-focus-ring: var(--accent-color);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Forced Dark Override (Pinned via toggle or explicit attribute)
+// --------------------------------------------------------------------------
+:root[data-color-scheme="dark"],
+:root[data-theme="dark"],
+[data-color-scheme="dark"],
+[data-theme="dark"],
+html.dark {
+  color-scheme: dark;
+  --bg-color: #121212;
+  --text-color: #e0e0e0;
+  --text-muted: #888888;
+  --text-light: #aaaaaa;
+  --border-color: #333333;
+  --card-bg: #1e1e1e;
+
+  --link-color: #e0e0e0;
+  --link-hover: #ffffff;
+  --link-hover-color: var(--link-hover);
+
+  --accent-color: #6ba4e8;
+  --accent-hover: #8cbcf3;
+  --accent-hover-color: var(--accent-hover);
+  --social-hover-color: var(--accent-hover);
+  --about-color: var(--text-light);
+
+  --footer-text-color: var(--text-muted);
+  --footer-link-color: var(--link-color);
+
+  --icon-fill: #e0e0e0;
+  --icon-fill-muted: #666666;
+  --icon-fill-dark: #ffffff;
+  --icon-hover-fill: var(--icon-fill-dark);
+  --header-icon-fill: var(--icon-fill-dark);
+
+  --button-bg: #2a2a2a;
+  --button-text: #e0e0e0;
+  --button-hover-bg: #444444;
+  --button-hover-text: #ffffff;
+
+  --selection-bg: rgba(107, 164, 232, .5);
+  --selection-color: #ffffff;
+
+  --toggle-btn-border: var(--border-color);
+  --toggle-btn-color: var(--text-color);
+  --toggle-btn-hover-bg: var(--button-bg);
+  --toggle-btn-focus-ring: var(--accent-color);
+}
+
+// --------------------------------------------------------------------------
+// Forced Light Override (Pinned via toggle on dark OS)
+// --------------------------------------------------------------------------
+:root[data-color-scheme="light"],
+:root[data-theme="light"],
+[data-color-scheme="light"],
+[data-theme="light"],
+html.light {
+  color-scheme: light;
+  --bg-color: #ffffff;
+  --text-color: #333;
+  --text-muted: #999;
+  --text-light: #646464;
+  --border-color: #c7c7c7;
+  --card-bg: #efefef;
+
+  --link-color: #333;
+  --link-hover: #9c9c9c;
+  --link-hover-color: var(--link-hover);
+
+  --accent-color: #3064a9;
+  --accent-hover: #307EA9;
+  --accent-hover-color: var(--accent-hover);
+  --social-hover-color: var(--accent-hover);
+  --about-color: var(--text-light);
+
+  --footer-text-color: var(--text-muted);
+  --footer-link-color: var(--link-color);
+
+  --icon-fill: #333;
+  --icon-fill-muted: #BBB;
+  --icon-fill-dark: #000;
+  --icon-hover-fill: var(--icon-fill-dark);
+  --header-icon-fill: var(--icon-fill-dark);
+
+  --button-bg: #efefef;
+  --button-text: #333;
+  --button-hover-bg: #333;
+  --button-hover-text: #fff;
+
+  --selection-bg: rgba(51, 51, 51, .8);
+  --selection-color: #fff;
+
+  --toggle-btn-border: var(--border-color);
+  --toggle-btn-color: var(--text-color);
+  --toggle-btn-hover-bg: var(--button-bg);
+  --toggle-btn-focus-ring: var(--accent-color);
+}
+
+// --------------------------------------------------------------------------
+// Print Media Override (Always clean light background for printing)
+// --------------------------------------------------------------------------
+@media print {
+  :root,
+  :root[data-color-scheme="dark"],
+  :root[data-color-scheme="light"],
+  :root[data-theme="dark"],
+  :root[data-theme="light"],
+  [data-color-scheme="dark"],
+  [data-theme="dark"],
+  html.dark,
+  html.light {
+    color-scheme: light !important;
+    --bg-color: #ffffff !important;
+    --text-color: #000000 !important;
+    --text-muted: #666 !important;
+    --text-light: #444 !important;
+    --border-color: #c7c7c7 !important;
+    --card-bg: #fff !important;
+
+    --link-color: #000 !important;
+    --link-hover: #000 !important;
+    --link-hover-color: #000 !important;
+
+    --accent-color: #000 !important;
+    --accent-hover: #000 !important;
+    --accent-hover-color: #000 !important;
+    --social-hover-color: #000 !important;
+    --about-color: #444 !important;
+
+    --footer-text-color: #666 !important;
+    --footer-link-color: #000 !important;
+
+    --icon-fill: #000 !important;
+    --icon-fill-muted: #666 !important;
+    --icon-fill-dark: #000 !important;
+    --icon-hover-fill: #000 !important;
+    --header-icon-fill: #000 !important;
+
+    --button-bg: #fff !important;
+    --button-text: #000 !important;
+    --button-hover-bg: #fff !important;
+    --button-hover-text: #000 !important;
+
+    --selection-bg: transparent !important;
+    --selection-color: #000 !important;
+  }
+
+  html,
+  body {
+    background-color: #fff !important;
+    color: #000 !important;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+
+  .dark-mode-toggle,
+  #dark-mode-toggle {
+    display: none !important;
+  }
+}
+
+// --------------------------------------------------------------------------
+// Toggle Button Component Styling
+// --------------------------------------------------------------------------
+.dark-mode-toggle {
+  position: fixed;
+  top: 1.25rem;
+  right: 1.25rem;
+  z-index: 1000;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  padding: 0;
+  background: var(--bg-color);
+  color: var(--toggle-btn-color);
+  border: 1px solid var(--toggle-btn-border);
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  transition: background-color 0.2s ease, border-color 0.2s ease, transform 0.2s ease;
+
+  &:hover {
+    background-color: var(--toggle-btn-hover-bg);
+    transform: scale(1.05);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--toggle-btn-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .dark-mode-icon {
+    width: 1.25rem;
+    height: 1.25rem;
+    stroke: currentColor;
+    transition: transform 0.3s ease;
+  }
+
+  // Baseline Light Mode: Show Moon, Hide Sun
+  .dark-mode-icon-sun {
+    display: none;
+  }
+  .dark-mode-icon-moon {
+    display: block;
+  }
+}
+
+// Media Query System Dark Mode (when not overridden to Light)
+@media (prefers-color-scheme: dark) {
+  :root:not([data-color-scheme="light"]):not([data-theme="light"]) {
+    .dark-mode-toggle {
+      .dark-mode-icon-sun {
+        display: block;
+      }
+      .dark-mode-icon-moon {
+        display: none;
+      }
+    }
+  }
+}
+
+// Pinned Dark Override: Show Sun, Hide Moon
+:root[data-color-scheme="dark"],
+:root[data-theme="dark"],
+[data-color-scheme="dark"],
+[data-theme="dark"],
+html.dark {
+  .dark-mode-toggle {
+    .dark-mode-icon-sun {
+      display: block;
+    }
+    .dark-mode-icon-moon {
+      display: none;
+    }
+  }
+}
+
+// Pinned Light Override: Show Moon, Hide Sun
+:root[data-color-scheme="light"],
+:root[data-theme="light"],
+[data-color-scheme="light"],
+[data-theme="light"],
+html.light {
+  .dark-mode-toggle {
+    .dark-mode-icon-sun {
+      display: none;
+    }
+    .dark-mode-icon-moon {
+      display: block;
+    }
+  }
+}
+
+// RTL layout positioning
+html[dir="rtl"] {
+  .dark-mode-toggle {
+    right: auto;
+    left: 1.25rem;
+  }
+}

data/_sass/_mixins.scss

@@ -99,13 +99,13 @@
 // layout
 
 @mixin section_border {
-  border-top: 4px solid #c7c7c7;
-  border-bottom: 2px solid #c7c7c7;
+  border-top: 4px solid var(--border-color, #c7c7c7);
+  border-bottom: 2px solid var(--border-color, #c7c7c7);
   padding: .2rem 0 .4rem;
 }
 
 @mixin section_border_thin {
-  border-top: 1px solid #c7c7c7;
-  border-bottom: 1px solid #c7c7c7;
+  border-top: 1px solid var(--border-color, #c7c7c7);
+  border-bottom: 1px solid var(--border-color, #c7c7c7);
   padding: .2rem 0 .2rem;
 }

data/_sass/_profile.scss

@@ -1,5 +1,10 @@
+html {
+  background-color: var(--bg-color, #fff);
+}
+
 body {
-  color: #333;
+  background-color: var(--bg-color, #fff);
+  color: var(--text-color, #333);
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
   line-height: 1;
   margin: 10% 0 8%;
@@ -24,7 +29,7 @@ body {
 }
 
 .about {
-  color: #646464;
+  color: var(--text-light, #646464);
   font-size: 87.5%;
   padding-bottom: 14px;
   line-height: .6cm;
@@ -38,7 +43,7 @@ body {
 }
 
 a:hover {
-  color: #3064a9;
+  color: var(--accent-color, #3064a9);
 }
 
 .social-links li {
@@ -47,16 +52,16 @@ a:hover {
 }
 
 .social-links li a {
-  color: #BBB;
+  color: var(--icon-fill-muted, #BBB);
 }
 
 .social-links li a:hover {
-  color: #307EA9;
+  color: var(--accent-hover, #307EA9);
 }
 
 .cv-button {
   border-radius: 3px;
-  background-color: #efefef;
+  background-color: var(--button-bg, #efefef);
   text-decoration: none;
   text-align: center;
   display: block;
@@ -64,12 +69,12 @@ a:hover {
   width: 220px;
   font-size: 1.375rem;
   font-weight: 300;
-  color: #333;
+  color: var(--button-text, #333);
   line-height: 55px;
   transition: (all .2s ease);
 }
 
 .cv-button:hover {
-  background-color: #333;
-  color: #fff;
+  background-color: var(--button-hover-bg, #333);
+  color: var(--button-hover-text, #fff);
 }

data/_sass/_resume-rtl.scss

@@ -66,4 +66,10 @@ html[dir="rtl"] {
   .page-footer {
     text-align: center; // keep centered
   }
+
+  // Dark mode toggle positioning for RTL
+  .dark-mode-toggle {
+    right: auto;
+    left: 1.25rem;
+  }
 }

data/_sass/_resume.scss

@@ -88,7 +88,7 @@
   position: relative;
   top: 4px;
   text-align: center;
-  border-top: 2px solid #c7c7c7;
+  border-top: 2px solid var(--border-color, #c7c7c7);
   padding-top: .4rem;
 
   @include mixins.media_larger_than_mobile {
@@ -106,7 +106,7 @@
     display: inline-block;
 
     &:hover .icon path {
-      fill: #333;
+      fill: var(--icon-fill, #333);
       @include mixins.transition(all .2s ease);
     }
   }
@@ -118,7 +118,7 @@
 
 .contact-button {
   @include mixins.border-radius(3px);
-  background-color: #efefef;
+  background-color: var(--button-bg, #efefef);
   text-decoration: none;
   text-align: center;
   display: block;
@@ -126,13 +126,13 @@
   width: 220px;
   font-size: 1.375rem;
   @include mixins.sans_light;
-  color: #333;
+  color: var(--button-text, #333);
   line-height: 55px;
   @include mixins.transition(all .2s ease);
 
   &:hover {
-    background-color: #333;
-    color: #fff;
+    background-color: var(--button-hover-bg, #333);
+    color: var(--button-hover-text, #fff);
   }
 
   &.not-looking {
@@ -172,13 +172,13 @@
   .resume-item-copy,
   .resume-item-list {
     a {
-      color: #333;
+      color: var(--link-color, #333);
       text-decoration: none;
       border-bottom: 1px solid;
 
       &:hover {
         border-bottom: none;
-        color: #9c9c9c;
+        color: var(--link-hover, #9c9c9c);
       }
     }
   }
@@ -261,7 +261,7 @@
 // footer styles
 
 .page-footer {
-  border-top: 4px solid #c7c7c7;
+  border-top: 4px solid var(--border-color, #c7c7c7);
   padding-top: 1.5rem;
   text-align: center;
   margin-bottom: 3rem;
@@ -269,11 +269,11 @@
   .footer-line {
     margin: 0;
     font-size: .875rem;
-    color: #999;
+    color: var(--text-muted, #999);
 
     >a {
       font-weight: 700;
-      color: #333;
+      color: var(--link-color, #333);
     }
   }
 }

data/_sass/_variables.scss

@@ -5,11 +5,11 @@ $container-width: 980px !default;
 $grid-gutter: 10px !default;
 
 // Colors
-$white: #fff;
-$black: #333;
+$white: var(--bg-color, #fff);
+$black: var(--text-color, #333);
 
 // Styles
-$text_color: $black;
+$text_color: var(--text-color, #333);
 
 // Font stack
 $body-font: Helvetica,

data/assets/css/cv-ar.scss

@@ -6,6 +6,7 @@
 @use "normalize";
 @use "mixins";
 @use "variables";
+@use "dark-mode";
 
 // Generic site base & layout styles
 @use "base";

data/assets/css/cv.scss

@@ -5,6 +5,7 @@
 @use "normalize";
 @use "mixins";
 @use "variables";
+@use "dark-mode";
 
 // Generic site base & layout styles
 @use "base";

data/assets/css/main.scss

@@ -2,5 +2,6 @@
 --- 
 // "Reset" styles and SCSS reusable components
 @use "normalize";
+@use "dark-mode";
 @use "profile";
 @use "all-pages";

data/docs/CONFIG_GUIDE.md

@@ -16,6 +16,7 @@ Make your site render correctly with this theme. This guide matches the shipped
 - [Social links](#social-links)
 - [Analytics](#analytics)
 - [Design and authors](#design-and-authors)
+- [Dark Mode](#dark-mode)
 - [Jekyll build settings](#jekyll-build-settings)
 - [Full example config](#full-example-config)
 - [FAQs](#faqs)
@@ -193,6 +194,86 @@ Choose one (do not enable both):
 
 ---
 
+## Dark Mode
+
+The theme features built-in, accessible dark mode support with automatic system preference detection via `prefers-color-scheme` and an optional interactive two-state manual toggle.
+
+### Configuration (`resume_dark_mode`)
+
+Configure dark mode behavior in your `_config.yml` using the `resume_dark_mode` option:
+
+```yaml
+# Dark mode configuration (options: auto | enabled)
+resume_dark_mode: auto
+```
+
+#### Accepted Values
+
+- **`auto`** (default):
+  - Pure CSS-first system detection via `@media (prefers-color-scheme: dark)` and `:root { color-scheme: light dark; }`.
+  - Automatically switches between light and dark palettes to match the visitor's operating system / browser theme.
+  - **No toggle button is rendered in the HTML**, resulting in zero JavaScript runtime overhead and no layout shifts.
+  - If `resume_dark_mode` is omitted or not defined, the theme safely defaults to `auto`.
+
+- **`enabled`**:
+  - Full automatic system detection **plus** an interactive floating toggle button rendered on resume pages (`resume-en.html` and `resume-ar.html`).
+  - Allows visitors to manually override their system color scheme.
+  - Preference is persisted across visits and pages via `localStorage`.
+
+### Two-State Toggle & State Machine
+
+When `resume_dark_mode: enabled` is configured, the toggle operates as a predictable two-state finite state machine (FSM):
+
+1. **State A: System Default (Unpinned)**
+   - Initial state when no preference is stored in `localStorage` (`color-scheme` key is `null`).
+   - The theme strictly follows the visitor's OS setting (`prefers-color-scheme`).
+   - Live media query listeners (`window.matchMedia`) dynamically update toggle accessibility labels if the OS theme shifts during the session.
+   - Clicking the toggle transitions to **State B (Pinned)**, forcing the *opposite* of the active system theme (e.g., clicking on a light OS pins dark mode).
+
+2. **State B: Forced Override (Pinned)**
+   - The chosen scheme (`"dark"` or `"light"`) is saved in `localStorage` under the key `color-scheme`.
+   - The `<html>` element receives `data-color-scheme` and `data-theme` attributes, and `<meta name="color-scheme">` is updated to match.
+   - Clicking the toggle again clears the `localStorage` key and transitions back to **State A (System Default)**.
+
+### Anti-FOUC (Flash of Unstyled Content) Prevention
+
+To eliminate any visual flash or layout shift for returning visitors:
+- A synchronous, non-deferred `<script>` tag is executed in the document `<head>` (via `_includes/shared-head.html`) immediately after `<meta name="color-scheme" content="light dark">`.
+- It reads `localStorage.getItem('color-scheme')` before DOM rendering starts and synchronously applies `data-color-scheme` / `data-theme` to the root element.
+
+### Bilingual Accessibility & RTL Parity
+
+The toggle component is designed for WCAG 2.1 AA compliance:
+- **Keyboard navigation**: Fully focusable with a high-contrast `:focus-visible` focus ring; toggles via <kbd>Enter</kbd> or <kbd>Space</kbd>.
+- **Screen readers**: Dynamic `aria-label` and `title` attributes announce the current action and target theme state in both English (LTR) and Arabic (RTL):
+  - **English (LTR)**:
+    - Unpinned (System Light): `"Switch to dark mode"`
+    - Unpinned (System Dark): `"Switch to light mode"`
+    - Pinned: `"Reset to system theme"`
+  - **Arabic (RTL)**:
+    - Unpinned (System Light): `"تبديل إلى الوضع الداكن"`
+    - Unpinned (System Dark): `"تبديل إلى الوضع الفاتح"`
+    - Pinned: `"إعادة ضبط المظهر إلى الوضع التلقائي للنظام"`
+- **RTL positioning**: In Arabic layouts (`resume-ar.html`), the toggle automatically repositions to the top-left (`left: 1.5rem`) to maintain balanced spacing relative to RTL content.
+
+### Print Media Behavior
+
+When printing or exporting to PDF:
+- The toggle button is automatically hidden via the `.no-print` class and `@media print { display: none !important; }`.
+- Print styles enforce a clean white background (`--bg-color: #ffffff !important`) and crisp black text (`--text-color: #000000 !important`), overriding both dark mode and manual pins.
+
+### Liquid Integration Example
+
+Theme layouts include the toggle conditionally using Liquid:
+
+```liquid
+{% if site.resume_dark_mode == "enabled" %}
+  {% include dark-mode-toggle.html %}
+{% endif %}
+```
+
+---
+
 ## Jekyll build settings
 
 - plugins (required): jekyll-feed, jekyll-seo-tag, jekyll-sitemap, jekyll-redirect-from
@@ -291,6 +372,7 @@ social_links:
 # Theme & analytics
 authors: []
 resume_theme: default
+# resume_dark_mode: auto  # Options: auto (default: CSS system detection), enabled (manual toggle button)
 analytics:
   # gtm: GTM-XXXXXXX
   # ga: true
@@ -334,3 +416,7 @@ exclude:
   - Enable `resume_header_intro_en: true` or `resume_header_intro_ar: true` in `_config.yml`, and create `_data/en/header.yml` (or `_data/ar/header.yml` for Arabic) in your active data path with an `intro:` field. You can copy sample files from `docs/_data/en/header.yml` and `docs/_data/ar/header.yml`.
 - Data for EN/AR lives in different folders.
   - Point `active_resume_path_en` and `active_resume_path_ar` at the right subtrees (e.g., `en` and `ar`).
+- How do I enable the interactive dark mode toggle?
+  - Set `resume_dark_mode: enabled` in your `_config.yml`. By default (`auto` or omitted), dark mode adapts automatically to the user's OS preference without rendering a toggle button.
+- Why doesn't dark mode apply when printing or saving to PDF?
+  - Resumes are optimized for clean physical and PDF printing with high-contrast black text on a pure white background. Dark mode tokens and the toggle button are automatically suppressed in print stylesheets.

data/docs/INCLUDES_GUIDE.md

@@ -24,6 +24,7 @@ This guide assumes basic familiarity with Jekyll and Liquid, but includes exampl
   - [social-links.html](#9-social-linkshtml)
   - [print-social-links.html](#10-print-social-linkshtml)
   - [vendors/ (SVG icon packs)](#11-vendors-svg-icon-packs)
+  - [dark-mode-toggle.html](#12-dark-mode-togglehtml)
 - [Dynamic section rendering (resume-section-*.html)](#dynamic-section-rendering-resume-section-html)
   - [How it works](#how-it-works)
   - [Section list and flags](#section-list-and-flags)
@@ -273,6 +274,36 @@ To add a new icon:
 
 ---
 
+### 12) dark-mode-toggle.html
+Purpose: Self-contained dark mode toggle button rendered conditionally in both resume layouts.
+- Outputs a fixed-position circular button (top-right for LTR, top-left for RTL) with inline sun/moon SVG icons.
+- Implements a **two-state** finite state machine:
+  - **System Default** — follows the OS `prefers-color-scheme` preference automatically. No `localStorage` entry.
+  - **Pinned** — forces light or dark regardless of OS. Saves `"light"` or `"dark"` to `localStorage["color-scheme"]`.
+- Includes an `addEventListener("change")` listener on `matchMedia("(prefers-color-scheme: dark)")` so the button icon updates in real-time if the user changes their OS theme while in System Default mode.
+- Fully accessible: keyboard focusable, dynamic `aria-label` and `title` updated on state changes, bilingual labels (English and Arabic).
+- Hides automatically in print/PDF output via `.no-print`.
+
+Configuration: Controlled by `resume_dark_mode` in `_config.yml`. Only rendered when set to `enabled`.
+
+```yaml
+# _config.yml
+resume_dark_mode: enabled  # renders toggle in both EN and AR layouts
+# resume_dark_mode: auto   # CSS-only system detection (default, no toggle)
+```
+
+The include is conditionally pulled into both `resume-en.html` and `resume-ar.html`:
+
+```liquid
+{% if site.resume_dark_mode == "enabled" %}
+  {% include dark-mode-toggle.html %}
+{% endif %}
+```
+
+Used by: `resume-en.html` and `resume-ar.html`.
+
+---
+
 ## Dynamic section rendering (resume-section-*.html)
 
 Two includes power all resume content:

data/docs/LAYOUTS_GUIDE.md

@@ -146,7 +146,7 @@ active_resume_path_ar: ""
 ## Rendering flow inside resume layouts
 
 ### 1) Head, SEO, analytics
-- Shared meta from `shared-head.html`
+- Shared meta from `shared-head.html` — includes `<meta name="color-scheme" content="light dark">` and an inline FOUC-prevention script that reads `localStorage["color-scheme"]` and applies the saved theme attribute before first paint
 - Resume-specific head from `resume-head-*.html` (CSS, fonts, favicons)
 - `{% seo %}` prints SEO meta and Open Graph/Twitter cards
 - `analytics-head.html` adds GTM or GA4; `analytics-body.html` adds GTM `<noscript>` in the body
@@ -250,6 +250,11 @@ resume_section_order:
 # Print behavior
 resume_print_social_links: true
 
+# Dark mode (controls whether a toggle button is rendered)
+# "auto" (default): CSS-only system detection, no toggle button
+# "enabled": renders an interactive toggle button in both EN and AR layouts
+resume_dark_mode: auto
+
 # Active data subtree for resume_data (separate for each language)
 active_resume_path_en: "en"
 active_resume_path_ar: "ar"

data/docs/SASS_GUIDE.md

@@ -22,6 +22,7 @@ A contributor- and user-friendly tour of the theme's styling system: how styles
   - [_resume-rtl.scss](#7-_resume-rtlscss)
   - [_profile.scss](#8-_profilescss)
   - [_all-pages.scss](#9-_all-pagesscss)
+  - [_dark-mode.scss](#10-_dark-modescss)
 - [Responsive, print, and RTL strategy](#responsive-print-and-rtl-strategy)
 - [Variables reference](#variables-reference)
 - [Mixins reference](#mixins-reference)
@@ -163,6 +164,38 @@ Purpose: Small shared bits across pages.
 
 ---
 
+### 10) `_dark-mode.scss`
+Purpose: Dark mode color token system and toggle button styles.
+
+This partial is the single source of truth for all theming colors. It defines CSS custom properties on `:root` for the light palette and overrides them for dark mode via two mechanisms:
+
+1. **Automatic** — `@media (prefers-color-scheme: dark)` picks up the user's OS preference with no JavaScript.
+2. **Manual pin** — `[data-color-scheme="dark"]` / `[data-color-scheme="light"]` attributes on `<html>` are set by the `dark-mode-toggle.html` JS when the user pins a preference.
+
+It also includes:
+- **Print reset** — overrides all tokens back to black-on-white under `@media print`, ensuring PDFs are always clean regardless of the active theme.
+- **Toggle button styles** — `.dark-mode-toggle` component: fixed-position, circular, with sun/moon icon visibility rules per theme state and RTL flip via `html[dir="rtl"]`.
+
+Key CSS custom properties defined:
+
+| Token | Purpose |
+|---|---|
+| `--bg-color` | Page/html background |
+| `--text-color` | Primary body text |
+| `--text-muted` | Secondary/muted text (e.g., footer) |
+| `--border-color` | Section borders |
+| `--card-bg` | Button and card backgrounds |
+| `--link-color` | Link default color |
+| `--link-hover` | Link hover color |
+| `--accent-color` | Focus rings and UI accent |
+| `--button-bg/text/hover-*` | Contact and CV button states |
+| `--icon-fill` | SVG icon fill |
+| `--selection-bg/color` | Text selection highlight |
+
+Loaded by: `assets/css/cv.scss`, `assets/css/cv-ar.scss`, and `assets/css/main.scss`.
+
+---
+
 ## Responsive, print, and RTL strategy
 
 - Responsive: Mixins `media_larger_than_mobile` and `media_mobile` (600px breakpoint) provide simple adjustments (e.g., stacking → floats).

data/docs/_data/_config.sample.yml

@@ -131,6 +131,11 @@ resume_print_social_links: true # Include social links on printed version
 authors: [] # optional
 resume_theme: default # Theme variant (currently only "default")
 
+# Dark mode configuration:
+# - "auto" (default): Automatic dark mode based on user's OS/browser preference (no toggle button)
+# - "enabled": Adds an interactive floating toggle button (English LTR and Arabic RTL supported)
+# resume_dark_mode: auto
+
 # Analytics (optional - choose one)
 analytics:
   # Google Tag Manager (recommended):

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bilingual-jekyll-resume-theme
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Khaldoon Mutahar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 2026-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -109,6 +109,7 @@ files:
 - _includes/analytics-body.html
 - _includes/analytics-head.html
 - _includes/ar-date.html
+- _includes/dark-mode-toggle.html
 - _includes/hreflang.html
 - _includes/main-head.html
 - _includes/print-social-links.html
@@ -141,6 +142,7 @@ files:
 - _layouts/resume-en.html
 - _sass/_all-pages.scss
 - _sass/_base.scss
+- _sass/_dark-mode.scss
 - _sass/_layout.scss
 - _sass/_mixins.scss
 - _sass/_normalize.scss