Release 1.4.0: root View Transitions theme crossfade with animating-class fallback.

Platform light/dark paint so extensions following tokens or html.dark-theme animate without per-widget transition rules.

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

Author: AMDphreak

CHANGELOG.adoc

@@ -14,6 +14,11 @@ Entries below are in **chronological order** by date: prior release, then the **
 * *Docs:* Clarify product roles — Valentus release bundle already includes dark mode; overlay / ui-module examples use Default UI (do not stack this package on Valentus `ui-bundle.zip`).
 * *CI:* Release workflow fixes (`v*.*.*` tag filter, `workflow_dispatch`, lockfile); npm publish via trusted publishing (OIDC) — no `NPM_TOKEN`.
 
+== [1.4.0] - 2026-08-01
+
+* *Feature:* Root light↔dark theme transition — View Transitions API on toggle when supported; fallback temporary `html.adt-theme-animating` with a universal paint transition so extension chrome following tokens / `html.dark-theme` animates without per-widget rules. Honors `prefers-reduced-motion: reduce`. Documented as the extension contract in Customization / How It Works.
+* See link:changelog-details/2026-08-01%20-%20root%20theme%20transition.adoc[Detailed notes — 2026-08-01 root theme transition].
+
 == [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]`.

changelog-details/2026-08-01 - root theme transition.adoc

@@ -0,0 +1,8 @@
+= 2026-08-01 — Root theme transition
+
+* *Problem:* Per-component `transition:` rules do not scale. Extensions paint their own backgrounds; when CSS variables / `html.dark-theme` flip, only elements that declared their own transitions animate.
+* *Platform fix (`site-dark-mode.js` + `site-extra.css`):*
+** Preferred: `document.startViewTransition` around the theme class flip (skipped when `prefers-reduced-motion: reduce`).
+** Fallback: add `html.adt-theme-animating` for ~300ms with a universal transition on paint properties (`background-color`, `color`, `border-color`, `fill`, `stroke`, `box-shadow`, `filter`, `opacity`).
+* *Contract:* Extensions style via tokens / `html.dark-theme`; they should not invent their own toggle animation.
+* *Consumers:* Valentus vendors this via `pnpm dark-mode:sync`; demo at the GitHub Pages site for this repo.

docs/modules/guide/pages/customization.adoc

@@ -75,6 +75,18 @@ html.dark-theme .my-custom-element {
 }
 ----
 
+[[theme-transition-contract]]
+== Theme transition contract (extensions)
+
+Light↔dark is animated at the *platform* root — not per widget.
+
+* Preferred: View Transitions API (`document.startViewTransition`) in `site-dark-mode.js` when the browser supports it and the user has not requested reduced motion.
+* Fallback: temporary `html.adt-theme-animating` for ~300ms with a universal paint transition (`background-color`, `color`, `border-color`, `fill`, `stroke`, `box-shadow`, `filter`, `opacity`).
+* Accessibility: both paths are skipped when `prefers-reduced-motion: reduce`.
+
+*Extension authors:* style chrome with CSS custom properties and/or `html.dark-theme` selectors so surfaces pick up the root animation.
+Do *not* invent a separate toggle animation for your widget — per-component `transition:` rules do not scale when other extensions paint their own backgrounds.
+
 == Toggle Button Position
 
 By default, the toggle button is inserted at the beginning of `.navbar-end`.

docs/modules/guide/pages/how-it-works.adoc

@@ -52,29 +52,34 @@ This JavaScript module handles:
 * *Click handling* - Switches between light and dark themes
 * *Persistence* - Saves preference to `localStorage`
 * *Icon updates* - Shows sun icon in dark mode, moon icon in light mode
+* *Root theme transition* - View Transitions when available; otherwise a short `html.adt-theme-animating` class so paint properties crossfade site-wide (skipped under `prefers-reduced-motion: reduce`)
 
 Key functions:
 
 [source,javascript]
 ----
-// Apply theme and update button icon
-function applyTheme(theme) {
-  if (theme === 'dark') {
-    document.documentElement.classList.add('dark-theme');
-  } else {
-    document.documentElement.classList.remove('dark-theme');
+// Paint theme with platform transition (VT or animating-class fallback)
+function runThemePaint(updateFn, animate) {
+  if (!animate || prefersReducedMotion()) {
+    updateFn()
+    return
+  }
+  if (typeof document.startViewTransition === 'function') {
+    document.startViewTransition(updateFn)
+    return
   }
-  updateButtonIcon(theme);
-  localStorage.setItem('antora-theme', theme);
+  html.classList.add('adt-theme-animating')
+  updateFn()
+  setTimeout(() => html.classList.remove('adt-theme-animating'), 300)
 }
 
-// Toggle between themes
 function toggleTheme() {
-  const isDark = document.documentElement.classList.contains('dark-theme');
-  applyTheme(isDark ? 'light' : 'dark');
+  setMode(isDark() ? 'light' : 'dark', true)
 }
 ----
 
+See xref:guide:customization.adoc#theme-transition-contract[Theme transition contract] for extension guidance.
+
 === 4. site-extra.css (Dark Styles)
 
 All dark mode styles use the selector prefix `html.dark-theme`:

package.json

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

supplemental-ui/css/site-extra.css

@@ -526,6 +526,38 @@ html.dark-theme .theme-toggle:hover {
   background-color: #2c2e33;
 }
 
+/*
+ * Root theme transition (platform contract)
+ * -----------------------------------------
+ * Toggle uses View Transitions when available (see site-dark-mode.js).
+ * Fallback: temporary html.adt-theme-animating for ~300ms with a universal
+ * paint transition so extension chrome that follows tokens / html.dark-theme
+ * crossfades without per-widget transition rules.
+ * Extensions should style via CSS variables or html.dark-theme — do not invent
+ * their own light↔dark toggle animation.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  html.adt-theme-animating,
+  html.adt-theme-animating *,
+  html.adt-theme-animating *::before,
+  html.adt-theme-animating *::after {
+    transition:
+      background-color 0.28s ease,
+      color 0.28s ease,
+      border-color 0.28s ease,
+      fill 0.28s ease,
+      stroke 0.28s ease,
+      box-shadow 0.28s ease,
+      filter 0.28s ease,
+      opacity 0.28s ease !important;
+  }
+
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation-duration: 0.28s;
+  }
+}
+
 /* VCS repo logo (valentus-theme replaces Download) — true 1:1 square, compact */
 .navbar .vcs-repo-logo {
   padding: 0 0.5rem 0 0;

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

@@ -4,12 +4,21 @@
   const SYSTEM_SNAPSHOT_KEY = "antora-theme-system-snapshot";
   const html = document.documentElement;
   const darkThemeClass = "dark-theme";
+  /** Temporary class while the class-based theme crossfade runs (VT fallback). */
+  const themeAnimatingClass = "adt-theme-animating";
+  const themeAnimMs = 300;
   const systemMq = window.matchMedia("(prefers-color-scheme: dark)");
+  const reducedMotionMq = window.matchMedia("(prefers-reduced-motion: reduce)");
+  let themeAnimTimer;
 
   function systemPreferenceLabel() {
     return systemMq.matches ? "dark" : "light";
   }
 
+  function prefersReducedMotion() {
+    return reducedMotionMq.matches;
+  }
+
   function captureSystemSnapshot() {
     localStorage.setItem(SYSTEM_SNAPSHOT_KEY, systemPreferenceLabel());
   }
@@ -31,31 +40,58 @@
     return "system";
   }
 
-  function applyVisibleTheme() {
+  /**
+   * Platform theme paint: View Transitions when available, else a short universal
+   * CSS transition via html.adt-theme-animating. Skipped when reduced motion.
+   */
+  function runThemePaint(updateFn, animate) {
+    if (!animate || prefersReducedMotion()) {
+      updateFn();
+      return;
+    }
+    if (typeof document.startViewTransition === "function") {
+      document.startViewTransition(() => {
+        updateFn();
+      });
+      return;
+    }
+    html.classList.add(themeAnimatingClass);
+    // Ensure the browser applies the animating transition before the class flip.
+    void html.offsetWidth;
+    updateFn();
+    window.clearTimeout(themeAnimTimer);
+    themeAnimTimer = window.setTimeout(() => {
+      html.classList.remove(themeAnimatingClass);
+    }, themeAnimMs);
+  }
+
+  function applyVisibleTheme(animate) {
     const mode = getMode();
     let useDark;
     if (mode === "system") {
       useDark = systemMq.matches;
     } else {
       useDark = mode === "dark";
     }
-    if (useDark) {
-      html.classList.add(darkThemeClass);
-    } else {
-      html.classList.remove(darkThemeClass);
-    }
-    updateToggleLabel();
+    runThemePaint(() => {
+      if (useDark) {
+        html.classList.add(darkThemeClass);
+      } else {
+        html.classList.remove(darkThemeClass);
+      }
+      updateToggleLabel();
+    }, Boolean(animate));
   }
 
-  function setMode(next) {
+  function setMode(next, animate) {
     if (next === "system") {
       localStorage.setItem(MODE_KEY, "system");
       clearSystemSnapshot();
     } else {
       localStorage.setItem(MODE_KEY, next);
       captureSystemSnapshot();
     }
-    applyVisibleTheme();
+    applyVisibleTheme(animate !== false);
   }
 
   function expireOverrideIfSystemChanged() {
@@ -67,22 +103,22 @@
       return;
     }
     if (snapshot !== systemPreferenceLabel()) {
-      setMode("system");
+      setMode("system", true);
     }
   }
 
   function onSystemThemeChange() {
     const mode = getMode();
     if (mode === "system") {
-      applyVisibleTheme();
+      applyVisibleTheme(true);
       return;
     }
     expireOverrideIfSystemChanged();
   }
 
   function applyInitialTheme() {
     expireOverrideIfSystemChanged();
-    applyVisibleTheme();
+    applyVisibleTheme(false);
     if (typeof systemMq.addEventListener === "function") {
       systemMq.addEventListener("change", onSystemThemeChange);
     } else {
@@ -115,7 +151,7 @@
   }
 
   function toggleTheme() {
-    setMode(isDark() ? "light" : "dark");
+    setMode(isDark() ? "light" : "dark", true);
     const toggle = document.getElementById("theme-toggle");
     if (toggle) toggle.blur();
   }

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

@@ -526,6 +526,38 @@ html.dark-theme .theme-toggle:hover {
   background-color: #2c2e33;
 }
 
+/*
+ * Root theme transition (platform contract)
+ * -----------------------------------------
+ * Toggle uses View Transitions when available (see site-dark-mode.js).
+ * Fallback: temporary html.adt-theme-animating for ~300ms with a universal
+ * paint transition so extension chrome that follows tokens / html.dark-theme
+ * crossfades without per-widget transition rules.
+ * Extensions should style via CSS variables or html.dark-theme — do not invent
+ * their own light↔dark toggle animation.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  html.adt-theme-animating,
+  html.adt-theme-animating *,
+  html.adt-theme-animating *::before,
+  html.adt-theme-animating *::after {
+    transition:
+      background-color 0.28s ease,
+      color 0.28s ease,
+      border-color 0.28s ease,
+      fill 0.28s ease,
+      stroke 0.28s ease,
+      box-shadow 0.28s ease,
+      filter 0.28s ease,
+      opacity 0.28s ease !important;
+  }
+
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation-duration: 0.28s;
+  }
+}
+
 /* VCS repo logo (valentus-theme replaces Download) — true 1:1 square, compact */
 .navbar .vcs-repo-logo {
   padding: 0 0.5rem 0 0;