← Back to Diagram Maker

🎨 Privacy Diagram DSL (PDDSL) - Complete LLM Reference

Version: 4.0 | Purpose: A compact, token-efficient DSL for generating diagrams. Reduces token usage by ~90% compared to JSON. NEW in v4.0: Relative positioning (no math!), automatic export watermarks, and improved typography.

📚 Table of Contents
⚠️ CRITICAL RULES FOR LLMs - READ FIRST
  1. Always start file with %pddsl
  2. Define canvas size: %canvas WIDTHxHEIGHT #BACKGROUND
  3. One element per line
  4. Comments start with #
  5. Text content in double quotes: "Hello World"
  6. Coordinates are x,y (no spaces)
  7. Dimensions are WIDTHxHEIGHT (no spaces)
  8. ⚡ TEXT X = LEFT EDGE of text box, NOT center point!
  9. ⚡ Use f=#color for fill color, c=#color for stroke/border
🚨 MOST COMMON LLM MISTAKE - TEXT POSITIONING

LLMs naturally think "center at X=500" for centering. This is WRONG!

PDDSL uses LEFT-EDGE coordinates with textAlign: center for internal centering.

❌ WRONG (text goes off-screen to the right):

# Canvas is 1000px wide, want centered text
text title 500,30 900x40 "My Title" center  # X=500 means text STARTS at center!

✅ CORRECT (text properly centered):

# Canvas is 1000px wide, want centered text with 900px width
# X = (canvas_width - text_width) / 2 = (1000 - 900) / 2 = 50
text title 50,30 900x40 "My Title" center

📐 Formula for Centering Text:

X = (canvas_width - text_width) / 2

# Example: 1200px canvas, 800px text width
X = (1200 - 800) / 2 = 200
text t1 200,50 800x30 "Centered Text" center
🆕 v4.0: RELATIVE POSITIONING (Recommended!)

Instead of calculating coordinates manually, use relative positioning:

Relative Position Syntax:

Syntax Description Example
below:id Position directly below element rect box2 below:box1 200x50
below:id+20 Below with 20px gap text t2 below:header+20 200x30
right-of:id+30 Right of element with 30px gap rect sidebar right-of:main+30 150x200
above:id Above element text title above:content 200x30
left-of:id Left of element rect icon left-of:label 30x30
align-x:id Align X coordinate with element rect b align-x:a 200x100
align-y:id Align Y coordinate with element rect b align-y:a 200x100
center-x Center horizontally on canvas text title center-x 400x40
center-y Center vertically on canvas rect box center-y 200x100
center Center on both axes rect box center 200x100

✅ BEST PRACTICE: Use Relative Positioning!

# OLD WAY (error-prone, hard to maintain):
rect header 50,50 300x50 f=#3b82f6
rect content 50,120 300x200 f=#22c55e  # Had to calculate 50 + 50 + 20 = 120

# NEW WAY (easy, self-documenting):
rect header 50,50 300x50 f=#3b82f6
rect content below:header+20 300x200 f=#22c55e  # Just say "below header + 20px gap"
📏 TEXT WIDTH ESTIMATION

LLMs cannot visually measure text. Use these rules:

Font Size Approx Width per Character Example
fs=12 ~7px "Hello" (5 chars) ≈ 35px + 20px padding = 55px
fs=16 ~10px "Hello World" (11 chars) ≈ 110px + 20px = 130px
fs=24 ~14px "Title" (5 chars) ≈ 70px + 20px = 90px
fs=32 ~19px "$29.8B" (6 chars) ≈ 114px + 20px = 134px
fs=48 ~28px "BIG" (3 chars) ≈ 84px + 20px = 104px

Tip: Always add 20-40px padding to calculated width for safety.

📝 Complete Syntax Reference

File Structure

%pddsl                              # Version declaration (REQUIRED)
%canvas 800x600 #f5f5f5                 # Canvas: WxH background-color
%theme rough=1.5 sw=2                   # Optional global theme

# Comments start with hash
# Blank lines are ignored

# Elements follow...
rect myBox 100,100 200x150 f=#fff c=#333 br=8
text label 100,150 200x30 "Hello" center f=#333

General Element Format

TYPE ID x,y WxH [options] ["text"]

TYPE    = rect | ellipse | diamond | triangle | text | line | arrow
ID      = unique identifier (alphanumeric, no spaces)
x,y     = position coordinates (top-left corner)
WxH     = width x height in pixels
options = property=value pairs (space separated)
"text"  = quoted text content (for text elements)

