technical-svg-diagrams

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

Identify diagram type needed (architecture, flow, or component)
Read
```
references/svg-patterns.md
```
for templates and color palette
Generate SVG using the established patterns
Save to target directory with descriptive filename
Export to PNG (via
```
agent-browser
```
) or WebP (via
```
cairosvg
```
) as needed </quick_start>

<design_system>

Color Palette

Purpose	Color	Hex
Background	Light gray	#fafafa
Grid lines	Subtle gray	#e5e5e5
Primary text	Dark gray	#333
Secondary text	Medium gray	#666
Muted text	Light gray	#999
Borders/arrows	Gray	#ccc
Success/positive	Green	#27ae60
Error/negative	Red	#e74c3c
Primary accent	Blue	#3498db
Warning/sandbox	Orange	#f39c12
Process step	Purple	#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

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>

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

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

<process> ## Creating a Diagram

Determine type and dimensions
- Architecture: 800x350-400, horizontal
- Flow: 600x700+, vertical
- Component: varies by content

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>

Add components using patterns from references/svg-patterns.md
Connect with arrows
- Solid lines for primary flow
- Dashed lines for secondary/return flow
- Use opacity="0.5" for response arrows
Add labels
- Component names in SCREAMING_SNAKE_CASE
- Action labels in lowercase_snake_case
- Use text-anchor="middle" for centered text

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> ## Export Formats

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

PNG via agent-browser (recommended)

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

WebP via cairosvg

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

# 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 </export>

technical-svg-diagrams

NPX Install

Tags

SKILL.md Content

Color Palette

Typography

Common Elements

Architecture Diagrams

Flow Diagrams

Component Diagrams

PNG via agent-browser (recommended)

WebP via cairosvg