mermaid-diagramming

Mermaid 图表绘制

为技术文档创建清晰、专业的 Mermaid 图表。涵盖所有主要图表类型，并提供基础版和样式版、渲染指南及导出建议。

适用场景

• 为流程文档或决策树创建流程图
• 绘制 API 交互或系统通信的时序图
• 为数据库架构文档构建 ERD
• 设计工作流状态的状态机图
• 制作项目时间线的甘特图
• 使用 C4 图或网络图记录系统架构
• 为 README 文件、ADR 或设计文档添加可视化辅助内容

快速参考

资源	用途	何时加载
references/diagram-types.md	每种 Mermaid 图表类型的语法、模式和代码示例	选择或构建图表时

---

工作流概览

Phase 1: Scope     → Identify what to visualize, audience, and diagram type
Phase 2: Draft     → Write base Mermaid code with correct syntax
Phase 3: Style     → Add theming, colors, and accessibility annotations
Phase 4: Deliver   → Provide rendering instructions and suggest iterations

---

阶段 1：确定范围

编写任何代码之前，请先明确：

1. 要讲述什么内容？ 图表应讲述一个故事或回答一个问题。
2. 受众是谁？ 开发者需要细节；利益相关者需要概览。
3. 有哪些实体和关系？ 绘图前先列出节点和边。
4. 哪种图表类型合适？ 使用下方的选择指南。

图表类型选择

如果需要展示……	使用
流程、决策、分支	flowchart
系统或参与者随时间发生的交互	sequenceDiagram
数据模型及其关系	erDiagram
对象结构和继承关系	classDiagram
状态和转换	stateDiagram-v2
项目计划和依赖关系	gantt
比例或分布	pie
层级式思维导图	mindmap
随时间发生的事件	timeline
系统架构层级	C4 上下文图/容器图
代码版本历史	gitGraph
用户体验流程	journey

---

阶段 2：起草

结构规则

1. 每张图表表达一个概念——将复杂系统拆分为多个视图
2. 限制节点数量——每张图表控制在 15 个节点以内；更多时请拆分
3. 使用有意义的标签——使用描述性文本，而非单个字母
4. 保持方向一致——优先采用自上而下（TB）或从左到右（LR）
5. 对相关节点分组——使用 subgraph 将相关元素归为一组

代码约定

%% Always start with a comment describing the diagram's purpose
%% Use consistent quoting for labels with special characters
flowchart LR
    A["User Request"] --> B{"Auth Check"}
    B -->|Valid| C["Process Request"]
    B -->|Invalid| D["Return 401"]

• 标签包含特殊字符时使用双引号
• 添加注释（%%）解释不明显的关系
• 实线优先使用 -->，虚线使用 -.->，粗线使用 ==>
• 使用描述性的边标签：-->|"reason"| TargetNode

---

阶段 3：设置样式

主题

使用 %%{init: ...}%% 指令应用一致的样式：

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9'}}}%%
flowchart TB
    A["Start"] --> B["End"]

节点样式

flowchart LR
    A["Normal"]
    B["Highlighted"]:::highlight
    classDef highlight fill:#f9f,stroke:#333,stroke-width:2px

无障碍

• 使用高对比度的配色
• 不要仅依赖颜色传达含义——应添加标签和形状
• 嵌入图表时添加替代文本：![Diagram description](path)
• 为复杂图表附上文字摘要

---

阶段 4：交付

始终提供

1. 基础版——简洁、无样式，可在任何地方渲染
2. 样式版——带有颜色和强调效果的主题变体
3. 渲染说明——说明可在哪里预览（GitHub、Mermaid Live、VS Code 扩展）
4. 建议——可搭配的图表或后续迭代方向

渲染选项

平台	支持情况
GitHub Markdown	在 .md 文件中原生渲染
GitLab Markdown	原生渲染
Mermaid Live Editor	使用 https://mermaid.live 进行交互式编辑
VS Code	使用 Mermaid 扩展进行预览
Docusaurus / MkDocs	基于插件进行渲染

导出格式

• SVG：最适合网页和文档（可缩放、文本可搜索）
• PNG：不支持 Mermaid 的平台可使用的备用格式
• PDF：适用于印刷或正式文档

---

最佳实践

• 从简单开始 — 先确定正确的结构，再添加样式
• 测试渲染效果 — 提交前在目标平台上验证
• 对图表进行版本管理 — 底层系统变更时更新图表
• 与文档放在一起 — 将图表保存在相关文档所在的同一目录中
• 使用子图 — 将相关节点分组，以降低视觉复杂度

反模式

• 在一张图表中放入过多节点（节点达到 15 个或更多时应拆分）
• 使用没有标签的单字母节点 ID
• 仅依靠颜色传达含义
• 硬编码像素宽度，导致图表在不同渲染器上显示异常
• 系统变更后未及时更新图表