Back to Details

draw-io

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

draw.io Diagram Skill

drawio 图表技能指南

1. Basic Rules

1. 基本规则

  • Edit only 
    .drawio
    files
  • Do not directly edit 
    .drawio.png
    files
  • Use auto-generated 
    .drawio.png
    by pre-commit hook in slides
  • 仅编辑 
    .drawio
    文件
  • 请勿直接编辑 
    .drawio.png
    文件
  • 在幻灯片中使用由pre-commit钩子自动生成的 
    .drawio.png
    文件

2. Font Settings

2. 字体设置

For diagrams used in Quarto slides, specify 
defaultFontFamily
in mxGraphModel tag:
xml
<mxGraphModel defaultFontFamily="Noto Sans JP" ...>
Also explicitly specify 
fontFamily
in each text element's style attribute:
xml
style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"
对于Quarto幻灯片中使用的图表，需在mxGraphModel标签中指定
defaultFontFamily
：
xml
<mxGraphModel defaultFontFamily="Noto Sans JP" ...>
同时需在每个文本元素的style属性中显式指定
fontFamily
：
xml
style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"

3. Conversion Commands

3. 转换命令

See conversion script at scripts/convert-drawio-to-png.sh.
sh
undefined
转换脚本请参考scripts/convert-drawio-to-png.sh。
sh
undefined

Convert all .drawio files

转换所有.drawio文件

mise exec -- pre-commit run --all-files
mise exec -- pre-commit run --all-files

Convert specific .drawio file

转换指定.drawio文件

mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
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

Internal command used:

```sh
drawio -x -f png -s 2 -t -o output.drawio.png input.drawio
OptionDescription
-x
Export mode
-f png
PNG format output
-s 2
2x scale (high resolution)
-t
Transparent background
-o
Output file path
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

使用的内部命令：

```sh
drawio -x -f png -s 2 -t -o output.drawio.png input.drawio
参数说明
-x
导出模式
-f png
输出PNG格式
-s 2
2倍缩放（高分辨率）
-t
透明背景
-o
输出文件路径

4. Layout Adjustment

4. 布局调整

4.1. Coordinate Adjustment Steps

4.1. 坐标调整步骤

  1. Open 
    .drawio
    file in text editor (plain XML format)
  2. Find 
    mxCell
    for element to adjust (search by 
    value
    attribute for text)
  3. Adjust coordinates in 
    mxGeometry
    tag 
    • x
      : Position from left
    • y
      : Position from top
    • width
      : Width
    • height
      : Height
  4. Run conversion and verify
  1. 在文本编辑器中打开.drawio文件（纯XML格式）
  2. 找到需要调整的元素对应的
    mxCell
    （通过
    value
    属性搜索文本内容）
  3. 在
    mxGeometry
    标签中调整坐标 
    • x
      : 距左侧的位置
    • y
      : 距顶部的位置
    • width
      : 宽度
    • height
      : 高度
  4. 执行转换并验证效果

4.2. Coordinate Calculation

4.2. 坐标计算

  • Element center coordinate = 
    y + (height / 2)
  • To align multiple elements, calculate and match center coordinates
  • 元素中心坐标 = 
    y + (height / 2)
  • 如需对齐多个元素，计算并匹配它们的中心坐标

5. Design Principles

5. 设计原则

5.1. Basic Principles

5.1. 基本原则

  • Clarity: Create simple, visually clean diagrams
  • Consistency: Unify colors, fonts, icon sizes, line thickness
  • Accuracy: Do not sacrifice accuracy for simplification
  • 清晰性：创建简洁、视觉干净的图表
  • 一致性：统一颜色、字体、图标大小和线条粗细
  • 准确性：请勿为了简化而牺牲准确性

5.2. Element Rules

5.2. 元素规则

  • Label all elements
  • Use arrows to indicate direction (prefer 2 unidirectional arrows over bidirectional)
  • Use latest official icons
  • Add legend to explain custom symbols
  • 为所有元素添加标签
  • 使用箭头指示方向（优先使用两个单向箭头，而非双向箭头）
  • 使用最新的官方图标
  • 添加图例说明自定义符号

