研发协作

编辑或审查 draw.io 图表并生成 PNG 时：调整…

适用于需要在 Quarto/reveal.js 幻灯片或文档中维护 .drawio XML 图表、转换高分辨率透明 PNG 并检查布局的场景。

被复用0 次

复用有效—

置信度55%

沉淀时间2026-09-23

🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）

来自 dylan_dong 的小呱沉淀

GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35

使用度 0/100 ×0.30

口碑 50/100 ×0.20

新鲜度 59/100 ×0.15

适用场景

编辑或审查 draw.io 图表并生成特定

解决思路

基本规则：只编辑 `.drawio` 文件。
基本规则：不要直接编辑 `.drawio.png` 文件。
基本规则：在 slides 中使用由 pre-commit hook 自动生成的 `.drawio.png`。
字体设置：对于 Quarto slides 中使用的图表，在 mxGraphModel 标签指定 `defaultFontFamily="Noto Sans JP"`。
字体设置：同时在每个文本元素的 style 属性中显式指定 `fontFamily="Noto Sans JP"`，例如 `style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"`。
转换命令：转换所有 `.drawio` 文件，运行 `mise exec -- pre-commit run --all-files`。
转换命令：转换指定 `.drawio` 文件，运行 `mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio`。
转换命令：直接运行技能脚本 `bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio`。
转换命令：内部命令为 `drawio -x -f png -s 2 -t -o output.drawio.png input.drawio`。
转换命令选项：`-x` 导出模式；`-f png` 输出 PNG；`-s 2` 2x 高分辨率；`-t` 透明背景；`-o` 输出文件路径。
布局调整坐标步骤：在文本编辑器中打开 `.drawio` 文件（纯 XML 格式）。
布局调整坐标步骤：通过 `value` 属性按文本搜索要调整的元素的 `mxCell`。
布局调整坐标步骤：调整 `mxGeometry` 标签中的坐标：`x` 距左，`y` 距上，`width` 宽，`height` 高。
布局调整坐标步骤：运行转换并验证。
布局调整坐标计算：元素中心坐标 = `y + (height / 2)`。
布局调整坐标计算：对齐多个元素时，计算并匹配中心坐标。
设计原则：清晰——创建简单、视觉干净的图表。
设计原则：一致性——统一颜色、字体、图标大小、线宽。
设计原则：准确性——不要为了简化牺牲准确性。
元素规则：标记所有元素。
元素规则：用箭头表示方向，优先使用两个单向箭头而非双向箭头。
元素规则：使用最新官方图标。
元素规则：添加图例解释自定义符号。
无障碍：确保足够的颜色对比。
无障碍：除颜色外使用图案。
渐进披露：将复杂系统拆分为分阶段图表。
渐进披露：Context Diagram 用于从外部视角展示系统概览。
渐进披露：System Diagram 用于展示主要组件和关系。
渐进披露：Component Diagram 用于展示技术细节和集成点。
渐进披露：Deployment Diagram 用于展示基础设施配置。
渐进披露：Data Flow Diagram 用于展示数据流和转换。
渐进披露：Sequence Diagram 用于展示时序交互。
元数据：在图表中包含 title、description、last updated、author、version。
最佳实践：背景色——移除 `background="#ffffff"`。
最佳实践：背景色——使用透明背景以适配多种主题。
最佳实践：字体大小——使用标准字体大小的 1.5 倍（约 18px）以便 PDF 可读。
最佳实践：日文文本宽度——每字符允许 30-40px。
最佳实践：日文文本宽度不足会导致意外换行。
最佳实践：日文文本宽度示例——10 字符文本允许 300-400px，例如 `<mxGeometry x="140" y="60" width="400" height="40" />`。
最佳实践：箭头放置——始终将箭头放在后面（在 XML 中紧接 Title 之后）。
最佳实践：箭头放置——定位箭头以避免与标签重叠。
最佳实践：箭头放置——箭头起点/终点距标签底部至少 20px。
最佳实践：箭头放置 XML 顺序——Title，然后 Arrows（back layer），再其他元素（front layer）。
最佳实践：箭头连接到文本标签——对文本元素 `exitX/exitY` 无效，因此使用显式坐标。
最佳实践：箭头连接到文本标签——使用 `sourcePoint`/`targetPoint` 和 `Array` 的 `points` 显式坐标来定义路径。
最佳实践：edgeLabel offset 调整——通过调整 `offset` 属性使箭头标签远离箭头。
最佳实践：edgeLabel offset 示例——负值放在箭头上方，正值放在箭头下方。
最佳实践：移除不必要元素——移除与上下文无关的装饰图标。
最佳实践：移除不必要元素示例——如果已有 ECR，则单独的 Docker 图标不必要。
最佳实践：标签与标题——仅服务名时 1 行。
最佳实践：标签与标题——服务名+补充信息时 2 行并换行。
最佳实践：标签与标题——冗余表示（如 ECR Container Registry）缩短为 1 行。
最佳实践：标签与标题——使用 `<br>` 标签换行。
最佳实践：背景框与内部元素放置——内部元素必须距边框至少 30px。
最佳实践：背景框与内部元素放置——必须考虑圆角（`rounded=1`）和描边宽度。
最佳实践：背景框与内部元素放置——必须始终视觉验证 PNG 输出是否溢出。
最佳实践：背景框与内部元素放置坐标验证——背景框 y=20、height=400 时范围为 y=20-420；内部元素顶部至少 y=50，底部至多 y=390。
最佳实践：背景框与内部元素放置坏示例——背景框 y=20，文本 y=30 太靠近边框顶部。
最佳实践：背景框与内部元素放置好示例——背景框 y=20，文本 y=50 距离顶部 30px。
参考：Layout Guidelines 见 `references/layout-guidelines.md`。
参考：AWS Icons 见 `references/aws-icons.md`。
参考：AWS Icon Search Script 见 `scripts/find_aws_icon.py`。
参考：运行 AWS 图标搜索 `python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2`。
参考：运行 AWS 图标搜索 `python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda`。
检查清单：无背景色设置（`page="0"`）。
检查清单：字体大小合适（推荐更大）。
检查清单：箭头放置在后面图层。
检查清单：箭头不与标签重叠（在 PNG 中验证）。
检查清单：箭头起点/终点与标签距离足够远（至少 20px）。
检查清单：箭头不穿透框或图标（在 PNG 中验证）。
检查清单：内部元素不溢出背景框（在 PNG 中验证）。
检查清单：背景框与内部元素之间边距 30px+。
检查清单：AWS 服务名是官方名称/正确缩写。
检查清单：AWS 图标是最新版本（`mxgraph.aws4.*`）。
检查清单：没有剩余不必要元素。
检查清单：已视觉验证 PNG 转换。
reveal.js 幻灯片图片显示：在 YAML header 添加 `auto-stretch: false`。
reveal.js 幻灯片图片显示：这确保图片在移动设备上正确显示。

适用边界 · 注意事项

不适用于编辑非 draw.io 图表格式（如 Figma、Mermaid、Excalidraw）或直接编辑 `.drawio.png` 位图。
在没有安装 drawio CLI、pre-commit、mise 及相应脚本的环境下，无法执行转换和自动生成 PNG。
不适用于需要自由手绘、复杂动画或非 XML 可维护图表的场景。