SVG Diagram Generation Skill

You can generate rich, inline SVG diagrams to visually explain concepts. Use this skill whenever a visual would help the user understand a system, process, architecture, or mechanism better than text alone.

---

Delivery

Diagrams ship through the generateSandboxedUi tool: the SVG markup goes in the html parameter, where it streams to the user element by element. SVG presentation attributes (fill, stroke, font-size) carry all styling here — if a diagram needs CSS animation classes, declare them in the css parameter, never in a <style> block inside html. Static diagrams need no jsFunctions or jsExpressions.

---

When to Use

• Explaining how something works (load paths, circuits, pipelines, algorithms)
• Showing architecture or structure (system diagrams, component layouts)
• Illustrating processes or flows (flowcharts, data flow, decision trees)
• Building intuition for abstract concepts (attention mechanisms, gradient descent, recursion)

SVG Setup

Use this template as a starting point; add an accessible title/description:

<svg width="100%" viewBox="0 0 680 H" xmlns="http://www.w3.org/2000/svg">
  <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="context-stroke"
            stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
    </marker>
  </defs>
  <!-- Content here -->
</svg>

• 680px is a useful default coordinate width via viewBox. Set width="100%" so it scales responsively.
• H (height) = bottom-most element's y + height + 40px padding. Don't guess — compute it.
• Safe content area: x=40 to x=640, y=40 to y=(H-40).
• Body fragments only: no <html>, <head>, <body>, or DOCTYPE.
• Background is transparent — the host provides the background.

---

Core Design Rules

Typography

• Two sizes only: 14px for titles/labels, 12px for subtitles/descriptions.
• Two weights only: 400 (regular), 500 (medium/bold). Never use 600 or 700.
• Font: Use font-family="system-ui, -apple-system, sans-serif" or inherit from host.
• Always set text-anchor="middle" and dominant-baseline="central" for centered text in boxes.
• Sentence case always. Never Title Case or ALL CAPS.

Text Width Estimation

At 14px, each character ~ 8px wide. At 12px, each character ~ 7px wide.

• "Load Balancer" (13 chars) at 14px ~ 104px -> needs rect ~ 140px wide (with padding).
• Always compute: rect_width = max(title_chars x 8, subtitle_chars x 7) + 48px padding.

Colors (Light/Dark Mode Safe)

Use these semantic color sets that work in both modes:

Teal:    fill="#E1F5EE" stroke="#0F6E56" text="#085041"  (dark: fill="#085041" stroke="#5DCAA5" text="#9FE1CB")
Purple:  fill="#EEEDFE" stroke="#534AB7" text="#3C3489"  (dark: fill="#3C3489" stroke="#AFA9EC" text="#CECBF6")
Coral:   fill="#FAECE7" stroke="#993C1D" text="#712B13"  (dark: fill="#712B13" stroke="#F0997B" text="#F5C4B3")
Amber:   fill="#FAEEDA" stroke="#854F0B" text="#633806"  (dark: fill="#633806" stroke="#EF9F27" text="#FAC775")
Blue:    fill="#E6F1FB" stroke="#185FA5" text="#0C447C"  (dark: fill="#0C447C" stroke="#85B7EB" text="#B5D4F4")
Gray:    fill="#F1EFE8" stroke="#5F5E5A" text="#444441"  (dark: fill="#444441" stroke="#B4B2A9" text="#D3D1C7")
Red:     fill="#FCEBEB" stroke="#A32D2D" text="#791F1F"  (dark: fill="#791F1F" stroke="#F09595" text="#F7C1C1")
Green:   fill="#EAF3DE" stroke="#3B6D11" text="#27500A"  (dark: fill="#27500A" stroke="#97C459" text="#C0DD97")
Pink:    fill="#FBEAF0" stroke="#993556" text="#72243E"  (dark: fill="#72243E" stroke="#ED93B1" text="#F4C0D1")

Color meaning, not sequence: Don't rainbow-cycle. Use 2-3 colors per diagram. Map colors to categories or physical properties (warm = heat/energy, cool = calm/cold, gray = structural/neutral).

If you're rendering inside a system that supports CSS variables, prefer:

• var(--color-text-primary) for primary text
• var(--color-text-secondary) for muted text
• var(--color-border-tertiary) for light borders

Shapes & Layout

• Stroke width: 0.5px for borders, 1.5px for arrows/connectors.
• Corner radius: rx="4" for subtle rounding, rx="8" for emphasized. rx="20" for large containers.
• Spacing: 60px minimum between boxes, 24px padding inside boxes, 12px text-to-edge clearance.
• Single-line box: 44px tall. Two-line box: 56px tall.
• Max 4-5 nodes per row at 680px width. If more, split into multiple diagrams.
• All connectors need fill="none" — SVG defaults fill to black, which turns paths into black blobs.

---

Component Patterns

Single-Line Node

<g>
  <rect x="100" y="20" width="180" height="44" rx="8"
        fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/>
  <text x="190" y="42" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#3C3489">Node title</text>
</g>

Two-Line Node

<g>
  <rect x="100" y="20" width="200" height="56" rx="8"
        fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"/>
  <text x="200" y="38" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#0C447C">Title</text>
  <text x="200" y="56" text-anchor="middle" dominant-baseline="central"
        font-size="12" fill="#185FA5">Short subtitle</text>
</g>

Arrow Connector

<line x1="200" y1="76" x2="200" y2="120"
      stroke="#534AB7" stroke-width="1.5" marker-end="url(#arrow)"/>

