diff --git a/docs/content/explanation/journeys.md b/docs/content/explanation/journeys.md
index 98f78c484..ff920f3a7 100644
--- a/docs/content/explanation/journeys.md
+++ b/docs/content/explanation/journeys.md
@@ -3,6 +3,9 @@
 Re: "do workflows need to know NMDC specifics", I've drafted a set of user journey diagrams with
 "Workflow" and "NMDC" as actors.
 
+!!! tip "Viewing diagrams in dark mode"
+    If you're having trouble viewing the diagrams below in dark mode, you can switch to light mode using the theme toggle in the top navigation bar.
+
 
 The first, "Keep NMDC in the know", is the current intended Workflow executioner journey, and is
 implemented by the NMDC Runtime:
diff --git a/docs/content/stylesheets/extra.css b/docs/content/stylesheets/extra.css
index d65072466..2b3c6ed08 100644
--- a/docs/content/stylesheets/extra.css
+++ b/docs/content/stylesheets/extra.css
@@ -54,4 +54,112 @@
          from the words surrounding them. */
 span.term {
     font-variant: small-caps ;
+}
+
+/* Fix Mermaid diagrams in dark mode */
+[data-md-color-scheme="slate"] .mermaid {
+    background-color: var(--md-default-bg-color);
+    border-radius: 0.1rem;
+    padding: 1rem;
+}
+
+[data-md-color-scheme="slate"] .mermaid svg {
+    background-color: var(--md-default-bg-color);
+}
+
+/* General text visibility fixes for dark mode */
+[data-md-color-scheme="slate"] .mermaid text {
+    fill: var(--md-default-fg-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .actor {
+    fill: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .actor-line {
+    stroke: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .messageLine0,
+[data-md-color-scheme="slate"] .mermaid .messageLine1 {
+    stroke: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .messageText {
+    fill: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .labelText {
+    fill: var(--md-default-fg-color);
+}
+
+/* Journey diagram specific fixes */
+[data-md-color-scheme="slate"] .mermaid .section0,
+[data-md-color-scheme="slate"] .mermaid .section1,
+[data-md-color-scheme="slate"] .mermaid .section2,
+[data-md-color-scheme="slate"] .mermaid .section3 {
+    fill: var(--md-default-bg-color);
+    stroke: var(--md-default-fg-color);
+    stroke-width: 1px;
+    opacity: 0.8;
+}
+
+[data-md-color-scheme="slate"] .mermaid .task0,
+[data-md-color-scheme="slate"] .mermaid .task1,
+[data-md-color-scheme="slate"] .mermaid .task2,
+[data-md-color-scheme="slate"] .mermaid .task3 {
+    fill: var(--md-accent-fg-color);
+    stroke: var(--md-accent-fg-color);
+    stroke-width: 1px;
+    opacity: 0.8;
+}
+
+[data-md-color-scheme="slate"] .mermaid .taskText0,
+[data-md-color-scheme="slate"] .mermaid .taskText1,
+[data-md-color-scheme="slate"] .mermaid .taskText2,
+[data-md-color-scheme="slate"] .mermaid .taskText3 {
+    fill: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .active0,
+[data-md-color-scheme="slate"] .mermaid .active1,
+[data-md-color-scheme="slate"] .mermaid .active2,
+[data-md-color-scheme="slate"] .mermaid .active3 {
+    fill: var(--md-primary-fg-color);
+    stroke: var(--md-primary-fg-color);
+    stroke-width: 1px;
+    opacity: 0.8;
+}
+
+[data-md-color-scheme="slate"] .mermaid .activeText0,
+[data-md-color-scheme="slate"] .mermaid .activeText1,
+[data-md-color-scheme="slate"] .mermaid .activeText2,
+[data-md-color-scheme="slate"] .mermaid .activeText3 {
+    fill: var(--md-primary-bg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .done0,
+[data-md-color-scheme="slate"] .mermaid .done1,
+[data-md-color-scheme="slate"] .mermaid .done2,
+[data-md-color-scheme="slate"] .mermaid .done3 {
+    fill: var(--md-default-fg-color);
+    stroke: var(--md-default-fg-color);
+    stroke-width: 1px;
+    opacity: 0.6;
+}
+
+[data-md-color-scheme="slate"] .mermaid .doneText0,
+[data-md-color-scheme="slate"] .mermaid .doneText1,
+[data-md-color-scheme="slate"] .mermaid .doneText2,
+[data-md-color-scheme="slate"] .mermaid .doneText3 {
+    fill: var(--md-default-bg-color);
+}
+
+/* Additional text elements that might need fixing */
+[data-md-color-scheme="slate"] .mermaid .titleText {
+    fill: var(--md-default-fg-color);
+}
+
+[data-md-color-scheme="slate"] .mermaid .sectionTitle {
+    fill: var(--md-default-fg-color);
 }
\ No newline at end of file
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 980e33b66..536562949 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -122,4 +122,5 @@ plugins:
   - mermaid2:
       arguments:
         securityLevel: 'loose'
+        theme: neutral
   - mkdocs-jupyter