Svg Diagram

SVG Diagram Skill — Production-Grade Handbook

Read this entire file before drawing any diagram. Then consult references/ for detailed specs and complete examples.

Step 1: Diagram Type Decision

Determine the diagram type first, then choose the technical approach.

Mandatory split rules (exceed these limits → split into multiple diagrams):

• Sequence participants > 6 → split into "overview + sub-flow"
• Horizontal flow nodes > 5 → switch to vertical or split
• Structure nesting > 3 levels → split into "system-level + component-level"
• Flows with loops → never draw circular, use HTML stepper (see references/interactive.md)

Step 2: Canvas & Coordinate System

viewBox="0 0 680 {H}"    ← 680 is a hard constant, never change it
width="100%"
role="img"               ← required for accessibility

How to calculate H (execute in order):

1. Complete coordinate calculations for all elements first
2. Find max_y = largest (y + height) across all elements
3. H = max_y + 40
4. Never estimate, never "start with 600 and adjust"

Safe zone: x ∈ [40, 640], y ∈ [40, H-40]

SVG root element skeleton:

<svg width="100%" viewBox="0 0 680 {H}" role="img"
  xmlns="http://www.w3.org/2000/svg">
  <title>Diagram title</title>
  <desc>One-line description for screen readers</desc>
  <defs>
    <style>
      <!-- Copy full style block from references/embedded-styles.md -->
      <!-- Keep only the c-* classes actually used in this diagram -->
      <!-- Keep corresponding dark-mode @media overrides for used c-* classes -->
    </style>
    <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="context-stroke"
        stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
    </marker>
  </defs>
  <!-- Content -->
</svg>

Critical: Both xmlns and <style> are mandatory. The style block must include CSS variables (--b, --bg2, --s), text classes (.t/.ts/.th), and only the c-* color classes used in the diagram with their dark-mode overrides. Copy the complete template from references/embedded-styles.md.

context-stroke makes arrowheads auto-inherit line color. Never use any other method to define arrowhead color.

Step 3: Color System

Color Class Reference

Color Usage Rules

Must follow:

• Same-type nodes use the same color (group by semantic role, not by sequence)
• Title text uses 800 shade, subtitle text uses 600 shade — never identical (loses hierarchy)
• c-* only on <g>, <rect>, <polygon>, <circle>, or <ellipse> — never on <path>
• c-* uses direct-child selectors; nesting <g> tags breaks styling — avoid deep nesting

Dark mode rules (what separates production from toy):