🔷 Element Types

Type Description Syntax Example
rect Rectangle/box shape rect box1 100,100 200x100 f=#dbeafe c=#1e40af br=8
ellipse Ellipse/circle/oval ellipse node1 200,150 80x80 f=#dcfce7 c=#166534
diamond Diamond shape (for decisions) diamond dec1 150,200 100x100 f=#fef08a c=#854d0e
triangle Triangle shape triangle tri1 100,100 60x60 f=#fecaca c=#991b1b
text Text label (requires quoted content) text t1 100,50 200x30 "Label" center bold f=#333
line Straight line (no arrow) line l1 100,100 ~~ 300,100 c=#666 sw=2
arrow Line with arrow head arrow a1 100,200 -> 300,200 c=#333 sw=2

⚙️ Properties & Shortcuts

Property Shortcuts

Short Full Name Description Example
c stroke Border/stroke color c=#1e40af
f fill Fill/background color f=#dbeafe
sw strokeWidth Border thickness sw=2
br borderRadius Corner rounding br=8
fs fontSize Text size in pixels fs=16
ff fontFamily Font family name ff=Arial
r roughness Sketch roughness (0-3) r=1.5
rot rotation Rotation angle in degrees rot=45
op opacity Transparency (0-1 or 0-100) op=0.5

Flag Properties (no value needed)

Flag Effect Example
bold Bold text weight text t1 0,0 100x30 "Title" bold
italic Italic text style text t1 0,0 100x30 "Note" italic
center Center-align text horizontally text t1 0,0 100x30 "Centered" center
left Left-align text text t1 0,0 100x30 "Left" left
right Right-align text text t1 0,0 100x30 "Right" right
underline Underlined text text t1 0,0 100x30 "Link" underline
strike Strikethrough text text t1 0,0 100x30 "Deleted" strike
overline Line above text text t1 0,0 100x30 "Note" overline
uppercase Transform to UPPERCASE text t1 0,0 100x30 "title" uppercase
lowercase Transform to lowercase text t1 0,0 100x30 "TITLE" lowercase
capitalize Capitalize Each Word text t1 0,0 100x30 "hello world" capitalize

🔤 Typography

Professional Typography: PDDSL supports advanced typography features including Google Fonts, variable font weights, line height, letter spacing, and text decorations.

Available Google Fonts

Font Family Category PDDSL Usage
Inter Sans-serif (Modern UI) ff=Inter
Roboto Sans-serif (Android) ff=Roboto
Poppins Sans-serif (Geometric) ff=Poppins
Montserrat Sans-serif (Elegant) ff=Montserrat
Open Sans Sans-serif (Friendly) ff="Open Sans"
Lato Sans-serif (Warm) ff=Lato
Raleway Sans-serif (Display) ff=Raleway
Oswald Sans-serif (Condensed) ff=Oswald
Playfair Display Serif (Elegant) ff="Playfair Display"
Roboto Mono Monospace (Code) ff="Roboto Mono"

Escape Sequences in Text

Use escape sequences for special characters in text content:

Escape Result Example
\\n Line break (new line) text t1 0,0 200x60 "Line 1\\nLine 2" lh=1.5
\\t Tab character text t1 0,0 200x30 "Item:\\tValue"
\\\\ Backslash character text t1 0,0 200x30 "Path: C:\\\\folder" 
# Multi-line text with line height
text poem 50,50 300x150 "Roses are red\\nViolets are blue\\nPDDSL is great\\nAnd so are you" lh=1.6 fs=18 f=#475569 center

# Tab-separated values
text data 50,220 400x80 "Name:\\tJohn Doe\\nEmail:\\tjohn@example.com" ff="Roboto Mono" fs=14 f=#1e293b

Typography Properties

Property Description Example
lh=1.5 Line height multiplier (spacing between lines) text t1 0,0 200x100 "Multi\\nLine" lh=1.8
ls=2 Letter spacing in pixels (tracking) text t1 0,0 200x30 "SPACED" ls=5
fw=700 Font weight (100-900) text t1 0,0 200x30 "Semi-Bold" fw=600

Font Weight Values

Value Name Use Case
100 Thin Ultra-light display text
200 Extra Light Light headlines
300 Light Elegant body text
400 Regular/Normal Standard body text
500 Medium Slightly emphasized text
600 Semi-Bold Subheadings
700 Bold Headlines, emphasis
800 Extra Bold Strong emphasis
900 Black Maximum impact

