Add styling for mermaid diagrams

[smeragoel]

Currently, mermaid diagrams are using default colours for styling: https://theme.scientific-python.org/features/#mermaid-diagrams which do not match the theme colors, and don't pass WCAG colour contrast standards.

[smeragoel]

Here's my first draft:

Dark Mode:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Segoe UI',
      'fontSize': '14px',
      'primaryColor': '#29313D',
      'primaryTextColor': '#CED6DD',
      'primaryBorderColor': '#48566b',
      'lineColor': '#48566b',
      'secondaryColor': '#6E1C64',
      'tertiaryColor': '#fff'
      
    }
  }
}%%

Light Mode:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Segoe UI',
      'fontSize': '14px',
      'primaryColor': '#F9F9FA',
      'primaryTextColor': '#545454',
      'primaryBorderColor': '#d1d5da',
      'lineColor': '#d1d5da',
      'secondaryColor': '#F3C7EE'
    }
  }
}%%

I'm using https://mermaid.live/ to try out different color stylings, however, I haven't been able to figure out how to change the background color. I think this needs tweaking because the diagrams will be rendered inside code blocks, so that's what I'll work on next.

[jarrodmillman]

We currently have to refresh the page when switching between dark / light mode for mermaid to switch themes.

Here are some random links so I don't lose them:

• https://discourse.gohugo.io/t/how-to-theme-mermaid-diagrams/48221/3
• https://github.com/gollum/gollum/pull/1938/files
• https://github.com/badboy/mdbook-mermaid/pull/39/files

[smeragoel]

Alright, I have an update on this. I reconstructed the graphs in Figma so that I could have better control over the colour values and I could easily check for contrast. Since the graphs will be generated in code blocks, I also added those colours in the background.

These are the colour values I used:

1. Dark Mode

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Segoe UI',
      'fontSize': '14px',
      'primaryColor': '#48566B',
      'primaryTextColor': '#ffffff',
      'primaryBorderColor': '#677384',
      'lineColor': '#677384',
      'secondaryColor': '#912583'      
    }
  }
}%%

2. Light Mode

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'fontFamily': 'Segoe UI',
      'fontSize': '14px',
      'primaryColor': '#D1D5DA',
      'primaryTextColor': '#14181E',
      'primaryBorderColor': '#9CA4AF',
      'lineColor': '#9CA4AF',
      'secondaryColor': '#F3C7EE'      
    }
  }
}%%

I'd love to get some feedback on this, but overall I think this styling is ready. The only caveat at this point is that this only covers the basic colours and styling, and for more complicated graphs, we would need additional styling. If there's a commonly used complex graph, I can design the styling for that, otherwise this is a good base point! 👍🏼

[smeragoel]

@trallard @isabela-pf could you take a look and share your feedback on the new styling?

[isabela-pf]

Thanks for the tag, the good descriptions, and the clear example mockups. I found this very easy to review and I am grateful!

Both in contrast checking and in matching the theme, I think these options work. I don't have any issues with the light or dark mode stylings. The only things I noticed were:

• The primaryColor to primaryBorderColorcontrast on both modes is just below the 3:1 I expected for a non-text element by my judgement. I'm not sure if this is something I'm missing though, since I am getting a 2.7:1 which is awfully close. So it may be my mistake somewhere along the line. Considering that the primaryTextColor options have good contrast on all the colors they are shown on, I am not concerned that they will become illegible due to any border color changes.
• The secondaryColor level of the charts not having a border is common practice as far as I'm aware, but I did want to check if we had any reason for it here. Is it just because this is what mermaid diagrams support in terms of styling? Or is there another reason behind the choice I'm missing and may not be testing for? The primaryTextColors do have enough contrast on their code block backgrounds and on the secondaryColor backgrounds which is great, but since there is not a big jump between the code block backgrounds and secondaryColor I wanted to double check that them being lower contrast is okay and intended.

Please let me know if you have any questions! I agree with @smeragoel that this styling can be implemented and will be an improvement compared to what's currently there even without my questions addressed.

More generally, I would like to ask one thing about maintenance: is there any extra maintenance load, dependencies, or anything else that comes from switching from default mermaid diagram colors to bespoke ones?

[trallard]

There should not be any extra dependencies needed or maintenance burden once the colour scheme is implemented.
IIRC the mermaid API is pretty stable right now so I don't anticipate needing a lot of upkeep to adopt and maintain a custom theme.