architecture-diagram

Architecture Diagram Skill

Create professional technical architecture diagrams as self-contained HTML files with inline SVG graphics and CSS styling.

Version 1.1 · MIT License · Authored by Cocoon AI

Design System

Color Palette

Use these semantic colors for component types:

Component Type	Fill (rgba)	Stroke
Frontend	`rgba(8, 51, 68, 0.4)`	`#22d3ee` (cyan-400)
Backend	`rgba(6, 78, 59, 0.4)`	`#34d399` (emerald-400)
Database	`rgba(76, 29, 149, 0.4)`	`#a78bfa` (violet-400)
AWS/Cloud	`rgba(120, 53, 15, 0.3)`	`#fbbf24` (amber-400)
Security	`rgba(136, 19, 55, 0.4)`	`#fb7185` (rose-400)
Message Bus	`rgba(251, 146, 60, 0.3)`	`#fb923c` (orange-400)
External/Generic	`rgba(30, 41, 59, 0.5)`	`#94a3b8` (slate-400)

Typography

Use JetBrains Mono for all text (monospace, technical aesthetic):

<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">

Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels.

Visual Elements

Background: #020617 (slate-950) with subtle grid pattern:

<pattern id=

Component boxes: Rounded rectangles (rx="6") with 1.5px stroke, semi-transparent fills.

Security groups: Dashed stroke (stroke-dasharray="4,4"), transparent fill, rose color.

Region boundaries: Larger dashed stroke (stroke-dasharray="8,4"), amber color, rx="12".

Arrows: Use SVG marker for arrowheads:

Arrow z-order: Draw connection arrows early in the SVG (after the background grid) so they render behind component boxes. SVG elements are painted in document order, so arrows drawn first will appear behind shapes drawn later.

Masking arrows behind transparent fills: Since component boxes use semi-transparent fills (rgba(..., 0.4)), arrows behind them will show through. To fully mask arrows, draw an opaque background rect (e.g., fill="#0f172a") at the same position before drawing the semi-transparent styled rect on top:

Auth/security flows: Dashed lines in rose color (#fb7185).

Message buses / Event buses: Small connector elements between services. Use orange color (#fb923c stroke, rgba(251, 146, 60, 0.3) fill):

Spacing Rules

CRITICAL: When stacking components vertically, ensure proper spacing to avoid overlaps:

Standard component height: 60px for services, 80-120px for larger components
Minimum vertical gap between components: 40px
Inline connectors (message buses): Place IN the gap between components, not overlapping

Example vertical layout:

Wrong: Placing a message bus at y=160 when Component B starts at y=170 (causes overlap) Right: Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170)

Legend Placement

CRITICAL: Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups).

Calculate where all boundaries end (y position + height)
Place legend at least 20px below the lowest boundary
Expand SVG viewBox height if needed to accommodate

Example:

Wrong: Legend at y=470 inside a cluster boundary that ends at y=490 Right: Legend at y=510, below the cluster boundary, with viewBox height extended

Layout Structure

Header - Title with pulsing dot indicator, subtitle, and export toolbar
Main SVG diagram - Contained in rounded border card
Summary cards - Grid of 3 cards below diagram with key details
Footer - Minimal metadata line

Every diagram ships with a single unobtrusive ⋯ toggle in the header. Click it to reveal three buttons — 📋 Copy (high-DPI PNG to clipboard, scale: 2), 🖼️ PNG (high-DPI PNG download), 📄 PDF (PNG embedded in a one-page PDF via jsPDF). The toolbar collapses back to the icon by default so it doesn't clutter the diagram. All three formats use the same html2canvas capture (with the toolbar excluded and 32px padding around the content), so PDF preserves the dark theme without going through the browser's print dialog.

When generating a new diagram, keep these intact in the template:

The two CDN scripts in <head> (pinned versions, with Subresource Integrity hashes and crossorigin="anonymous"):
- https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js — integrity="sha384-ZZ1pncU3bQe8y31yfZdMFdSpttDoPmOZg2wguVK9almUodir1PghgT0eY7Mrty8H"
- https://cdn.jsdelivr.net/npm/jspdf@2.5.2/dist/jspdf.umd.min.js — integrity="sha384-en/ztfPSRkGfME4KIm05joYXynqzUgbsG5nMrj/xEFAHXkeZfO3yMK8QQ+mP7p1/"
- SRI ensures generated diagrams are tamper-resistant against CDN compromise. Do not modify the hashes; if the version is bumped, the new hash must be computed fresh.
id="report-container" on the outermost .container div (this is what gets captured)
.toolbar markup with .toolbar-actions (collapsed by default) and .toolbar-toggle (the ⋯ button)
.toolbar CSS + @media print { .toolbar { display: none !important; } }
copyAsImage(), downloadPNG(), and downloadPDF() script before </body>, all using getBoundingClientRect() + html2canvas(document.body, { x, y, width, height, ignoreElements }) to capture a precise rect with breathing room and no toolbar

Caveats: clipboard API needs a user gesture and a secure context (https/file/localhost). SVG <foreignObject> renders inconsistently in html2canvas — stick to plain <svg> shapes and <text>. Bump scale: 2 to 3 or 4 for higher-res output.

Component Box Pattern

Info Card Pattern

Template

Copy and customize the template at resources/template.html. Key customization points:

Update the <title> and header text
Modify SVG viewBox dimensions if needed (default: 1000 x 680)
Add/remove/reposition component boxes
Draw connection arrows between components
Update the three summary cards
Update footer metadata

Output

Always produce a single self-contained .html file with:

Embedded CSS (no external stylesheets except Google Fonts)
Inline SVG (no external images)
No JavaScript required (pure CSS animations)

The file should render correctly when opened directly in any modern browser. The export toolbar uses two CDN scripts (html2canvas and jsPDF) — no other JavaScript dependencies.