svg

SVG Diagram Skill

Generate professional, whitepaper-quality diagrams as raw SVG. Each diagram should look distinct -- the right visual form for the content, not a templated layout.

When to use SVG over other formats:

• User wants maximum visual quality and custom design
• Diagram type lacks native support in Mermaid/D2 (threat models, comparisons, Venn, hub-spoke)
• Pixel-precise positioning is needed
• Output must render in any browser without JS dependencies
• User explicitly requests SVG

When another format may be better:

• Quick documentation diagrams that will live in GitHub markdown (Mermaid)
• Informal whiteboard-style sketches (Excalidraw)
• Architecture diagrams where auto-layout is preferred over manual positioning (D2)

Consult the design-system skill for color, typography, composition, and quality rules that apply across all formats.

Workflow

1. Understand Intent

Before generating anything, establish:

• What story does the diagram tell? The answer determines the diagram type.
• Who is the audience? (executives, engineers, customers, mixed)
• What are the key relationships? (hierarchy, sequence, data flow, comparison, threat surface)
• Are there source documents? Read them -- extract real terminology and structure.

2. Choose the Right Diagram Type

This is the most important decision. Do not default to a layered architecture stack. Each content type has a natural visual form:

Content	Best Diagram Type	Why
System components and layers	Layered architecture	Shows hierarchy and containment
Request/response lifecycle	Sequence diagram	Shows temporal ordering between actors
Data or process pipeline	Flow diagram (LTR or TTB)	Shows transformation steps
Attack surface / threat model	Threat flow with trust boundaries	Shows where controls intersect threats
Before/after or option comparison	Side-by-side comparison	Shows contrast
Central service with consumers	Hub and spoke	Shows radial relationships
Capability x category mapping	Matrix / grid	Shows coverage
State transitions	State machine	Shows conditions and transitions
Timeline with milestones	Roadmap / timeline	Shows progression
Org/team responsibility	Swimlane diagram	Shows who does what
Token/identity merging	Composition diagram	Shows inputs converging to output
Decision logic	Decision tree / flowchart	Shows branching paths
Set overlaps	Venn diagram	Shows shared/unique characteristics

If the content could work as multiple types, choose the one that best highlights the primary relationship the reader needs to understand. When in doubt, ask the user.

Consult layout-patterns.md for structural guidance and SVG construction patterns for each type.

3. Generate the SVG

Build the SVG using the component library in svg-design-system.md. Read the "Common SVG Mistakes" section first -- it lists the most frequent errors. Core principles:

• Always use <defs> for gradients, shadows, markers -- define once, reference everywhere
• System fonts -- -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif
• Depth through gradients and shadows -- not flat fills
• Generous whitespace -- padding is a design element
• Visual hierarchy through size, color weight, and elevation (shadows)

Beyond these fundamentals, adapt the visual treatment to the diagram type:

• A sequence diagram needs lifelines, activation bars, and message arrows -- not rounded boxes with bullet points
• A threat model needs trust boundaries (dashed regions), threat actors, and control points -- not a platform container
• A timeline needs a horizontal axis with markers -- not stacked layers
• A state machine needs circles/rounded-rects for states and labeled transitions

The design system references are a toolkit of components, not a template. Select the right components for the diagram type.

4. Validate

After writing the SVG file, run the validation script to check for layout issues:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-svg.py <file.svg>

The validator checks for:

• OVERLAP: Arrow lines passing through unrelated boxes
• PARALLEL: Parallel arrows closer than 30px (visually merge)
• LABEL-LINE: Labels overlapping arrow lines
• LABEL-BOX: Labels overlapping unrelated boxes
• PADDING: Container boundaries clipping enclosed elements

Exit codes: 0 = clean, 1 = issues found, 2 = parse error.

How to interpret results:

• OVERLAP and PARALLEL are the most critical -- these are structural defects that must be fixed by rerouting arrows or adding separation
• LABEL-LINE usually means a label needs to be repositioned (offset 8-12px from the line)
• LABEL-BOX can be false positives for labels intentionally inside boxes (the validator does not know which labels belong to which boxes by default) -- focus on cases where a label from one element overlaps a different element's box
• PADDING means a dashed container boundary is too tight around an enclosed element -- expand the container or shrink the element

Fix any OVERLAP or PARALLEL issues before presenting to the user. LABEL and PADDING issues are worth fixing but are lower priority.

5. Iterate

Present the SVG and ask for feedback. Common refinements: information density, visual emphasis, terminology alignment, color palette, annotations.

SVG Document Structure

Every generated SVG follows this structure:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}"
     font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
     role="img" aria-labelledby="diagramTitle diagramDesc">
  <title id="diagramTitle">{Concise diagram title}</title>
  <desc id="diagramDesc">{1-2 sentence description}</desc>
  <defs>
    <!-- Gradients, shadows, markers, patterns -->
  </defs>
  <rect width="{width}" height="{height}" fill="#FAFBFC"/>
  <!-- Content groups, ordered back-to-front -->
