feat(sankey): add Apple-style rendering with smart labels and custom node colors

[xinbenlv]

📑 Summary

This PR adds Apple-style rendering enhancements to Sankey diagrams, including smart label positioning, outlined labels, and custom node colors.

Resolves #6129 - Sankey improvements: Let user specify node and path color

Related to #6290 - This PR provides an alternative/extended implementation with additional features beyond custom colors.

✨ New Features

1. Custom Node Colors (nodeColors)

Allows specifying colors for individual nodes via frontmatter config:

---
config:
  sankey:
    nodeColors:
      Revenue: "#424245"
      Profit: "#34c759"
      Expenses: "#ff3b30"
---
sankey
source,Revenue,100
Revenue,Profit,60
Revenue,Expenses,40

2. Outlined Labels (labelStyle: 'default')

New default label style with white stroke background for better readability on dark backgrounds.

To use the original plain text labels, set labelStyle: 'legacy'.

3. Smart Label Positioning

Labels automatically position based on node layer relative to the central node (node with maximum value):

• Nodes left of center → labels on left (right-aligned)
• Nodes right of center → labels on right (left-aligned)

4. Configurable Layout

New options:

• nodeWidth: Width of node rectangles (default: 10)
• nodePadding: Padding between nodes (default: 12)

📏 Design Decisions

• nodeColors vs colors: Used nodeColors (object mapping node ID → color) for clarity. Nodes not specified fall back to default D3 color scheme.
• labelStyle enum: 'default' = outlined labels (new), 'legacy' = plain text labels (original). No breaking change since 'default' is now the default.
• Smart label positioning: Inspired by Apple's financial flow diagrams - labels don't overlap with nodes and flows.
• Backward compatible: Existing diagrams render with the new outlined style automatically.

📋 Tasks

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation.
• 🦋 generate changeset

Energy Demo

Before

After

Apple Finance

Before

After

[changeset-bot]

🦋 Changeset detected

Latest commit: 0660f07

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	0660f07
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69cd0f33673d630008cd04d1
😎 Deploy Preview	https://deploy-preview-7272--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 project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

npm i https://pkg.pr.new/mermaid@7272

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7272

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 0660f07

[codecov]

Codecov Report

❌ Patch coverage is 3.03030% with 96 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.34%. Comparing base (f52a239) to head (0660f07).
⚠️ Report is 18 commits behind head on develop.

Files with missing lines	Patch %	Lines
...ages/mermaid/src/diagrams/sankey/sankeyRenderer.ts	0.00%	57 Missing ⚠️
packages/mermaid/src/diagrams/sankey/styles.js	0.00%	27 Missing ⚠️
packages/mermaid/src/utils/sanitizeDirective.ts	0.00%	12 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #7272   +/-   ##
=======================================
  Coverage     3.34%   3.34%           
=======================================
  Files          525     524    -1     
  Lines        55320   55385   +65     
  Branches       795     795           
=======================================
+ Hits          1850    1853    +3     
- Misses       53470   53532   +62     

