technical-svg-diagrams

为博客文章和文档生成风格统一的技术 SVG 图表。请在 SVG 旁附上无障碍文本描述，或为有意义的内联图表添加标题/描述和无障碍名称。不要仅依赖颜色传达信息。所有图表都使用统一的视觉语言：网格背景、等宽字体、柔和色彩搭配语义强调色，以及简洁的几何形状。

<quick_start>

1. 确定所需的图表类型（架构图、流程图或组件图）
2. 阅读 references/svg-patterns.md，了解模板和调色板
3. 使用既定模式生成 SVG
4. 使用描述性文件名保存到目标目录
5. 仅在收到请求时导出，并使用可用的浏览器截图工具或 cairosvg </quick_start>

<design_system>

调色板

用途	颜色	Hex
背景	浅灰色	#fafafa
网格线	柔和灰色	#e5e5e5
主要文本	深灰色	#333
次要文本	中灰色	#666
弱化文本	灰色	#666
边框/箭头	灰色	#ccc
成功/正向	绿色	#27ae60
错误/负向	红色	#e74c3c
主要强调色	蓝色	#3498db
警告/沙盒	橙色	#f39c12
流程步骤	紫色	#9b59b6

排版

• 字体系列： 所有文本均使用 monospace
• 标题： 14px 粗体，#333
• 副标题/标签： 12px，#666，使用方括号 [ 类似这样 ]
• 标签文字： 10–11px，颜色与元素匹配
• 注释： 根据最终显示/导出尺寸确定字号；优先保证文本易读，不要为了压缩内容而将字号缩小到 7–8px。请在最终背景上检查对比度。

常用元素

网格背景：

<pattern id="grid" width="20" height="20" patternUnits="userSpaceOnUse">
  <path d="M 20 0 L 0 0 0 20" fill="none" stroke="#e5e5e5" stroke-width="0.5"/>
</pattern>

箭头标记：

<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
  <path d="M0,0 L0,6 L9,3 z" fill="#ccc"/>
</marker>

节点（带内点的圆）：

<circle cx="X" cy="Y" r="35" fill="none" stroke="#ccc" stroke-width="2"/>
<circle cx="X" cy="Y" r="18" fill="#COLOR"/>

方框容器：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="2"/>

虚线容器（沙盒/隔离）：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#f39c12" stroke-width="2" stroke-dasharray="5,3"/>

标签框：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="1"/>
<text x="CX" y="CY" font-family="monospace" font-size="11" fill="#666" text-anchor="middle">LABEL_NAME</text>

</design_system>

<diagram_types>

架构图

以从左到右的水平流程展示系统组件。

适用于： 前后对比、系统概览、数据流

结构：

• 左上方放置标题和标签
• 组件从左向右排列
• 使用箭头连接组件
• 底部注释总结要点

尺寸： 800x350 到 800x400

流程图

以从上到下的垂直流程展示处理步骤。

适用于： 执行流程、请求生命周期、分步流程

结构：

• 顶部放置标题和标签
• 使用垂直虚线引导线
• 使用带多边形箭头头部的箭头连接步骤
• 使用菱形表示分支决策
• 使用椭圆表示开始/结束状态

尺寸： 600x700（根据步骤调整高度）

组件图

聚焦展示单个组件的内部结构。

适用于： 展示内部结构、嵌套元素、详细分解

结构：

• 外层容器方框
• 使用语义颜色表示内部元素
• 在容器上方或下方放置标签 </diagram_types>

## 创建图表

1. 确定类型和尺寸

   • 架构图：800x350-400，横向
   • 流程图：600x700+，纵向
   • 组件图：根据内容而定

2. 设置 SVG 结构

   <svg viewBox="0 0 WIDTH HEIGHT" xmlns="http://www.w3.org/2000/svg">
     <defs>
       
       
     </defs>
   
     
     <rect width="WIDTH" height="HEIGHT" fill="#fafafa"/>
     <rect width="WIDTH" height="HEIGHT" fill="url(#grid)"/>
   
     
     <text x="40" y="40" font-family="monospace" font-size="14" fill="#333" font-weight="bold">TITLE</text>
     <text x="X" y="40" font-family="monospace" font-size="12" fill="#666">[ TAG ]</text>
   
     
   
     
     <text x="CENTER" y="BOTTOM" font-family="monospace" font-size="10" fill="#666" text-anchor="middle">summary note</text>
   </svg>
   

