需要画 Mermaid 图时如何选对图类型并保证语法可渲染

为产品文档、PRD、路线图或汇报创建语法正确、可渲染的 Mermaid 图，并选出最合适的图类型。

适用场景

解决思路

1. 先判断是否真的需要图：问自己「这是否展示了列表或表格会压平的 分支、关系或流程？」是则画图，否则改用有序列表、无序列表或表格。
2. 按沟通需求选图类型：决策/审批流程用 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。
3. 遵守六条语法有效性规则：1) 给标签加引号——任何含空格、括号、方括号、冒号、逗号或保留字的标签都必须用双引号包裹；2) 转义特殊字符——对 mermaid 或 markdown 中有含义的字符（>、<、行首的 -、#）进行转义或加引号；3) 先声明后引用——在边中使用节点前先定义它，某些图类型中引用未声明节点会静默失败；4) 遵守上限——每种图类型都有最大节点/参与者数量，超过后可读性会崩溃（见 references/diagram-catalog.md 中每种类型的上限）；5) 用 %% 注释说明意图——记录不明显的选择（为何用这个布局方向、为何这样分组）；6) 发布前测试——粘贴到 mermaid 渲染器（mermaid.live、VS Code 预览或目标环境）验证能正确渲染。
4. 按步骤执行：1) 明确要传达什么——需要让哪种关系、流程、层级或比例可见？受众是谁？2) 应用核心规则——确认图比列表或表格更有价值；3) 选择图类型——用上面的选择指南，按任务查 references/pm-use-cases.md，或按类型查 references/diagram-catalog.md；4) 规划图——填写 references/TEMPLATE.md 中的规划工作表：目的、受众、节点清单、类型理由；5) 编写 mermaid 代码——遵循 references/syntax-guide.md 的规则，从 references/diagram-catalog.md 的最小语法示例开始再扩展；6) 验证——过一遍下面的质量检查清单；7) 嵌入——把验证过的 mermaid 代码块放进文档。
5. 交付物要求：规划产物是填好的图规划工作表（references/TEMPLATE.md）；最终输出是嵌入目标文档的语法有效 mermaid 代码块；质量门是质量检查清单全部通过。
6. 过质量检查清单：图在目标环境无错误渲染；满足核心规则——列表或表格不会表达得更清楚；没有无分支、关系或层级的线性序列；所有含空格或特殊字符的标签都正确加引号；需要处已转义特殊字符；节点/参与者数量在类型上限内；颜色可访问（WCAG AA 最低 3:1 对比度，浅色背景上用黑字）；颜色绝不是唯一区分手段——形状和标签也能区分元素；图有描述性标题或周围文字语境；%% 注释记录了任何不明显的布局或分组选择。

适用边界 · 注意事项

• 把图导出为图片文件（PNG/SVG）——那是渲染工具的职责
• 使用非 mermaid 的绘图工具（Figma、Lucidchart、draw.io）
• 创建纯装饰性、没有信息目的的视觉内容
• 制作完整的客户旅程产物（阶段、触点、情绪曲线、痛点）而非独立图——应使用 discover-journey-map，它会组合本技能用于其时间线或流程图部分