/canvas Skill

Create and edit Obsidian Canvas files (.canvas JSON format) for architecture visualization.

When to Use This Skill

Use when creating or editing .canvas files (Obsidian Canvas format):

• Create architecture context diagrams (C4 Level 1)
• Design system landscape maps
• Visualize data flow architectures
• Show AWS infrastructure layouts
• Compare scenarios side-by-side
• Map system dependencies

⚠️ CRITICAL: Linter Configuration Warning

The Obsidian linter will corrupt .canvas files if enabled. If you have a linter active (prettier, eslint, etc.):

1. DISABLE it for .canvas files
2. Or DISABLE it globally during canvas editing
3. Canvas files use a specific JSON format that lingers may reformat incorrectly

The linter will delete nodes with empty text fields and reduce complex diagrams to 2 nodes.

Canvas JSON Structure

Correct Format

Every node MUST use text property for content (NOT label):

{
  "nodes": [
    {
      "id": "unique-id",
      "type": "text",
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 100,
      "color": "3",
      "text": "Node Content\nMultiline supported\nWith \\n character"
    }
  ],
  "edges": [
    {
      "id": "edge-id",
      "fromNode": "node-id-1",
      "toNode": "node-id-2",
      "fromSide": "right",
      "toSide": "left",
      "label": "Edge Label"
    }
  ],
  "metadata": {
    "version": "1.0-1.0",
    "frontmatter": {}
  }
}

Property Reference

Node Properties:

Property	Required	Type	Values	Notes
id	✅	string	Any unique ID	Use kebab-case
type	✅	string	"text"	Currently only text type supported
x	✅	number	Any integer	Canvas X coordinate
y	✅	number	Any integer	Canvas Y coordinate
width	✅	number	Any positive int	Node width in pixels
height	✅	number	Any positive int	Node height in pixels
text	✅	string	Any text	USE THIS FOR NODE CONTENT (not label)
color	❌	string	"1"-"6"	Color: 1=red, 2=orange, 3=yellow, 4=purple, 5=cyan, 6=green

Edge Properties:

Property	Required	Type	Values
id	✅	string	Any unique ID
fromNode	✅	string	ID of source node
toNode	✅	string	ID of target node
fromSide	✅	string	"top", "right", "bottom", "left"
toSide	✅	string	"top", "right", "bottom", "left"
label	❌	string	Any text

Metadata:

"metadata": {
  "version": "1.0-1.0",
  "frontmatter": {}
}

Common Mistakes

❌ WRONG: Using label for node content

{"id":"node1","type":"text","x":0,"y":0,"width":100,"height":50,"label":"Node Text"}

Result: Text appears on edges, boxes are empty

✅ CORRECT: Using text for node content

{"id":"node1","type":"text","x":0,"y":0,"width":100,"height":50,"text":"Node Text"}

Result: Text displays inside the box

❌ WRONG: Empty text field

{"id":"node1","type":"text","x":0,"y":0,"width":100,"height":50,"text":""}

Result: Obsidian deletes the node on next edit

✅ CORRECT: No empty fields

Only include properties with values. Don't include text field if empty.

Workflow

Phase 1: Define Canvas Structure

Plan the canvas:

• Sections/clusters - Group related nodes (e.g., "SOURCE SYSTEMS", "KAFKA EVENT BUS")
• Nodes - Individual boxes with content
• Edges - Connections with labels

Example structure:

SECTION HEADERS (120px high, wide)
  ↓
MAIN NODES (100+ px high, sized to fit content)
  ↓
EDGES with labels connecting them

Phase 2: Calculate Coordinates

• X axis: Left to right (0 → +)
• Y axis: Top to bottom (0 → +)
• Group related items with consistent spacing
• Use 20-30px padding between nodes

Example grid:

(0,0)    (300,0)    (600,0)    (900,0)
  A        B          C          D

(0,100)  (300,100)  (600,100)  (900,100)
  E        F          G          H

Phase 3: Determine Node Heights

Size nodes based on content:

• Section headers: 40px height
• Simple labels: 50px height
• Multi-line (2-3 lines): 70px height
• Multi-line (4+ lines): 80-100px height
• Large info boxes: 100px+ height

Add ~10-15px padding for text overflow.

Phase 4: Create JSON

Use text property for all node content. Use label property for edge labels only.

Phase 5: Validate & Test

1. Save .canvas file
2. Verify JSON syntax: node -e "JSON.parse(require('fs').readFileSync('file.canvas'))"
3. Open in Obsidian and verify:
   • All boxes display with text inside (not on edges)
   • Edge labels appear on connections
   • Layout matches intended design
   • Colours display correctly

Examples from This Vault

All of these use correct JSON Canvas format:

• Canvas - C4 Context Diagram - 9 nodes, 9 edges
• Canvas - System Landscape - 18 nodes, 14 edges
• Canvas - Data Flow Diagram - 22 nodes, 18 edges
• Canvas - AWS Architecture - 24 nodes, 11 edges
• Canvas - Scenario Comparison - 19 nodes, 2 edges
• Canvas - Data Platform Data Flow - 38 nodes, 68 edges

All use text property for node content and label property for edge labels.

Color Reference

Canvas supports 6 colors:

• "1" - Red (Critical, Production)
• "2" - Orange (High Priority, Warning)
• "3" - Yellow (Source Systems, Starting Point)
• "4" - Purple (Access/Gateway, Tools)
• "5" - Cyan (Transformation, Processing)
• "6" - Green (Analytics, Destination, Data Lake)

Size Guidelines

Width:

• Section headers: 160-200px (full width of section)
• Small nodes: 100-120px
• Medium nodes: 150-160px
• Large nodes: 200-260px
• Full-width containers: 240-300px+

Height:

• Thin header: 40px
• Simple label: 50px
• 2-3 lines: 70px
• 4-5 lines: 80px
• 5+ lines or containers: 100px+

Testing Checklist

Before considering a canvas file "done":

• JSON syntax is valid
• All node content uses text property
• All edge labels use label property
• No empty text fields exist
• File opens in Obsidian without errors
• All boxes display text inside (not on edges)
• All edge labels appear on connections
• Colours display correctly
• Layout matches intended design
• Spacing and alignment looks good

Related Skills

• /diagram - Generate diagrams programmatically using Python
• /scenario-compare - Create side-by-side scenario comparison canvases
• /impact-analysis - Visualize system impact on canvas

File Naming Convention

Canvas - {{Diagram Name}}.canvas
Canvas - C4 Context Diagram.canvas
Canvas - System Landscape.canvas
Canvas - Data Flow Diagram.canvas
Canvas - AWS Architecture.canvas

JSON Validation

Quick validation command:

node -e "try { JSON.parse(require('fs').readFileSync('file.canvas', 'utf8')); console.log('✓ Valid JSON'); } catch(e) { console.log('✗ Error:', e.message); }"

---

Key Principle: text = node content, label = edge labels. Never use label for node content.

Key Warning: Disable linters before editing .canvas files - they corrupt the JSON structure.