3. 使用 references/svg-patterns.md 中的样式添加组件

4. 用箭头连接

   • 主流程使用实线
   • 次要流程／返回流程使用虚线
   • 响应箭头使用 opacity="0.5"

5. 添加标签

   • 组件名称使用 SCREAMING_SNAKE_CASE
   • 操作标签使用 lowercase_snake_case
   • 居中对齐的文本使用 text-anchor="middle"

6. 使用描述性文件名保存

   • diagram-before.svg、diagram-after.svg
   • diagram-flow.svg、diagram-architecture.svg

<success_criteria> 图表完成条件：

• 使用统一的配色方案
• 所有文本均为等宽字体
• 添加网格背景
• 包含带方括号标签的标题
• 使用箭头正确连接各组件
• 标签清晰且位置恰当
• 包含底部摘要说明
• SVG 有效且可正确渲染
• 若请求栅格输出，则导出为 PNG 或 WebP </success_criteria>

## 导出格式

创建 SVG 后，根据需要导出为栅格格式。

通过浏览器自动化导出 PNG

使用可用的浏览器自动化工具进行像素级精准渲染。如果当前运行环境没有浏览器工具或 agent-browser 可执行文件，请使用下方的 cairosvg 方案，而不要停下来或安装新工具。

步骤 1：创建 HTML 包装文件

# Resolve this to the directory of the loaded skill, not the current project.
SVG_SKILL_DIR="/path/to/loaded/technical-svg-diagrams"
SVG_CAPTURE_DIR="$(mktemp -d)"
bun run "$SVG_SKILL_DIR/scripts/create-html.ts" --svg diagram.svg --output "$SVG_CAPTURE_DIR/diagram.html" --width 1600

选项：

• --padding <px> — SVG 周围的非负内边距（默认值：40；支持 0）
• --width <px> — 渲染后的 SVG 宽度（默认值：1600）
• --background <color> — 用于覆盖检测到的背景，可使用十六进制、命名颜色、rgb() 或 hsl()

使用嵌入资源的自包含 SVG。包装文件使用 SVG 图像模式，因此脚本不会执行，且无法访问外部资源。检查实际栅格图；背景检测器可处理根样式和铺满画布的矩形，但无法处理任意 SVG 绘制／合成效果。复杂图形请指定背景色。脚本可通过 Bun 或支持 TypeScript 类型剥离的现代 Node 运行；请使用已安装的运行时。

步骤 2：捕获高分辨率 PNG

# Load agent-browser's installed core skill first; use a unique task session.
SVG_CAPTURE_SESSION="svg-capture-$$"
agent-browser --session "$SVG_CAPTURE_SESSION" open "file://$SVG_CAPTURE_DIR/diagram.html"
agent-browser --session "$SVG_CAPTURE_SESSION" set viewport 1800 1200
agent-browser --session "$SVG_CAPTURE_SESSION" wait --fn 'document.querySelector("img").complete && document.querySelector("img").naturalWidth > 0'
agent-browser --session "$SVG_CAPTURE_SESSION" screenshot .container diagram.png
agent-browser --session "$SVG_CAPTURE_SESSION" close

步骤 3：清理

rm "$SVG_CAPTURE_DIR/diagram.html"
rmdir "$SVG_CAPTURE_DIR"

通过 cairosvg 导出 WebP

轻量，无需浏览器。适用于 agent-browser 不可用的情况。

uvx --from cairosvg cairosvg diagram.svg -o diagram.png --output-width 1600
uv run --with pillow python -c "from PIL import Image; Image.open('diagram.png').save('diagram.webp', 'WEBP', lossless=True)"
rm diagram.png

对边缘和文本有精确要求时使用 lossless=True。若下载文件大小很重要，请比较输出大小；无损 WebP 并非总比有损 WebP 小。

替代工具（如有）：

# ImageMagick
convert -background none -density 150 diagram.svg diagram.webp

# librsvg + cwebp
rsvg-convert -w 1600 diagram.svg -o diagram.png && cwebp diagram.png -o diagram.webp

平台说明：

• macOS：如果 cairosvg 运行失败，请执行 brew install cairo
• Linux：如有需要，请执行 apt install libcairo2-dev