6256 - Allow themeVariables to have additional valid CSS colors

[MikeSQ]

📑 Summary

This is to resolve the recent issue I submitted. Before this PR there are several color options that can't be used without the sanitization stripping them out. After the PR, you should be able to set a themeVariable to:

• var(--some-css-var)
• light-dark(var(--lightColor), var(--darkColor))
• lighten(var(--someColor), 10%)
• oklch(from var(--base-color) calc(1 * 1.15) c h)

For me, this will enable easy theming of the diagrams based on user selection of light mode or dark mode, but in general it should open up a lot of theming possibilities for everybody I think.

This is my first PR on a major project, so apologies if I make any mistakes :)

Resolves #6256

📏 Design Decisions

The only change here was to the regular expression, I tried to do the bare minimum to allow the CSS. Dashes were added which covers most of the features above, I also added the ability to do *, +, /

📋 Tasks

Make sure you

• [✅ ] 📖 have read the contribution guidelines
• [✅ ] 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b6c35be

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	b6c35be
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/67a63f5154d7d900080ae731
😎 Deploy Preview	https://deploy-preview-6261--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/mermaid-js/mermaid@6261

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/mermaid-zenuml@6261

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-elk@6261

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/parser@6261

commit: b6c35be

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 1 line in your changes missing coverage. Please review.

Project coverage is 4.47%. Comparing base (8dd0e7a) to head (b6c35be).

Files with missing lines	Patch %	Lines
packages/mermaid/src/utils/sanitizeDirective.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #6261   +/-   ##
=======================================
  Coverage     4.47%   4.47%           
=======================================
  Files          385     384    -1     
  Lines        54191   54180   -11     
  Branches       598     623   +25     
=======================================
  Hits          2425    2425           
+ Misses       51766   51755   -11     

Flag	Coverage Δ
unit	4.47% <0.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/utils/sanitizeDirective.ts	13.09% <0.00%> (ø)

... and 1 file with indirect coverage changes

[nour0205]

Hi @MikeSQ,

Thank you for your work on this PR! I tested it locally, and here are my findings:

What Works

• The PR correctly allows CSS variables like var(--bs-blue), light-dark(), and lighten(var(--someColor), 10%) in themeVariables without being stripped during validation.

Remaining Issues

This PR aims to resolve Issue #6256, but I encountered the following problems during testing:

1. CSS variables are not retained in the final theme configuration.

   • After initializing Mermaid with:

     mermaid.initialize({
       startOnLoad: true,
       themeVariables: {
         primaryColor: "var(--bs-blue)",
         secondaryColor: "light-dark(white, black)",
         tertiaryColor: "lighten(var(--someColor), 10%)"
       }
     });

   • Running console.log(mermaid.mermaidAPI.getConfig()?.themeVariables); does not show the CSS variables.
   • Instead, only standard color values (like "blue", "red", "green") appear.

2. An "Unsupported color format" error occurs.

   • The console throws this error when trying to use CSS variables:

     Uncaught Error: Unsupported color format: "var(--bs-blue)"
     

   • This suggests that while validation allows CSS variables, another part of Mermaid still does not support them.

Next Steps

Would love to hear your thoughts on this!
Thanks again for your work on this!

Best,
nour0205

[MikeSQ]

Oh thank you for taking a look @nour0205 ! I had only been testing with the sequence diagram, as that was the one I had been working with when I wanted to allow easier conversion between light mode and dark mode. It had worked fine there, I assumed that it would be similar in other diagrams if it worked there. I was pretty excited to see it working fine in the deployed netlify branch haha

I haven't really worked with the Mermaid library source before, do you know if this somehow has another blocker that makes it a bad idea? I'd really like to get support for these things if we can, but I don't know if it somehow runs counter to original design intentions

[MikeSQ]

Interesting, I did a bit more testing, and it looks like it only cares a lot about primaryColor and secondaryColor, tertiaryColor doesn't mind the dashes and of course the others I had been testing were working ok

      mermaid.initialize({
        startOnLoad: true,
        logLevel: 0,
        themeVariables: { 
          primaryColor: "blue",   //Threw error with dashes
          secondaryColor: "blue", //Threw error with dashes
          tertiaryColor: "var(--sd-hotpink)", //Works fine
          activationBkgColor: "light-dark(var(--sd-hotpink),green)",  //Fine
          activationBorderColor: "rebeccapurple", //Fine
          activeTaskBkgColor: "#123abc" //Fine
         }
      });

edit: Further investigation shows that it really depends on what theme you have chosen and how much it relies on those base colors for calculating variable values in the theme's updateColors() function. If I change the theme to another theme then tertiaryColor also breaks.

I don't know what the best way to solve this might be. Possibly just allowing dashes in the non-base-color variables? Those are the ones that seem most likely to have color math applied to them. It would be great if it was supported everywhere, but I don't know if there is a reliable way to resolve the css function stuff to colors prior to the math is attempted.

[nour0205]

Hi @MikeSQ,

Thanks for your additional testing!
Your findings make a lot of sense primaryColor and secondaryColor likely break because they are core theme variables that undergo transformations, while tertiaryColor and other variables may not always be processed the same way.

The fact that tertiaryColor works in some themes but not others suggests that certain themes apply dynamic calculations (updateColors()), while others allow CSS variables to pass through untouched.

Your idea of allowing dashes only in non-base colors seems like a practical approach, as those are less likely to be used in calculations. If a more complete fix is needed, ensuring that CSS variables pass through where possible but are skipped in places where math is applied could be worth exploring.

Thanks again for your great work on this PR!

Best,
nour0205