feat: add dark_mode_navbar toggle icon tone (v1.3.1)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: AMDphreak

CHANGELOG.adoc

@@ -8,6 +8,12 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version
 
 Entries below are in **chronological order** by date: prior release, then the **2026-03-04** org creation and repository move, then the next release.
 
+== [Unreleased]
+
+== [1.3.1] - 2026-06-13
+
+* *Toggle icon:* Playbook `site.keys.dark_mode_navbar` (`dark` | `light`) selects light-mode navbar tone for the theme toggle — dark top bar (Antora default, white icon) vs. light top bar (dark icon). Sets `meta[name=dm-navbar]` and `html[data-dm-navbar]`.
+
 == [1.3.0] - 2026-06-13
 
 * *npm:* First publish as `antora-dark-mode` (overlay transport: `supplemental-ui/` + `ui-modules/`). Deprecate legacy `antora-dark-theme` npm package name.
@@ -16,8 +22,6 @@ Entries below are in **chronological order** by date: prior release, then the **
 
 link:changelog-details/2026-06-13%20-%20overlay-first%20install%20and%20ui-module.adoc[Detailed notes — 2026-06-13]
 
-== [Unreleased]
-
 == [1.2.0] - 2026-06-09
 
 * *Split:* Repository renamed to `antora-dark-mode`; doc chrome (mast, header, layout, VCS icons) moved to link:https://github.com/antora-supplemental/valentus-theme[valentus-theme]. This package is dark mode only (`site-extra.css`, FOUC script, theme toggle).

docs/modules/guide/pages/configuration.adoc

@@ -81,6 +81,10 @@ The supplemental header and footer read optional playbook keys so you can brand
 | `title_bar_section`
 | component title
 | Browser tab middle segment; see `partials/head-title.hbs`.
+
+| `dark_mode_navbar`
+| `dark`
+| Light-mode top bar tone for the theme toggle icon. `dark` — black navbar (Antora default UI); icon inherits the navbar foreground (white). `light` — light top bar; icon uses dark stroke (`#1a1a1a`). Sets `meta[name=dm-navbar]` and `html[data-dm-navbar]` for toggle CSS. Required for light header strips such as link:https://github.com/antora-supplemental/valentus-theme[valentus-theme].
 |===
 
 Example—custom logo without overriding `partials/header-content.hbs`:

docs/modules/guide/pages/customization.adoc