Typography Examples

# Elegant heading with Playfair Display
text heading 50,50 400x60 "Elegant Title" ff="Playfair Display" fs=48 fw=700 f=#1e293b

# Modern UI text with Inter
text body 50,130 400x80 "Clean modern interface text" ff=Inter fs=18 lh=1.6 f=#475569

# Monospace code snippet
text code 50,230 400x40 "const x = 42;" ff="Roboto Mono" fs=16 f=#22c55e

# Spaced-out uppercase heading (HEADER STYLE)
text header 50,290 400x40 "SECTION TITLE" ff=Oswald fs=24 ls=8 uppercase f=#1e40af

# Underlined link text
text link 50,350 200x30 "Click Here" underline f=#3b82f6

# Strikethrough for deleted text
text deleted 50,400 200x30 "Old Price $99" strike f=#94a3b8

# Combined styles: Light italic Raleway
text quote 50,450 400x60 "Typography is the craft of endowing human language with a durable visual form." ff=Raleway fs=18 fw=300 italic lh=1.5 f=#64748b

↗️ Lines & Arrows

📌 Connector Syntax:

Connector Examples

# Horizontal line
line h1 100,200 ~~ 400,200 c=#666 sw=2

# Vertical arrow (same X coordinate)
arrow v1 250,100 -> 250,300 c=#333 sw=2

# Diagonal arrow
arrow d1 100,100 -> 300,250 c=#1e40af sw=2

# Dashed arrow
arrow dash1 100,100 ..> 300,100 c=#999

Connector Between Elements

# You can use element IDs to auto-connect (centers bottom->top)
rect box1 100,100 150x60 f=#dbeafe c=#1e40af
rect box2 100,250 150x60 f=#dbeafe c=#1e40af
box1 --> box2   # Creates arrow from box1 bottom to box2 top

📐 Positioning & Layout

Absolute Positioning

# Elements use absolute x,y coordinates from top-left
rect a 100,100 200x100    # Left: 100px, Top: 100px
rect b 350,100 200x100    # 50px gap to the right of 'a'

🌊 Export Watermark (New v4.0)

Automatic Branding: All exported diagrams (PNG, SVG, PDF) automatically include a professional "Made with Privacy Diagram by PrivacyPixTools.com" watermark at the bottom-right.

This watermark is:

Relative Positioning Macros

Macro Description Example
@below(id,gap) Position below element with gap rect b @below(a,20) 200x100
@above(id,gap) Position above element with gap rect c @above(a,20) 200x100
@right(id,gap) Position to the right with gap rect d @right(a,30) 200x100
@left(id,gap) Position to the left with gap rect e @left(a,30) 200x100

Common Layout Patterns

# Vertical stack (flowchart style)
rect step1 300,50 150x60
rect step2 300,140 150x60   # 30px gap below step1
rect step3 300,230 150x60   # 30px gap below step2

# Horizontal row
rect col1 50,200 180x100
rect col2 260,200 180x100   # 30px gap
rect col3 470,200 180x100   # 30px gap

# Grid layout (3x2)
rect r1c1 50,50 150x80
rect r1c2 220,50 150x80
rect r1c3 390,50 150x80
rect r2c1 50,150 150x80
rect r2c2 220,150 150x80
rect r2c3 390,150 150x80

📋 Built-in Templates (22 Total)

Flowcharts

Architecture

UML Diagrams

Organization

Business

🧩 Common Patterns

Pattern: Box with Label

# Create a box with centered text inside
rect box 100,100 200x80 f=#dbeafe c=#1e40af br=8
text label 100,125 200x30 "My Label" center f=#1e40af

Pattern: Header Box (colored header with white body)

# Entity/card with colored header
rect body 100,100 200x150 f=#fff c=#1e40af br=4
rect header 100,100 200x40 f=#3b82f6 c=#1e40af br=4
text title 100,110 200x20 "Entity Name" center bold f=#fff

Pattern: Layer/Container with Children

# Large container with smaller boxes inside
rect layer 50,50 800x200 f=#dbeafe c=#1e40af sw=1
text layerTitle 350,60 200x30 "Presentation Layer" bold center f=#1e40af

rect child1 100,100 150x80 f=#fff c=#3b82f6 br=8
text c1label 100,130 150x30 "Component 1" center f=#1e40af

rect child2 280,100 150x80 f=#fff c=#3b82f6 br=8
text c2label 280,130 150x30 "Component 2" center f=#1e40af

Pattern: Connected Flow

