mcpField
U
utility-mermaid-diagrams

utility-mermaid-diagrams

github.com/product-on-purpose文档处理769742 次安装4 天前更新
代码仓库

关于 utility-mermaid-diagrams

用于在产品文档中创建和验证 Mermaid 图表的技能，适合产品经理和文档作者。它帮助从 15 种图表类型中选择、编写有效语法，并判断图表是否比列表或表格更清晰。

主要功能

  1. 01涵盖 15 种图表类型
  2. 02按沟通目标选择图表
  3. 03Mermaid 语法与转义规则
  4. 04规划模板与参考资料
  5. 05渲染及无障碍检查

适用场景

  1. 01在 PRD 和规格文档中添加图表
  2. 02为产品工作流选择图表
  3. 03排查无法渲染的 Mermaid 图表
  4. 04检查图表的清晰度与无障碍性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/product-on-purpose/pm-skills --skill utility-mermaid-diagrams

安装后在 Claude Code 中输入/utility-mermaid-diagrams确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

HISTORY.md
evals/
trigger-fixtures.json
references/
diagram-catalog.md
EXAMPLE.md
pm-use-cases.md
syntax-guide.md
TEMPLATE.md

详细介绍

Mermaid 图表

为产品文档创建有效且语法正确的 mermaid 图表。

适用场景

  • 为 PRD、规格说明、路线图或利益相关方演示创建 mermaid 图表
  • 从 15 种图表类型中选择适合特定沟通需求的类型
  • 调试无法渲染或渲染结果不正确的 mermaid 代码
  • 审查图表的清晰度、准确性和可访问性

不适用场景

  • 将图表导出为图片文件（PNG/SVG）——这属于渲染工具的范畴
  • 使用非 mermaid 图表工具（Figma、Lucidchart、draw.io）
  • 创建没有信息传达目的的纯装饰性视觉内容
  • 制作完整的客户旅程产物（包含阶段、触点、情绪曲线、痛点），而不是独立图表——请使用 discover-journey-map，它会在时间线或流程图部分组合使用此技能

首要原则

列表能说明白的内容，就不要画成图表。

图表的价值在于揭示关系、分支或流程，这些内容用文字表述时往往会被简化。在创建任何图表之前，请先问：

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

  • 能 → 继续使用图表
  • 不能 → 改用编号列表、项目符号列表或表格

一个包含 5 个步骤的线性流程应该用列表表示。一个包含 5 个步骤、两个决策点和一个重试循环的流程则应该用图表表示。

图表选择指南

我需要展示……使用也可以考虑
决策或审批流程FlowchartState
多服务或多方交互SequenceFlowchart
功能生命周期或状态转换StateFlowchart
工作阶段或管道状态KanbanState
存在依赖关系的发布或冲刺时间线GanttTimeline
版本历史或按时间排列的里程碑TimelineGantt
二维优先级排序（工作量/影响、风险/价值）Quadrant-
分配明细或组成结构PieTreemap
问题分解或头脑风暴Mindmap-
领域模型或数据关系ERClass
API 或对象契约ClassER
系统拓扑或基础设施ArchitectureFlowchart
流量或预算分配SankeyPie
分层比例数据TreemapPie
趋势或时间序列指标XY-Chart-

按 PM 任务整理的完整示例，请参阅 references/pm-use-cases.md。 各类型的完整语法和选项，请参阅 references/diagram-catalog.md。

语法有效性原则

以下 6 条规则可以避免大多数渲染失败：

  1. 为标签加引号 - 任何包含空格、括号、方括号、冒号、逗号或保留字的标签，都必须用双引号括起来
  2. 转义特殊字符 - 具有 mermaid 或 Markdown 含义的字符（行首的 >、<、-、#）需要转义或加引号
  3. 先声明，再引用 - 在边中使用节点之前，先定义该节点；在某些类型中，引用未声明的节点会导致静默失败
  4. 遵守限制 - 每种图表类型都有最大节点数或参与者数量限制，超过后可读性会急剧下降（各类型的限制请参阅 references/diagram-catalog.md）
  5. 注释说明意图 - 使用 %% 注释记录不明显的选择（例如为什么选择这种布局方向、为什么采用这种分组）
  6. 交付前测试 - 将代码粘贴到 mermaid 渲染器（mermaid.live、VS Code 预览或目标环境）中，并确认渲染结果正确

完整语法参考请参阅 references/syntax-guide.md。

说明

  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 代码块放入文档中

输出约定

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

质量检查清单

  • 图表在目标环境中渲染正常
  • 符合首要原则：列表或表格无法更清晰地传达信息
  • 不包含没有分支、关系或层级的线性序列
  • 所有包含空格或特殊字符的标签均已正确加引号
  • 需要转义的特殊字符均已转义
  • 节点／参与者数量符合图表类型的限制
  • 颜色符合无障碍要求（WCAG AA 对比度至少为 3:1，浅色背景上使用黑色文字）
  • 颜色绝不作为唯一的区分方式；还要用形状和标签区分元素
  • 图表具有描述性标题，或周围的正文提供了上下文
  • 使用 %% 注释说明所有不明显的布局或分组选择

参考资料

文件用途
references/TEMPLATE.md图表规划工作表——编写 mermaid 代码前填写
references/EXAMPLE.md完整示例：PM 为产品发布创建 4 个图表
references/diagram-catalog.md全部 15 种图表类型：语法、PM 示例、限制和易错点
references/pm-use-cases.mdPM 任务 → 图表类型映射，并附简短完整示例
references/syntax-guide.md完整的语法有效性规则、转义、样式设置和验证清单

评论

支持 Markdown