Back to Details

technical-svg-diagrams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Generate technical SVG diagrams with consistent styling for blog posts and documentation. All diagrams use a unified visual language: grid backgrounds, monospace fonts, muted colors with semantic accents, and clean geometric shapes. </objective>
<quick_start>
  1. Identify diagram type needed (architecture, flow, or component)
  2. Read 
    references/svg-patterns.md
    for templates and color palette
  3. Generate SVG using the established patterns
  4. Save to target directory with descriptive filename
  5. Export to PNG (via 
    agent-browser
    ) or WebP (via 
    cairosvg
    ) as needed </quick_start>
<design_system>
<objective> 为博客文章和文档生成风格统一的技术SVG图表。所有图表采用统一的视觉语言：网格背景、等宽字体、带有语义强调的柔和配色，以及简洁的几何形状。 </objective>
<quick_start>
  1. 确定所需的图表类型（架构图、流程图或组件图）
  2. 阅读
    references/svg-patterns.md
    获取模板和配色方案
  3. 使用既定规范生成SVG
  4. 以描述性文件名保存到目标目录
  5. 按需通过
    agent-browser
    导出为PNG或通过
    cairosvg
    导出为WebP </quick_start>
<design_system>

Color Palette

配色方案

PurposeColorHex
BackgroundLight gray#fafafa
Grid linesSubtle gray#e5e5e5
Primary textDark gray#333
Secondary textMedium gray#666
Muted textLight gray#999
Borders/arrowsGray#ccc
Success/positiveGreen#27ae60
Error/negativeRed#e74c3c
Primary accentBlue#3498db
Warning/sandboxOrange#f39c12
Process stepPurple#9b59b6
用途颜色十六进制值
背景浅灰色#fafafa
网格线淡灰色#e5e5e5
主文本深灰色#333
次要文本中灰色#666
弱化文本浅灰色#999
边框/箭头灰色#ccc
成功/积极状态绿色#27ae60
错误/消极状态红色#e74c3c
主强调色蓝色#3498db
警告/沙箱环境橙色#f39c12
流程步骤紫色#9b59b6

Typography

排版规范

  • Font family: 
    monospace
    for all text
  • Title: 14px bold, #333
  • Subtitle/tag: 12px, #888, in brackets 
    [ LIKE_THIS ]
  • Labels: 10-11px, color matches element
  • Notes: 7-8px, #999
  • 字体族: 所有文本使用
    monospace
    等宽字体
  • 标题: 14px 粗体，#333
  • 副标题/标签: 12px，#888，放在方括号
    [ LIKE_THIS ]
    中
  • 标签文本: 10-11px，颜色与对应元素匹配
  • 注释: 7-8px，#999

Common Elements

通用元素

Grid background:
xml
<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>
Arrow marker:
xml
<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>
Node (circle with inner dot):
xml
<circle cx="X" cy="Y" r="35" fill="none" stroke="#ccc" stroke-width="2"/>
<circle cx="X" cy="Y" r="18" fill="#COLOR"/>
Box container:
xml
<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="2"/>
Dashed container (sandbox/isolation):
xml
<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#f39c12" stroke-width="2" stroke-dasharray="5,3"/>
Label box:
xml
<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>
网格背景:
xml
<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>
箭头标记:
xml
<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>
节点（带内部圆点的圆形）:
xml
<circle cx="X" cy="Y" r="35" fill="none" stroke="#ccc" stroke-width="2"/>
<circle cx="X" cy="Y" r="18" fill="#COLOR"/>
盒子容器:
xml
<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="2"/>
虚线容器（沙箱/隔离环境）:
xml
<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#f39c12" stroke-width="2" stroke-dasharray="5,3"/>
标签框:
xml
<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>

Architecture Diagrams

架构图

Horizontal left-to-right flow showing system components.
Use for: Before/after comparisons, system overviews, data flow
Structure:
  • Title + tag at top left
  • Components flow left to right
  • Arrows connect components
  • Bottom note summarizes key point
Dimensions: 800x350 to 800x400
从左到右的水平布局，展示系统组件。
适用场景: 前后对比、系统概览、数据流展示
结构:
  • 左上角显示标题+标签
  • 组件从左到右排列
  • 箭头连接各组件
  • 底部注释总结核心要点
尺寸: 800x350 至 800x400

Flow Diagrams

流程图

Vertical top-to-bottom showing process steps.
Use for: Execution flows, request lifecycles, step-by-step processes
Structure:
  • Title + tag at top
  • Dashed vertical guide line
  • Steps connected by arrows with polygon heads
  • Decision diamonds for branching
  • Ellipses for start/end states
Dimensions: 600x700 (adjust height for steps)
从上到下的垂直布局，展示流程步骤。
适用场景: 执行流程、请求生命周期、分步流程
结构:
  • 顶部显示标题+标签
  • 虚线垂直引导线
  • 步骤通过带多边形箭头的线条连接
  • 决策点使用菱形
  • 开始/结束状态使用椭圆形
尺寸: 600x700（根据步骤数量调整高度）

Component Diagrams

组件图

Focused view of a single component's internals.
Use for: Showing internal structure, nested elements, detailed breakdowns
Structure:
  • Outer container box
  • Inner elements with semantic colors
  • Labels above or below containers </diagram_types>
<process>
聚焦单个组件的内部结构。
适用场景: 展示内部结构、嵌套元素、详细分解
结构:
  • 外部容器盒子
  • 带有语义配色的内部元素
  • 容器上方或下方添加标签 </diagram_types>