rect start 250,50 100x50 f=#4ade80 c=#166534 br=25
text t1 250,60 100x30 "Start" center f=#166534

rect process 225,150 150x60 f=#dbeafe c=#1e40af br=8
text t2 225,165 150x30 "Process" center f=#1e40af

rect end 250,260 100x50 f=#fca5a5 c=#991b1b br=25
text t3 250,270 100x30 "End" center f=#991b1b

# Vertical arrows connecting boxes
arrow a1 300,100 -> 300,150 c=#666
arrow a2 300,210 -> 300,260 c=#666

🎨 Color Palette

💡 Tip: Use fill + stroke pairs for professional look. Light fill, dark stroke.
Semantic Fill (f=) Stroke (c=) Usage
Primary/Blue #dbeafe #1e40af Default, process steps
Success/Green #dcfce7 #166534 Start, complete, success
Warning/Orange #fef3c7 #92400e Caution, pending, business
Error/Red #fecaca #991b1b End, stop, error
Purple #e0e7ff #4338ca Special, API, gateway
Pink #fce7f3 #9d174d Accent, highlight
Neutral/Gray #f8fafc #475569 Background, disabled
White Card #ffffff #e2e8f0 Cards within containers
Dark Header #1e293b #0f172a Headers, emphasis

📄 Complete Examples

Example 1: Simple Flowchart

%pddsl 1.0
%canvas 600x450 #f5f5f5

# Start node
rect start 250,30 100x50 f=#4ade80 c=#166534 br=25
text t1 250,42 100x30 "Start" center f=#166534

# Process steps
rect step1 225,120 150x60 f=#dbeafe c=#1e40af br=8
text t2 225,140 150x30 "Step 1" center f=#1e40af

rect step2 225,220 150x60 f=#dbeafe c=#1e40af br=8
text t3 225,240 150x30 "Step 2" center f=#1e40af

# End node
rect end 250,320 100x50 f=#fca5a5 c=#991b1b br=25
text t4 250,332 100x30 "End" center f=#991b1b

# Connectors
arrow a1 300,80 -> 300,120 c=#666 sw=2
arrow a2 300,180 -> 300,220 c=#666 sw=2
arrow a3 300,280 -> 300,320 c=#666 sw=2

Example 2: System Architecture

%pddsl 1.0
%canvas 900x500 #f8fafc

# Frontend Layer
rect frontend 50,50 800x120 f=#dbeafe c=#1e40af sw=1
text fh 350,60 200x30 "Frontend" bold center f=#1e40af

rect web 100,90 180x60 f=#fff c=#3b82f6 br=8
text wt 100,110 180x30 "Web App" center f=#1e40af

rect mobile 330,90 180x60 f=#fff c=#3b82f6 br=8
text mt 330,110 180x30 "Mobile App" center f=#1e40af

# API Layer
rect api 300,220 300x80 f=#e0e7ff c=#4338ca br=8
text at 300,250 300x30 "API Gateway" center bold f=#4338ca

# Backend Layer
rect backend 50,350 800x120 f=#fef3c7 c=#92400e sw=1
text bh 350,360 200x30 "Backend Services" bold center f=#92400e

rect auth 100,390 150x60 f=#fff c=#f59e0b br=8
rect users 280,390 150x60 f=#fff c=#f59e0b br=8
rect orders 460,390 150x60 f=#fff c=#f59e0b br=8
rect payment 640,390 150x60 f=#fff c=#f59e0b br=8

text a1 100,410 150x30 "Auth" center f=#92400e
text u1 280,410 150x30 "Users" center f=#92400e
text o1 460,410 150x30 "Orders" center f=#92400e
text p1 640,410 150x30 "Payment" center f=#92400e

# Connectors
arrow c1 450,170 -> 450,220 c=#666 sw=2
arrow c2 450,300 -> 450,350 c=#666 sw=2

🚀 Advanced Visual Features (v2.0)

NEW in PDDSL 2.0: Create stunning, professional diagrams with gradients, shadows, curves, and icons!

Opacity Control (op=)

Add transparency to any element. Accepts values from 0-1 or 0-100.

Syntax Description Example
op=0.8 80% opacity (decimal) rect box 100,100 200x100 f=#3b82f6 op=0.8
op=50 50% opacity (percentage) text t1 100,50 200x30 "Watermark" op=50 
# Semi-transparent overlay
rect overlay 0,0 800x600 f=#000 op=0.5

