Mermaid diagrams have quietly become the default way developers sketch a system before anyone writes the actual documentation. Type a few lines of text, get a flowchart, a sequence diagram, or an entity relationship map. GitHub renders them. Notion renders them. Documentation sites render them. The problem has never been the syntax. It’s the output.
Anyone who has tried to make a Mermaid diagram match a product’s visual language knows the pain. You wrestle with theme variables, inline styles, and the occasional CSS override that breaks the moment the diagram gets embedded somewhere else. The rendered result is an SVG, technically, but it often feels like a black box that resists customization.
Pele, a new open-source project making the rounds among developer tooling enthusiasts, takes a different angle. Instead of treating Mermaid’s rendered SVG as a finished artifact, it treats it as a starting point. Pele wraps Mermaid’s output and exposes it as a themeable SVG surface, letting you restyle diagrams through a consistent theming layer rather than scattering ad-hoc hacks across your stylesheets.
That might sound modest, but it addresses a real friction point. Teams that maintain design systems have long complained that diagramming tools sit outside the design system entirely. A flowchart embedded in internal documentation can look like it came from a different decade than the page around it. Pele’s approach means the same tokens that govern button colors and typography can, in principle, flow into diagrams too.
The mechanics are worth understanding. Mermaid generates SVG with its own internal class names and structure, which shift between versions and diagram types. That makes stable theming awkward. By wrapping the output and applying a themeable layer on top, Pele gives developers a more predictable interface: define your colors, fonts, and spacing once, and the diagrams inherit them. Because the output stays as SVG, it remains scalable, searchable, and accessible in the ways raster images aren’t.
There’s a broader trend here. The last couple of years have seen a quiet renaissance in developer-facing diagramming. Text-to-diagram tools won because they fit version control workflows: a diagram that lives as plain text in a repository can be reviewed, diffed, and updated like code. But the moment diagrams became code, the question of styling became unavoidable. If your diagram is checked into the same repo as your frontend, it should probably look like it belongs.
Pele also fits a growing appetite for themeable, embeddable visuals across documentation platforms. Static site generators, wikis, and internal portals all want diagrams that respect light and dark modes. Mermaid’s built-in theming has improved, but many teams still find themselves writing custom CSS to bridge the gap. A wrapper that systematizes that process is a reasonable bet.
Balance matters, though. Wrapper projects carry inherent maintenance risk. Mermaid’s rendering internals evolve, and any layer that depends on them has to keep pace. Whether Pele can stay current as Mermaid changes is an open question, and teams evaluating it should look at how actively it tracks upstream releases. There’s also the question of ceiling: heavy customization can push SVG output toward fragility, especially when diagrams are exported, printed, or embedded in tools that sanitize markup aggressively.
None of that undercuts the core idea. The most interesting developer tools of the past few years have been small, focused utilities that remove a specific irritation rather than reinvent a category. Pele doesn’t try to replace Mermaid. It accepts Mermaid as the standard and solves the styling layer on top. That’s a pragmatic posture, and pragmatism tends to age well in tooling.
For teams already standardizing on Mermaid, the appeal is obvious: one theming approach across every diagram, fewer one-off CSS patches, and output that fits the surrounding interface. For everyone else, Pele is a useful signal about where diagramming is heading. Diagrams are no longer throwaway sketches. They’re part of the product surface, and they’re starting to be treated that way, with the same attention to design, consistency, and maintainability that the rest of the interface gets.
Whether Pele becomes the default answer or simply nudges Mermaid and its ecosystem toward better native theming, the direction is right. The diagram you embed in your docs should not look like an afterthought. Pele is one more step toward making sure it doesn’t.