5.3. Accessibility

5.3. 可访问性

  • Ensure sufficient color contrast
  • Use patterns in addition to colors
  • 确保足够的颜色对比度
  • 除颜色外，使用图案辅助区分

5.4. Progressive Disclosure

5.4. 渐进式展示

Separate complex systems into staged diagrams:
Diagram TypePurpose
Context DiagramSystem overview from external perspective
System DiagramMain components and relationships
Component DiagramTechnical details and integration points
Deployment DiagramInfrastructure configuration
Data Flow DiagramData flow and transformation
Sequence DiagramTime-series interactions
将复杂系统拆分为多个阶段的图表：
图表类型用途
上下文图表从外部视角展示系统概览
系统图表展示主要组件及其关系
组件图表展示技术细节和集成点
部署图表展示基础设施配置
数据流图表展示数据流转与转换
时序图表展示时序交互过程

5.5. Metadata

5.5. 元数据

Include title, description, last updated, author, and version in diagrams.
在图表中包含标题、描述、最后更新时间、作者和版本信息。

6. Best Practices

6. 最佳实践

6.1. Background Color

6.1. 背景颜色

  • Remove 
    background="#ffffff"
  • Transparent background adapts to various themes
  • 移除
    background="#ffffff"
    属性
  • 透明背景可适配多种主题

6.2. Font Size

6.2. 字体大小

  • Use 1.5x standard font size (around 18px) for PDF readability
  • 为提升PDF可读性，使用标准字体大小的1.5倍（约18px）

6.3. Japanese Text Width

6.3. 日文文本宽度

  • Allow 30-40px per character
  • Insufficient width causes unintended line breaks
xml
<!-- For 10-character text, allow 300-400px -->
<mxGeometry x="140" y="60" width="400" height="40" />
  • 每个字符预留30-40px宽度
  • 宽度不足会导致意外换行
xml
<!-- 对于10字符文本，预留300-400px宽度 -->
<mxGeometry x="140" y="60" width="400" height="40" />

6.4. Arrow Placement

6.4. 箭头放置

  • Always place arrows at back (position in XML right after Title)
  • Position arrows to avoid overlapping with labels
  • Keep arrow start/end at least 20px from label bottom edge
xml
<!-- Title -->
<mxCell id="title" value="..." .../>

<!-- Arrows (back layer) -->
<mxCell id="arrow1" style="edgeStyle=..." .../>

<!-- Other elements (front layer) -->
<mxCell id="box1" .../>
  • 始终将箭头置于底层（在XML中位于标题之后）
  • 调整箭头位置以避免与标签重叠
  • 箭头起点/终点与标签下边缘至少保持20px距离
xml
<!-- 标题 -->
<mxCell id="title" value="..." .../>

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

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

6.5. Arrow Connection to Text Labels

6.5. 箭头与文本标签的连接

For text elements, exitX/exitY don't work, so use explicit coordinates:
xml
<!-- Good: Explicit coordinates with 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>
对于文本元素，exitX/exitY属性无效，需使用显式坐标：
xml
<!-- 正确示例：使用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 Adjustment

6.6. 边缘标签偏移调整

Adjust offset attribute to distance arrow labels from arrows:
xml
<!-- Place above arrow (negative value to distance) -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- Place below arrow (positive value to distance) -->
<mxPoint x="0" y="40" as="offset"/>
调整offset属性以拉开箭头标签与箭头的距离：
xml
<!-- 置于箭头上方（负值拉开距离） -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- 置于箭头下方（正值拉开距离） -->
<mxPoint x="0" y="40" as="offset"/>

6.7. Remove Unnecessary Elements

6.7. 移除不必要元素

  • Remove decorative icons irrelevant to context
  • Example: If ECR exists, separate Docker icon is unnecessary
  • 移除与上下文无关的装饰性图标
  • 示例：若已包含ECR，则无需额外添加Docker图标

6.8. Labels and Headings