Dashed Flow Indicator

<line x1="200" y1="76" x2="200" y2="120"
      stroke="#534AB7" stroke-width="1.5" stroke-dasharray="4 3"/>

Leader Line with Label (for annotations)

<line x1="440" y1="100" x2="500" y2="130"
      stroke="currentColor" stroke-width="0.5" stroke-dasharray="4 4" opacity="0.5"/>
<circle cx="440" cy="100" r="2" fill="currentColor" opacity="0.5"/>
<text x="506" y="134" font-size="12" fill="currentColor" opacity="0.7">Annotation text</text>

Large Container (for structural diagrams)

<rect x="80" y="40" width="520" height="300" rx="20"
      fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"/>
<text x="340" y="68" text-anchor="middle"
      font-size="14" font-weight="500" fill="#085041">Container name</text>

---

Diagram Types & When to Use Each

1. Flowchart

When: Sequential processes, decision trees, pipelines. Layout: Top-to-bottom or left-to-right. Single direction only. Rules:

• Arrows must never cross unrelated boxes. Route around with L-bends if needed.
• Keep all same-type boxes the same height.
• Max 4-5 nodes per diagram. Break complex flows into multiple diagrams.

2. Structural Diagram

When: Containment matters — things inside other things (architecture, org charts, system components). Layout: Nested rectangles. Outer = container, inner = regions. Rules:

• Max 2-3 nesting levels.
• 20px minimum padding inside every container.
• Use different color ramps for parent vs child to show hierarchy.

3. Illustrative Diagram

When: Building intuition. "How does X actually work?" Layout: Freeform — follows the subject's natural geometry. Rules:

• Shapes can be freeform (paths, ellipses, polygons), not just rects.
• Color encodes intensity, not category (warm = active, cool = dormant).
• Overlap shapes for depth, but never let strokes cross text.
• Labels go in margins with leader lines pointing to the relevant part.

---

Critical Checks Before Finalizing

1. ViewBox height: Find your lowest element (max y + height). Set H = that + 40px.
2. No content past x=640 or below y=(H-40).
3. Text fits in boxes: (char_count x 8) + 48 < rect_width for 14px text.
4. No arrows through boxes: Trace every line's path — if it crosses a rect, reroute.
5. All <path> connectors have fill="none".
6. All text has appropriate fill color — never rely on inheritance (SVG defaults to black).
7. Colors work in dark mode: If using hardcoded colors, provide both light and dark variants. If using CSS variables, you're fine.

---

Multi-Diagram Approach

For complex topics, use multiple smaller SVGs instead of one dense one:

• Each SVG should have 3-5 nodes max.
• Write explanatory text between diagrams.
• First diagram = overview, subsequent = zoom into subsections.
• Never promise diagrams you don't deliver.

---

Example: Simple 3-Step Flow

<svg width="100%" viewBox="0 0 680 288" xmlns="http://www.w3.org/2000/svg">
  <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="context-stroke"
            stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
    </marker>
  </defs>

  <!-- Step 1 -->
  <rect x="230" y="20" width="220" height="56" rx="8"
        fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"/>
  <text x="340" y="38" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#085041">User request</text>
  <text x="340" y="56" text-anchor="middle" dominant-baseline="central"
        font-size="12" fill="#0F6E56">HTTP POST /api/data</text>

  <!-- Arrow 1->2 -->
  <line x1="340" y1="76" x2="340" y2="100" stroke="#534AB7"
        stroke-width="1.5" marker-end="url(#arrow)"/>

  <!-- Step 2 -->
  <rect x="230" y="106" width="220" height="56" rx="8"
        fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/>
  <text x="340" y="124" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#3C3489">Server processing</text>
  <text x="340" y="142" text-anchor="middle" dominant-baseline="central"
        font-size="12" fill="#534AB7">Validate and transform</text>

  <!-- Arrow 2->3 -->
  <line x1="340" y1="162" x2="340" y2="186" stroke="#854F0B"
        stroke-width="1.5" marker-end="url(#arrow)"/>

  <!-- Step 3 -->
  <rect x="230" y="192" width="220" height="56" rx="8"
        fill="#FAEEDA" stroke="#854F0B" stroke-width="0.5"/>
  <text x="340" y="210" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#633806">Database write</text>
  <text x="340" y="228" text-anchor="middle" dominant-baseline="central"
        font-size="12" fill="#854F0B">INSERT into table</text>
</svg>

---

Tips for Great Diagrams

• Less is more: A clean 4-node diagram teaches better than a cramped 12-node one.
• Color = meaning: Warm colors for active/hot/important, cool for passive/cold/secondary, gray for structural.
• Streaming effect: Since SVGs render top-to-bottom as tokens arrive, structure your elements top-down for a natural build-up animation.
• Annotations on the side: Put explanatory labels in the right margin (x > 560) with leader lines pointing to the relevant element.
• Consistent heights: All boxes of the same type should be the same height.
• Whitespace is your friend: Don't fill every pixel. Breathing room makes diagrams readable.

Task and accessibility checks

Use a diagram when it improves understanding; plain text and native components are also valid answers. No mandatory planning or narration sequence is required. Use headings and concise explanations inside multi-section answers when useful. Provide an SVG title/description or adjacent textual equivalent. Keep text readable at narrow widths; simplify or reflow dense diagrams instead of shrinking labels. Do not invent data. Label illustrative quantities and show units and sources. Use keyboard-operable HTML controls for interactions, and honor reduced motion.