diagrams

📁 tychohq/agent-skills 📅 2 days ago

总安装量

周安装量

#51918

全站排名

安装命令

npx skills add https://github.com/tychohq/agent-skills --skill diagrams

Agent 安装分布

mcpjam 3

claude-code 3

replit 3

junie 3

windsurf 3

zencoder 3

Skill 文档

Diagrams

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

Quick Start

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

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

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

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

Property	Type	Description
`id`	string	Required. Unique identifier
`width`	number	Node width in px (default 120)
`height`	number	Node height in px (default 40)
`labels`	array	`[{text}]` â used by ELK for layout calculation
`label`	string	Display text rendered in SVG (supports emoji). Falls back to `id`
`color`	string	Color key from palette (see below)
`subtitle`	string	Smaller text below the label
`fontSize`	number	Label font size (default 13)
`children`	array	Nested nodes â makes this a container
`containerColor`	string	Color key for container background

Edge Properties

Property	Type	Description
`id`	string	Required. Unique identifier
`sources`	string[]	Source node id(s)
`targets`	string[]	Target node id(s)
`labels`	array	`[{text, width, height}]` â edge labels
`edgeColor`	string	Hex color (default `#64748B`)
`dashed`	boolean	Dashed line style
`strokeWidth`	number	Line thickness (default 1.5)

Color Palette

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

Key	Color	Meaning	Use For
`action`	ðµ Blue	System action	Steps the app performs â API calls, DB writes, cron triggers
`external`	ð¢ Teal	External service	Third-party APIs â Google, Twilio, Stripe, Resend
`decision`	ð©· Pink	Decision point	Yes/no branches, if/else, conditional checks
`user`	ð Orange	User action	Things the user does â clicks, inputs, reviews
`success`	ð¢ Green	Positive outcome	Done, confirmed, created, visible
`negative`	ð´ Red	Negative outcome	Canceled, error, failed, not built
`neutral`	â« Gray	Neutral / info	Starting points, labels, inactive, informational
`data`	ð¡ Amber	Data / artifact	Records, drafts, outputs, intermediate data

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.

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台