> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 55. Diagram Visualization Standards

> Architecture Decision Record: 55. Diagram Visualization Standards

# 55. Diagram Visualization Standards

Date: 2025-11-15

## Status

Accepted

## Category

Development & Tooling

## Context

The MCP Server LangGraph project uses Mermaid.js diagrams extensively (82+ diagrams across 67+ files) to visualize system architecture, authentication flows, deployment topologies, data flow, and state machines.

Prior to standardization, diagrams suffered from:

* **Inconsistent styling**: Each diagram used different colors, making cross-diagram navigation confusing
* **Deprecated syntax**: Mix of `graph TB` (deprecated) and `flowchart TB` (modern) syntax
* **Accessibility issues**: Random color choices failed WCAG 2.1 AA contrast ratio requirements (4.5:1)
* **Maintenance burden**: Inline styles instead of reusable `classDef` declarations
* **Semantic ambiguity**: Hex codes like `#8dd3c7` don't convey meaning (vs. `externalStyle`, `errorStyle`)
* **No validation**: Diagrams could break without detection

## Decision

Adopt **ColorBrewer2 Set3 palette** as the mandatory standard for all user-facing Mermaid diagrams with:

1. **Standardized color palette**: ColorBrewer2 Set3 (11 colors)
2. **Semantic color assignments**: Component types mapped to specific colors
3. **Modern Mermaid syntax**: `flowchart` (not `graph`), `sequenceDiagram` with theme initialization
4. **Reusable styles**: `classDef` declarations (not inline `style` statements)
5. **Automated validation**: Pre-commit hooks + CI/CD checks

### ColorBrewer2 Set3 Palette with Semantic Assignments

| Color       | Hex Code | Stroke Color | Semantic Usage                | Accessibility |
| ----------- | -------- | ------------ | ----------------------------- | ------------- |
| Cyan        | #8dd3c7  | #2a9d8f      | External/clients/start nodes  | WCAG AA       |
| Orange      | #fdb462  | #e67e22      | Ingress/processing/middleware | WCAG AA       |
| Green       | #b3de69  | #7cb342      | Application/execution/success | WCAG AA       |
| Red         | #fb8072  | #e74c3c      | LLM/critical paths/errors     | WCAG AA       |
| Blue        | #80b1d3  | #3498db      | Data/storage/services         | WCAG AA       |
| Yellow      | #ffffb3  | #f1c40f      | Decisions/observability       | WCAG AA       |
| Purple      | #bc80bd  | #8e44ad      | Secrets/special features      | WCAG AA       |
| Lavender    | #bebada  | #7e5eb0      | Auth/security/clusters        | WCAG AA       |
| Pink        | #fccde5  | #ec7ab8      | External services/monitoring  | WCAG AA       |
| Light Green | #ccebc5  | #82c99a      | Results/dashboards            | WCAG AA       |
| Gray        | #d9d9d9  | #95a5a6      | Neutral/generic               | WCAG AA       |

All colors meet WCAG 2.1 Level AA requirements for contrast ratio (4.5:1 minimum) when used with `color:#333` text.

### Validation Infrastructure

**Pre-commit Hook**: `check-mermaid-styling`

* Stage: `pre-push` (comprehensive validation)
* Checks: Modern syntax, ColorBrewer2 styling, standard comment marker, sequence diagram themes
* Exclusions: Internal docs (`docs-internal/`, `reports/`)

**Validation Scripts** (7 total):

1. `validate_all_mermaid.py` - Syntax validation via mmdc CLI
2. `check_mermaid_styling.py` - Style compliance checking
3. `fix_mermaid_sequence_diagrams.py` - Auto-fix sequence issues
4. `add_sequence_diagram_themes.py` - Theme injection
5. `add_diagram_styling.py` - Style migration
6. `convert_inline_styles_to_classdef.py` - Refactoring tool
7. `add_colorbrewer_styling.py` - Batch styler

**Test Infrastructure**:

* `tests/test_validate_mintlify_docs.py` - Validation tests
* `tests/test_documentation_integrity.py` - Integrity tests

## Rationale

### Why ColorBrewer2 Set3?

1. **Accessibility Compliance (WCAG 2.1 AA)**
   * ColorBrewer2 is specifically designed for data visualization with accessibility in mind
   * All 11 colors meet WCAG 2.1 Level AA contrast requirements (4.5:1 ratio)
   * Tested for color-blind accessibility (Deuteranopia, Protanopia, Tritanopia)
   * Recommended by W3C for accessible data visualization

2. **Proven Track Record**
   * Industry standard for cartography and data visualization
   * Used by National Geographic, New York Times, USGS, NOAA
   * Peer-reviewed research: Brewer et al. (1997), Harrower & Brewer (2003)
   * 20+ years of refinement for print and digital media
   * Built into D3.js, Matplotlib, ggplot2, Tableau

3. **Semantic Clarity**
   * Set3 palette provides 11 distinct colors perfect for component categorization
   * Enough variety (11 colors) for complex diagrams
   * Not too many (cognitive load limit \~7±2 categories)
   * Qualitative palette (categorical data, not sequential)
   * Colors are perceptually distinct even to color-blind users

4. **Print and Digital Compatibility**
   * Print-safe (CMYK conversion tested)
   * Screen-optimized (sRGB color space)
   * Consistent across browsers (standard hex codes)
   * Works in black & white (different luminance values)

### Why Not Alternative Approaches?

