Enable CSS-like linear gradient fills for flowchart nodes

[enourbakhsh]

📑 Summary

This PR adds support for CSS-like linear-gradient fills to Mermaid, following the CSS linear-gradient syntax. It introduces a reusable gradient utility that can be applied to other diagrams in the future, though this PR focuses on flowcharts as an example of how the feature can be used. A wide-ranging, editable collection of side-by-side examples comparing Mermaid and CSS linear gradients is available on this CodePen.

Resolves #2907 and #4476

📏 Design Decisions

The implementation involves updating the lexer to recognize the linear-gradient syntax and modifying the renderer to correctly apply the gradient fills to flowchart nodes. The design follows a CSS-like approach to maintain familiarity for users. See how gradient lines adapt dynamically to various shapes in this CodePen demo, which reflects the design principles behind the added feature.

📋 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]

🦋 Changeset detected

Latest commit: 5f46a0f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

Not sure what this means? Click here to learn what changesets are.

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	5f46a0f
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/673855fc9d28910008718405
😎 Deploy Preview	https://deploy-preview-5913--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

pnpm add https://pkg.pr.new/mermaid-js/mermaid@5913

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/mermaid-zenuml@5913

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-elk@5913

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/parser@5913

commit: 5f46a0f

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Dec 31, 2024, 11:13 PM

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 881 lines in your changes missing coverage. Please review.

Project coverage is 4.42%. Comparing base (8328f74) to head (5f46a0f).

Files with missing lines	Patch %	Lines
...kages/mermaid/src/rendering-util/createGradient.ts	0.00%	747 Missing ⚠️
.../src/diagrams/flowchart/flowRenderer-v3-unified.ts	0.00%	134 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #5913      +/-   ##
==========================================
- Coverage     4.49%   4.42%   -0.08%     
==========================================
  Files          382     383       +1     
  Lines        53914   54792     +878     
  Branches       621     622       +1     
==========================================
  Hits          2425    2425              
- Misses       51489   52367     +878     

Flag	Coverage Δ
unit	4.42% <0.00%> (-0.08%)	⬇️

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

Files with missing lines	Coverage Δ
.../src/diagrams/flowchart/flowRenderer-v3-unified.ts	0.00% <0.00%> (ø)
...kages/mermaid/src/rendering-util/createGradient.ts	0.00% <0.00%> (ø)

[enourbakhsh]

@knsv @sidharthv96, your review on this PR would be appreciated when you have time. Thank you!

[sidharthv96]

Hi @enourbakhsh thank you for your patience. This is a high-quality PR, with great tests and documentation. I wonder if there is an option to offload the complexity of gradients to CSS, instead of reimplementing the logic inside mermaid, or is there some technical limitation that prevents it?

[enourbakhsh]

Hi @enourbakhsh thank you for your patience. This is a high-quality PR, with great tests and documentation. I wonder if there is an option to offload the complexity of gradients to CSS, instead of reimplementing the logic inside mermaid, or is there some technical limitation that prevents it?

Hi @sidharthv96, thank you for your feedback! I first tried the CSS approach using a div element with linear-gradient and clip-path inside a foreignObject since I agree it’s best to lean on CSS when possible. This pure CSS approach worked well for rectangular nodes but didn’t adapt to other shapes as expected. That’s why I went through the hassle of implementing the gradient logic directly in SVG, which is probably the most complete solution for converting CSS linear-gradient syntax to SVG <linearGradient> on the internet (at least as far as I’m aware, lol).

The thing is, with the CSS-based approach, we are limited to rendering the gradient in the rectangular frame of the node's bbox and then clipping it, which doesn’t respect the shape-dependent gradient line length explored in this CodePen. Please let me know if you know a workaround. Here’s a comparison of both methods:

flowchart TD
   A[Rectangle] --> B{Rhombus} --> C((Circle)) --> D[(Cylinder)]
   B --> E[/Parallelogram/]
   C --> F([Stadium])
   E --> G[[Subroutine]]
   classDef default fill:linear-gradient(135deg, red, yellow 15%, orange 85%, blue);

SVG-based <linearGradient> (current PR)	CSS-based linear-gradient

As you can see, in the CSS method, the blue and red wings are mostly clipped in some nodes. It might not be a big deal for everyone, but it threw me off.

[sidharthv96]

Ahh, that makes sense! I'm not against adding extra complexity if there is a valid reason. As the codepen was also full of rectangles, I didn't really understand why we needed to re-invent the wheel (although I knew there would be a good one). Now that we know what the problem is, I'll discuss with the team on how to proceed. Thank you!

[enourbakhsh]

Suggested change

	// Log all cssCompiledStyles for the node if available
	// Log the combined style array if available

[enourbakhsh]

This is where the magic happens—we use gradientLineLength to precisely control how the gradient spans the exact node shape at the given angle, something CSS can only do for rectangular shapes.