Figcraft Documentation

Code-driven professional SVG diagram library for TypeScript / Node.js.

Installation

npm install figcraft

Requires Node.js 18+. The library has no browser dependency — it runs entirely in Node.js.

Quick Start

Create a file diagram.ts and run it with npx tsx diagram.ts:

import { Figure } from 'figcraft'

const fig = new Figure(800, 400, { bg: '#fff' })

const a = fig.rect('Input', {
  pos: [50, 100], size: [120, 50],
  fill: '#e3f2fd', radius: 6
})

const b = fig.rect('Output', {
  pos: [250, 100], size: [120, 50],
  fill: '#c8e6c9', radius: 6
})

fig.arrow(a, b, { head: 'stealth', label: 'data' })

await fig.export('diagram.svg', { fit: true, margin: 20 })

Figure Constructor

new Figure(width?: number, height?: number, options?: FigureOptions)

FigureOptions

Font Registration

fig.font(name: string, source?: string)

Register fonts for use in diagrams:

// Local system font
fig.font('PingFang SC')

// Google Fonts
fig.font('Inter', 'google')

// Custom URL
fig.font('MyFont', 'https://example.com/font.woff2')

Elements Overview

Figcraft provides 10 element types. All are created through fig.<type>(label, config?).

2D Shapes

Rect

const box = fig.rect('Label', {
  pos: [50, 50], size: [120, 60],
  fill: '#e3f2fd', radius: 8,
  stroke: { color: '#1565c0', width: 2 }
})

Circle

const node = fig.circle('Node', {
  pos: [200, 100], r: 35,
  fill: '#fff3e0', color: '#e65100'
})

Diamond

const decision = fig.diamond('Yes?', {
  pos: [100, 100], size: [80, 60],
  fill: '#fce4ec'
})

Trapezoid

const pool = fig.trapezoid('MaxPool', {
  pos: [100, 100], size: [100, 50],
  fill: '#e8f5e9', topRatio: 0.55
})

Text

const label = fig.text('**Bold** and *italic*', {
  pos: [100, 50], fontSize: 14
})

Image

const img = fig.image('./photo.png', {
  pos: [100, 50], size: [120, 80]
})

3D Shapes

Cylinder

Great for databases and CNN feature maps. depth controls the ellipse ratio (0-1).

const db = fig.cylinder('Database', {
  pos: [50, 50], size: [100, 70],
  fill: '#e8f5e9', depth: 0.2
})

Cuboid

3D block for tensors and data volumes. depth is the extrusion distance in pixels.

const tensor = fig.cuboid('Feature Map', {
  pos: [50, 50], size: [80, 60],
  fill: '#fff8e1', depth: 18
})

Sphere

const node = fig.sphere('Attention', {
  pos: [100, 100], r: 35,
  fill: '#e0f7fa'
})

Stack

Multi-layer stacking effect. count sets layers, stackOffset controls offset per layer.

const layers = fig.stack('Conv ×4', {
  pos: [50, 50], size: [100, 60],
  fill: '#ede7f6', count: 4,
  stackOffset: [6, -6]
})

ElementConfig

All properties are optional. Apply to any element type.

Nesting (Containers)

Any element can contain child elements. Children are positioned relative to their parent:

const parent = fig.rect('Container', {
  pos: [50, 50], size: [200, 150]
})

// Children use percentage positioning relative to parent
parent.circle('Center', { pos: ['50%', '50%'], r: 20 })
parent.rect('TopLeft', { pos: [10, 30], size: [60, 30] })

Basic Arrow

fig.arrow(source, target, config?)

Connect two elements. Auto-snaps to nearest edges if no anchor is specified.

fig.arrow(a, b)  // simplest form
fig.arrow(a, b, { head: 'stealth', color: '#1565c0' })

Anchor Points

Control exactly where arrows connect to elements:

// Simple: specify a side
fig.arrow(a, b, { from: 'right', to: 'left' })

// Detailed: specify side + position along edge (0-100%)
fig.arrow(a, b, {
  from: { side: 'bottom', at: 30 },  // 30% from left on bottom edge
  to: { side: 'top', at: 70 }         // 70% from left on top edge
})

Arrow Head Types

11 built-in arrow head styles:

Path Types

// Curved arrow
fig.arrow(a, b, { path: 'curve', curve: 40 })

// Polyline with rounded corners
fig.arrow(a, b, { path: 'polyline', cornerRadius: 8 })

Styles & Labels

fig.arrow(a, b, {
  style: 'dashed',           // 'solid' | 'dashed' | 'dotted'
  color: '#e65100',
  width: 2,
  label: 'data flow',
  bidirectional: true,       // double-headed arrow
  headSize: 10
})

arrows() — Fan-out / Fan-in

Create multiple arrows at once. Supports 1-to-many and many-to-1:

// Fan-out: one source to many targets
fig.arrows(source, [targetA, targetB, targetC], {
  head: 'stealth', color: '#1565c0'
})

