Svg Diagram

SVG Diagram Generator

Generate clean, professional technical diagrams as SVG files with an accompanying HTML page for PNG export.

Core Philosophy

1. Pure SVG -- No external dependencies. One .svg file that opens anywhere.
2. Crisp text -- SVG text renders sharply at any resolution, unlike rasterized alternatives.
3. Export-ready -- Every diagram ships with an HTML wrapper for 1x and 2x PNG download.
4. Minimal footprint -- Two files: .svg and -export.html. No build tools.

---

Phase 1: Understand the Diagram

Before generating, determine what the user needs. If the request is vague, ask via AskUserQuestion.

If the user provides a screenshot or detailed description, skip questions and generate directly. Use your judgment for layout, colors, and structure -- there are no prescribed patterns. Design each diagram to fit its content.

---

Phase 2: Generate the SVG

File naming

Use a descriptive kebab-case name based on the content (e.g. api-architecture.svg, deploy-pipeline.svg).

SVG structure

  
    text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; }
    /* Define reusable text classes */
  

  
  

  

---

What NOT To Do (Critical Anti-Patterns)

These are the SVG pitfalls that ruin diagrams. Avoid all of them.

DO NOT let text overlap

SVG has no auto-layout. Text elements placed at similar Y coordinates WILL collide. You must manually guarantee separation.

• Never place a title and description at the same Y coordinate. Use a two-row layout: title near the top of a box, description below it with a clear gap (40-50px minimum between baselines).
• Never assume text will fit. Before placing any text, estimate its pixel width: character_count x per_char_width. Common per-char widths:
• 13px font: ~7px/char
• 14px font: ~8.5px/char
• 16-17px font: ~9.5px/char
• 28px font: ~16px/char
• Never skip the bounding-box check. For every text element, confirm: estimated_text_width elements with dy spacing between them.
• Container width rule: width >= (longest_word_in_chars x per_char_width) + 16px padding at minimum.

DO NOT use external SVG references in the HTML export

Browsers block canvas.toDataURL() on images loaded from file:// URLs due to CORS. This silently breaks PNG export.

• Never use `` in the export HTML. Always inline the full SVG markup directly into the HTML page.

DO NOT forget text rendering basics

• Never omit text-anchor on centered text. Without text-anchor="middle", text positioned at a center X coordinate will be left-aligned from that point, not centered on it.
• **Never use a single ` element for multi-line content.** SVG is single-line only. Use elements with dy` attributes for line breaks.
• Never mix alignment modes at the same Y position. A left-aligned title and a center-aligned description at the same Y will collide when the description is long.

DO NOT create cluttered or cramped diagrams

• Never pack elements edge-to-edge. Leave minimum 30px padding from the canvas edge and 20-30px gaps between major elements.
• Never use too many colors. Pick a small, purposeful palette. Colors should encode meaning (grouping, status, hierarchy), not decorate.
• Never make the canvas too small for the content. Size the canvas to fit the content with breathing room. It's better to be slightly too large than to cram things.

DO NOT forget accessibility and structure

• Never create a diagram without ` and ` elements inside the SVG root. Screen readers need them.
• Never use color as the only differentiator. Pair color with labels, borders, or patterns so the diagram is readable without color.

DO NOT over-engineer the SVG

• Never add drop shadows, gradients, or filters unless they serve a purpose. They add complexity and slow rendering. Use flat design by default.
• Never define unused ``. Only add markers, filters, or patterns you actually reference.

---

Phase 3: Generate the HTML Export Wrapper

For every SVG, create a companion -export.html file. The SVG MUST be inlined directly (see anti-pattern above).

  {Diagram Title}
  
    body { margin: 40px; font-family: sans-serif; background: #f5f5f5; }
    button { padding: 12px 24px; font-size: 16px; cursor: pointer; background: #333; color: #fff; border: none; border-radius: 6px; margin-bottom: 20px; margin-right: 8px; }
    button:hover { background: #555; }
    .preview { max-width: 100%; border: 1px solid #ddd; border-radius: 8px; overflow: hidden; background: #fff; }
    .preview svg { display: block; width: 100%; height: auto; }
    canvas { display: none; }
  

  Download as PNG
  Download as PNG (2x)
  
  
    
    
      ...
    
  
  

  
    function downloadPNG(scale) {
      const svgEl = document.querySelector('#preview svg');
      const svgData = new XMLSerializer().serializeToString(svgEl);
      const blob = new Blob([svgData], { type: 'image/svg+xml;charset=utf-8' });
      const url = URL.createObjectURL(blob);

      const canvas = document.getElementById('canvas');
      const ctx = canvas.getContext('2d');
      const img = new Image();

      img.onload = function() {
        canvas.width = img.naturalWidth * scale;
        canvas.height = img.naturalHeight * scale;
        ctx.fillStyle = '#ffffff';
        ctx.fillRect(0, 0, canvas.width, canvas.height);
        ctx.drawImage(img, 0, 0, canvas.width, canvas.height);

        const link = document.createElement('a');
        link.download = '{name}.png';
        link.href = canvas.toDataURL('image/png');
        link.click();

        URL.revokeObjectURL(url);
      };

      img.src = url;
    }
  

Replace {name} with the actual diagram name.

---

Phase 4: Deliver

1. Write both files to the user's working directory
2. Open the HTML file in the browser: open -export.html
3. Summarize what was created and offer to adjust

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tielur
• Source: tielur/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.