**Material Design Palette** - Rejected: Good for UI, but not optimized for diagrams

* Designed for interactive UI elements (buttons, cards)
* Not tested for diagram-specific use cases
* Accessibility not guaranteed across all color pairs
* Too many variations (14 colors × 10 shades = 140 options = cognitive overload)

**Custom Brand Colors** - Rejected: Accessibility concerns

* Brand colors rarely meet WCAG AA requirements
* Semantic meanings may conflict with brand associations
* Harder to maintain (no standard reference)
* Creates vendor lock-in

**Randomized Colors** - Rejected: Semantic ambiguity

* No consistency across diagrams
* Colors don't convey meaning
* Accessibility not guaranteed
* Maintenance nightmare

**Grayscale Only** - Rejected: Poor information density

* Harder to distinguish components quickly
* Reduced accessibility for sighted users
* Diagrams are less engaging

## Consequences

### Positive

* Visual consistency: All 82+ diagrams follow same color language
* Accessibility compliance: 100% WCAG 2.1 AA conformance
* Faster comprehension: Users learn color meanings once, apply everywhere
* Semantic clarity: Red = error, Green = success, Blue = data (universal meanings)
* Maintainability: classDef reuse reduces code duplication
* Automated enforcement: Pre-commit hooks prevent regressions
* Modern syntax: Future-proof with Mermaid 11.4.1+ features
* Professional appearance: Industry-standard visualization quality
* Print compatibility: Diagrams work in documentation PDFs

### Negative

* Initial migration effort: Required updating 82+ diagrams (completed 2025-11-15)
* Learning curve: Contributors must learn ColorBrewer2 Set3 palette (mitigated by templates)
* Less flexibility: Can't use arbitrary colors (trade-off for consistency)
* Validation overhead: Pre-commit hooks add \~5-10 seconds (acceptable for quality)

### Neutral

* 11 colors: Sufficient for most diagrams, but complex diagrams may need careful planning
* Semantic mapping: Requires thoughtful component categorization (documented in guide)
* Tooling dependency: Requires mmdc CLI for validation (already in use)

## Implementation

### Phase 1: Standards Definition (Completed 2025-10-01)

* Created `docs/.mintlify/MERMAID_OPTIMIZATION_GUIDE.md` (446 lines)
* Created `docs/references/mermaid-guide.mdx` (400 lines)
* Defined ColorBrewer2 Set3 palette with semantic assignments
* Created 3 ready-to-use diagram templates

### Phase 2: Validation Infrastructure (Completed 2025-10-15)

* Implemented 7 validation/automation scripts
* Added 2 test suites
* Configured pre-commit hook (`check-mermaid-styling`)
* Set up CI/CD validation

### Phase 3: Migration (Completed 2025-11-15)

* Migrated 82+ diagrams to ColorBrewer2 Set3 palette
* Converted all `graph` syntax to `flowchart` syntax
* Refactored inline styles to `classDef` declarations
* Added theme initialization to all sequence diagrams

### Phase 4: Compliance Achievement (Completed 2025-11-15)

* **100% production diagram compliance** ✅
* **0 syntax errors** ✅
* **0 deprecated syntax** ✅
* **100% ColorBrewer2 Set3 adoption** ✅

## Compliance Metrics

* **Total diagrams**: 82+ across 67+ files
* **Syntax compliance**: 100% (modern flowchart/sequenceDiagram)
* **Style compliance**: 100% (ColorBrewer2 Set3 styled)
* **Accessibility**: 100% (WCAG 2.1 AA compliant)

## Maintenance

### Ongoing Responsibilities

**Weekly**:

* Run validation on changed files (automated via pre-commit hook)
* Review new diagrams for semantic color accuracy

**Monthly**:

* Run full validation suite (`make validate-all`)
* Review complexity metrics (target \< 50)
* Refactor overly complex diagrams (complexity > 70)

**Quarterly**:

* Full accessibility review (contrast ratios, color-blind simulation)
* Update `MERMAID_OPTIMIZATION_GUIDE.md` with new patterns
* Review and update semantic color assignments if needed

## References

* **ColorBrewer2**: [https://colorbrewer2.org/](https://colorbrewer2.org/)
* **Mermaid.js**: [https://mermaid.js.org/](https://mermaid.js.org/)
* **WCAG 2.1 Guidelines**: [https://www.w3.org/WAI/WCAG21/quickref/](https://www.w3.org/WAI/WCAG21/quickref/)
* **User Guide**: `docs/references/mermaid-guide.mdx`
* **Internal Guide**: `docs/.mintlify/MERMAID_OPTIMIZATION_GUIDE.md`

### Academic References

* Brewer, C. A., MacEachren, A. M., Pickle, L. W., & Herrmann, D. (1997). "Mapping Mortality: Evaluating Color Schemes for Choropleth Maps." *Annals of the Association of American Geographers*, 87(3), 411-438.
* Harrower, M., & Brewer, C. A. (2003). "ColorBrewer.org: An Online Tool for Selecting Colour Schemes for Maps." *The Cartographic Journal*, 40(1), 27-37.

## Related ADRs

* ADR-0030: Resilience Patterns - Contains state diagram examples
* ADR-0027: Rate Limiting Strategy - Contains sequence diagram examples
* ADR-0028: Caching Strategy - Contains complex architecture diagrams

***

**Last Reviewed**: 2025-11-15
**Next Review**: 2026-02-15 (Quarterly)
**Owner**: Documentation Team