Mermaid improvements (#4910)

* Phase 1 of Mermaid improvements

* Phase 1 of Mermaid improvements

Author: Duncanma

.gitignore

@@ -53,3 +53,4 @@ test-results/*
 screenshots
 # Ignore cookbook recipes since they are synced from the remote repo
 ai-cookbook
+scripts/mermaid-compare/*

docs/design-patterns/local-activities.mdx

@@ -22,7 +22,7 @@ sequenceDiagram
     participant S as Temporal Server
 
     rect rgb(230, 235, 250)
-        Note over W,S: Regular Activity — server round-trips on each call
+        Note over W,S: Regular Activity —<br/>server round-trips on each call
         W->>S: Schedule ActivityTask
         S-->>W: Dispatch ActivityTask
         W->>W: Execute activity
@@ -31,7 +31,7 @@ sequenceDiagram
     end
 
     rect rgb(220, 245, 225)
-        Note over W,S: Local Activity — runs in-process, zero server calls
+        Note over W,S: Local Activity —<br/>runs in-process, zero server calls
         W->>W: Execute activity function directly
         Note over W: Result bundled in WorkflowTask completion
     end

docusaurus.config.js

@@ -2,6 +2,7 @@
 const FontPreloadPlugin = require('webpack-font-preload-plugin');
 const { prismDarkTheme, prismLightTheme } = require('./src/prismThemes');
 const { ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY, ALGOLIA_INDEX_NAME } = require('./src/constants/algolia');
+const mermaidTheme = require('./src/constants/mermaidTheme');
 
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 
@@ -225,6 +226,15 @@ module.exports = async function createConfigAsync() {
           ],
         },
       },
+      mermaid: {
+        theme: mermaidTheme.theme,
+        options: {
+          themeVariables: { fontFamily: mermaidTheme.fontFamily },
+          flowchart: mermaidTheme.flowchart,
+          sequence: mermaidTheme.sequence,
+          state: mermaidTheme.state,
+        },
+      },
     },
     presets: [
       [

src/constants/mermaidTheme.js

@@ -0,0 +1,48 @@
+// Single source of truth for Mermaid diagram layout/typography, used by
+// docusaurus.config.js (themeConfig.mermaid.options) and by the dev-only
+// diagram review tool (scripts/mermaid-compare/, regenerate its
+// mermaid-theme.json from this file after editing it).
+//
+// These are mode-independent (no colors) because Docusaurus applies
+// `themeConfig.mermaid.options` identically in light and dark mode; only
+// `themeConfig.mermaid.theme.{light,dark}` (a built-in theme name) varies by
+// color mode. Brand colors are handled separately via CSS overrides in
+// src/css/custom.css targeting Mermaid's generated SVG classes, which is not
+// subject to that light/dark limitation — see the comment there for why.
+module.exports = {
+  // Kept mode-aware (matching Docusaurus's own default) rather than pinned
+  // to a single base theme, as a safety net for anything custom.css's
+  // Mermaid overrides don't explicitly recolor (e.g. rarely-used elements
+  // like the sequenceNumber marker) — verified those still need Mermaid's
+  // own light/dark split to stay correct, not just the CSS layer.
+  theme: { light: 'default', dark: 'dark' },
+  fontFamily: '"Aeonik", "Poppins", -apple-system, BlinkMacSystemFont, sans-serif',
+  flowchart: {
+    padding: 14,
+    nodeSpacing: 45,
+    rankSpacing: 60,
+    curve: 'basis',
+    htmlLabels: true,
+    wrap: true,
+  },
+  sequence: {
+    actorMargin: 60,
+    messageMargin: 40,
+    boxMargin: 12,
+    noteMargin: 12,
+    // NOT wrap: true — Mermaid mis-sizes the note/message box width whenever
+    // the text already has explicit <br/> breaks (a common pattern in these
+    // diagrams) while wrap is on, at any font size: the box comes out
+    // narrower than the actual rendered text, so text overflows its own
+    // box. Confirmed by direct comparison; flowchart's `wrap` does not have
+    // this problem (only sequence). Long single-line messages without <br/>
+    // just render unwrapped (no auto line-break) instead — worse for that
+    // one case, but the halo on .messageText already keeps unwrapped text
+    // readable where it crosses a line, whereas a mis-sized note box is a
+    // correctness bug with no equivalent mitigation.
+    mirrorActors: false,
+  },
+  state: {
+    padding: 14,
+  },
+};