</svg>

Required Accessibility Elements

• role="img" on the root <svg> element
• <title> with a concise diagram name
• <desc> with a 1-2 sentence description
• aria-labelledby="diagramTitle diagramDesc"

Canvas Sizes

Diagram Type	Recommended viewBox
Architecture	0 0 1400 1000
Sequence	0 0 1400 800 to 0 0 1600 900
Flow	0 0 1400 600 to 0 0 1600 800
Threat model	0 0 1400 900
Timeline	0 0 1500 600 to 0 0 1500 700
State machine	0 0 1200 800
Comparison	0 0 1400 700
Compact/embed	0 0 1000 600

SVG-Specific Rules

Common Mistakes to Avoid

1. DO NOT use CSS style attribute on <svg> -- use SVG attributes directly. CSS background does not work when SVG is used as <img> source.
2. DO NOT use rgba() in fill/stroke -- use fill="white" fill-opacity="0.18" instead.
3. DO NOT make diagonal gradients unless intentional -- use x1="0%" y1="0%" x2="0%" y2="100%" for top-to-bottom.
4. DO NOT use V-shaped arrowheads (open chevrons) -- use filled triangles: M0,0 L12,4 L0,8 L3,4 Z.
5. DO NOT use text-transform as SVG attribute -- it is CSS-only. Write the text in uppercase directly.
6. ALWAYS use background <rect> -- not CSS background. <rect width="{w}" height="{h}" fill="#FAFBFC"/> as first child after <defs>.

Arrow and Layout Clearance Rules

These rules prevent the most common SVG quality issues -- overlapping arrows, lines running through boxes, and labels colliding with elements.

Arrow routing -- NEVER route through unrelated boxes:

• Before drawing any arrow/line path, check whether it crosses through a box it is not connected to
• If a straight line would pass through an intermediate box, route AROUND it using L-shaped or Z-shaped paths with enough clearance
• Minimum clearance between an arrow path and any unrelated box edge: 20px

Parallel arrow separation:

• When multiple arrows run parallel (same direction, nearby coordinates), maintain minimum 30px separation between them
• If two L-shaped routes share a vertical or horizontal segment, offset them visually so they are clearly distinct paths, not a single thick line
• Label each parallel path clearly so the reader can trace individual connections

Arrow-to-label clearance:

• Arrow labels must not overlap the arrow line itself -- offset labels 8-12px perpendicular to the line
• Labels must not overlap any box they are not labeling -- check that label text bounds do not intersect nearby elements
• For vertical arrows, place labels to the left or right (not centered on the line where they become unreadable)

Box-to-box clearance:

• Minimum gap between boxes at the same level: 40px (enough for arrows to route between them)
• Minimum gap between a container boundary (trust boundary, group box) and its contained elements: 20px on all sides
• Dashed boundary indicators (like PCI DSS scope) must fully enclose their target with 15px+ padding on all sides -- never clip the edge of a box

Annotation and badge placement:

• Security control badges (shield icons, TLS/AUTH/WAF pills) should be placed ON the boundary line between zones, not floating in space
• Badges must not overlap arrow paths or box labels
• If a badge would collide with an arrow, move the badge along the boundary to a clear spot

Self-check before output: After constructing the SVG, mentally trace each arrow path and verify:

1. Does this line pass through any box it is not connected to? If yes, reroute.
2. Is this line visually distinguishable from nearby parallel lines? If no, add separation.
3. Does any label overlap a line, box, or other label? If yes, reposition.
4. Do all container/scope boundaries fully enclose their targets with padding? If no, expand.

Token Budget Awareness

SVG is token-expensive (~24x more tokens than Mermaid for equivalent diagrams). Manage this by:

• Reusing <defs> aggressively -- define gradients, shadows, markers once
• Using <use href="#id"> for repeated elements (icons, patterns)
• Keeping element count within complexity limits
• Preferring simple geometric shapes over complex paths where possible
• Using <symbol> for icon libraries rather than inline paths

Anti-Patterns

• Do not default to layered-architecture for everything -- choose the diagram type that fits the content
• Do not crowd text into boxes -- if it does not fit, the box is too small
• Do not reuse the same layout across different diagrams -- each should look distinct
• Do not add detail the user did not ask for -- match the requested abstraction level
• Do not skip the <defs> block -- inline styles waste tokens and break consistency

Additional Resources

• For SVG component toolkit (gradients, shadows, typography, icons, element patterns), see svg-design-system.md
• For structural patterns for 12+ diagram types with SVG construction guidance, see layout-patterns.md
• For reusable SVG <defs> block, see svg-components.svg