6.8. 标签与标题

  • Service name only: 1 line
  • Service name + supplementary info: 2 lines with line break
  • Redundant notation (e.g., ECR Container Registry): shorten to 1 line
  • Use 
    &lt;br&gt;
    tag for line breaks
  • 仅服务名称：单行显示
  • 服务名称+补充信息：换行分为两行
  • 冗余表述（如ECR Container Registry）：简化为单行
  • 使用
    &lt;br&gt;
    标签实现换行

6.9. Background Frame and Internal Element Placement

6.9. 背景框与内部元素放置

When placing elements inside background frames (grouping boxes), ensure sufficient margin.
  • YOU MUST: Internal elements must have at least 30px margin from frame boundary
  • YOU MUST: Account for rounded corners (
    rounded=1
    ) and stroke width
  • YOU MUST: Always visually verify PNG output for overflow
Coordinate calculation verification:
text
Background frame: y=20, height=400 -> range is y=20-420
Internal element top: frame y + 30 or more (e.g., y=50)
Internal element bottom: frame y + height - 30 or less (e.g., up to y=390)
Bad example (may overflow):
xml
<!-- Background frame -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="400" />
</mxCell>
<!-- Text: y=30 is too close to frame top (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="30" width="540" height="35" />
</mxCell>
Good example (sufficient margin):
xml
<!-- Background frame -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- Text: y=50 is 30px from frame top (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>
当在背景框（分组框）内放置元素时，需确保足够的边距。
  • 必须遵守：内部元素与背景框边界至少保持30px边距
  • 必须遵守：需考虑圆角（
    rounded=1
    ）和描边宽度
  • 必须遵守：始终通过PNG输出视觉验证是否存在溢出
坐标计算验证：
text
背景框：y=20, height=400 → 范围为y=20-420
内部元素顶部：背景框y值 + 30及以上（例如y=50）
内部元素底部：背景框y值 + 高度 -30及以下（例如最高到y=390）
错误示例（可能溢出）：
xml
<!-- 背景框 -->
<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>
正确示例（边距充足）：
xml
<!-- 背景框 -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- 文本：y=50距离背景框顶部（y=20）为30px -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>

7. Reference

7. 参考资料

  • Layout Guidelines
  • AWS Icons
  • AWS Icon Search Script
AWS icon search examples:
sh
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda
  • 布局指南
  • AWS图标
  • AWS图标搜索脚本
AWS图标搜索示例：
sh
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

8. Checklist

8. 检查清单

  • No background color set (page="0")
  • Font size appropriate (larger recommended)
  • Arrows placed at back layer
  • Arrows not overlapping labels (verify in PNG)
  • Arrow start/end sufficiently distant from labels (at least 20px)
  • Arrows not penetrating boxes or icons (verify in PNG)
  • Internal elements not overflowing background frame (verify in PNG)
  • 30px+ margin between background frame and internal elements
  • AWS service names are official names/correct abbreviations
  • AWS icons are latest version (mxgraph.aws4.*)
  • No unnecessary elements remaining
  • Visually verified PNG conversion
  • 未设置背景颜色（page="0"）
  • 字体大小合适（建议使用较大字号）
  • 箭头置于底层
  • 箭头未与标签重叠（在PNG中验证）
  • 箭头起点/终点与标签保持足够距离（至少20px）
  • 箭头未穿透方框或图标（在PNG中验证）
  • 内部元素未溢出背景框（在PNG中验证）
  • 背景框与内部元素边距≥30px
  • AWS服务名称为官方名称/正确缩写
  • AWS图标为最新版本（mxgraph.aws4.*）
  • 无多余元素残留
  • 已视觉验证PNG转换效果

9. Image Display in reveal.js Slides

9. 在reveal.js幻灯片中展示图片

Add 
auto-stretch: false
to YAML header:
yaml
---
title: "Your Presentation"
format:
  revealjs:
    auto-stretch: false
---
This ensures correct image display on mobile devices.
在YAML头部添加
auto-stretch: false
：
yaml
---
title: "Your Presentation"
format:
  revealjs:
    auto-stretch: false
---
这可确保图片在移动设备上正确显示。