diff --git a/src/components/Diagram.astro b/src/components/Diagram.astro
index 5a1c451aa..2d42efe34 100644
--- a/src/components/Diagram.astro
+++ b/src/components/Diagram.astro
@@ -1,6 +1,14 @@
 ---
+import { buildMermaidThemeVariables, mermaidThemeConfig } from './diagram-mermaid-styles.config';
+
 const { caption, width, type = "image", code } = Astro.props;
 const id = `diagram-${Math.random().toString(36).substr(2, 9)}`;
+
+// Pass config to client-side script
+const themeVariables = buildMermaidThemeVariables();
+const sequenceParticipantStyles = mermaidThemeConfig.sequence.participants;
+const flowchartSubgraphStyle = mermaidThemeConfig.flowchart.subgraph;
+const flowchartNodeCornerRadius = mermaidThemeConfig.flowchart.nodeCornerRadius;
 ---
 
 <div class="diagram" data-diagram-type={type}>
@@ -17,7 +25,7 @@ const id = `diagram-${Math.random().toString(36).substr(2, 9)}`;
 </div>
 
 {type === "mermaid" && (
-  <script define:vars={{ id, code }}>
+  <script define:vars={{ id, code, themeVariables, sequenceParticipantStyles, flowchartSubgraphStyle, flowchartNodeCornerRadius }}>
     // Mermaid rendering script
     async function renderMermaidDiagram() {
       const diagramElement = document.getElementById(id);
@@ -34,11 +42,16 @@ const id = `diagram-${Math.random().toString(36).substr(2, 9)}`;
       try {
         // Import and initialize mermaid
         const { default: mermaid } = await import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs');
+        
+        // Global theme configuration for all Mermaid diagrams
+        // Using 'base' theme allows customization via themeVariables
+        // Theme variables are imported from mermaid-styles.config.ts
         mermaid.initialize({
           startOnLoad: false,
-          theme: 'default',
+          theme: 'base',
           securityLevel: 'loose',
-          fontFamily: 'Arial, sans-serif'
+          fontFamily: themeVariables.fontFamily,
+          themeVariables: themeVariables
         });
         
         // Generate SVG
@@ -50,6 +63,354 @@ const id = `diagram-${Math.random().toString(36).substr(2, 9)}`;
         const svgElement = svgDoc.querySelector('svg');
         
         if (svgElement) {
+          // Apply styles directly to SVG elements (before converting to blob)
+          // Sequence diagram participant styles are imported from mermaid-styles.config.ts
+          const participantStyles = sequenceParticipantStyles;
+          
+          // Strategy: Find all rectangles and text elements, then match them
+          // Participant boxes are rectangles positioned at the top of the diagram
+          const allRects = Array.from(svgDoc.querySelectorAll('rect'));
+          const allTexts = Array.from(svgDoc.querySelectorAll('text'));
+          
+          // Store reference to background rect (we'll add it later) to exclude it
+          let backgroundRect = null;
+          
+          // Find participant boxes: they're wide, short rectangles at the top
+          // First, identify the top row by finding the topmost wide rectangles
+          const candidateRects = Array.from(allRects).filter(rect => {
+            const width = parseFloat(rect.getAttribute('width') || '0');
+            const height = parseFloat(rect.getAttribute('height') || '0');
+            const y = parseFloat(rect.getAttribute('y') || '0');
+            
+            // Skip background rectangles
+            if (width > 1000 || height > 1000) {
+              return false;
+            }
+            
+            // Candidate: wide rectangles (wider than tall) near the top
+            return width > 60 && width < 500 && 
+                   height > 10 && height < 100 && 
+                   width > height * 1.8 &&  // Wider than tall
+                   y < 120;  // Top portion of diagram
+          });
+          
+          // Find the topmost y position among candidates (this should be the participant row)
+          const topYPositions = candidateRects.map(rect => parseFloat(rect.getAttribute('y') || '0')).sort((a, b) => a - b);
+          const topY = topYPositions.length > 0 ? topYPositions[0] : 50; // Fallback to 50 if none found
+          const participantYRange = 25; // Participant boxes should be within 25px of the topmost one
+          
+          allRects.forEach((rect) => {
+            const width = parseFloat(rect.getAttribute('width') || '0');
+            const height = parseFloat(rect.getAttribute('height') || '0');
+            const x = parseFloat(rect.getAttribute('x') || '0');
+            const y = parseFloat(rect.getAttribute('y') || '0');
+            
+            // Skip if this is a full-width background rectangle
+            if (width > 1000 || height > 1000) {
+              return;
+            }
+            
+            // Participant boxes characteristics:
+            // - Wider than tall (width/height ratio >= 1.8)
+            // - At the top row (within participantYRange of topmost, OR if no topY found, just check y < 120)
+            // - Not too small or too large
+            // - Exclude tall rectangles (activation boxes) - they have height > width
+            const isWideAndShort = width > height * 1.8;
+            const isAtTopRow = topYPositions.length > 0 
+              ? Math.abs(y - topY) <= participantYRange
+              : y < 120; // Fallback if we couldn't determine top row
+            const isRightSize = width > 60 && width < 500 && height > 10 && height < 100;
+            
+            const isParticipantBox = isWideAndShort && isAtTopRow && isRightSize;
+            
+            if (isParticipantBox) {
+              // Find text elements that are positioned near this rectangle
+              // Text is usually centered horizontally within the box
+              const rectCenterX = x + width / 2;
+              const rectCenterY = y + height / 2;
+              
+              const nearbyTexts = allTexts.filter(text => {
+                const textX = parseFloat(text.getAttribute('x') || '0');
+                const textY = parseFloat(text.getAttribute('y') || '0');
+                // Check if text is within the rectangle bounds or very close
+                const horizontalMatch = textX >= x - 20 && textX <= x + width + 20;
+                const verticalMatch = textY >= y - 10 && textY <= y + height + 10;
+                return horizontalMatch && verticalMatch;
+              });
+              
+              if (nearbyTexts.length > 0) {
+                // Collect text content
+                let textContent = '';
+                nearbyTexts.forEach(t => {
+                  const text = (t.textContent || '').trim();
+                  if (text) {
+                    textContent += text.toLowerCase() + ' ';
+                  }
+                });
+                
+                // Match participant by text content and apply styles
+                for (const [key, style] of Object.entries(participantStyles)) {
+                  if (textContent.includes(key)) {
+                    rect.setAttribute('fill', style.fill);
+                    rect.setAttribute('stroke', style.stroke);
+                    rect.setAttribute('stroke-width', style.strokeWidth);
+                    // Also set style attribute as backup
+                    const currentStyle = rect.getAttribute('style') || '';
+                    rect.setAttribute('style', `${currentStyle} fill: ${style.fill}; stroke: ${style.stroke}; stroke-width: ${style.strokeWidth};`.trim());
+                    break;
+                  }
+                }
+              }
+            }
+          });
+          
+          // Also style bottom participant boxes (at the end of lifelines)
+          // Find the bottommost y position for participant boxes
+          const bottomCandidateRects = Array.from(allRects).filter(rect => {
+            const width = parseFloat(rect.getAttribute('width') || '0');
+            const height = parseFloat(rect.getAttribute('height') || '0');
+            const y = parseFloat(rect.getAttribute('y') || '0');
+            
+            // Skip background rectangles
+            if (width > 1000 || height > 1000) {
+              return false;
+            }
+            
+            // Candidate: wide rectangles near the bottom
+            return width > 60 && width < 500 && 
+                   height > 10 && height < 100 && 
+                   width > height * 1.8 &&  // Wider than tall
+                   y > 200;  // Bottom portion of diagram (well below top)
+          });
+          
+          // Find the bottommost y position among candidates
+          const bottomYPositions = bottomCandidateRects.map(rect => parseFloat(rect.getAttribute('y') || '0')).sort((a, b) => b - a);
+          const bottomY = bottomYPositions.length > 0 ? bottomYPositions[0] : 0;
+          const bottomParticipantYRange = 25;
+          
+          // Style bottom participant boxes
+          allRects.forEach((rect) => {
+            const width = parseFloat(rect.getAttribute('width') || '0');
+            const height = parseFloat(rect.getAttribute('height') || '0');
+            const x = parseFloat(rect.getAttribute('x') || '0');
+            const y = parseFloat(rect.getAttribute('y') || '0');
+            
+            // Skip if this is a full-width background rectangle
+            if (width > 1000 || height > 1000) {
+              return;
+            }
+            
+            // Bottom participant boxes: wide, short, at the bottom row
+            const isWideAndShort = width > height * 1.8;
+            const isAtBottomRow = bottomYPositions.length > 0 
+              ? Math.abs(y - bottomY) <= bottomParticipantYRange
+              : false; // Only style if we found a bottom row
+            const isRightSize = width > 60 && width < 500 && height > 10 && height < 100;
+            
+            const isBottomParticipantBox = isWideAndShort && isAtBottomRow && isRightSize;
+            
+            if (isBottomParticipantBox) {
+              // Find text elements near this rectangle
+              const nearbyTexts = allTexts.filter(text => {
+                const textX = parseFloat(text.getAttribute('x') || '0');
+                const textY = parseFloat(text.getAttribute('y') || '0');
+                const horizontalMatch = textX >= x - 20 && textX <= x + width + 20;
+                const verticalMatch = textY >= y - 10 && textY <= y + height + 10;
+                return horizontalMatch && verticalMatch;
+              });
+              
+              if (nearbyTexts.length > 0) {
+                // Collect text content
+                let textContent = '';
+                nearbyTexts.forEach(t => {
+                  const text = (t.textContent || '').trim();
+                  if (text) {
+                    textContent += text.toLowerCase() + ' ';
+                  }
+                });
+                
+                // Match participant by text content and apply same styles as top boxes
+                for (const [key, style] of Object.entries(participantStyles)) {
+                  if (textContent.includes(key)) {
+                    rect.setAttribute('fill', style.fill);
+                    rect.setAttribute('stroke', style.stroke);
+                    rect.setAttribute('stroke-width', style.strokeWidth);
+                    const currentStyle = rect.getAttribute('style') || '';
+                    rect.setAttribute('style', `${currentStyle} fill: ${style.fill}; stroke: ${style.stroke}; stroke-width: ${style.strokeWidth};`.trim());
+                    break;
+                  }
+                }
+              }
+            }
+          });
+          
+          // ===== FLOWCHART POST-PROCESSING =====
+          // Check if this is a flowchart by looking for flowchart-specific elements
+          const isFlowchart = code.trim().toLowerCase().includes('flowchart') || 
+                             code.trim().toLowerCase().includes('graph');
+          
+          if (isFlowchart) {
+            // Find all rectangles that represent nodes (not already styled with classDef)
+            // Nodes without explicit styling should have transparent backgrounds
+            const allFlowchartRects = Array.from(svgDoc.querySelectorAll('rect'));
+            const styledNodes = new Set();
+            
+            // Find nodes that have been styled with classDef (they'll have specific fill colors)
+            allFlowchartRects.forEach(rect => {
+              const fill = rect.getAttribute('fill') || '';
+              const style = rect.getAttribute('style') || '';
+              // If it has a non-default fill color, it's been styled
+              if (fill && fill !== 'transparent' && fill !== 'none' && 
+                  fill !== '#ffffff' && fill !== '#fff' && !fill.includes('rgb(255')) {
+                styledNodes.add(rect);
+              }
+            });
+            
+            // Make unstyled nodes transparent
+            allFlowchartRects.forEach(rect => {
+              const width = parseFloat(rect.getAttribute('width') || '0');
+              const height = parseFloat(rect.getAttribute('height') || '0');
+              
+              // Skip background and very large rectangles
+              if (width > 1000 || height > 1000) {
+                return;
+              }
+              
+              // Skip if already styled
+              if (styledNodes.has(rect)) {
+                return;
+              }
+              
+              // Check if this is a node rectangle (not a subgraph/cluster)
+              // Node rectangles are typically smaller and have text inside
+              const hasTextNearby = Array.from(allTexts).some(text => {
+                const textX = parseFloat(text.getAttribute('x') || '0');
+                const textY = parseFloat(text.getAttribute('y') || '0');
+                const rectX = parseFloat(rect.getAttribute('x') || '0');
+                const rectY = parseFloat(rect.getAttribute('y') || '0');
+                const rectWidth = parseFloat(rect.getAttribute('width') || '0');
+                const rectHeight = parseFloat(rect.getAttribute('height') || '0');
+                
+                return textX >= rectX && textX <= rectX + rectWidth &&
+                       textY >= rectY && textY <= rectY + rectHeight;
+              });
+              
+              // If it's a node rectangle (has text), make it transparent
+              if (hasTextNearby && width < 500 && height < 200) {
+                rect.setAttribute('fill', 'none');
+                // Keep a subtle border for visibility
+                if (!rect.getAttribute('stroke') || rect.getAttribute('stroke') === 'none') {
+                  rect.setAttribute('stroke', '#777777');
+                  rect.setAttribute('stroke-width', '1px');
+                }
+              }
+            });
+            
+            // Style subgraphs/clusters - find them by looking for cluster groups and large rectangles
+            const clusters = [];
+            
+            // First, look for groups with cluster-related class names
+            const clusterGroups = svgDoc.querySelectorAll('g.cluster, g[class*="cluster"], g[class*="subgraph"]');
+            clusterGroups.forEach(group => {
+              const rects = group.querySelectorAll('rect');
+              rects.forEach(rect => {
+                const width = parseFloat(rect.getAttribute('width') || '0');
+                const height = parseFloat(rect.getAttribute('height') || '0');
+                if (width > 100 && height > 50) {
+                  clusters.push({ rect, y: parseFloat(rect.getAttribute('y') || '0') });
+                }
+              });
+            });
+            
+            // Also find large rectangles that contain other rectangles (subgraph containers)
+            allFlowchartRects.forEach(rect => {
+              const width = parseFloat(rect.getAttribute('width') || '0');
+              const height = parseFloat(rect.getAttribute('height') || '0');
+              
+              // Subgraphs are large rectangles (but not the background)
+              if (width > 200 && height > 150 && width < 2000 && height < 2000) {
+                // Check if this rectangle contains other rectangles (indicating it's a cluster)
+                const rectX = parseFloat(rect.getAttribute('x') || '0');
+                const rectY = parseFloat(rect.getAttribute('y') || '0');
+                
+                const containsOtherRects = allFlowchartRects.some(otherRect => {
+                  if (otherRect === rect) return false;
+                  const otherX = parseFloat(otherRect.getAttribute('x') || '0');
+                  const otherY = parseFloat(otherRect.getAttribute('y') || '0');
+                  const otherWidth = parseFloat(otherRect.getAttribute('width') || '0');
+                  const otherHeight = parseFloat(otherRect.getAttribute('height') || '0');
+                  
+                  // Check if otherRect is inside this rect
+                  return otherX > rectX && otherY > rectY &&
+                         (otherX + otherWidth) < (rectX + width) &&
+                         (otherY + otherHeight) < (rectY + height);
+                });
+                
+                if (containsOtherRects) {
+                  // Check if we haven't already added this rect
+                  const alreadyAdded = clusters.some(c => c.rect === rect);
+                  if (!alreadyAdded) {
+                    clusters.push({ rect, y: rectY });
+                  }
+                }
+              }
+            });
+            
+            // Sort clusters by y position and apply subgraph styling from config
+            // Subgraph styles are configured in mermaid-styles.config.ts
+            const subgraphStyle = flowchartSubgraphStyle;
+            clusters.sort((a, b) => a.y - b.y);
+            clusters.forEach((cluster) => {
+              // Apply subgraph styles from config
+              cluster.rect.setAttribute('fill', subgraphStyle.fill);
+              cluster.rect.setAttribute('stroke', subgraphStyle.stroke);
+              cluster.rect.setAttribute('stroke-width', subgraphStyle.strokeWidth);
+              cluster.rect.setAttribute('stroke-dasharray', subgraphStyle.strokeDasharray);
+              cluster.rect.setAttribute('rx', subgraphStyle.cornerRadius.toString());
+              cluster.rect.setAttribute('ry', subgraphStyle.cornerRadius.toString());
+              // Remove any existing style and set new one
+              cluster.rect.removeAttribute('style');
+              cluster.rect.setAttribute('style', `fill: ${subgraphStyle.fill} !important; stroke: ${subgraphStyle.stroke} !important; stroke-width: ${subgraphStyle.strokeWidth} !important; stroke-dasharray: ${subgraphStyle.strokeDasharray} !important;`);
+            });
+          }
+          
+          // ===== APPLY ROUNDED CORNERS TO ALL BOXES =====
+          // Add rounded corners to all rectangles that represent boxes/nodes
+          // Corner radius is configured in mermaid-styles.config.ts
+          const defaultCornerRadius = flowchartNodeCornerRadius;
+          const allBoxRects = Array.from(svgDoc.querySelectorAll('rect'));
+          allBoxRects.forEach(rect => {
+            const width = parseFloat(rect.getAttribute('width') || '0');
+            const height = parseFloat(rect.getAttribute('height') || '0');
+            
+            // Skip background rectangles
+            if (width > 1000 || height > 1000) {
+              return;
+            }
+            
+            // Skip very small rectangles (likely decorative elements)
+            if (width < 5 || height < 5) {
+              return;
+            }
+            
+            // Skip if already has rounded corners (e.g., subgraphs that were explicitly styled)
+            const existingRx = rect.getAttribute('rx');
+            const existingRy = rect.getAttribute('ry');
+            if (existingRx && existingRy && parseFloat(existingRx) > 0) {
+              return;
+            }
+            
+            // Calculate appropriate corner radius based on box size
+            // Use configured radius, but scale down for very small boxes
+            const cornerRadius = Math.min(defaultCornerRadius, Math.min(width, height) * 0.1);
+            
+            // Apply rounded corners (minimum 2px for visibility)
+            if (cornerRadius >= 2) {
+              rect.setAttribute('rx', cornerRadius.toString());
+              rect.setAttribute('ry', cornerRadius.toString());
+            }
+          });
+          
           // Calculate dimensions preserving aspect ratio
           let width = 1920;
           let height = 1080;
@@ -74,7 +435,8 @@ const id = `diagram-${Math.random().toString(36).substr(2, 9)}`;
           svgElement.insertBefore(rect, svgElement.firstChild);
         }
         
-        const enhancedSvg = new XMLSerializer().serializeToString(svgDoc);
+        // Serialize the SVG element (not the whole document)
+        const enhancedSvg = svgElement ? new XMLSerializer().serializeToString(svgElement) : new XMLSerializer().serializeToString(svgDoc);
         
         // Create blob URL for the SVG
         const blob = new Blob([enhancedSvg], { type: 'image/svg+xml' });
diff --git a/src/components/diagram-mermaid-styles.config.ts b/src/components/diagram-mermaid-styles.config.ts
new file mode 100644
index 000000000..f2c96aae2
--- /dev/null
+++ b/src/components/diagram-mermaid-styles.config.ts
@@ -0,0 +1,350 @@
+/**
+ * Mermaid Diagram Styling Configuration
+ * 
+ * This file contains all styling configuration for Mermaid diagrams.
+ * Styles are organized by diagram type for easy maintenance.
+ * 
+ * ===== HOW TO MODIFY STYLES =====
+ * 
+ * 1. Find the relevant section below (e.g., "FLOWCHART DIAGRAMS", "SEQUENCE DIAGRAMS")
+ * 2. Update the color/style values
+ * 3. Changes will apply to all diagrams of that type automatically
+ * 
+ * ===== DIAGRAM TYPES =====
+ * 
+ * - flowchart: Flowchart nodes, edges, subgraphs, and color scales
+ * - sequence: Sequence diagram participants (individual styling by label)
+ * - class: Class diagram boxes
+ * - state: State diagram nodes
+ * - er: Entity-relationship diagrams
+ * - gantt: Gantt chart tasks and sections
+ * - pie: Pie chart slices
+ * - journey: User journey diagrams
+ * - gitgraph: Git graph branches
+ * - requirement: Requirement diagrams
+ * - note: Note boxes (applies to all diagrams)
+ * - mindmap: Mindmap nodes
+ * - timeline: Timeline sections
+ * - c4: C4 architecture diagrams
+ * 
+ * ===== COMMON STYLE CHANGES =====
+ * 
+ * To change subgraph colors:
+ *   Edit flowchart.subgraph.fill and flowchart.subgraph.stroke
+ * 
+ * To change sequence diagram participant colors:
+ *   Edit sequence.participants object (keys match participant label text)
+ * 
+ * To change default node colors:
+ *   Edit flowchart.defaultNodeFill, flowchart.nodeTextColor, etc.
+ * 
+ * To change rounded corners:
+ *   Edit flowchart.nodeCornerRadius and flowchart.subgraph.cornerRadius
+ */
+
+export const mermaidThemeConfig = {
+  // ===== GLOBAL SETTINGS =====
+  // These apply to all diagram types unless overridden
+  global: {
+    primaryColor: '#1976d2',
+    primaryTextColor: '#000000',
+    primaryBorderColor: '#1565c0',
+    lineColor: '#666666',
+    secondaryColor: '#666666',
+    tertiaryColor: '#999999',
+    background: '#ffffff',
+    mainBkg: '#ffffff',
+    secondBkg: '#f5f5f5',
+    textColor: '#000000',
+    secondaryTextColor: '#666666',
+    border1: '#666666',
+    border2: '#999999',
+    border3: '#cccccc',
+    fontSize: '16px',
+    fontFamily: 'Arial, sans-serif',
+  },
+
+  // ===== FLOWCHART DIAGRAMS =====
+  // Styles for flowchart nodes, edges, and subgraphs
+  flowchart: {
+    // Default node styling (applies to nodes without classDef)
+    defaultNodeFill: 'none', // Transparent background for text nodes
+    nodeTextColor: '#000000',
+    nodeBorder: '#666666',
+    nodeCornerRadius: 8, // Rounded corners for all boxes (in pixels)
+    
+    // Subgraph/cluster styling
+    subgraph: {
+      fill: '#ffffff', // White background
+      stroke: '#cccccc', // Light gray border
+      strokeWidth: '2px',
+      strokeDasharray: '5,5', // Dotted border
+      cornerRadius: 8, // Rounded corners
+    },
+    
+    // Color scales for classDef styling (cScale0-7)
+    colorScales: {
+      cScale0: '#e3f2fd', // Light blue
+      cScale1: '#f3e5f5', // Light purple
+      cScale2: '#fff9c4', // Light yellow
+      cScale3: '#e8f5e9', // Light green
+      cScale4: '#ffe0b2', // Light orange
+      cScale5: '#ffcdd2', // Light red
+      cScale6: '#b2dfdb', // Light teal
+      cScale7: '#f8bbd0', // Light pink
+    },
+    
+    edgeLabelBackground: '#ffffff',
+  },
+
+  // ===== SEQUENCE DIAGRAMS =====
+  // Styles for sequence diagram participants and messages
+  sequence: {
+    // Default participant box styling (applies to all participants globally)
+    participantBoxFill: '#f5f5f5',
+    participantBoxStroke: '#666666',
+    
+    // Actor box styling
+    actorBoxFill: '#e3f2fd',
+    actorBoxStroke: '#1976d2',
+    
+    // Activation box styling
+    activationBoxFill: '#f5f5f5',
+    activationBoxStroke: '#666666',
+    
+    // Individual participant styling (by label text)
+    // These override the default styles above
+    participants: {
+      'user': { fill: '#E3F2FD', stroke: '#2196F3', strokeWidth: '2px' },
+      'search() api': { fill: '#F3E5F5', stroke: '#9C27B0', strokeWidth: '2px' },
+      'event bus': { fill: '#FFF9C4', stroke: '#FBC02D', strokeWidth: '2px' },
+      'searchresults': { fill: '#E8F5E9', stroke: '#4CAF50', strokeWidth: '2px' },
+      'facets': { fill: '#FFE0B2', stroke: '#FF9800', strokeWidth: '2px' },
+      'pagination': { fill: '#FFCDD2', stroke: '#F44336', strokeWidth: '2px' },
+      'sortby': { fill: '#B2DFDB', stroke: '#009688', strokeWidth: '2px' },
+      'graphql api': { fill: '#F8BBD0', stroke: '#E91E63', strokeWidth: '2px' },
+    },
+  },
+
+  // ===== CLASS DIAGRAMS =====
+  class: {
+    classBoxFill: '#ffffff',
+    classBoxStroke: '#666666',
+    classTextColor: '#000000',
+  },
+
+  // ===== STATE DIAGRAMS =====
+  state: {
+    stateBkgColor: '#ffffff',
+    stateBorderColor: '#666666',
+    stateLabelBkgColor: '#f5f5f5',
+    stateLabelTextColor: '#000000',
+    stateNodeBkgColor: '#e3f2fd',
+    stateNodeBorderColor: '#1976d2',
+  },
+
+  // ===== ER DIAGRAMS =====
+  er: {
+    erBoxFillColor: '#ffffff',
+    erBoxStrokeColor: '#666666',
+    erTextColor: '#000000',
+    erAttributeBoxFillColor: '#f5f5f5',
+    erAttributeBoxStrokeColor: '#999999',
+  },
+
+  // ===== GANTT CHARTS =====
+  gantt: {
+    ganttSectionBkgColor: '#f5f5f5',
+    ganttSectionStrokeColor: '#666666',
+    ganttTaskBkgColor: '#e3f2fd',
+    ganttTaskStrokeColor: '#1976d2',
+    ganttTaskTextColor: '#000000',
+    ganttTaskTextLightColor: '#666666',
+    ganttTaskTextOutsideColor: '#000000',
+    ganttTaskTextClickableColor: '#1976d2',
+    ganttActiveTaskBkgColor: '#1976d2',
+    ganttActiveTaskStrokeColor: '#1565c0',
+    ganttGridColor: '#cccccc',
+    ganttDoneTaskBkgColor: '#4caf50',
+    ganttDoneTaskStrokeColor: '#388e3c',
+    ganttCritTaskBkgColor: '#f44336',
+    ganttCritTaskStrokeColor: '#d32f2f',
+    ganttTodayLineColor: '#f44336',
+  },
+
+  // ===== PIE CHARTS =====
+  pie: {
+    pie1: '#e3f2fd',
+    pie2: '#f3e5f5',
+    pie3: '#fff9c4',
+    pie4: '#e8f5e9',
+    pie5: '#ffe0b2',
+    pie6: '#ffcdd2',
+    pie7: '#b2dfdb',
+    pieTitleTextSize: '16px',
+    pieTitleTextColor: '#000000',
+    pieSectionTextSize: '14px',
+    pieSectionTextColor: '#000000',
+    pieLegendTextSize: '14px',
+    pieLegendTextColor: '#000000',
+    pieStrokeColor: '#ffffff',
+  },
+
+  // ===== USER JOURNEY DIAGRAMS =====
+  journey: {
+    journeyTaskBkgColor: '#e3f2fd',
+    journeyTaskTextColor: '#000000',
+    journeyTaskTextLightColor: '#666666',
+    journeyActiveTaskBkgColor: '#1976d2',
+    journeyActiveTaskBorderColor: '#1565c0',
+    journeyActiveTaskTextColor: '#ffffff',
+    journeyDoneTaskBkgColor: '#4caf50',
+    journeyDoneTaskBorderColor: '#388e3c',
+    journeyDoneTaskTextColor: '#ffffff',
+    journeyTaskBorderColor: '#666666',
+    journeyCritTaskBkgColor: '#f44336',
+    journeyCritTaskBorderColor: '#d32f2f',
+    journeyCritTaskTextColor: '#ffffff',
+    journeyTaskTextOutsideColor: '#000000',
+    journeyTaskTextClickableColor: '#1976d2',
+  },
+
+  // ===== GITGRAPH DIAGRAMS =====
+  gitgraph: {
+    git0: '#e3f2fd',
+    git1: '#f3e5f5',
+    git2: '#fff9c4',
+    git3: '#e8f5e9',
+    git4: '#ffe0b2',
+    git5: '#ffcdd2',
+    git6: '#b2dfdb',
+    git7: '#f8bbd0',
+    gitBranchLabel0: '#000000',
+    gitBranchLabel1: '#000000',
+    gitBranchLabel2: '#000000',
+    gitBranchLabel3: '#000000',
+    gitBranchLabel4: '#000000',
+    gitBranchLabel5: '#000000',
+    gitBranchLabel6: '#000000',
+    gitBranchLabel7: '#000000',
+  },
+
+  // ===== REQUIREMENT DIAGRAMS =====
+  requirement: {
+    requirementBkgColor: '#ffffff',
+    requirementBorderColor: '#666666',
+    requirementTextColor: '#000000',
+    relationBkgColor: '#f5f5f5',
+    relationBorderColor: '#999999',
+  },
+
+  // ===== NOTE BOXES (all diagrams) =====
+  note: {
+    noteBkgColor: '#fff9c4',
+    noteTextColor: '#000000',
+    noteBorderColor: '#fbc02d',
+  },
+
+  // ===== MINDMAP DIAGRAMS =====
+  mindmap: {
+    mindmapNodeBkgColor: '#ffffff',
+    mindmapNodeBorderColor: '#666666',
+    mindmapNodeTextColor: '#000000',
+  },
+
+  // ===== TIMELINE DIAGRAMS =====
+  timeline: {
+    timelineBkgColor: '#ffffff',
+    timelineBorderColor: '#666666',
+    timelineTextColor: '#000000',
+    timelineSectionBkgColor: '#f5f5f5',
+    timelineSectionStrokeColor: '#999999',
+  },
+
+  // ===== C4 DIAGRAMS =====
+  c4: {
+    c4PersonBkgColor: '#e3f2fd',
+    c4PersonBorderColor: '#1976d2',
+    c4SystemBkgColor: '#f3e5f5',
+    c4SystemBorderColor: '#9c27b0',
+    c4ContainerBkgColor: '#fff9c4',
+    c4ContainerBorderColor: '#fbc02d',
+    c4ComponentBkgColor: '#e8f5e9',
+    c4ComponentBorderColor: '#4caf50',
+    c4DbBkgColor: '#ffe0b2',
+    c4DbBorderColor: '#ff9800',
+    c4QueueBkgColor: '#ffcdd2',
+    c4QueueBorderColor: '#f44336',
+  },
+} as const;
+
+/**
+ * Helper function to build Mermaid themeVariables object from config
+ */
+export function buildMermaidThemeVariables() {
+  return {
+    // Global settings
+    ...mermaidThemeConfig.global,
+    
+    // Flowchart
+    defaultNodeFill: mermaidThemeConfig.flowchart.defaultNodeFill,
+    clusterFill: mermaidThemeConfig.flowchart.subgraph.fill,
+    clusterBkg: mermaidThemeConfig.flowchart.subgraph.fill,
+    clusterBorder: mermaidThemeConfig.flowchart.subgraph.stroke,
+    cScale0: mermaidThemeConfig.flowchart.colorScales.cScale0,
+    cScale1: mermaidThemeConfig.flowchart.colorScales.cScale1,
+    cScale2: mermaidThemeConfig.flowchart.colorScales.cScale2,
+    cScale3: mermaidThemeConfig.flowchart.colorScales.cScale3,
+    cScale4: mermaidThemeConfig.flowchart.colorScales.cScale4,
+    cScale5: mermaidThemeConfig.flowchart.colorScales.cScale5,
+    cScale6: mermaidThemeConfig.flowchart.colorScales.cScale6,
+    cScale7: mermaidThemeConfig.flowchart.colorScales.cScale7,
+    nodeTextColor: mermaidThemeConfig.flowchart.nodeTextColor,
+    nodeBorder: mermaidThemeConfig.flowchart.nodeBorder,
+    edgeLabelBackground: mermaidThemeConfig.flowchart.edgeLabelBackground,
+    
+    // Sequence diagrams
+    participantBoxFillColor: mermaidThemeConfig.sequence.participantBoxFill,
+    participantBoxStrokeColor: mermaidThemeConfig.sequence.participantBoxStroke,
+    actorBoxFillColor: mermaidThemeConfig.sequence.actorBoxFill,
+    actorBoxStrokeColor: mermaidThemeConfig.sequence.actorBoxStroke,
+    activationBoxFillColor: mermaidThemeConfig.sequence.activationBoxFill,
+    activationBoxStrokeColor: mermaidThemeConfig.sequence.activationBoxStroke,
+    
+    // Class diagrams
+    ...mermaidThemeConfig.class,
+    
+    // State diagrams
+    ...mermaidThemeConfig.state,
+    
+    // ER diagrams
+    ...mermaidThemeConfig.er,
+    
+    // Gantt charts
+    ...mermaidThemeConfig.gantt,
+    
+    // Pie charts
+    ...mermaidThemeConfig.pie,
+    
+    // User journey
+    ...mermaidThemeConfig.journey,
+    
+    // Gitgraph
+    ...mermaidThemeConfig.gitgraph,
+    
+    // Requirement
+    ...mermaidThemeConfig.requirement,
+    
+    // Note boxes
+    ...mermaidThemeConfig.note,
+    
+    // Mindmap
+    ...mermaidThemeConfig.mindmap,
+    
+    // Timeline
+    ...mermaidThemeConfig.timeline,
+    
+    // C4
+    ...mermaidThemeConfig.c4,
+  };
+}
diff --git a/src/content/docs/dropins/product-discovery/index.mdx b/src/content/docs/dropins/product-discovery/index.mdx
index 6448285ad..9482af9cd 100644
--- a/src/content/docs/dropins/product-discovery/index.mdx
+++ b/src/content/docs/dropins/product-discovery/index.mdx
@@ -24,7 +24,7 @@ Each container reacts to search events orchestrated by the **[search](/dropins/p
   type="mermaid" 
   caption="Event Driven Architecture — Search"
   code={`sequenceDiagram
-    participant U as User
+    participant U as user
     participant API as search() API
     participant EB as Event Bus
     participant SR as SearchResults
@@ -32,6 +32,7 @@ Each container reacts to search events orchestrated by the **[search](/dropins/p
     participant P as Pagination
     participant S as SortBy
     participant GQL as GraphQL API
+
     %% Initial search
     U->>API: search({phrase: "shirts"})
     API->>GQL: request data from Catalog Services
@@ -39,7 +40,6 @@ Each container reacts to search events orchestrated by the **[search](/dropins/p
     API->>EB: emit('search/loading', true)
     API->>EB: emit('search/result', { request, result })
     API->>EB: emit('search/loading', false)
-    
     %% All containers receive loading and result events
     EB->>SR: search/loading<br/>search/result
     EB->>F: search/loading<br/>search/result