<process>

Creating a Diagram

创建图表步骤

  1. Determine type and dimensions
    • Architecture: 800x350-400, horizontal
    • Flow: 600x700+, vertical
    • Component: varies by content
  2. Set up SVG structure
    xml
    <svg viewBox="0 0 WIDTH HEIGHT" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <!-- Grid pattern -->
    <!-- Arrow markers as needed -->
  </defs>

  <!-- Background -->
  <rect width="WIDTH" height="HEIGHT" fill="#fafafa"/>
  <rect width="WIDTH" height="HEIGHT" fill="url(#grid)"/>

  <!-- Title -->
  <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="#888">[ TAG ]</text>

  <!-- Content -->

  <!-- Bottom note -->
  <text x="CENTER" y="BOTTOM" font-family="monospace" font-size="10" fill="#999" text-anchor="middle">summary note</text>
</svg>
  3. Add components using patterns from references/svg-patterns.md
  4. Connect with arrows
    • Solid lines for primary flow
    • Dashed lines for secondary/return flow
    • Use opacity="0.5" for response arrows
  5. Add labels
    • Component names in SCREAMING_SNAKE_CASE
    • Action labels in lowercase_snake_case
    • Use text-anchor="middle" for centered text
  6. Save with descriptive filename
    • diagram-before.svg
      , 
      diagram-after.svg
    • diagram-flow.svg
      , 
      diagram-architecture.svg
      </process>
<success_criteria> Diagram is complete when:
  • Uses consistent color palette
  • All text is monospace
  • Grid background applied
  • Title with bracketed tag present
  • Components properly connected with arrows
  • Labels are clear and properly positioned
  • Bottom summary note included
  • SVG is valid and renders correctly
  • Exported to PNG or WebP if raster output requested </success_criteria>
<export>
  1. 确定图表类型和尺寸
    • 架构图：800x350-400，水平布局
    • 流程图：600x700+，垂直布局
    • 组件图：根据内容调整尺寸
  2. 搭建SVG结构
    xml
    <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="#888">[ TAG ]</text>

  <!-- 内容 -->

  <!-- 底部注释 -->
  <text x="CENTER" y="BOTTOM" font-family="monospace" font-size="10" fill="#999" 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
      </process>
<success_criteria> 图表完成的判定标准：
  • 使用统一配色方案
  • 所有文本为等宽字体
  • 应用了网格背景
  • 包含带方括号标签的标题
  • 组件通过箭头正确连接
  • 标签清晰且位置恰当
  • 包含底部总结注释
  • SVG有效且渲染正常
  • 若需要栅格输出，已导出为PNG或WebP </success_criteria>
<export>

Export Formats

导出格式

After creating the SVG, export to raster formats as needed.
创建SVG后，按需导出为栅格格式。

PNG via agent-browser (recommended)

通过agent-browser导出为PNG（推荐）

Uses a real browser engine for pixel-perfect rendering. Requires the 
agent-browser
skill.
Step 1: Create HTML wrapper
bash
bun run scripts/create-html.ts --svg diagram.svg --output diagram.html
Options:
  • --padding <px>
    — padding around SVG (default: 40)
  • --background <color>
    — override auto-detected background
Step 2: Capture high-resolution PNG
bash
agent-browser set viewport 3840 2160
agent-browser open "file://$(pwd)/diagram.html"
agent-browser wait 1000
agent-browser screenshot --full diagram.png
agent-browser close
Step 3: Clean up
bash
rm diagram.html
使用真实浏览器引擎实现像素级完美渲染。需要
agent-browser
技能。
步骤1：创建HTML包装器
bash
bun run scripts/create-html.ts --svg diagram.svg --output diagram.html
可选参数：
  • --padding <px>
    — SVG周围的内边距（默认：40）
  • --background <color>
    — 覆盖自动检测的背景色
步骤2：捕获高分辨率PNG
bash
agent-browser set viewport 3840 2160
agent-browser open "file://$(pwd)/diagram.html"
agent-browser wait 1000
agent-browser screenshot --full diagram.png
agent-browser close
步骤3：清理文件
bash
rm diagram.html

WebP via cairosvg

通过cairosvg导出为WebP

Lightweight, no browser needed. Best when agent-browser is unavailable.
bash
uvx --from cairosvg cairosvg diagram.svg -o diagram.png --output-width 1600
uvx --with pillow python -c "from PIL import Image; Image.open('diagram.png').save('diagram.webp', 'WEBP', lossless=True)"
rm diagram.png
Note: 
lossless=True
is best for diagrams — smaller than lossy AND perfect quality.
Alternative tools (if available):
bash
undefined
轻量级工具，无需浏览器。当agent-browser不可用时最佳选择。
bash
uvx --from cairosvg cairosvg diagram.svg -o diagram.png --output-width 1600
uvx --with pillow python -c "from PIL import Image; Image.open('diagram.png').save('diagram.webp', 'WEBP', lossless=True)"
rm diagram.png
注意：
lossless=True
最适合图表——比有损压缩文件更小且画质完美。
替代工具（若可用）：
bash
undefined

ImageMagick

ImageMagick

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

librsvg + cwebp

librsvg + cwebp

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

**Platform notes:**
- macOS: `brew install cairo` if cairosvg fails
- Linux: `apt install libcairo2-dev` if needed
</export>
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`
</export>