Diagrams

Diagrams

Generate diagrams from structured JSON → SVG (and optionally PNG).

Quick Start

1. Install elkjs in the target directory (if not already present):

   cd <project>/docs/diagrams && npm init -y && npm install elkjs
   # Set "type": "module" in package.json
   

2. Write ELK JSON files describing the diagram (see schema below)

3. Render:

   # Single file
   node <skill-dir>/scripts/render-elk.mjs diagram.json output.svg
   
   # Batch: all .json files in a folder → svg/ subfolder
   node <skill-dir>/scripts/render-elk.mjs --dir <folder>
   
   # Batch + PNG (macOS only, uses sips)
   node <skill-dir>/scripts/render-elk.mjs --dir <folder> --png
   

4. Embed in markdown:

   ![Diagram Title](diagrams/svg/my-diagram.svg)
   

ELK JSON Schema

{
  "id": "root",
  "title": "Diagram Title (rendered as heading)",
  "layoutOptions": {
    "elk.algorithm": "layered",
    "elk.direction": "DOWN",
    "elk.spacing.nodeNode": "30",
    "elk.layered.spacing.nodeNodeBetweenLayers": "40",
    "elk.padding": "[top=40,left=20,bottom=20,right=20]"
  },
  "children": [
    {
      "id": "node1",
      "width": 220,
      "height": 45,
      "labels": [{"text": "Node label for ELK layout"}],
      "label": "📦 Display label (rendered in SVG)",
      "color": "core",
      "subtitle": "Optional second line"
    }
  ],
  "edges": [
    {
      "id": "e1",
      "sources": ["node1"],
      "targets": ["node2"],
      "labels": [{"text": "Yes", "width": 25, "height": 14}],
      "edgeColor": "#10B981",
      "dashed": true
    }
  ]
}

Node Properties

Edge Properties

Color Palette

8 semantic colors. Every node maps to one. A legend auto-renders at the bottom of each SVG.

Set "legend": false on the root graph to hide the auto-legend.

Layout Options

Common layoutOptions values:

• elk.direction: DOWN (default), RIGHT, LEFT, UP
• elk.algorithm: layered (default, best for flowcharts), force, stress
• elk.spacing.nodeNode: Space between sibling nodes (px)
• elk.layered.spacing.nodeNodeBetweenLayers: Space between layers (px)
• elk.padding: [top=N,left=N,bottom=N,right=N]

Design Tips

• Sizing: 200-280px wide for most nodes. 45px tall for single-line, 55px for two-line labels.
• Decision nodes: Use context (pink) color for yes/no branching.
• Edge labels: Keep short (Yes/No/Error). Set width/height for proper positioning.
• Containers: Add children array to a node. Use containerColor: "step" for a light blue group.
• Manual trips vs automated: Use dashed: true on edges for alternative/optional paths.
• Title: Set title on the root graph for a rendered heading above the diagram.
• Emoji in labels: Supported and encouraged for visual scanning.

Gotchas

• Container layout: ELK's layered algorithm with nested containers in RIGHT direction can produce overlapping layouts. Prefer DOWN for containers, or flatten to a non-container layout if horizontal.
• labels vs label: labels (array) is what ELK uses for layout spacing. label (string) is what gets rendered in the SVG. Always set both — labels[0].text should approximate the display label length for correct sizing.
• package.json must have "type": "module" for the ESM import to work.
• elkjs must be installed locally in the directory where you run the script. It's not global.