feat: implemented neo look for mermaid#7376
feat: implemented neo look for mermaid#7376omkarht wants to merge 9 commits intofeature/neo-look-basefrom
Conversation
|
github-actions
bot
added
Type: Enhancement
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## feature/neo-look-base #7376 +/- ##
=======================================================
Coverage 3.53% 3.53%
=======================================================
Files 496 502 +6
Lines 49144 51566 +2422
Branches 771 771
=======================================================
+ Hits 1735 1822 +87
- Misses 47409 49744 +2335
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
…proved readability on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
ashishjain0512
left a comment
ashishjain0512
left a comment
There was a problem hiding this comment.
[sisyphus-bot]
Thanks for this ambitious work, @omkarht — adding a whole new look system with 6 themes to Mermaid is a significant effort, and I appreciate the thoughtful design around gradient borders, drop shadows, and data-attribute-based CSS targeting. Apologies that this has been waiting for review since early February — let's work through the feedback and get this moving.
What's working well
🎉 Clean CSS architecture using [data-look="neo"] attribute selectors. This is the right approach — it allows neo-specific styles to be scoped without polluting the classic or handDrawn look. The data-look attribute set via handleUndefinedAttr(node.look) in nodes.ts follows the existing pattern used by other shape utilities.
🎉 Thorough theme implementation. The 6 new theme files follow the established theme class pattern (constructor → updateColors → calculate). The borderColorArray/bkgColorArray in redux-color themes are well-organized with clear comments. Using khroma color utilities consistently is good practice.
Things to address
🔴 [blocking] — Hardcoded SVG filter IDs in shared render.ts will collide across diagrams
packages/mermaid/src/rendering-util/render.ts:72,85: The drop-shadow filters use hardcoded IDs 'drop-shadow' and 'drop-shadow-small'. When a page has multiple Mermaid diagrams (very common — GitHub renders many per page), all diagrams will create filters with the same IDs. The SVG spec says the first definition wins, so a dark-themed diagram could inherit a light-themed diagram's shadow color or vice versa.
Additionally, these filters are created for every diagram regardless of look — classic and handDrawn diagrams get these filter elements too, even though they don't use them. The filter creation should be:
- Scoped to the diagram: Use the SVG ID as prefix, e.g.,
${svg.attr('id')}-drop-shadow - Conditional on neo look: Only create when
data4Layout.config.look === 'neo'
The CSS in styles.ts that references filter: ${options.dropShadow} would need to match the scoped ID.
🟡 [important] — linearGradient appended outside <defs>
render.ts:97: The gradient is appended directly to svg via svg.append('linearGradient'). Per SVG spec, <linearGradient> must be inside a <defs> element. The filter definitions on lines 70 and 83 correctly use svg.append('defs').append('filter') — the gradient should follow the same pattern:
svg.append('defs').append('linearGradient')Browsers may render it regardless, but invalid SVG can cause issues with server-side renderers and strict XML parsers (relevant since Mermaid is rendered server-side by GitHub/GitLab).
🟡 [important] — Existing themes default to useGradient: true
theme-base.js, theme-forest.js, theme-neutral.js all set this.useGradient = true. This means the classic look with these themes will create SVG gradient definitions in every diagram, even though the gradient CSS is scoped to [data-look="neo"] and won't visually apply.
Consider defaulting useGradient: false in existing themes and only setting it to true in the neo/redux themes. The theme-default.js correctly has useGradient: false.
🟡 [important] — No-op conditional in clusters.js
packages/mermaid/src/rendering-util/rendering-elements/clusters.js:435-440:
let outerRectClass = 'outer';
if (node.look === 'neo') {
outerRectClass = 'divider';
} else {
outerRectClass = 'divider';
}Both branches set the same value 'divider'. The initial assignment to 'outer' is immediately overwritten. This appears to be unfinished — either the neo branch should use a different class, or this conditional should be removed.
🟡 [important] — No E2E visual regression tests
This PR modifies shared rendering code (render.ts, styles.ts, nodes.ts, edges.js, edgeMarker.ts, clusters.js) and adds a new look option. Visual regression tests in cypress/integration/rendering/ using imgSnapshotTest() are essential to:
- Verify the neo look renders correctly across multiple diagram types
- Confirm the classic and handDrawn looks are not regressed by the shared code changes
At minimum, a few snapshot tests with { look: 'neo', theme: 'neo' } and { look: 'neo', theme: 'redux' } for flowchart diagrams would provide baseline coverage.
🟡 [important] — Missing changeset
The changeset checkbox is unchecked. Since this is a significant user-facing feature, it needs:
pnpm changesetSelect minor bump with feat: prefix.
🟡 [important] — Hardcoded #000000 in shared styles
styles.ts:
[data-look="neo"].node circle .state-start {
fill: #000000;
}This hardcoded color won't respect theme settings. For dark themes, #000000 on a dark background will be invisible. Use a theme variable instead (e.g., options.nodeBorder or options.textColor).
🟢 [nit] — svgId in CSS url() should be quoted
styles.ts: Several places use 'url(' + svgId + '-gradient)'. If svgId contains special characters (parentheses, spaces), this breaks. Safer: 'url("' + svgId + '-gradient")'. Same applies to the gradient reference in render.ts.
Security
No XSS or injection issues identified. The changes use D3's .attr() for DOM manipulation with config-derived theme variables (not user diagram text). The data-look attribute is set from node.look which comes from the config system ('classic'/'handDrawn'/'neo'), not from user-provided diagram text. The gradientStart/gradientStop values are theme-defined colors. The handleUndefinedAttr utility safely converts undefined values to empty strings. The final SVG passes through DOMPurify sanitization.
Self-check
- At least one 🎉 [praise] item (2)
- No duplicate comments
- Severity tally: 1 🔴 blocking / 6 🟡 important / 1 🟢 nit / 0 💡 suggestion / 2 🎉 praise
- Verdict matches criteria: REQUEST_CHANGES (🔴 present + 6 🟡)
- Not a draft PR
- Tone check: warm, acknowledges delay
Summary
| Severity | Count |
|---|---|
| 🔴 blocking | 1 |
| 🟡 important | 6 |
| 🟢 nit | 1 |
| 💡 suggestion | 0 |
| 🎉 praise | 2 |
The core architectural decisions are sound — data-attribute-based CSS scoping, theme class pattern, and shared SVG definitions. The main blocker is the hardcoded filter IDs in shared rendering code, which will cause real issues on pages with multiple diagrams. Once the ID scoping is fixed and the other items are addressed, this will be a solid foundation for the neo look. Let's get this across the finish line!
…/mermaid into feature/neo-look-implemented
on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
3 participants
📑 Summary
This PR implements a new "neo" look for Mermaid diagrams, introducing modern visual styling with gradient borders, drop shadows, and new theme options designed for a sleek, contemporary appearance.
Resolves #
📏 Design Decisions
New Look:
neoAdded a new diagram look option
neoalongside the existingclassicandhandDrawnlooks. The neo look features:gradientStartandgradientStoptheme variablesdropShadowtheme variable)strokeWidththeme variabledata-look="neo"attribute for CSS targeting, enabling clean separation of neo-specific stylesNew Themes
Introduced 6 new themes optimized for the neo look:
neoneo-darkreduxredux-darkredux-colorredux-dark-colorSVG Enhancements
📋 Tasks
Make sure you
MERMAID_RELEASE_VERSIONis used for all new features.pnpm changesetand following the prompts. Changesets that add features should beminorand those that fix bugs should bepatch. Please prefix changeset messages withfeat:,fix:, orchore:.