• All text colors must use CSS variables or c-* class auto-inversion
• Never hardcode hex on text (invisible in dark mode)
• Line colors may use hardcoded hex (mid-tone values readable in both modes, e.g. #1D9E75)
• Only exception: physical-scene diagrams (fire, sky, real-world colors) may hardcode everything, but must provide @media (prefers-color-scheme: dark) variants
• Mixing trap: hardcoded background + c-* foreground = only half-inverts in dark mode. Never mix.

Step 4: Precise Character Widths

Measured widths at 14px Anthropic Sans (used for calculating rect minimum width):

Rect minimum width formula:

rect_min_width = max(title_width, subtitle_width) + 48
                                               ↑ 24px padding on each side

12px subtitle text width = 14px estimate × 0.86

Verification steps (do before every rect):

1. Find the longest text string in that rect
2. Estimate rendered width by type
3. Add 48px for minimum width
4. If planned rect width < minimum width, widen the rect or shorten the text

Step 5: Per-Type Specifications

Each type below lists the core rules. For detailed coordinate tables, complete specs, and full examples, read the corresponding reference file before drawing.

Sequence Diagram

Read references/sequence.md before drawing any sequence diagram.

X-coordinate allocation (by participant count):

Participant box height fixed at 40px, rx=6.

Lifeline:

<line x1="{cx}" y1="60" x2="{cx}" y2="{H-60}"
  stroke="var(--b)" stroke-width="0.5" stroke-dasharray="4 3"/>

Message arrows (solid = active call, dashed = return/async):

<!-- Active call -->
<line x1="{from_cx}" y1="{y}" x2="{to_cx}" y2="{y}"
  stroke="{color}" stroke-width="1.5" marker-end="url(#arrow)"/>

<!-- Return / response -->
<line x1="{from_cx}" y1="{y}" x2="{to_cx}" y2="{y}"
  stroke="#888780" stroke-width="1" stroke-dasharray="5 3"
  marker-end="url(#arrow)"/>

Message label placed 8px above the arrow: y="{arrow_y - 8}"

Phase group background:

<rect x="28" y="{group_y}" width="630" height="{group_h}"
  rx="4" fill="var(--bg2)" opacity="0.5"/>
<text class="ts" x="36" y="{group_y + 16}" fill="var(--s)">① Phase name</text>

Spacing rules and group height:

• Adjacent arrows: ≥ 32px; between groups: +20px extra
• group_h = (n_msgs + 1) × 32 + 16
• For pre-computed Y-coordinate lookup tables (single-group and two-group scenarios), see references/sequence.md

Flowchart

Read references/flowchart.md before drawing any flowchart.

Layout direction — decide before drawing:

• Horizontal (compact): ≤ 4 nodes, linear flow (no branches), short labels (title only, no subtitle). Produces a short, wide diagram — ideal for simple sequential flows.
• Vertical (spacious): > 4 nodes, has decision branches, needs subtitles, or complex routing. Produces a tall diagram — necessary for branching logic.

Standard node sizes:

• Single-line node: height 44px
• Two-line node (title + subtitle): height 56px
• Decision diamond: <polygon>, width ~120px, height ~60px

Two-line node text positioning:

<text class="th" x="{cx}" y="{rect_y + 19}"
  text-anchor="middle" dominant-baseline="central">Title</text>
<text class="ts" x="{cx}" y="{rect_y + 38}"
  text-anchor="middle" dominant-baseline="central">Subtitle</text>

Horizontal layout width calculation:

gap = 40 (minimum — 10px exit + 20px visible shaft + 10px entry)
total = sum(node_w) + (n-1) × gap, must satisfy total ≤ 600
node_w = max(title_width + 48, 90)  per node — variable width
start_x = (680 - total) / 2

Vertical arrow endpoints (leave 10px gap):

Upper node exit: y1 = rect_y + rect_h + 10
Lower node entry: y2 = rect_y - 10

Backward / return edge (L-shaped):

<path d="M {x1} {y1} L {x_detour} {y1} L {x_detour} {y2} L {x2} {y2}"
  fill="none" stroke="#E24B4A" stroke-width="1"
  stroke-dasharray="5 3" marker-end="url(#arrow)"/>

Decision diamonds: Exit points are the left/right corners. Downstream boxes center-align to exit corners, NOT to diamond center. Non-overlap constraint: box_right_x ≥ box_left_x + box_w + 20. For full branching layout, arrow routing templates, and common mistakes, see references/flowchart.md.

Error path collection: When multiple diamonds share the same error endpoint, use a vertical collector line on the right side. All error branches connect horizontally to it (no arrowheads), collector feeds into error box. For complete XML templates and layout rules, see references/flowchart.md.

Structure Diagram

Nested levels must use different color classes:

• Outer level: lighter color (e.g. c-blue)
• Inner level: contrasting color (e.g. c-teal, c-amber)
• Same-color nesting destroys hierarchy — hard production rule

Container padding: Outer ≥ 24px, inner spacing ≥ 16px, label to edge ≥ 12px.

See references/structure.md for nesting rules and complete example.

Illustrative Diagram (abstract concepts)

Use when explaining how something works, showing data structures, or presenting spatial relationships.

Core principle: Draw the mechanism itself, not a "diagram about the mechanism." Color represents intensity, not category (warm = active, cool = static).

See references/illustrative.md for detailed specs and examples.

Step 6: Complete Dark Mode Rules

This is the biggest difference between production-grade and toy output.

Safe usage (auto-adapts to dark mode):

<!-- c-* classes: auto-handle light & dark -->
<g class="c-blue">
  <rect .../>
  <text class="th">Label</text>  <!-- auto-correct color -->
</g>

<!-- CSS variables: auto-adapt -->
<line stroke="var(--b)" .../>
<rect fill="var(--bg2)" .../>

Dangerous usage (breaks in dark mode):

<!-- Forbidden: hardcoded hex on text -->
<text fill="#333333">Label</text>  <!-- invisible on dark background -->

<!-- Forbidden: c-* background + hardcoded text -->
<g class="c-blue">
  <rect .../>
  <text fill="#333">Label</text>  <!-- bg inverts, text doesn't -->
</g>

Safe hex values for line colors (mid-tone, readable in both modes):

#1D9E75  teal 400
#534AB7  purple 400 (for purple-semantic lines)
#185FA5  blue 600
#BA7517  amber 400
#993C1D  coral 600
#888780  gray 400 (general neutral lines)
#E24B4A  red 400 (error/fallback paths)

Line color rule — match source node's semantic color: Connecting lines (arrows) must use the same color family as the source node (where the arrow starts), not the target. This creates a visual "information flows from" signal. Use the safe hex value corresponding to the source node's c-* class:

• Source is c-teal → line stroke #1D9E75
• Source is c-purple → line stroke #534AB7
• Source is c-blue → line stroke #185FA5
• Source is c-amber → line stroke #BA7517
• Source is c-coral → line stroke #993C1D
• Source is c-green → line stroke #3B6D11
• Source is c-gray or neutral → line stroke #888780
• Error/fallback paths → line stroke #E24B4A

Exception: return/response lines always use #888780 (gray) regardless of source color.

Step 7: Line Crossing Prevention

Before drawing every line, perform these checks:

Checklist:

1. List all rect bounding boxes: {x, y, x+w, y+h}
2. Compare line path X, Y ranges against each box
3. If line X range overlaps a rect X range, AND Y range overlaps → crossing detected

Mitigation options:

<!-- Option A: L-shaped detour around right side -->
<path d="M {x1} {y1} L {x1} {y_bypass} L {x2} {y_bypass} L {x2} {y2}"
  fill="none" stroke="..." marker-end="url(#arrow)"/>

<!-- Option B: detour around left side -->
<path d="M {x1} {y1} L {x_left-20} {y1} L {x_left-20} {y2} L {x2} {y2}"
  fill="none" stroke="..." marker-end="url(#arrow)"/>

<!-- Option C: symbolic cross-reference (when routing is too complex) -->
<!-- Place matching letter markers at source and target -->
<text class="ts" x="{x}" y="{y}">→ A</text>

Sequence diagram special rule: Messages are strictly horizontal, never diagonal. If two participants aren't adjacent, the message is still horizontal, just spanning farther.

Step 8: Post-Draw Checklist (7 items, covering the most common failures)

Check in order — don't skip:

• Root <svg> has xmlns="http://www.w3.org/2000/svg"; <defs> contains <style> block (including dark-mode @media)
• viewBox H = max(element y + height) + 40 — computed, not estimated
• All <text> has a class (th/ts/t); text inside nodes has dominant-baseline="central"
• All <path> lines have fill="none"
• Single <svg> element per diagram, with role="img" + <title> + <desc>
• Node position overlap check: for every pair of shape elements (rect, polygon, circle, ellipse), verify bounding boxes do not overlap. Compare {x, x+w} and {y, y+h} ranges — if both X and Y ranges overlap, the nodes collide and one must be repositioned. Pay special attention to decision diamonds: their bounding box is wider than it appears (cx ± half_w), and adjacent rects must start after cx + half_w.
• Line connectivity check: every <line> and <path> must connect to a valid target element (a rect, circle, or another line endpoint). No line should point into empty space. For error/fallback paths from decision diamonds, verify the error line reaches an error box or a collector line that leads to one.

Other rules (text not overflowing rects, line colors using safe hex, lines not crossing nodes) are naturally enforced during drawing and don't need a separate post-check.

Reference File Index

PNG Export

After saving the SVG, convert to @2x PNG for sharing on platforms that don't render SVG:

node {skillDir}/scripts/svg2png.mjs <svg-path> [options]

Options:

• -s, --scale <n> — Scale factor (default: 2)
• -o, --output <path> — Custom output path

Prerequisites: run cd {skillDir}/scripts && npm install once to install sharp.

Output Instructions

1. SVG must be self-contained: embed <style> (copy from references/embedded-styles.md, keep only used c-* classes) + xmlns
2. If visualize:show_widget is available, pass the full SVG code; otherwise write to .svg file and use open command to view in browser
3. HTML interactive diagrams: pass the complete HTML fragment (no DOCTYPE/html/body tags)
4. Add text context before and after the diagram to explain what it shows