🦾 Canvas

Executive Summary

JSON Canvas is an open standard for spatial canvases, heavily used in our ecosystem for macro-architecture mapping, agent ecosystem visualization, and project exploration. Unlike Mermaid (which is strictly auto-layout), JSON Canvas allows deliberate 2D spatial arrangement, grouping, and embedding of other files. This skill defines how to create and maintain robust .canvas files for the Funday project.

When to use / When NOT to use

Use When:

• Building high-level architecture or project maps.
• Visualizing complex agent interactions where spatial grouping matters.
• Creating “dashboards” of related Markdown files and notes (Obsidian-style canvases).
• Documenting system landscapes with distinct zones (e.g., Frontend, Backend, Infrastructure).

When NOT to use:

• Simple flowcharts or sequence diagrams (use Mermaid).
• Inline document visuals (JSON Canvas requires a separate file or specific viewer).
• Pixel-perfect graphical illustrations (use SVG).

Rules

1. Specification Compliance

Always output strict JSON Canvas 1.0 format. The file must contain a top-level JSON object with nodes and edges arrays.

2. Node Minimum Sizes

To ensure text and file nodes are readable without extreme zooming, minimum dimensions must be respected:

• Text nodes: Minimum 360x180.
• File nodes (embedding Markdown): Minimum 400x300.
• Group nodes: Must comfortably enclose their children with padding.

3. Meaningful Grouping

Groups must contain at least two nodes. Do not create single-item groups unless strictly necessary for future expansion. Use groups to define architectural boundaries (e.g., “Kubernetes Cluster”, “Database Tier”).

4. Edge Connections

Connect edges semantically using sides (top, bottom, left, right). Avoid overlapping edges over unrelated nodes. Use end: "arrow" for directional flow.

Examples

Minimal Valid Canvas Structure

{
  "nodes": [
    {
      "id": "node-1",
      "type": "text",
      "text": "# API Gateway\nRoutes incoming traffic to microservices.",
      "x": 0,
      "y": 0,
      "width": 360,
      "height": 180,
      "color": "1"
    },
    {
      "id": "node-2",
      "type": "text",
      "text": "# Auth Service\nValidates session tokens.",
      "x": 400,
      "y": 0,
      "width": 360,
      "height": 180,
      "color": "2"
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "fromSide": "right",
      "toNode": "node-2",
      "toSide": "left",
      "toEnd": "arrow"
    }
  ]
}

Failure Modes / Checks

1. Parser Rejection: Extraneous top-level keys or missing nodes/edges arrays will cause rendering failure.
2. Micro-nodes: Nodes sized below the minimum (e.g., 50x50) result in clipped, unreadable text.
3. Orphaned Edges: Referencing a fromNode or toNode ID that doesn’t exist in the nodes array.
4. Z-Index Issues: Group nodes overlaying text nodes instead of enclosing them. Ensure groups are positioned logically.

Related Links

• JSON Canvas Specification
• Mermaid Guru