// Fan-in: many sources to one target
fig.arrows([srcA, srcB, srcC], target, {
  head: 'triangle', style: 'dashed'
})

fork() — Branching

Create a forking arrow with a shared main trunk that splits to multiple targets:

fig.fork(source, [targetA, targetB, targetC], {
  head: 'stealth',
  style: 'solid',
  color: '#333'
})

row()

Arrange elements horizontally. The first element must have pos set.

fig.row([a, b, c], { gap: 40 })  // default gap: 40px

col()

Arrange elements vertically.

fig.col([a, b, c], { gap: 30 })

grid()

Arrange elements in a grid.

fig.grid([a, b, c, d, e, f], {
  cols: 3,        // 3 columns (default)
  gap: 20,        // uniform gap
  rowGap: 30,     // override vertical gap
  colGap: 15      // override horizontal gap
})

group()

Draw a labeled frame around elements. Call after layout methods (needs resolved positions). Returns a Rect that can be used as an arrow target.

const frame = fig.group([a, b, c], {
  label: 'Pipeline',
  fill: 'rgba(25,118,210,0.05)',
  stroke: { color: '#90caf9', dash: [6, 3] },
  radius: 8,
  padding: 20,
  fontSize: 11,
  fontColor: '#1565c0',
  size: [400, 200]    // optional fixed size (auto-centers members)
})

Markdown in Labels

All element labels support inline markdown formatting:

fig.rect('**Conv2D** $3 \\times 3 \\times 64$', { ... })
fig.text('Loss: `cross_entropy`', { ... })

Export Formats

File format is auto-detected from the file extension:

// SVG
await fig.export('output.svg', { fit: true, margin: 20 })

// High-res PNG
await fig.export('output.png', { fit: true, scale: 3, margin: 30 })

// Get SVG string without saving
const svg = fig.render({ fit: true })

ExportOptions

Export Format Showcase

One source file, every format you need. Click the tabs below to compare outputs:

.svg

fig.export('flowchart.svg')

• Vector format — infinite scaling
• Smallest file size
• Full canvas size preserved

.png

fig.export('flowchart.png')

• Default 2x resolution
• White background
• Full canvas size

.jpg

fig.export('flowchart.jpg', {
  fit: true, margin: 20
})

• fit: true auto-crops to content
• 20px margin around content
• Quality: 90 (adjustable)

.png fit

fig.export('flowchart-fit.png', {
  fit: true, margin: 20
})

• fit: true crops to content bounds
• Removes excess whitespace
• Best for embedding in documents

.png transparent

// Omit bg = transparent background
const fig = new Figure(800, 350)
fig.export('out.png', { fit: true })

• Omit bg for transparency
• Checkerboard = alpha channel
• Great for overlaying on other content

.webp

fig.export('flowchart.webp', {
  fit: true, margin: 20
})

• Modern format, smaller size
• Supports transparency
• Ideal for web publishing

MCP Integration

Figcraft includes a built-in MCP (Model Context Protocol) server. AI agents like Claude Code and Cursor can generate diagrams directly without writing code.

Setup

Add to your Claude Code or Cursor MCP settings:

{
  "mcpServers": {
    "figcraft": {
      "command": "npx",
      "args": ["figcraft-mcp"]
    }
  }
}

Then just describe your diagram to the AI: "Draw a Transformer architecture diagram with encoder and decoder stacks".

MCP Tools

JSON Specification Format

The create_diagram tool accepts this JSON structure:

{
  "width": 800,
  "height": 400,
  "bg": "#ffffff",
  "fontFamily": "Arial",
  "autoAlign": true,
  "elements": [
    {
      "id": "a",
      "type": "rect",
      "label": "Input",
      "pos": [50, 100],
      "size": [120, 60],
      "fill": "#e3f2fd",
      "radius": 6
    },
    {
      "id": "b",
      "type": "rect",
      "label": "Output",
      "pos": [300, 100],
      "size": [120, 60],
      "fill": "#c8e6c9"
    }
  ],
  "arrows": [
    {
      "from": "a",
      "to": "b",
      "fromSide": "right",
      "toSide": "left",
      "label": "data",
      "head": "stealth"
    }
  ],
  "groups": [
    {
      "members": ["a", "b"],
      "label": "Pipeline",
      "padding": 20,
      "stroke": "#999"
    }
  ],
  "layouts": [
    { "type": "row", "elements": ["a", "b"], "gap": 40 }
  ],
  "fanArrows": [
    { "from": "src", "to": ["a", "b", "c"] }
  ],
  "forks": [
    { "from": "root", "to": ["x", "y", "z"] }
  ],
  "export": {
    "path": "output.svg",
    "fit": true,
    "margin": 20
  }
}

Figure Class — All Methods

ElementConfig — Full Reference

ArrowConfig — Full Reference

ExportOptions — Full Reference