svg

What this skill does

# 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](references/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](references/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:

```bash
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:

```xml
<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