Flag	Coverage Δ
unit	3.34% <3.03%> (+<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/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/defaultConfig.ts	43.43% <100.00%> (+0.77%)	⬆️
packages/mermaid/src/utils/sanitizeDirective.ts	5.33% <0.00%> (-0.83%)	⬇️
packages/mermaid/src/diagrams/sankey/styles.js	0.00% <0.00%> (ø)
...ages/mermaid/src/diagrams/sankey/sankeyRenderer.ts	0.58% <0.00%> (-0.17%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	5 changed, 9 added	Apr 1, 2026, 12:40 PM

[xinbenlv]

Dear authors, just friendly ping to see if this PR is something you would cojnsider?

[xinbenlv]

Dear authors, just friendly ping to see if this PR is something you would cojnsider?

[ashishjain0512]

Hey @xinbenlv

Thanks for this contribution. We will review this PR soon.

[xinbenlv]

Thank you @ashishjain0512

[xinbenlv]

Hi team, look forward to your early feedback. let me know if there is anything I can help make the review easier

[knsv]

Done together with Claude Code.

Thanks for this contribution, @xinbenlv — the Apple-style financial flow rendering looks excellent, and the before/after screenshots really sell the value of these enhancements. Apologies that this has been waiting for review since late December; let's work through the feedback and get this across the finish line.

---

What's working well

🎉 [praise] The e2e test coverage is thorough — tests for label styles, node width/padding, custom colors with fallback, and the full financial flow demo. This is exactly the kind of coverage Sankey diagrams need.

🎉 [praise] Using config.schema.yaml as the source of truth for new config options is the correct approach. The schema additions for nodeWidth, nodePadding, labelStyle, and nodeColors are well-structured.

🎉 [praise] Before/after screenshots for both energy flow and Apple finance diagrams are very helpful for reviewers. Thank you for including these.

🎉 [praise] The getNodeColor abstraction cleanly separates custom colors from the default D3 color scheme, with a natural fallback.

---

Things to address

🔴 [blocking] Schema damage — SankeyLinkColor definition truncated

config.schema.yaml: The patch accidentally removes two lines from the existing SankeyLinkColor definition when inserting the new SankeyLabelStyle block:

• gradient: Use a gradient of the source and target for the color of the link. (from meta:enum)
• default: gradient

These are essential to the existing Sankey link coloring behavior. The SankeyLabelStyle definition needs to be inserted after the complete SankeyLinkColor block, not in place of its last two lines. Please restore the deleted lines.

🔴 [blocking] Security concern — sanitizeDirective.ts bypass

sanitizeDirective.ts:38-39: The hardcoded dictionaryConfigKeys allowlist skips recursive sanitization for nodeColors, meaning arbitrary user-provided strings bypass the theme variable character whitelist. While color values may seem benign, this creates a precedent where future dictionary configs could silently skip sanitization.

A safer approach would be to either:

1. Validate that each value in nodeColors matches a CSS color pattern (e.g., /^#[0-9a-fA-F]{3,8}$|^rgb/) before accepting it
2. Or run the existing sanitization on the values while skipping the key validation (since the keys are user-defined node IDs)

This is shared infrastructure — changes here affect all diagram types, so it's worth getting the pattern right.

🔴 [blocking] Default rendering output change — potentially breaking

The PR changes two aspects of default rendering for all existing Sankey diagrams:

1. Label style: labelStyle defaults to 'default' (outlined labels with two text elements). All existing diagrams now render with stroke-outlined labels instead of plain text.
2. Label positioning: Changed from position-based (d.x0 < width / 2) to layer-based (relative to the max-value "central" node). This repositions labels on existing diagrams.

Per project conventions, "changing default rendering output in ways visible to consumers" is considered potentially breaking — Mermaid is rendered server-side by GitHub/GitLab, so this would affect existing documents. It would be great to consider:

• Defaulting labelStyle to 'legacy' so existing diagrams are unaffected, and users opt-in to the new style
• Or treating this as a minor bump with clear migration notes in the changeset

🟡 [important] Hardcoded colors in styles.js — theme support

styles.js: The new styles use hardcoded colors that won't adapt to dark/forest/neutral themes:

• stroke: rgba(255, 255, 255, 0.9) — white background stroke will be invisible on light-themed backgrounds, and incorrect on dark theme
• fill: ${options.textColor || '#1d1d1f'} — the #1d1d1f fallback is a dark color that won't work on dark theme

Worth using theme variables throughout (e.g., options.mainBkg or options.background for stroke, options.textColor without a hardcoded fallback). You can reference existing diagrams like journey/styles.js for the pattern.

🟡 [important] Missing changeset

The PR checklist notes this isn't done yet. This is a feature-level change that needs pnpm changeset → select @mermaid-js/mermaid → minor bump → feat: prefixed description.

🟡 [important] Missing documentation

New config options (nodeColors, labelStyle, nodeWidth, nodePadding) need documentation in packages/mermaid/src/docs/. New feature docs should use the MERMAID_RELEASE_VERSION placeholder for version references.

🟡 [important] defaultConfig.ts — unusual pattern for nodeColors

defaultConfig.ts:268: Setting nodeColors: undefined with the comment "allows it through sanitizeDirective" couples the default config to sanitization behavior in a non-obvious way. If the sanitization approach is revised per the security concern above, this coupling may no longer be needed. Worth revisiting after addressing the sanitizeDirective.ts feedback.

🟢 [nit] Type safety in findCentralNodeLayer

sankeyRenderer.ts:36: The function accepts any[] — since the d3-sankey typings are available, it would be nice to use the actual node type for better safety, though I understand d3-sankey's types can be tricky.

🟢 [nit] Duplicated D3 chains in label rendering

sankeyRenderer.ts:197-236: The three label rendering branches (bg, fg, legacy) share nearly identical D3 chain calls. A small helper to build the common chain could reduce the duplication.

---

Out of scope (pre-existing)

Noticed while reading: sankeyRenderer.ts line 64 appears to use defaultSankeyConfig.width! as the fallback for height, which looks like a pre-existing bug. Not related to this PR, but worth a separate fix.

---

Looking forward to your updates — the core feature set here is really valuable for Sankey users. 🙌

[xinbenlv]

Thank you @knsv for your review and encouragement. I will address these comments accordingly soon.

[xinbenlv]

Thank you @knsv, @ashishjain0512 . I've updated the PR,
All tests passes except for the only pending one is failing in argo for visual regressions. I personally inspected and it seems as expected - yes we are introducing new visual. Could you take a look and see if this is ready to be merged? Thx!
Or let me know if there is any change needed from me.

[ashishjain0512]

Great job @xinbenlv !
I have reviewed the argos and approved the build.

Just fix these conflicts, and we'll be happy to merge for the next release.

[github-actions]

❌ Lockfile Validation Failed

The following issue(s) were detected:

Please address these and push an update.

Posted automatically by GitHub Actions

[xinbenlv]

@knsv Thank you for the thorough review! Here's how each item has been addressed:

---

🔴 Blocking Items

1. Schema damage — SankeyLinkColor definition truncated
✅ Resolved. The SankeyLinkColor definition in config.schema.yaml is now complete with all three enum values (source, target, gradient), full meta:enum descriptions, and default: gradient.

2. Security concern — sanitizeDirective.ts bypass
✅ Resolved. Replaced the dictionaryConfigKeys allowlist approach with CSS color pattern validation. nodeColors values are now validated against /^#[\da-f]{3,8}$|^rgb\([\d\s%,.]+\)$|^hsl\([\d\s%,.]+\)$|^[a-z]+$/i — invalid values are rejected and logged. No more bypassing recursive sanitization.

3. Default rendering output change — potentially breaking
✅ Resolved. labelStyle now defaults to legacy, preserving existing Sankey diagram rendering. Users must explicitly opt-in to outlined style. Set in both config.schema.yaml and the renderer fallback.

---

🟡 Important Items

4. Hardcoded colors in styles.js — theme support
✅ Resolved. Replaced hardcoded colors with theme variables: ${options.mainBkg || options.background || '#fff'} for stroke background and ${options.textColor} for label fill. Only a #fff fallback remains when no theme variable is available.

5. Missing changeset
✅ Resolved. Added .changeset/sankey-apple-style.md with 'mermaid': minor bump and feat: prefixed description.

6. Missing documentation
✅ Resolved. Added documentation to packages/mermaid/src/docs/syntax/sankey.md covering all new config options with examples:

• labelStyle — legacy (default) vs outlined
• nodeWidth — node rectangle width in pixels (default: 10)
• nodePadding — vertical padding between nodes (default: 12)
• nodeColors — custom color map with CSS color validation

All use the MERMAID_RELEASE_VERSION placeholder for version references.

7. defaultConfig.ts — nodeColors: undefined
✅ Acceptable. nodeColors: undefined remains so that configKeys includes the key for sanitizeDirective — but since the sanitization approach was revised (item 2), this coupling is now safe: values are validated by CSS color regex, not skipped.

---

🟢 Nits

8. Type safety in findCentralNodeLayer
✅ Resolved. Replaced any[] with a proper SankeyNodeWithLayer interface that extends d3SankeyNode<{ id: string }, Record<string, unknown>> with an optional layer property (computed at runtime by d3-sankey but not in the type definitions).

9. Duplicated D3 chains in label rendering
✅ Resolved. Extracted a shared appendLabel(className?) helper that builds the common D3 chain (.selectAll(), .data(), .join(), .attr(), .text()). The outlined/legacy branches now call this helper instead of duplicating the chain.

---

All feedback has been addressed. Ready for re-review when you have a chance!

[xinbenlv]

Everything passes except for visual regression tests that needs decision from maintainer

[xinbenlv]

Friendly ping @knsv and @ashishjain0512 if anything left

[xinbenlv]

Friendly ping @knsv and @ashishjain0512 if anything left

[xinbenlv]

Rebased onto latest develop and resolved all conflicts. Tests should be green — ready for re-review! 🙏

[mermaid-bot]

@xinbenlv, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.