Pele：让Mermaid图表变成可主题化SVG的开源工具

Mermaid 已经成为开发者画流程图、时序图、架构图的事实标准之一，但它自带的渲染样式往往和产品界面或文档主题格格不入。最近在 Hacker News 上出现的开源项目 Pele，正是瞄准了这个痛点——把 Mermaid 图表输出为可主题化的 SVG 文件。

Pele 是什么

Pele 是一个把 Mermaid 图表转换为可主题化 SVG 的工具。传统 Mermaid 渲染通常直接生成带内联样式的 SVG，颜色、字体、背景等都被写死在图形里，想要适配暗色模式或者品牌配色，往往只能改 Mermaid 的主题变量，或者事后用脚本替换颜色。Pele 的思路是把样式从图形结构中抽离出来，让 SVG 具备可主题化的能力，从而在不同界面、不同文档风格下复用同一张图。

据 Hacker News 上的讨论，该项目获得了 27 个点，评论不多但关注度集中在对「主题化」这一核心价值的认可上。

为什么主题化 SVG 值得关注

内联样式的局限

Mermaid 的默认输出把颜色、描边、字体等样式内联在 SVG 元素上。这种做法的好处是图形自包含、打开即用，但代价是难以和外部样式系统联动。当文档站需要跟随用户切换明暗主题，或者企业需要图表符合品牌规范时，内联样式就成了障碍。

SVG 内联样式与外部样式表：SVG 规范允许样式通过三种方式定义——内联 style 属性、<style> 元素内嵌 CSS、以及通过 <link> 或 @import 引入外部 CSS。Mermaid 默认采用前两种，导致样式与图形耦合。而主题化的核心是让 SVG 元素使用 class 或 CSS 自定义属性（CSS Variables），由外部样式表或主题系统动态覆盖。需要注意的是，SVG 作为独立图片被 <img> 标签引用时，外部 CSS 不会生效；只有内联到 HTML 文档中或通过 <object>/<iframe> 嵌入时，外部样式才能作用。因此，Pele 这类工具通常要求使用方将 SVG 内联到页面中，或通过构建步骤将主题变量注入。

主题化带来的复用价值

可主题化的 SVG 意味着同一张图可以在不同上下文中呈现不同外观，而无需重新生成。这对文档系统、设计系统和多产品线的团队尤其有价值——图表的语义结构不变，视觉表现交给主题控制。

设计 Token：设计 Token 是设计系统中用于存储视觉样式（颜色、字体、间距等）的命名变量，通常以 JSON 或 CSS 自定义属性形式存在。将 Pele 输出的 SVG 中的样式属性映射到设计 Token，可以实现图表与产品界面使用同一套视觉语言。例如，把节点填充色绑定到 --color-primary，文字颜色绑定到 --color-text，这样切换主题时只需更新 Token 值，所有图表自动适配。这种机制也是现代前端主题切换（如暗色模式）的常见实现方式。

与现有方案的对比

Mermaid 本身提供了主题配置和 CSS 类名机制，可以在渲染时指定主题变量。但这类配置是渲染期的，产物仍然偏向自包含。Pele 选择在 SVG 层面做主题化，相当于把控制权后移到使用方：图形结构一次性生成，样式可以按需覆盖。这种分层思路和现代前端「结构与样式分离」的理念一致，也更容易接入已有的设计 token 体系。

Mermaid 主题配置：Mermaid 通过 theme 和 themeVariables 配置项支持主题定制，内置 default、dark、forest、neutral 等主题，也允许覆盖颜色、字体等变量。但这类配置在渲染时生效，生成的 SVG 仍包含大量内联样式。此外，Mermaid 支持通过 classDef 为节点添加自定义 CSS 类，但类名仅用于渲染期，产物中的样式仍以内联为主。Pele 的差异在于对生成的 SVG 进行后处理，移除内联样式并替换为 CSS 类或变量，使样式控制权转移到使用方。

适用场景与注意事项

Pele 适合文档站点、知识库、设计系统文档以及需要品牌一致性的图表场景。需要注意的是，主题化 SVG 的最终效果依赖于使用方对 SVG 样式的控制能力；如果目标环境对 SVG 外部样式有限制（例如某些邮件客户端或图片嵌入场景），主题化能力可能无法发挥。另外，项目在 Hacker News 上的讨论规模较小，社区生态和长期维护情况还有待观察。

小结

Pele 切入的是一个真实存在但常被忽视的环节：图表的视觉一致性。把 Mermaid 图表输出为可主题化 SVG，让结构归结构、样式归样式，这个方向对文档与设计系统团队有实际意义。是否值得引入，取决于你的团队是否真的需要图表跟随主题变化——如果需要，这类工具能省掉不少手工调色的麻烦。