| name | svg-diagrams |
| description | Render architecture diagrams, system maps, and technical illustrations as live SVG directly in chat using a fenced `svg` block. |
| emoji | 🧩 |
| version | 1.0.0 |
SVG Diagrams
Render architecture diagrams, system maps, and technical illustrations as live SVG directly in chat using a fenced svg block.
CRITICAL OUTPUT RULES
- Output a single fenced
```svg block containing raw SVG
- No file saving. Inline output only — no file tools
- No declare_plan. Read skill → output SVG. Done
- The frontend renders it as a live scaled widget automatically
When to Use SVG vs Other Formats
| Need | Use |
|---|
| Data chart (bar, line, pie) | chart-visualizer skill |
| Text-defined flowchart or sequence diagram | mermaid-diagrams skill |
| Architecture with custom layout/spatial positioning | This skill (SVG) |
| Multi-panel interactive dashboard | html-interactive skill |
| Icon or small illustration inline | This skill (SVG) |
Use SVG when you need precise control over position — exact box placement, specific arrow routing, custom shapes, color-coded regions.
SVG Setup Rules
<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="font-family:sans-serif; width:100%">
</svg>
Always:
- Set
viewBox — this makes it responsive
- Set
width="100%" on the root <svg> — fills the chat panel
- Set
font-family:sans-serif as a base style
- Define arrow markers in
<defs> if using arrows
Never:
- Set a
background on the root <svg> — leaves transparent so it works in dark and light mode
- Hardcode pixel widths without
viewBox — it won't scale
- Use absolute font sizes above 16px for labels
Arrow Marker (always include when using arrows)
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="#94a3b8" stroke-width="1.5"
stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<line x1="120" y1="50" x2="200" y2="50" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arrow)"/>
For colored arrows, define a separate marker per color — the marker stroke doesn't inherit from the line.
Component Box Patterns
Standard component box (single label)
<rect x="50" y="40" width="140" height="44" rx="8" fill="#1e1b4b" stroke="#6366f1" stroke-width="1.5"/>
<text x="120" y="67" text-anchor="middle" fill="#a5b4fc" font-size="13" font-weight="500">API Gateway</text>
Two-line box (title + subtitle)
<rect x="50" y="40" width="160" height="56" rx="8" fill="#1e1b4b" stroke="#6366f1" stroke-width="1.5"/>
<text x="130" y="62" text-anchor="middle" fill="#a5b4fc" font-size="13" font-weight="600">Auth Service</text>
<text x="130" y="80" text-anchor="middle" fill="#6366f1" font-size="11">JWT + OAuth2</text>
Container / group box (dashed boundary)
<rect x="20" y="20" width="360" height="200" rx="12" fill="none" stroke="#334155" stroke-width="1.5" stroke-dasharray="6,4"/>
<text x="40" y="42" fill="#64748b" font-size="12" font-weight="500">AWS Region us-east-1</text>
Database cylinder (approximated)
<ellipse cx="300" cy="65" rx="50" ry="12" fill="#0f172a" stroke="#22d3ee" stroke-width="1.5"/>
<rect x="250" y="65" width="100" height="60" fill="#0f172a" stroke="#22d3ee" stroke-width="1.5"/>
<ellipse cx="300" cy="125" rx="50" ry="12" fill="#0f172a" stroke="#22d3ee" stroke-width="1.5"/>
<text x="300" y="100" text-anchor="middle" fill="#67e8f9" font-size="12">PostgreSQL</text>
Color System
Use these consistently. Dark backgrounds, colored borders and labels:
| Component type | Fill | Border | Label |
|---|
| Service / app | #1e1b4b | #6366f1 | #a5b4fc |
| Database | #0f172a | #22d3ee | #67e8f9 |
| Queue / broker | #1a0a2e | #8b5cf6 | #c4b5fd |
| External / 3rd party | #1c1917 | #94a3b8 | #cbd5e1 |
| User / client | #0c1a0c | #4ade80 | #86efac |
| Warning / error state | #1f0a0a | #f43f5e | #fca5a5 |
| Container boundary | none | #334155 (dashed) | #64748b |
Arrow / connector color: #94a3b8 (neutral gray) unless the connection type matters — use colored arrows sparingly.
Layout Guidelines
Horizontal flow (left → right): Use for request pipelines, data flows, CI/CD pipelines
- Start x at ~40, increment by box-width + gap (usually 60–80px gap)
- Keep all boxes vertically centered on the same y baseline
- Total width: stay within viewBox width minus 40px padding each side
Vertical flow (top → bottom): Use for layered architectures (frontend → backend → DB)
- Start y at ~40, increment by box-height + gap (usually 40–60px)
- Center boxes horizontally in the viewBox
Grid layout: Use for microservice maps
- Define rows and columns, space evenly
- Connect with L-shaped paths for non-adjacent boxes to avoid crossing
Avoid:
- Arrows that cross through unrelated boxes — route around them with
<path d="M x1 y1 L x1 ymid L x2 ymid L x2 y2"/>
- Text that overflows its box — shorten labels or widen boxes
- More than ~12 components in one diagram — split into sub-diagrams
Full Example: 3-Tier Web Architecture
<svg viewBox="0 0 760 200" xmlns="http://www.w3.org/2000/svg" style="font-family:sans-serif; width:100%">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<rect x="20" y="78" width="120" height="44" rx="8" fill="#0c1a0c" stroke="#4ade80" =/>
Browser
API Gateway
Rate limit · Auth
App Server
Node.js · Express
PostgreSQL
Redis Cache
Pro Tips
- Label placement: Center text with
text-anchor="middle" at the horizontal midpoint of the box and y at about 60% of the box height
- Consistent spacing: Define your column x-positions and row y-positions as variables mentally before drawing — inconsistent gaps look sloppy
- Dashed lines for async/optional: Use
stroke-dasharray="5,4" for async connections, webhooks, optional paths
- Group related components with a dashed container rect behind them (lower z-order = earlier in SVG source)
- Keep viewBox height tight — calculate the actual bottom of your lowest element + 30px padding and use that as the viewBox height
Proactive Triggering
Automatically produce an SVG diagram (without being asked) when:
- User describes a system with multiple components and asks how it works
- User asks to "design" or "architect" something with services, databases, or queues
- A multi-agent team completes a task and the result is a system or workflow worth mapping
- User asks "what does the relationship between X and Y look like"
