Technical Svg Diagrams

Typography

• Font family: monospace for all text
• Title: 14px bold, #333
• Subtitle/tag: 12px, #666, in brackets [ LIKE_THIS ]
• Labels: 10-11px, color matches element
• Notes: size for the final display/export; aim for readable text rather than shrinking meaningful content to 7–8px. Verify contrast on the final background.

Common Elements

Grid background:

<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:

<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):

<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:

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

Dashed container (sandbox/isolation):

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

Label box:

<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>

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

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)

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

1. Determine type and dimensions

   • Architecture: 800x350-400, horizontal
   • Flow: 600x700+, vertical
   • Component: varies by content

2. Set up SVG structure

   <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="#666">[ TAG ]</text>
   
     <!-- Content -->
   
     <!-- Bottom note -->
     <text x="CENTER" y="BOTTOM" font-family="monospace" font-size="10" fill="#666" 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

After creating the SVG, export to raster formats as needed.

PNG via browser automation

Use an available browser automation surface for pixel-accurate rendering. If the active runtime has no browser tool or agent-browser executable, use the cairosvg route below rather than stopping or installing a new tool.

Step 1: Create HTML wrapper

# 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

Options:

• --padding <px> — non-negative padding around SVG (default: 40; zero supported)
• --width <px> — rendered SVG width (default: 1600)
• --background <color> — hex, named, rgb(), or hsl() override for the detected background

Use self-contained SVGs with embedded assets. The wrapper uses SVG image mode, so scripts do not execute and external resources are unavailable. Inspect the actual raster; the background detector handles root styles and full-canvas rectangles, not arbitrary SVG paint/compositing. Use an explicit background for complex art. Bun or modern Node with TypeScript type stripping runs the script; use an already installed runtime.

Step 2: Capture high-resolution 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

Step 3: Clean up

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

WebP via cairosvg

Lightweight, no browser needed. Best when agent-browser is unavailable.

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

Use lossless=True when exact edges and text matter. Compare output size if download weight matters; lossless is not universally smaller than lossy WebP.

Alternative tools (if available):

# 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

Platform notes:

• macOS: brew install cairo if cairosvg fails
• Linux: apt install libcairo2-dev if needed