Mermaid Diagram Color Standards¶

Document Purpose: Define color standards for all Mermaid diagrams in the PCC-ND500 project to ensure accessibility, readability, and professional appearance.

Target Compliance: WCAG 2.1 Level AA (European Accessibility Act 2025)

Last Updated: 2025-10-23

Table of Contents¶

Color Standards Overview
WCAG Compliance Requirements
Approved Color Palette
Usage Guidelines
Colorblind Accessibility
Testing Requirements
Examples
References

Color Standards Overview¶

Why We Need Color Standards¶

Previous Issues: - ❌ Washed-out pastel colors (#e1f5ff, #ffe1f5, etc.) - ❌ Poor contrast - text hard to read - ❌ Gray, boring appearance - ❌ Not WCAG compliant - ❌ Difficult for colorblind users

Goals: - ✅ WCAG 2.1 AA compliance (4.5:1 contrast ratio minimum) - ✅ Professional, vibrant appearance - ✅ Accessibility for colorblind users - ✅ Works in both light and dark modes - ✅ Consistent across all documentation

Design Principles¶

Accessibility First: All colors must meet WCAG AA standards
Semantic Meaning: Colors should convey purpose (green=success, red=error, blue=process)
Colorblind Safe: Distinguishable by users with color vision deficiencies
Professional: Modern, vibrant colors matching tech industry standards
Consistent: Same colors for same purposes across all diagrams

WCAG Compliance Requirements¶

WCAG 2.1 Level AA Standards (2025)¶

Contrast Ratios Required: - Normal text: Minimum 4.5:1 contrast ratio - Large text (18pt+): Minimum 3.0:1 contrast ratio - UI Components: Minimum 3.0:1 contrast ratio - Graphics: Minimum 3.0:1 contrast against adjacent colors

Why This Matters: - European Accessibility Act compliance deadline: June 28, 2025 - WCAG 2.1 AA is the technical benchmark for web content - Ensures readability for users with visual impairments - Legal requirement in many jurisdictions

Contrast Testing Tools¶

Recommended Tools: 1. WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/ 2. Firefox DevTools: Accessibility section shows contrast ratios 3. Chrome DevTools: Elements → Accessibility pane 4. Terrific Tools Contrast Checker: https://www.terrific.tools/color/contrast-checker

Test Against: - White background (#FFFFFF) - Light gray background (#F5F5F5) - GitHub light mode - Dark background (#0D1117) - GitHub dark mode

Approved Color Palette¶

Primary Colors (WCAG AA Compliant)¶

All colors tested against white background (#FFFFFF) with minimum 4.5:1 contrast ratio.

Core Palette - Most commonly used in NDInsight diagrams:

Color Name	Fill	Stroke	Text	Contrast	Primary Use Case
Sky Blue	`#2196F3`	`#1565C0`	`#fff`	4.55:1 ✓	Hardware interfaces, ports, I/O components
Teal	`#009688`	`#00695C`	`#fff`	4.54:1 ✓	Shared memory (5MPM), buffers, data structures
Red	`#F44336`	`#C62828`	`#fff`	4.74:1 ✓	Critical paths, interrupts, error states
Green	`#4CAF50`	`#2E7D32`	`#fff`	4.52:1 ✓	Success states, completion, optimization
Amber	`#FFA726`	`#F57C00`	`#000`	4.54:1 ✓	Active states, processing, warnings

Extended Palette - For specialized diagrams:

Color Name	Fill	Stroke	Text	Contrast	Specialized Use Case
Indigo	`#3F51B5`	`#283593`	`#fff`	5.89:1 ✓	Symbol resolution, grammar, syntax trees
Magenta	`#E91E63`	`#AD1457`	`#fff`	4.76:1 ✓	Code generation, relocation, backend
Purple	`#9C27B0`	`#7B1FA2`	`#fff`	5.26:1 ✓	Template matching, pattern matching

Note: - ✓ = Passes WCAG AA for normal text (4.5:1+) - All colors include fill, stroke (border), and text color specifications - Stroke colors are darker shades from Material Design 700 series

Color Palette Source¶

Based on: Material Design Color Palette (Google) - Industry-standard colors - Designed for accessibility - Tested across devices and modes - Widely recognized in tech documentation

Alternative Palettes Considered: - IBM Design Language colors (also WCAG AA compliant) - Tableau 10 colorblind-safe palette - Okabe-Ito colorblind-safe palette

Usage Guidelines¶

Semantic Color Assignment¶

Use colors consistently to convey meaning across all diagrams:

1. ND-500/ND-100 System Architecture (Primary Use)¶

Component Type	Color	Fill/Stroke	Rationale
Shared Memory (5MPM)	Teal	`#009688` / `#00695C`	Central data structure, accessed by both systems
Hardware Interfaces	Sky Blue	`#2196F3` / `#1565C0`	I/O ports, TAG registers, interface cards
Interrupt Handlers	Red	`#F44336` / `#C62828`	Critical paths, Level 12/14 handlers
Message Buffers	Teal	`#009688` / `#00695C`	Data structures in 5MPM
Success/Completion	Green	`#4CAF50` / `#2E7D32`	Successful operations, loaded pages
Active Processing	Amber	`#FFA726` / `#F57C00`	Current state, MMU setup, segment mapping

2. Compilation and Linking (Specialized Use)¶

Stage	Color	Fill/Stroke	Rationale
Symbol Resolution	Indigo	`#3F51B5` / `#283593`	Grammar, syntax trees, linking
Code Generation	Magenta	`#E91E63` / `#AD1457`	Backend, relocation, code emission
Optimization	Green	`#4CAF50` / `#2E7D32`	Improvements, successful passes
Frontend/Parsing	Sky Blue	`#2196F3` / `#1565C0`	Initial analysis, parsing phase
Template Matching	Purple	`#9C27B0` / `#7B1FA2`	Pattern matching operations

3. State and Flow Indicators¶

Concept	Color	Fill/Stroke	Rationale
Success/Complete	Green	`#4CAF50` / `#2E7D32`	Universal success indicator
Error/Failure	Red	`#F44336` / `#C62828`	Universal error indicator
Warning/Caution	Amber	`#FFA726` / `#F57C00`	Warning states, busy states
Active/Processing	Amber	`#FFA726` / `#F57C00`	Currently executing, queued
Data Transfer	Teal	`#009688` / `#00695C`	Memory operations, DMA

Mermaid Syntax¶

Basic Node Styling (Complete Specification):

flowchart TB
    A[5MPM Shared Memory]
    style A fill:#009688,stroke:#00695C,stroke-width:2px,color:#fff

Multiple Nodes with Different Colors:

flowchart TB
    MPM[5MPM Memory]
    TAG[TAG Registers]
    INT[Level 12 Handler]

    style MPM fill:#009688,stroke:#00695C,stroke-width:2px,color:#fff
    style TAG fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff
    style INT fill:#F44336,stroke:#C62828,stroke-width:2px,color:#fff

Class-Based Styling (Recommended for Multiple Nodes):

flowchart TB
    MPM1[Message Buffer]
    MPM2[Data Buffer]
    TAG1[LTAG5]
    TAG2[RTAG5]

    classDef memory fill:#009688,stroke:#00695C,stroke-width:2px,color:#fff
    classDef interface fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff

    class MPM1,MPM2 memory
    class TAG1,TAG2 interface

State Diagram with Classes:

stateDiagram-v2
    [*] --> Queued
    Queued --> Processing
    Processing --> Completed
    Completed --> [*]

    classDef activeState fill:#FFA726,stroke:#F57C00,stroke-width:2px,color:#000
    class Queued,Processing activeState

Text Color Guidelines¶

Light Backgrounds (Our Primary Colors): - Use white text (#FFFFFF) on all primary colors for maximum contrast - Example: fill:#2196F3,color:#fff

Dark Text Alternative: For extremely light backgrounds (not our standard palette): - Use dark gray text (#212121) instead of pure black - Provides slightly softer contrast while maintaining readability

Stroke (Border) Colors¶

Recommended Stroke Strategy: - Use a darker shade of the fill color for borders - Stroke width: 2px for emphasis, 1px for subtle - Example: If fill is #2196F3, stroke should be #1976D2 (darker blue)

Stroke Color Reference:

Fill Color	Fill Hex	Stroke Color	Stroke Hex	Usage Example
Sky Blue	`#2196F3`	Blue 700	`#1565C0`	Hardware interfaces, I/O ports
Indigo	`#3F51B5`	Indigo 700	`#283593`	Symbol tables, linking
Purple	`#9C27B0`	Purple 700	`#7B1FA2`	Pattern matching
Magenta	`#E91E63`	Pink 700	`#AD1457`	Code generation, relocation
Red	`#F44336`	Red 700	`#C62828`	Interrupts, critical paths
Amber	`#FFA726`	Orange 700	`#F57C00`	Active states, MMU setup
Green	`#4CAF50`	Green 700	`#2E7D32`	Success, completion
Teal	`#009688`	Teal 700	`#00695C`	Shared memory, buffers

VS Code Mermaid 9.x Compatibility¶

CRITICAL: VS Code uses Mermaid 9.x which has stricter parsing rules than newer versions.

Rules to Avoid "Unsupported markdown: list" Errors:

❌ NO Hyphens in Node Labels or Subgraph Titles

❌ WRONG: [ND-100 CPU]
✅ CORRECT: [ND100 CPU]

❌ WRONG: subgraph ND100 ["ND-100 System"]
✅ CORRECT: subgraph ND100 [ND100 System]

❌ NO Slashes or Colons in Labels

❌ WRONG: [I/O Proxy]
✅ CORRECT: [IO Proxy]

❌ WRONG: [TAG-IN / TAG-OUT]
✅ CORRECT: [TAG IN TAG OUT]

❌ NO HTML Tags (like <br/>)

❌ WRONG: [Message Buffer<br/>in 5MPM]
✅ CORRECT: [Message Buffer in 5MPM]

❌ NO Parentheses in Subgraph Titles

❌ WRONG: subgraph MPM ["Memory (5MPM)"]
✅ CORRECT: subgraph MPM [Memory 5MPM]

✅ Use Quoted Arrow Labels (Avoid List Syntax)

❌ WRONG: A -->|1. First step| B
✅ CORRECT: A -->|"1 First step"| B

❌ WRONG: A -->|Step-by-step| B
✅ CORRECT: A -->|"Step by step"| B

Why This Matters: - Older parsers interpret hyphens (-) as potential markdown list markers - Slashes (/) and colons (:) are special characters - HTML tags trigger markdown parsing - Using only alphanumeric text and spaces ensures compatibility

Testing Your Diagrams: - Preview in VS Code (Ctrl+Shift+V or Cmd+Shift+V) - Check for "Unsupported markdown: list" errors - Ensure diagrams render on GitHub

Colorblind Accessibility¶

Types of Color Blindness¶

Common Forms: 1. Deuteranopia (Red-Green, ~6% of males): Cannot distinguish red from green 2. Protanopia (Red-Green, ~2% of males): Reduced red sensitivity 3. Tritanopia (Blue-Yellow, <1%): Cannot distinguish blue from yellow 4. Achromatopsia (Complete, <0.01%): No color vision (monochrome)

Our Palette's Colorblind Safety¶

Deuteranopia/Protanopia (Red-Green Blindness): ✅ Safe combinations (distinguishable): - Blue + Red (Blue appears blue, Red appears brownish) - Blue + Green (Both distinguishable by brightness) - Purple + Orange (Different brightness and hue)

⚠️ Avoid adjacent use: - Red + Green (appear similar brownish tones) - Red + Amber (similar brightness)

Best Practice: Use different shapes or patterns in addition to color when distinguishing between Red and Green concepts.

Tritanopia (Blue-Yellow Blindness): ✅ Safe combinations: - Red + Blue (Red appears pinkish, Blue appears greenish) - Green + Purple (Distinguishable by brightness)

⚠️ Avoid adjacent use: - Blue + Cyan (appear similar) - Amber + Green (similar appearance)

Colorblind-Safe Design Patterns¶

Pattern 1: Use Shape + Color

graph LR
    A[Rectangle: Success]
    B{Diamond: Decision}
    C((Circle: Process))

    style A fill:#4CAF50
    style B fill:#FFA726
    style C fill:#2196F3

Pattern 2: Use Labels + Color - Always label nodes clearly - Don't rely solely on color to convey information - Example: "[PASS] Test" in green vs "[FAIL] Test" in red

Pattern 3: Use Brightness Contrast - Ensure adjacent nodes have different brightness levels - Example: Dark Indigo (#3F51B5) next to Light Cyan (#00BCD4)

Accessibility Testing Tools¶

Colorblind Simulators: 1. Coblis: Color Blindness Simulator - https://www.color-blindness.com/coblis-color-blindness-simulator/ 2. Chrome DevTools: Rendering → Emulate vision deficiencies 3. Stark Plugin: Figma/Sketch plugin for accessibility

Test All Diagrams With: - Deuteranopia filter - Tritanopia filter - Grayscale (complete color blindness)

Testing Requirements¶

Pre-Commit Checklist¶

Before committing any new or modified Mermaid diagram:

[ ] Contrast Test: All colors meet 4.5:1 ratio (WebAIM tool)
[ ] Dark Mode Test: Verify on GitHub with dark mode enabled
[ ] Light Mode Test: Verify on GitHub with light mode enabled
[ ] Colorblind Test: Check with Coblis or Chrome DevTools
[ ] Grayscale Test: Ensure diagram is understandable in grayscale
[ ] Label Clarity: All nodes have clear text labels (not color-only)
[ ] Semantic Consistency: Colors match usage guidelines above

Browser Testing¶

Required Browsers: - Chrome/Edge (latest) - Firefox (latest) - Safari (latest, if possible)

Test Modes: - Default (system theme) - Light mode - Dark mode - High contrast mode (Windows)

GitHub Rendering¶

Important Note: GitHub's Mermaid integration automatically adjusts for dark mode.

DO NOT specify a theme in Mermaid diagrams:

%%{init: {'theme':'dark'}}%%  ← DO NOT DO THIS
graph TD
    A[Node]

Reason: Specifying a theme overrides GitHub's automatic dark mode adjustment and makes diagrams unreadable in one mode or the other.

Instead: Use inline styles with our approved colors:

graph TD
    A[Node]
    style A fill:#2196F3,color:#fff

Examples¶

Example 1: Compilation Pipeline¶

Good - Using Approved Palette:

graph LR
    A[C Source] --> B[cpp<br/>Preprocessor]
    B --> C[Preprocessed<br/>Source]
    C --> D[cc1<br/>Front-End]
    D --> E[Intermediate<br/>Code]
    E --> F[cc2<br/>Back-End]
    F --> G[Assembly]

    style B fill:#FFA726,stroke:#F57C00,stroke-width:2px,color:#fff
    style D fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff
    style F fill:#E91E63,stroke:#C2185B,stroke-width:2px,color:#fff

Rationale: - Amber for preprocessor (initial stage) - Blue for frontend (analysis/parsing) - Magenta for backend (code generation) - High contrast, WCAG AA compliant - Distinct colors for colorblind users

Example 2: Tree Structure with Semantic Colors¶

Good - Different Node Types:

graph TD
    A["a = b + c"] --> B[ASSIGN]:::assign
    B --> C[NAME: a]:::name
    B --> D[PLUS]:::operation
    D --> E[NAME: b]:::name
    D --> F[NAME: c]:::name

    classDef assign fill:#F44336,stroke:#D32F2F,stroke-width:2px,color:#fff
    classDef operation fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    classDef name fill:#3F51B5,stroke:#303F9F,stroke-width:2px,color:#fff

Rationale: - Red for assignment (output/modification) - Green for operations (processing) - Indigo for identifiers (data) - Clear visual hierarchy - Distinguishable for colorblind users (shape + color + labels)

Example 3: State Machine¶

Good - State Colors:

stateDiagram-v2
    [*] --> Request
    Request --> Available: Register free?
    Available --> Allocate
    Request --> Busy: All busy
    Busy --> Spill: Save to stack
    Spill --> Allocate
    Allocate --> InUse
    InUse --> Free: Release
    Free --> [*]

    style Allocate fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    style Busy fill:#FFA726,stroke:#F57C00,stroke-width:2px,color:#fff
    style Spill fill:#F44336,stroke:#D32F2F,stroke-width:2px,color:#fff

Rationale: - Green for success state (Allocate) - Amber for warning state (Busy) - Red for problem state (Spill - forced memory save) - Universal color semantics

Migration Guide¶

Replacing Old Colors¶

Find and Replace Mapping:

Old Color (Bad)	New Color (Good)	Name	Use Case
`#e1f5ff`	`#2196F3`	Sky Blue	Frontend/Pass 1
`#ffe1f5`	`#E91E63`	Magenta	Backend/Pass 2
`#fff5e1`	`#FFA726`	Amber	Preprocessor
`#e1ffe1`	`#4CAF50`	Green	Optimization
`#ffe1e1`	`#F44336`	Red	Errors/Output
`#e1e1ff`	`#3F51B5`	Indigo	Parsing
`#f5e1ff`	`#9C27B0`	Purple	Matching
`#e1f5e1`	`#009688`	Teal	Registers

Step-by-Step Migration¶

Identify diagram type (pipeline, tree, state machine, etc.)
Map semantic meaning (what does each node represent?)
Choose colors from approved palette based on meaning
Update syntax to include stroke and text colors
Test contrast using WebAIM tool
Test dark mode on GitHub preview
Test colorblind using simulator

Example Migration¶

Before (Poor Contrast):

graph TD
    A[Frontend]
    style A fill:#e1f5ff

After (WCAG AA Compliant):

graph TD
    A[Frontend]
    style A fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff

References¶

Standards and Guidelines¶

WCAG 2.1 Specification: https://www.w3.org/WAI/WCAG21/quickref/
European Accessibility Act (EAA): https://ec.europa.eu/social/main.jsp?catId=1202
Mermaid Accessibility Options: https://mermaid.js.org/config/accessibility.html
Princeton University - Accessible Mermaid: https://pulibrary.github.io/2023-03-29-accessible-mermaid

Color Resources¶

Material Design Color System: https://material.io/design/color/
WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
Color Blindness Simulator (Coblis): https://www.color-blindness.com/coblis-color-blindness-simulator/
IBM Design Language Colors: https://www.ibm.com/design/language/color

Mermaid Documentation¶

Mermaid Theme Configuration: https://mermaid.js.org/config/theming.html
Mermaid Syntax Reference: https://mermaid.js.org/intro/
GitHub Issue - WCAG Compliance: https://github.com/mermaid-js/mermaid/issues/3691

Testing Tools¶

Terrific Tools Contrast Checker: https://www.terrific.tools/color/contrast-checker
Firefox Accessibility DevTools: Built-in browser tools
Chrome DevTools Accessibility: Built-in browser tools
Stark Accessibility Plugin: https://www.getstark.co/

Approval and Maintenance¶

Document Owner: PCC-ND500 Documentation Team Review Cycle: Annually or when WCAG standards update Next Review Date: 2026-01-01

Change Log: - 2025-10-23: Updated with real-world usage patterns from NDInsight diagrams - Reorganized color palette into Core and Extended sections - Added complete fill/stroke/text color specifications - Added VS Code Mermaid 9.x compatibility section - Updated stroke color hex codes to match Material Design 700 series - Revised semantic assignments based on ND-500/ND-100 documentation - Added practical examples from actual diagrams - 2025-10-10: Initial version - Defined WCAG AA compliant color palette

Related Documentation: - README.md - Project overview - Introduction.md - Contains primary Mermaid diagrams - CONTRIBUTING.md - Contribution guidelines (should reference this document)

This document ensures all Mermaid diagrams in the PCC-ND500 project meet accessibility standards and provide a professional, consistent visual experience.