name: draw-io description: draw.io 图表创建、编辑和审阅。用于 .drawio XML 编辑、PNG 转换、布局调整和 AWS 图标使用。

draw.io 图表技能

1. 基本规则

仅编辑 .drawio 文件
不要直接编辑 .drawio.png 文件
在幻灯片中使用预提交钩子自动生成的 .drawio.png

2. 字体设置

对于用于 Quarto 幻灯片的图表，在 mxGraphModel 标签中指定 defaultFontFamily：

<mxGraphModel defaultFontFamily="Noto Sans JP" ...>

同时，在每个文本元素的 style 属性中显式指定 fontFamily：

style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"

3. 转换命令

查看转换脚本：scripts/convert-drawio-to-png.sh.

# 转换所有 .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`	2倍缩放（高分辨率）
`-t`	透明背景
`-o`	输出文件路径

4. 布局调整

4.1. 坐标调整步骤

在文本编辑器中打开 .drawio 文件（纯 XML 格式）
找到要调整元素的 mxCell（通过 value 属性搜索文本）
调整 mxGeometry 标签中的坐标
- x：从左边的位置
- y：从顶部的位置
- width：宽度
- height：高度
运行转换并验证

4.2. 坐标计算

元素中心坐标 = y + (height / 2)
要对齐多个元素，计算并匹配中心坐标

5. 设计原则

5.1. 基本原则

清晰性：创建简单、视觉清晰的图表
一致性：统一颜色、字体、图标大小、线条粗细
准确性：不要为简化而牺牲准确性

5.2. 元素规则

标记所有元素
使用箭头指示方向（优先使用两个单向箭头而不是双向箭头）
使用最新的官方图标
添加图例解释自定义符号

5.3. 可访问性

确保足够的颜色对比度
除了颜色外，使用图案

5.4. 渐进式披露

将复杂系统分为阶段图：

图表类型	目的
上下文图	从外部视角的系统概述
系统图	主要组件和关系
组件图	技术细节和集成点
部署图	基础设施配置
数据流图	数据流和转换
序列图	时间序列交互

5.5. 元数据

在图表中包含标题、描述、最后更新、作者和版本。

6. 最佳实践

6.1. 背景颜色

移除 background="#ffffff"
透明背景适应各种主题

6.2. 字体大小

使用标准字体大小的1.5倍（约18px）以提高 PDF 可读性

6.3. 日文文本宽度

每个字符允许30-40px
宽度不足会导致意外的换行

<!-- 对于10个字符的文本，允许300-400px -->
<mxGeometry x="140" y="60" width="400" height="40" />

6.4. 箭头放置

始终将箭头放在背面（在 XML 中紧接 Title 之后的位置）
放置箭头以避免与标签重叠
保持箭头起点/终点至少距离标签底部边缘20px

<!-- 标题 -->
<mxCell id="title" value="..." .../>

<!-- 箭头（背层） -->
<mxCell id="arrow1" style="edgeStyle=..." .../>

<!-- 其他元素（前层） -->
<mxCell id="box1" .../>

6.5. 箭头连接到文本标签

对于文本元素，exitX/exitY 不起作用，因此使用显式坐标：

<!-- 好：使用 sourcePoint/targetPoint 的显式坐标 -->
<mxCell id="arrow" style="..." edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="1279" y="500" as="sourcePoint"/>
    <mxPoint x="119" y="500" as="targetPoint"/>
    <Array as="points">
      <mxPoint x="1279" y="560"/>
      <mxPoint x="119" y="560"/>
    </Array>
  </mxGeometry>
</mxCell>

6.6. edgeLabel 偏移调整

调整 offset 属性以距离箭头标签：

<!-- 放在箭头上方（负值以距离） -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- 放在箭头下方（正值以距离） -->
<mxPoint x="0" y="40" as="offset"/>

6.7. 移除不必要的元素

移除与上下文无关的装饰性图标
示例：如果存在 ECR，单独的 Docker 图标是不必要的

6.8. 标签和标题

仅服务名称：1行
服务名称 + 补充信息：2行，带换行
冗余表示（例如，ECR Container Registry）：缩短为1行
使用 <br> 标签进行换行

6.9. 背景框架和内部元素放置

当在背景框架（分组框）中放置元素时，确保足够的边距。

必须：内部元素必须距离框架边界至少30px
必须：考虑圆角（rounded=1）和笔画宽度
必须：始终视觉验证 PNG 输出以避免溢出

坐标计算验证：

背景框架：y=20, height=400 -> 范围是 y=20-420
内部元素顶部：框架 y + 30 或更多（例如，y=50）
内部元素底部：框架 y + height - 30 或更少（例如，最多 y=390）

坏示例（可能溢出）：

<!-- 背景框架 -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="400" />
</mxCell>
<!-- 文本：y=30 太接近框架顶部（y=20） -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="30" width="540" height="35" />
</mxCell>

好示例（足够的边距）：

<!-- 背景框架 -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- 文本：y=50 距离框架顶部30px（y=20） -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>

7. 参考

AWS 图标搜索示例：

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

8. 检查清单

[ ] 未设置背景颜色（page=“0”）
[ ] 字体大小适当（推荐较大）
[ ] 箭头放置在背层
[ ] 箭头不重叠标签（在 PNG 中验证）
[ ] 箭头起点/终点足够远离标签（至少20px）
[ ] 箭头不穿透框或图标（在 PNG 中验证）
[ ] 内部元素不溢出背景框架（在 PNG 中验证）
[ ] 背景框架和内部元素之间至少30px边距
[ ] AWS 服务名称是官方名称/正确缩写
[ ] AWS 图标是最新版本（mxgraph.aws4.*）
[ ] 没有不必要的元素剩余
[ ] 视觉验证 PNG 转换

9. 在 reveal.js 幻灯片中显示图像

在 YAML 头中添加 auto-stretch: false：

---
title: "您的演示文稿"
format:
  revealjs:
    auto-stretch: false
---