utility-mermaid-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Diagrams

Mermaid图表

Create effective, syntactically valid mermaid diagrams for product documents.

为产品文档创建高效、语法规范的Mermaid图表。

When to Use

使用场景

Creating mermaid diagrams for PRDs, specs, roadmaps, or stakeholder presentations
Choosing which of 15 diagram types fits a specific communication need
Debugging mermaid code that won't render or renders incorrectly
Reviewing diagrams for clarity, accuracy, and accessibility

为PRD、规格文档、路线图或面向利益相关者的演示创建Mermaid图表
从15种图表类型中选择适合特定沟通需求的类型
调试无法渲染或渲染错误的Mermaid代码
检查图表的清晰度、准确性和可访问性

When NOT to Use

不适用场景

Exporting diagrams to image files (PNG/SVG) . that's a rendering tool concern
Using non-mermaid diagramming tools (Figma, Lucidchart, draw.io)
Creating purely decorative visuals with no informational purpose

将图表导出为图片文件（PNG/SVG）——这属于渲染工具的功能范畴
使用非Mermaid绘图工具（Figma、Lucidchart、draw.io）
创建无信息价值的纯装饰性视觉元素

The Cardinal Rule

核心原则

Don't diagram what a list can say.

Diagrams earn their place when they reveal relationships, branching, or flow that prose flattens. Before creating any diagram, ask:

Does this show branching, relationships, or flow that a list or table would flatten?

Yes → proceed with a diagram
No → use a numbered list, bullet list, or table instead

A 5-step linear process is a list. A 5-step process with two decision points and a retry loop is a diagram.

能用列表说明的内容，就不要用图表。

图表的价值在于揭示文字叙述无法展现的关系、分支或流程。创建任何图表之前，请先问自己：

这张图表是否展示了列表或表格无法清晰呈现的分支、关系或流程？

是 → 继续制作图表
否 → 改用编号列表、项目符号列表或表格

一个5步线性流程适合用列表展示。而包含两个决策点和重试循环的5步流程则适合用图表展示。

Diagram Selection Guide

图表类型选择指南

I need to show...	Use	Also consider
A decision or approval process	Flowchart	State
Multi-service or multi-party interactions	Sequence	Flowchart
Feature lifecycle or status transitions	State	Flowchart
Work stages or pipeline status	Kanban	State
Release or sprint timeline with dependencies	Gantt	Timeline
Version history or chronological milestones	Timeline	Gantt
2D prioritization (effort/impact, risk/value)	Quadrant	.
Allocation breakdown or composition	Pie	Treemap
Problem decomposition or brainstorming	Mindmap	.
Domain models or data relationships	ER	Class
API or object contracts	Class	ER
System topology or infrastructure	Architecture	Flowchart
Flow quantities or budget allocation	Sankey	Pie
Hierarchical proportional data	Treemap	Pie
Trends or time-series metrics	XY-Chart	.

For worked examples organized by PM task, see

references/pm-use-cases.md

. For full syntax and options per type, see

references/diagram-catalog.md

我需要展示...	使用类型	其他可选类型
决策或审批流程	Flowchart（流程图）	State（状态图）
多服务或多方交互	Sequence（时序图）	Flowchart（流程图）
功能生命周期或状态转换	State（状态图）	Flowchart（流程图）
工作阶段或流水线状态	Kanban（看板图）	State（状态图）
带有依赖关系的发布或迭代时间线	Gantt（甘特图）	Timeline（时间线图）
版本历史或时间里程碑	Timeline（时间线图）	Gantt（甘特图）
二维优先级排序（投入/影响、风险/价值）	Quadrant（四象限图）	—
分配细分或组成结构	Pie（饼图）	Treemap（树形图）
问题分解或头脑风暴	Mindmap（思维导图）	—
领域模型或数据关系	ER（实体关系图）	Class（类图）
API或对象契约	Class（类图）	ER（实体关系图）
系统拓扑或基础设施	Architecture（架构图）	Flowchart（流程图）
流量或预算分配	Sankey（桑基图）	Pie（饼图）
层级比例数据	Treemap（树形图）	Pie（饼图）
趋势或时间序列指标	XY-Chart（XY图表）	—

按产品经理任务分类的示例，请查看

references/pm-use-cases.md

。各类型的完整语法和选项，请查看

references/diagram-catalog.md

。

Syntax Validity Principles

语法有效性原则

Six rules that prevent most rendering failures:

Quote labels . Any label containing spaces, parentheses, brackets, colons, commas, or reserved words must be quoted with double quotes
Escape special characters . Characters with mermaid or markdown meaning (
```
>
```
,
```
<
```
,
```
-
```
at line start,
```
#
```
) need escaping or quoting
Declare before referencing . Define a node before using it in an edge; referencing an undeclared node causes silent failures in some types
Respect limits . Each diagram type has a maximum node/participant count beyond which readability collapses (see
```
references/diagram-catalog.md
```
for per-type limits)
Comment your intent . Use
```
%%
```
comments to document non-obvious choices (why this layout direction, why this grouping)
Test before shipping . Paste into a mermaid renderer (mermaid.live, VS Code preview, or your target environment) and verify it renders correctly