@@ -87,6 +87,41 @@ To change its position, modify the `ensureToggleButton()` function in `site-dark
 navbarEnd.appendChild(button);
 ----
 
+[[toggle-navbar-tone]]
+== Light-mode navbar tone (toggle icon color)
+
+The default Antora UI uses a *dark* top bar in light mode, so the toggle icon inherits a light (white) stroke via `currentColor`.
+If your light-mode header is a *light* strip (for example link:https://github.com/antora-supplemental/valentus-theme[valentus-theme]), set the playbook key so the moon/sun icon stays visible:
+
+[source,yaml]
+----
+site:
+  keys:
+    dark_mode_navbar: light
+----
+
+Values:
+
+* `dark` (default) — dark top bar in light mode; icon inherits navbar foreground (Antora default UI).
+* `light` — light top bar in light mode; icon uses dark stroke (`#1a1a1a`) and a subtle dark hover.
+
+This emits `meta[name=dm-navbar]` from `partials/head-meta.hbs` and sets `html[data-dm-navbar]` before paint.
+Ui-module installs without the head partial can add the same meta tag in supplemental UI:
+
+[source,html]
+----
+<meta name="dm-navbar" content="light">
+----
+
+Or override in CSS:
+
+[source,css]
+----
+html:not(.dark-theme) .theme-toggle {
+  color: #1a1a1a;
+}
+----
+
 == Custom Toggle Button
 
 If you want to use your own toggle button markup, add an element with `id="theme-toggle"` anywhere in your page:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "antora-dark-mode",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Dark mode supplemental UI for Antora — slot-based overlay, toggle, FOUC prevention, and CSS overrides.",
   "keywords": [
     "antora",

supplemental-ui/css/site-extra.css

@@ -473,7 +473,10 @@ html.dark-theme .home-link {
   color: #ffffff;
 }
 
-/* Toggle button styles */
+/* Toggle button styles
+   Light-mode navbar tone: playbook site.keys.dark_mode_navbar → meta[name=dm-navbar] → html[data-dm-navbar].
+   dark (default): Antora default UI black top bar — inherit white icon from navbar.
+   light: light top bar — dark icon; set dark_mode_navbar: light or meta content="light". */
 .theme-toggle {
   background: none;
   border: 0;
@@ -491,8 +494,16 @@ html.dark-theme .home-link {
   text-transform: none;
 }
 
-.theme-toggle:hover {
-  background-color: #e9ecef;
+html:not(.dark-theme):not([data-dm-navbar="light"]) .theme-toggle:hover {
+  background-color: #1f2125;
+}
+
+html[data-dm-navbar="light"]:not(.dark-theme) .theme-toggle {
+  color: #1a1a1a;
+}
+
+html[data-dm-navbar="light"]:not(.dark-theme) .theme-toggle:hover {
+  background-color: rgba(0, 0, 0, 0.07);
 }
 
 .theme-toggle .theme-icon {

supplemental-ui/js/site-dark-mode.js

@@ -120,6 +120,14 @@
     if (toggle) toggle.blur();
   }
 
+  function toggleButtonClassName() {
+    const useLightNavbarChrome = document.querySelector(".header.adt-header");
+    if (useLightNavbarChrome) {
+      return "navbar-item adt-header-icon-btn theme-toggle";
+    }
+    return "navbar-item theme-toggle";
+  }
+
   function ensureToggleButton() {
     const selector = document.getElementById("theme-selector");
     if (selector) {
@@ -141,7 +149,7 @@
 
     const button = document.createElement("button");
     button.id = "theme-toggle";
-    button.className = "navbar-item theme-toggle";
+    button.className = toggleButtonClassName();
     button.type = "button";
     button.addEventListener("click", toggleTheme);
 

supplemental-ui/partials/head-meta.hbs

@@ -1,6 +1,11 @@
 <link rel="stylesheet" href="{{{uiRootPath}}}/css/site-extra.css">
+<meta name="dm-navbar" content="{{or (lookup site.keys 'dark_mode_navbar') 'dark'}}">
 <script>
 (function () {
+  const dmNavbar = document.querySelector('meta[name="dm-navbar"]')
+  if (dmNavbar && dmNavbar.content) {
+    document.documentElement.dataset.dmNavbar = dmNavbar.content
+  }
   const MODE = 'antora-theme-mode'
   const LEGACY = 'antora-theme'
   function mode() {

ui-modules/packages/dark-mode/ui-module.json5

@@ -1,7 +1,7 @@
 {
   id: "dark-mode",
   name: "Antora dark mode",
-  version: "1.3.0",
+  version: "1.3.1",
   type: "ui-module",
   description: "Dark mode CSS, FOUC prevention, and navbar theme toggle. Slot-based overlay — does not replace theme partials.",
   repository: "https://github.com/antora-supplemental/antora-dark-mode",

ui-modules/packages/dark-mode/ui/css/site-extra.css

@@ -473,7 +473,10 @@ html.dark-theme .home-link {
   color: #ffffff;
 }
 
-/* Toggle button styles */
+/* Toggle button styles
+   Light-mode navbar tone: playbook site.keys.dark_mode_navbar → meta[name=dm-navbar] → html[data-dm-navbar].
+   dark (default): Antora default UI black top bar — inherit white icon from navbar.
+   light: light top bar — dark icon; set dark_mode_navbar: light or meta content="light". */
 .theme-toggle {
   background: none;
   border: 0;
@@ -491,8 +494,16 @@ html.dark-theme .home-link {
   text-transform: none;
 }
 
-.theme-toggle:hover {
-  background-color: #e9ecef;
+html:not(.dark-theme):not([data-dm-navbar="light"]) .theme-toggle:hover {
+  background-color: #1f2125;
+}
+
+html[data-dm-navbar="light"]:not(.dark-theme) .theme-toggle {
+  color: #1a1a1a;
+}
+
+html[data-dm-navbar="light"]:not(.dark-theme) .theme-toggle:hover {
+  background-color: rgba(0, 0, 0, 0.07);
 }
 
 .theme-toggle .theme-icon {

ui-modules/packages/dark-mode/ui/js/site-dark-mode.js

@@ -120,6 +120,14 @@
     if (toggle) toggle.blur();
   }
 
+  function toggleButtonClassName() {
+    const useLightNavbarChrome = document.querySelector(".header.adt-header");
+    if (useLightNavbarChrome) {
+      return "navbar-item adt-header-icon-btn theme-toggle";
+    }
+    return "navbar-item theme-toggle";
+  }
+
   function ensureToggleButton() {
     const selector = document.getElementById("theme-selector");
     if (selector) {
@@ -141,7 +149,7 @@
 
     const button = document.createElement("button");
     button.id = "theme-toggle";
-    button.className = "navbar-item theme-toggle";
+    button.className = toggleButtonClassName();
     button.type = "button";
     button.addEventListener("click", toggleTheme);