# Watermark text
text watermark 300,400 200x30 "DRAFT" center f=#ff0000 fs=48 op=0.2

Drop Shadows & Glows (sh=)

Add depth and emphasis with shadows and glow effects.

Syntax Format Example
sh=x,y,blur,color offsetX, offsetY, blur radius, color sh=0,4,10,#00000030
sh=glow,blur,color Centered glow effect sh=glow,20,#3b82f680 
# Card with drop shadow
rect card 100,100 250x150 f=#fff c=#e2e8f0 br=12 sh=0,4,15,#00000020

# Glowing button
rect btn 100,300 180x50 f=#3b82f6 c=#1e40af br=25 sh=glow,20,#3b82f680
text btnText 100,312 180x30 "Subscribe" center f=#fff bold

Gradient Fills (gf=)

Create professional gradient backgrounds with linear or radial gradients.

Syntax Description Example
gf=linear(c1,c2) Horizontal linear gradient gf=linear(#1e40af,#60a5fa)
gf=linear(c1,c2,angle) Angled linear gradient gf=linear(#1e40af,#60a5fa,45)
gf=radial(c1,c2) Radial gradient (center to edge) gf=radial(#fff,#3b82f6) 
# Header with gradient
rect header 0,0 1200x120 gf=linear(#1e40af,#3b82f6,90)
text title 500,40 200x40 "Dashboard" center bold fs=28 f=#fff

# Radial glow circle
ellipse glow1 400,150 120x120 gf=radial(#fff,#3b82f6)

Curved Lines (curve)

Draw smooth quadratic bezier curves for flow lines and charts.

Syntax Description
curve ID x1,y1 cx,cy x2,y2 [opts] Quadratic curve from (x1,y1) to (x2,y2) with control point (cx,cy) 
# Smooth curved connector
curve c1 100,200 250,50 400,200 c=#3b82f6 sw=3

# Growth chart with multiple curves
curve growth1 50,400 150,350 250,380 c=#22c55e sw=2
curve growth2 250,380 350,200 450,100 c=#22c55e sw=2

SVG Paths (path)

Use SVG path syntax for complex custom shapes.

Syntax Description
path ID x,y WxH "M..." [opts] SVG path data in quotes 
# Custom arrow shape
path arrow1 100,100 50x50 "M 0 25 L 35 25 L 35 15 L 50 25 L 35 35 L 35 25" f=#3b82f6 c=#1e40af

# Custom star
path star1 200,100 100x100 "M 50 0 L 61 35 L 100 35 L 69 57 L 80 95 L 50 70 L 20 95 L 31 57 L 0 35 L 39 35 Z" f=#fbbf24 c=#92400e

Icon Embedding (icon)

Embed icons from Tabler, AWS, Azure, or GCP icon libraries.

Syntax Description Example
icon ID x,y size name Tabler icon (default) icon i1 100,100 48 user
icon ID x,y size lib:name Specific library icon icon i2 100,100 64 aws:ec2

Supported Icon Libraries

Library Icons Prefix Example Icons
Tabler 4,985 tabler: (default) user, settings, home, search, mail, heart, star, database
AWS 309 aws: ec2, s3, lambda, rds, dynamodb, cloudfront, athena
Azure 705 azure: vm, storage, functions, sql, cosmos, cdn, kubernetes
GCP 45 gcp: compute, storage, bigquery, cloud-run, vertex-ai, gke
🎨 Icon Picker UI (6,044 Icons!)

Use the Icon Library button in the toolbar (grid icon) to browse and insert icons visually:

Total: 6,044 icons available for architecture diagrams, infographics, and UI mockups!

# Dashboard with icons
rect card1 100,100 200x150 f=#fff c=#e2e8f0 br=12 sh=0,4,15,#00000015
icon userIcon 165,120 48 user c=#3b82f6
text label1 100,180 200x30 "Active Users" center f=#64748b

# Cloud architecture with AWS icons
icon awsEc2 100,100 64 aws:ec2
icon awsS3 250,100 64 aws:s3
icon awsLambda 175,200 64 aws:lambda
arrow a1 140,132 -> 210,132 c=#666
arrow a2 175,145 -> 175,195 c=#666

Complete Enhanced Example

%pddsl 1.0
%canvas 1200x800 #0f172a

# Header with gradient
rect header 0,0 1200x120 gf=linear(#1e40af,#3b82f6,90)
text title 400,40 400x40 "Company Growth 2024" center bold fs=32 f=#fff sh=0,2,8,#00000040

# Stats cards with shadows
rect card1 100,180 280x200 f=#fff c=#e2e8f0 br=16 sh=0,4,20,#00000015
rect card2 440,180 280x200 f=#fff c=#e2e8f0 br=16 sh=0,4,20,#00000015
rect card3 780,180 280x200 f=#fff c=#e2e8f0 br=16 sh=0,4,20,#00000015

# Icons in cards
icon icon1 200,220 64 trending-up c=#22c55e
icon icon2 540,220 64 users c=#3b82f6
icon icon3 880,220 64 currency-dollar c=#f59e0b

# Stats text
text stat1 100,300 280x40 "+127%" center bold fs=36 f=#22c55e
text stat2 440,300 280x40 "10.5K" center bold fs=36 f=#3b82f6
text stat3 780,300 280x40 "$2.4M" center bold fs=36 f=#f59e0b

text label1 100,345 280x25 "Revenue Growth" center f=#64748b
text label2 440,345 280x25 "Active Users" center f=#64748b
text label3 780,345 280x25 "Total Sales" center f=#64748b

# Growth curve
curve growthLine 100,600 400,450 700,500 c=#22c55e sw=4
curve growthLine2 700,500 900,350 1100,200 c=#22c55e sw=4

# Glow effect on call-to-action
rect cta 500,700 200x50 gf=linear(#3b82f6,#1e40af) br=25 sh=glow,20,#3b82f680
text ctaText 500,712 200x30 "Learn More" center bold f=#fff

🎨 Infographic Features (v3.0)

NEW in PDDSL 3.0: Create stunning infographics with pillars, organic shapes, isometric 3D elements, and illustrations!

Gradient Pillars (pillar)

Create vertical pillars with gradient fills - perfect for comparison charts and data visualization.

Syntax Description
pillar ID x,y WxH "Title" gf=linear(c1,c2) Vertical pillar with title and gradient 
# Comparison pillars for infographic
pillar p1 100,300 150x200 "PHASE 1" gf=linear(#ef4444,#b91c1c)
pillar p2 280,300 150x200 "PHASE 2" gf=linear(#22c55e,#15803d)
pillar p3 460,300 150x200 "PHASE 3" gf=linear(#3b82f6,#1d4ed8)

Wave Shapes (wave)

Create organic wave backgrounds for visual interest.

Syntax Description
wave ID x,y WxH f=#color op=0.5 freq=N Wave shape with color, opacity, and frequency 
# Background waves for infographic
wave bg1 0,0 1200x300 f=#3b82f6 op=0.2 freq=2
wave bg2 0,100 1200x300 f=#1e40af op=0.15 freq=3

Blob Shapes (blob)

Create organic blob shapes for decorative backgrounds.

Syntax Description
blob ID x,y size f=#color op=0.5 seed=N Organic blob with fill, opacity, and random seed 
# Decorative blobs
blob decor1 100,50 120 f=#ef4444 op=0.15 seed=42
blob decor2 800,200 150 f=#3b82f6 op=0.2 seed=17

Isometric 3D Elements

Add depth with isometric cubes and stacks.

Type Syntax Description
isocube isocube ID x,y size f=#color Single isometric cube
isostack isostack ID x,y size h=N f=#color Stack of N cubes 
# 3D isometric elements
isocube cube1 100,200 60 f=#3b82f6
isostack tower1 250,200 50 h=4 f=#22c55e
isostack tower2 350,200 50 h=6 f=#ef4444

Illustrations (illus)

Embed pre-built SVG illustrations.

Syntax Description
illus ID x,y WxH name Embed illustration by name

Available Illustrations

Category Names
People person-thinking, person-boat, person-building, teamwork
Scenes water-waves, gradient-sky
Concepts success, compass, growth 
# Illustration usage
illus hero 100,150 200x180 person-thinking
illus team 400,150 250x180 teamwork

Circle Shapes (circle)

Create perfect circles (different from ellipse).

Syntax Description
circle ID x,y WxW f=#color c=#stroke Circle with diameter WxW 
# Circles for data points or icons
circle c1 100,100 50x50 f=#ef4444
circle c2 200,100 50x50 f=#22c55e
circle c3 300,100 50x50 f=#3b82f6

Hexagon & Star Shapes

Type Syntax Description
hexagon hexagon ID x,y WxH f=#color Six-sided polygon
star star ID x,y WxH f=#color Five-pointed star 
# Special shapes
hexagon hex1 100,100 80x90 f=#fbbf24 c=#92400e
star star1 250,100 80x80 f=#ef4444 c=#991b1b

Complete Infographic Example

%pddsl
%canvas 1000x800 #f8fafc

# Header
rect header 0,0 1000x100 f=#dc2626
text title 50,30 900x40 "COMPANY STATS 2024" fs=36 bold f=#ffffff center

# Stats row
rect stat1_bg 50,130 280x100 f=#fef2f2 br=12
text s1_num 50,150 280x40 "$29.8M" fs=32 bold f=#dc2626 center
text s1_lbl 50,190 280x25 "Revenue" fs=14 f=#64748b center

rect stat2_bg 360,130 280x100 f=#f0fdf4 br=12
text s2_num 360,150 280x40 "1.2K" fs=32 bold f=#16a34a center
text s2_lbl 360,190 280x25 "Customers" fs=14 f=#64748b center

rect stat3_bg 670,130 280x100 f=#eff6ff br=12
text s3_num 670,150 280x40 "98%" fs=32 bold f=#2563eb center
text s3_lbl 670,190 280x25 "Satisfaction" fs=14 f=#64748b center

# Growth pillars
pillar p1 100,350 200x300 "Q1" gf=linear(#fecaca,#ef4444)
pillar p2 350,350 200x300 "Q2" gf=linear(#bbf7d0,#22c55e)
pillar p3 600,350 200x300 "Q3" gf=linear(#bfdbfe,#3b82f6)
pillar p4 850,350 200x300 "Q4" gf=linear(#e9d5ff,#a855f7)

# Footer
rect footer 0,730 1000x70 f=#1e293b
text foot 50,750 900x30 "Annual Report 2024" fs=14 f=#94a3b8 center

✅ Best Practices for LLMs

1. Start Simple

Begin with header, then add shapes, then text labels, then connectors last.

2. Use Consistent Spacing

Keep gaps between elements consistent (20-30px typical). Align elements on a grid.

3. ID Naming Convention
4. Text Positioning

For text inside a box, use the same x coordinate and add offset to y. Use center flag for centering.

rect box 100,100 200x80 f=#dbeafe c=#1e40af
text label 100,130 200x30 "Centered Text" center f=#1e40af
5. Vertical Arrows

For vertical arrows, keep X coordinates the same:

arrow v1 300,100 -> 300,200 c=#666  # Same X=300, vertical line
6. Calculate Canvas Size

Add 50-100px padding around your content. If rightmost element is at x=800 with width 200, canvas should be at least 1050px wide.

📊 Token Comparison
Diagram Type JSON Tokens PDDSL Tokens Savings
5-node flowchart ~1,500 ~180 88%
3-tier architecture ~3,200 ~400 87%
Org chart (10 nodes) ~4,000 ~500 87%

🚫 Common LLM Mistakes & Fixes

Mistake 1: Centering Text by Setting X to Canvas Center 
# ❌ WRONG - Text starts at X=500 and goes RIGHT, overflowing canvas
text title 500,30 900x40 "Title" center

# ✅ CORRECT - X = (canvas_width - text_width) / 2
text title 50,30 900x40 "Title" center
Mistake 2: Confusing f= (fill) and c= (stroke) 
# ❌ WRONG - c= is stroke/border, text will be black
text t1 50,50 200x30 "Hello" c=#ffffff

# ✅ CORRECT - f= is fill color for text
text t1 50,50 200x30 "Hello" f=#ffffff
Mistake 3: Text Width Too Small for Content 
# ❌ WRONG - 100px is too narrow for "Hello World" at fs=16
text t1 50,50 100x30 "Hello World" fs=16  # Will overflow!

# ✅ CORRECT - Calculate: 11 chars × 10px + 20px padding = 130px
text t1 50,50 130x30 "Hello World" fs=16
Mistake 4: Not Aligning Text X with Container X 
# ❌ WRONG - Text X doesn't match rect X
rect box 100,100 200x80 f=#dbeafe
text label 150,130 200x30 "Label" center  # Misaligned!

# ✅ CORRECT - Same X coordinate, same width
rect box 100,100 200x80 f=#dbeafe
text label 100,130 200x30 "Label" f=#1e40af center
Quick Reference: Property Confusion Cheat Sheet
What You Want Use This NOT This
Text color f=#color c=#color (that's stroke)
Shape fill f=#color
Shape border c=#color f=#color (that's fill)
Border thickness sw=2
Rotation rot=45
Transparency op=0.5

🚀 v4.0 Layout Engine (NEW!)

v4.0 enables LLM-friendly diagram creation WITHOUT manual X,Y coordinates!

Use %pddsl 4.0 to enable the new layout engine. Elements are positioned automatically based on indentation and layout primitives.

📐 Layout Primitives

v4.0 uses indentation-based nesting. Child elements are indented by 2 spaces under their parent layout.

stack (Vertical Layout)

%pddsl 4.0
%canvas 800x600 #f8fafc

stack main padding=40 gap=24
  card card1 w=280
    title "First Card"
    desc "Description here"
  card card2 w=280
    title "Second Card"
Option Default Description
padding 0 Inner padding around stack
gap 16 Space between children
align center Horizontal alignment: left, center, right

row (Horizontal Layout)

row stats gap=24
  stat revenue
    value "$12.4K"
    label "Revenue"
  stat users
    value "1,234"
    label "Users"
Option Default Description
gap 16 Space between children
justify center Horizontal: start, center, end, between
align center Vertical: top, center, bottom

grid (Grid Layout)

grid features cols=3 gap=20
  card c1 w=200
    title "Feature 1"
  card c2 w=200
    title "Feature 2"
  card c3 w=200
    title "Feature 3"
Option Default Description
cols 2 Number of columns
gap 16 Gap between cells

🧩 Semantic Components

card

A content card with optional icon, title, description, and badge.

card myCard w=280 padding=20 bg=#ffffff shadow=sm
  icon shield size=48 color=primary
  title "Secure"
  desc "Enterprise-grade security"
  badge "NEW" color=success
Option Default Description
w 280 Card width in pixels
padding 20 Internal padding
bg theme.bg Background color
shadow sm Shadow size: none, sm, md, lg
radius 12 Corner radius

badge

badge "Pro" color=primary size=md

stat

Statistics display with value, label, and optional trend indicator.

stat revenue w=150
  value "$12.4K"
  label "Revenue"
  trend up

button

button "Get Started" variant=solid color=primary size=md

Variants: solid, outline, ghost

avatar

avatar user initials=JD color=primary size=md

Sizes: sm (32px), md (48px), lg (64px)

divider

divider style=solid color=#e5e7eb

Styles: solid, dashed, dotted

📊 Chart Components

Bar Chart

chart sales type=bar w=400 h=250
  data "Jan" 120
  data "Feb" 180
  data "Mar" 150 color=#22c55e

Pie Chart

chart market type=pie w=300 h=300
  data "Chrome" 65 color=#3b82f6
  data "Firefox" 20 color=#f59e0b
  data "Safari" 15 color=#10b981

Line Chart

chart growth type=line w=400 h=200
  data "Q1" 100
  data "Q2" 150
  data "Q3" 200
  data "Q4" 280

Progress Bar

chart progress type=progress w=300 value=75 color=success

🎨 Theme System

Define colors once and use semantic tokens throughout your diagram.

Custom Theme

%pddsl 4.0
%canvas 800x600 #f8fafc
%theme primary=#3b82f6 success=#22c55e warning=#f59e0b danger=#ef4444

Preset Themes

%theme preset=dark   # Dark mode colors
%theme preset=light  # Light mode (default)
%theme preset=vibrant   # Colorful palette
Theme Color Tokens: primary, secondary, success, warning, danger, muted, bg, surface, border, text, text-muted

🔗 Smart Connections

Connect elements by ID with automatic obstacle-avoiding routing.

arrow from=card1 to=card2 label="Next" color=primary
line from=step1 to=step2 style=dashed
Option Description
from Source element ID
to Target element ID
label Optional connection label
color Line color (supports theme tokens)
style solid or dashed

📋 Complete v4.0 Example

%pddsl 4.0
%canvas 800x600 #f8fafc
%theme primary=#3b82f6 success=#22c55e

# Stats row at top
row stats padding=40 gap=24
  stat revenue
    value "$12.4K"
    label "Monthly Revenue"
    trend up
  stat users
    value "1,234"
    label "Active Users"

# Feature cards
stack features gap=20 padding=20
  card feature1 w=300
    icon shield
    title "Enterprise Security"
    desc "Bank-grade encryption"
    badge "NEW" color=success
  card feature2 w=300
    icon zap
    title "Lightning Fast"
    desc "Sub-50ms response time"

# Connect the cards
arrow from=feature1 to=feature2
⚡ LLM Tip: Use v4.0 for complex layouts! No coordinate calculations needed. Just describe the structure with indentation and let the engine position everything automatically.