For the complete syntax reference, see

references/syntax-guide.md

六条避免大多数渲染失败的规则：

标签加引号——任何包含空格、括号、方括号、冒号、逗号或保留字的标签必须用双引号括起来
转义特殊字符——具有Mermaid或Markdown特殊含义的字符（
```
>
```
、
```
<
```
、行首的
```
-
```
、
```
#
```
）需要转义或加引号
先声明再引用——在边中使用节点之前先定义该节点；引用未声明的节点会导致某些类型的图表出现静默失败
遵守限制——每种图表类型都有最大节点/参与者数量限制，超过该限制后可读性会下降（各类型限制请查看
```
references/diagram-catalog.md
```
）
注释意图——使用
```
%%
```
注释记录非显而易见的选择（如为何选择此布局方向、为何如此分组）
交付前测试——将代码粘贴到Mermaid渲染器（mermaid.live、VS Code预览或目标环境）中，验证其能否正确渲染

完整语法参考，请查看

references/syntax-guide.md

。

Instructions

操作步骤

Identify what you're communicating . What relationship, flow, hierarchy, or proportion needs to be visible? Who is the audience?
Apply the cardinal rule . Confirm a diagram adds value over a list or table
Select a diagram type . Use the selection guide above, browse
```
references/pm-use-cases.md
```
by task, or browse
```
references/diagram-catalog.md
```
by type
Plan the diagram . Fill out the planning worksheet in
```
references/TEMPLATE.md
```
: purpose, audience, node inventory, type rationale
Write the mermaid code . Follow
```
references/syntax-guide.md
```
rules; start with the minimal syntax example from
```
references/diagram-catalog.md
```
and expand
Validate . Run through the quality checklist below
Embed . Place the validated mermaid code block in your document

明确沟通内容——需要展示什么关系、流程、层级或比例？受众是谁？
遵循核心原则——确认图表比列表或表格更有价值
选择图表类型——使用上面的选择指南，按任务浏览
```
references/pm-use-cases.md
```
，或按类型浏览
```
references/diagram-catalog.md
```
规划图表——填写
```
references/TEMPLATE.md
```
中的规划工作表：目的、受众、节点清单、类型选择理由
编写Mermaid代码——遵循
```
references/syntax-guide.md
```
中的规则；从
```
references/diagram-catalog.md
```
中的最简语法示例开始扩展
验证——完成下面的质量检查清单
嵌入——将验证后的Mermaid代码块放入目标文档

Output Contract

输出规范

Planning artifact: A completed diagram planning worksheet (
```
references/TEMPLATE.md
```
)
Final output: A syntactically valid mermaid code block embedded in the target document
Quality gate: All items in the quality checklist pass

规划产物：填写完整的图表规划工作表（
```
references/TEMPLATE.md
```
）
最终输出：嵌入目标文档中的语法规范的Mermaid代码块
质量门槛：质量检查清单中的所有项均通过

Quality Checklist

质量检查清单

Diagram renders without error in target environment
Cardinal rule satisfied . a list or table would not communicate this more clearly
No linear sequences without branching, relationships, or hierarchy
All labels with spaces or special characters are properly quoted
Special characters escaped where needed
Node/participant count within type-specific limits
Colors are accessible (WCAG AA 3:1 contrast minimum, black text on light backgrounds)
Color is never the sole differentiator . shapes and labels also distinguish elements
Diagram has a descriptive title or surrounding prose context
```
%%
```
comments document any non-obvious layout or grouping choices

图表在目标环境中能无错误渲染
符合核心原则——列表或表格无法更清晰地传达此内容
没有无分支、无关系、无层级的线性序列
所有包含空格或特殊字符的标签都已正确加引号
特殊字符已按需转义
节点/参与者数量在各类型的限制范围内
颜色符合可访问性要求（WCAG AA 3:1最小对比度，浅色背景配黑色文字）
颜色并非唯一区分方式——形状和标签也可区分元素
图表有描述性标题或配套文字说明
```
%%
```
注释记录了所有非显而易见的布局或分组选择

References

参考资料

File	Purpose
`references/TEMPLATE.md`	Diagram planning worksheet . fill out before writing mermaid code
`references/EXAMPLE.md`	Worked example: PM creating 4 diagrams for a product launch
`references/diagram-catalog.md`	All 15 diagram types: syntax, PM examples, limits, pitfalls
`references/pm-use-cases.md`	PM task → diagram type mapping with mini worked examples
`references/syntax-guide.md`	Complete syntax validity rules, escaping, styling, and validation checklist

文件	用途
`references/TEMPLATE.md`	图表规划工作表——编写Mermaid代码前填写
`references/EXAMPLE.md`	示例：产品经理为产品发布创建4种图表
`references/diagram-catalog.md`	全部15种图表类型：语法、产品经理示例、限制、注意事项
`references/pm-use-cases.md`	产品经理任务→图表类型映射，含小型示例
`references/syntax-guide.md`	完整的语法有效性规则、转义、样式和验证清单