diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index edd9fe971..012902837 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -412,14 +412,10 @@ html.dark .only-light {
   margin-bottom: 3em;
 }
 
-/* -----------------------------------------------------------------------------
-   Mermaid Diagrams (Dark Mode Fix)
-   ----------------------------------------------------------------------------- */
-html.dark .mermaid svg,
-html[data-theme="dark"] .mermaid svg {
-  background-color: white;
-  padding: 1em;
-  border-radius: 8px;
+/* Mermaid renders a native dark theme; Shibuya's inversion would undo it. */
+html.dark pre.mermaid > svg,
+html[data-theme="dark"] pre.mermaid > svg {
+  filter: none;
 }
 
 /* -----------------------------------------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index 773265317..d0e611db5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -208,19 +208,14 @@
 
 
 # Mermaid configuration
-mermaid_version = "11.2.0"
-mermaid_init_js = """
-mermaid.initialize({
-    startOnLoad: true,
-    theme: 'default',
-    securityLevel: 'loose',
-    flowchart: {
-        useMaxWidth: true,
-        htmlLabels: true,
-        curve: 'basis'
-    }
-});
-"""
+mermaid_version = "11.12.1"
+mermaid_light_theme = "default"
+mermaid_dark_theme = "dark"
+mermaid_init_config = {
+    "startOnLoad": False,
+    "securityLevel": "loose",
+    "flowchart": {"useMaxWidth": True, "htmlLabels": True, "curve": "basis"},
+}
 
 html_theme_options = {
     "logo_target": "/",