draw-io

draw.io 图表技能

1. 基本规则

• 仅编辑 .drawio 文件
• 不要直接编辑 .drawio.png 文件
• 在幻灯片中使用 pre-commit hook 自动生成的 .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。

# Convert all .drawio files
mise exec -- pre-commit run --all-files

# Convert specific .drawio file
mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio

# Run script directly (using skill's script)
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

注意：有关 draw.io CLI 标志和导出选项，请参阅 drawio-skills 技能。

4. 布局调整

• 在文本编辑器中打开 .drawio；通过 value 属性查找 mxCell
• 调整 mxGeometry：x（左）、y（上）、width、height
• 元素中心点 = y + (height / 2)；对齐中心点以对齐元素

5. 配色方案和布局模式

可自动更新的参考文件（更新流程请参阅第 10 节）：

• 配色方案 - Material Design 颜色和使用规则
• 布局指南 - 模式目录（A-K）和 AWS 布局规则

6. 设计原则

6.1. 幻灯片图表约束（1920x1080）

• 必须：设置 page="0"（透明背景）
• 必须：所有文本均使用 fontFamily=Noto Sans JP
• 必须：每个图表最多使用 1-3 种强调色
• 必须：在底部添加总结栏（注释色或主色）

6.2. 核心原则

• 清晰、一致、准确
• 为所有元素添加标签；使用箭头表示方向（优先使用单向箭头）
• 每个图表只表达一个概念；将复杂系统拆分为分阶段图表
• 确保颜色对比度；除颜色外还要使用图案

6.3. 相关图表集的一致性

• 必须：相关图表使用相同的画布宽度、颜色、字体和描边宽度
• 创建任何图表之前，先定义图表集规范
• 完成后并排检查

7. 最佳实践

7.1. 通用

• 移除 background="#ffffff"（透明背景可适应主题）
• 字体大小：标准字号的 1.5 倍（约 18px），以确保可读性
• 日文文本：每个字符预留 30-40px 宽度
• 画布尺寸：Zenn 文章不超过 800px，幻灯片使用 1920x1080
• 增大字体时，按比例缩放画布

7.2. 箭头

• 结构性箭头（流程图、ER）：在 XML 中紧跟 Title 放置（底层）
• 与徽章关联的箭头（导航）：在 XML 中最后放置（顶层）
• 箭头起点/终点与标签底边至少相距 20px
• 对于文本元素，使用显式的 sourcePoint/targetPoint（exitX/exitY 无效）
• 边标签偏移：<mxPoint x="0" y="-40" as="offset"/>（负值 = 上方）
• 双向箭头：设置 startArrow=classic;endArrow=classic;startFill=1;endFill=1
• 至少留出 80-100px 间距，避免箭头尖端重叠（>< 形状）
• 在同一图表中统一箭头长度
• 边标签：将 <mxCell> 放在 <root> 的末尾，并设置 labelBackgroundColor=#ffffff

7.3. 容器和间距

• 内部元素：距边框至少 30px
• 父容器标签留白：第一个子元素的 Y >= parent.y + spacingTop + fontSize + 10 （对于 fontSize >= 24px，使用 fontSize * 1.5）
• 标签内边距：在方框样式中添加 spacingLeft=8;spacingTop=8
• 保持容器内的垂直对称（上边距 = 下边距）
• 将元素对齐到容器的水平中心线

7.4. 标签

• 仅服务名称：1 行；带补充信息：使用 <br> 分为 2 行
• 删除冗余表述（例如，“ECR Container Registry” -> “ECR”）
• 删除与上下文无关的装饰性图标

7.5. Z 顺序（XML 文档顺序 = 渲染顺序）

元素类型	在 XML 中的位置	原因
结构箭头	标题之后、方框之前	后层
背景/方框	中间	基础层
徽标	方框之后	前层
徽标箭头	徽标之后	顶层
边缘标签	<root> 末尾	始终可见

8. 参考资料

• 配色方案 - 可自动更新
• 布局指南 - 可自动更新
• AWS 图标
• AWS 图标搜索脚本

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

9. 工作流与检查清单

9.1. 阶段 0：设计

• 每张图只表达一个概念
• 已查看并理解参考图像
• 已定义图表集规范（画布尺寸、颜色、字体、描边宽度）

9.2. 阶段 1：布局计算

• 已计算父容器尺寸
• 已计算子元素的间距（参见 7.3）
• 已计算对称放置坐标
• 已确定箭头的 Z 顺序（参见 7.5）

9.3. 阶段 2：实现

• 已设置 page="0"（透明背景）
• 字体大小合适；画布按比例缩放
• 画布符合目标显示宽度
• 箭头的 Z 顺序正确
• 已设置标签内边距（spacingLeft/spacingTop）
• 使用最新版 AWS 图标（mxgraph.aws4.*）

9.4. 阶段 3：验证（PNG 审查）

使用 Read 工具转换并进行目视验证：

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

• 绝不要仅凭 XML 就声称“没有问题”；务必目视检查 PNG
• 如果无法查看参考图像，请如实说明

验证：

• 元素没有溢出边框（留出 30px 以上的边距）
• 箭头没有与标签重叠，也没有穿过方框
• 双向箭头显示为 <-->，而不是 ><
• 文本没有被截断或裁切
• 箭头长度一致
• 徽标/箭头的放置对称
• 父标签与子元素没有交叉
• 边缘标签可见（位于 <root> 末尾）
• 图表集保持一致（并排查看时）

如果发现问题，请修复 XML，并从转换步骤重新开始。

10. 自更新协议

创建新 .drawio 文件时会演进的可自动更新文件：

文件	稳定性
references/color-palette.md	可更新
references/layout-guidelines.md	可更新
SKILL.md 第 7 节	可追加
SKILL.md 第 9 节	可追加

创建或编辑 .drawio 文件后触发：

1. 解析所有 mxCell 元素的样式属性
2. 检测新颜色 → 在 color-palette.md 中添加并注明语义角色
3. 检测新的布局模式 → 添加到 layout-guidelines.md
4. 检测新的最佳实践或检查项 → 追加到 SKILL.md
5. 更新元数据（最后更新日期、源文件）

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

在 YAML 标头中添加 auto-stretch: false，以确保图像在移动设备上正确显示：

format:
  revealjs:
    auto-stretch: false